################################################################################
### R BASICS WORKSHOP                                                        ###
### PRESENTATION 2.1: FUNCTIONS AND ARGUMENTS                                  ### 
###                                                                          ###
### Center for Conservation and Sustainable Development                      ###
### Missouri Botanical Garden                                                ###
### Website: rbasicsworkshop.weebly.com                                      ### 
################################################################################


### A. ESCRIBIR EN R ES SIMILAR A ESCRIBIR EN ESPAÑOL ##########################

# Un comando en español: 

# "Salta tres veces"

# 1. *Salta* es el verbo que define una acción
# 2. *tres veces* y *hacia adelante* son dos modificadores de esa acción


# Otro comando en español: 

# "Genera una secuencia del 5 al 20 con valores cada 0.5"

# 1. *Genera una secuencia* es la acción a tomar
# 2. *Del 5* modifica la acción definiendo donde empezar
# 3. *al 20* define el final de la secuencia
# 4. *con valores cada 0.5* define como construir la secuencia 

# ¿Cómo darle el comando anterior a una computadora? 
# Utilizando un lenguaje de programación como R!

seq(from=5, to=20, by=0.5)

# 1. *seq* es el nombre de una función, y define una acción a tomar en R
# 2. *from=5*: es el nombre de un argumento que define el inicio de la secuencia, 
#     en este caso el valor de from es 5
# 3. *to=20* es un segundo argumento con su valor 20 que define el final de la
#     secuencia
# 4. *by=0.5* es un tercer argumento que define la separación entre valores en 
#     la secuencia



### B. LA ANATOMÍA BÁSICA DE UN COMANDO EN R ###################################

seq(from=5, to=20, by=0.5)

# 1. Nombre de la función
# 2. Paréntesis abierto
# 3. Nombre del argumento
# 4. Símbolo de igual (=)
# 5. Valor dado al argumento
# 6. Coma (,)
# 7. Repetir 3,4, y 5 para cada argumento.
# 8. Paréntesis cerrado

# Unos pocos otros ejemplos:

rep(x = 8, times = 3) # La función *rep* repite datos.

rep(x = 3, times = 8)

rnorm(n=10, mean=2, sd=1) # La función *rnorm* genera valores al azar a partir 
                          # de una distribución normal.

rnorm(n=100, mean=-10, sd=3)

# Fíjese como la estructura de los comandos es siempre parecida!


### C. ALGUNAS REGLAS BÁSICAS SOBRE ARGUMENTOS #################################

# REGLA 1: Cada función tiene sus propios argumentos.

rep(x = 8, times = 3) # *rep* tiene *x*, *times*
rnorm(n=10, mean=2, sd=1) # *rnorm* tiene *n*, *mean*, *sd*


# REGLA 2. La descripción de cada función y sus argumentos puede encontrarse en  
# la ayuda de la función. Para acceder a la ayuda, utiliza la función *help*

help(topic="seq")


# REGLA 3. Los argumentos casi siempre tienen nombres (e.g. from, to, by),
# y valores se pasan a estos argumentos utilizando "="


# REGLA 4. Los nombres de los argumentos pueden ser eliminados si los valores 
#    se dan a la función en el orden pre-determinado. Por ejemplo, estos dos 
#    comandos son equivalentes:

seq(from=5, to=20, by=0.5)

seq(5, 20, 0.5)
seq(5, to = 20, 0.5) 


# Pero son distintos de este: 
seq(0.5, 5, 20)


# REGLA 5. Cada función tiene un orden pre-determinado de argumentos. 
#    Por ejemplo, para la función *seq* el orden es *from* primero, 
#   luego *to*, y luego *by*. 

help(topic="seq") # Confirme esto en la ayuda de la función *seq*


# REGLA 6. El orden de los argumentos puede modificarse SOLO si se utilizan los
# nombres. Por ejemplo, estos comandos son equivalentes: 

seq(from=5, to=20, by=0.5)
seq(by=0.5, from=5, to=20)


# REGLA 7. Algunos argumentos tienen valores pre-determinados! 

rnorm(n=10)

# Cuales son los valores pre-determinados de la función *rnorm*?

# Estos argumentos con valores pre-determinados no necesitan ser especificados
# para que la función trabaje, pero uno tiene que tener cuidado de que los 
# valores predeterminados son los que uno quiere. 


# REGLA 8. Cuando *...* aparece en la página de ayuda de una función, esto 
#    quiere decir frequentemente que hay multiples argumentos sin nombres. 

# Por jemplo, en la función *c*, *...* significa multiples valores a 
# concatenarse:
help(c)
c(9, 5, 3, 5)


# REGLA 9. R distingue entre mayúsculas y minúsculas. Por ejemplo la funcion 
# *seq* existe, pero la funcion *Seq* no existe:

Seq(from = 5, to = 20, by = 0.5)


# REGLA 10. En R, el espacio en blanco no tiene una función:

seq(from=5,to=20,by=0.5)

seq(from     =     5,      to     =     20,      by     =     0.5)

seq(from=5, 
     to=20, 
         by=
            0.5)



### D. UNOS EJEMPLOS ADICIONALES DE FUNCIONES Y ARGUMENTOS #####################

# *rep*
rep(x = "R", times = 10)

rep(times = 10, x = "R")

rep("R", 10)

rep(10, "R") # Why doesn't this work?


# *rnorm*
rnorm(n=10)

rnorm(n=100, mean=10, sd=5)


# *rpois*
rpois(n=10, lambda=5)

rpois(n=10) # Why doesn't this work?


# *paste*
paste("R", "Basics", "Workshop", sep="_")

paste("R", "Basics", "Workshop", sep=" ")


# *sum*
sum(19, 4, 2, 6, 2)

sum(6, 4, 19, 2, 2)


# *log*
log(x=10) # What type of logarithm is calculated here?



### E. FUNCIONES DENTRO DE FUNCIONES ###########################################

# Es muy común en R tener comandos que tienen varias funciones, e incluso que 
# tienen funciones dentro de funciones. Por ejemplo:

c(19, 4, 2, 6, 2) # Concatena varios valores
 
mean(x=c(19, 4, 2, 6, 2)) # Calcula el promedio de los valores en el argumento x

mean(x=19, 4, 2, 6, 2) # Esta versión NO hace lo mismo

# Otro ejemplo un poco más complejo:
rnorm(n=50, mean=0, sd=1) # Genera 50 valores de una distribución normal con 
                           # un promedio de 0 y una desviación estándar de 1

boxplot(x=list(rnorm(n=50, mean=0, sd=1), rnorm(n=500, mean=3, sd=1)))


# LAS ACCIONES DENTRO SIEMPRE SE EJECUTAN ANTES QUE LAS ACCIONES FUERA. Cuando 
# uno encuentra estos comandos complejos es útil traducirlos al español 
# de dentro hacia afuera. 

# En R:
boxplot(x=list(rnorm(n=50, mean=0, sd=1), rnorm(n=500, mean=3, sd=1)))

# En español:
# A. Obtener 50 valores al azar de una distribución normal con un promedio
#    de zero y una desviación estandar de 1. 
# B. Obtener 500 valores al azar de una distribución normal con un promedio de 3
#    y una SD de 1 
# C. Poner estos dos vectores de valores en una lista.
# D. Usar estos dos vectores en la lista para hacer un gráfico de cajas.




### F. FUENTES PRINCIPALES DE AYUDA SOBRE FUNCIONES Y SUS ARGUMENTOS  ##########

# 1. Lea el archivo de ayuda para la función

# 2. Hága una búsqueda en la web - use google.com (tiene todas las respuestas:
#    https://www.youtube.com/watch?v=YuOBzWF0Aws)

# 3. Has una pregunta en un foro en línea - www.r-project.org/mail.html

# 4. Estudia el código detrás de la función - para acceder al código se puede
#    escribir en la consola el nombre de la función sin los paréntesis. Esto no
#    funciona para funciones escritas en otros lenguajes. 



### G. EL ARCHIVO DE AYUDA PARA UNA FUNCIÓN ####################################

# Dos maneras principales de acceder el archivo de ayuda: *help* y *?*
help(seq)
?seq

# Las partes más importantes del archivo de ayuda:
# 1. DESCRIPTION -  una breve descripción de que es lo que la función hace

# 2. USAGE - como implementar la función

# 3. ARGUMENTS - una descripción de los argumentos de la función

# 4. DETAILS - detalles sobre la acción de la función o sus argumentos

# 5. VALUE - una descripción de los resultados de la función

# 6. SEE ALSO - una lista de funciones relacionadas

# 7. EXAMPLES - una serie de ejemplos del uso de la función