################################################################################
### TALLER SOBRE FUNDAMENTOS DE R                                            ###
### PRESENTACIÓN 2.1: FUNCIONES Y ARGUMENTOS                                 ### 
###                                                                          ###
### Center for Conservation and Sustainable Development                      ###
### Missouri Botanical Garden                                                ###
### Sitio en la red: rbasicsworkshop.weebly.com                              ### 
################################################################################


### A. ESCRIBIR EN R ES SIMILAR A ESCRIBIR EN CASTELLANO ##########################

# Un comando en castellano: 

# "Salte tres veces hacia adelante"

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


# Otro comando en castellano: 

# "Genere una secuencia de 5 a 20 con valores cada 0.5"

# 1. *Genera una secuencia* es la acción
# 2. *Del 5* modifica la acción definiendo el principio de la secuencia
# 3. *al 20* modifica la acción definiendo el final de la secuencia
# 4. *con valores cada 0.5* también modifica la acción definiendo el intervalo de 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
# 2. *from=5*: es un argumento que define el inicio de la secuencia, 
#     en este caso el valor de "from" es 5
# 3. *to=20* es otro argumento que define el final de la secuencia,
#     en este caso el valor de "to" es 20
# 4. *by=0.5* es un tercer argumento que define el intervalo de la secuencia



### B. LA ESTRUCTURA 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 ejemplos:

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

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)


### 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 de estos argumentos se definen utilizando "="


# REGLA 4. Los nombres de los argumentos pueden ser excluidos del código si los
# valores de los argumentos se escriben en el orden pre-determinado para la función.
# Por ejemplo, estos tres líneas de código 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)

# ¿Cuáles son los valores pre-determinados de la función *rnorm*?

# Los argumentos con valores pre-determinados no necesitan ser definidos
# para ejecutar la función, pero es importante saber cuáles son los 
# valores pre-determinados implícitos en el código. 


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

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


# REGLA 9. R distingue entre mayúsculas y minúsculas. Por ejemplo la función 
# *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 afecta el resultado de ejecuctar el código:

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") # ¿Por qué esta línea de código no funciona?


# *rnorm*
rnorm(n=10)

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


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

rpois(n=10) # ¿Por qué esta línea de código no funciona?


# *paste*
paste("soy", "un", "hombre", "divertido", sep="_")

paste("yo", "no", "sé", "lo", "que", "es", "tristeza", sep="_")

paste("soy", "un", "hombre", "divertido", sep=" ")

paste("y", "cuándo", "llego", "a", "una", "fiesta", sep=" ")

paste("soy", "un", "hombre", "divertido", sep="+")

paste("yo", "me", "pongo", "a", "parrandear", sep="+")


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

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


# *log*
log(x=10) # ¿Cuál logaritmo se calcula aquí?

log10(10) # ¿Y aquí?



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

# En r es común escribir líneas de código que tienen varias funciones, e incluso que 
# tienen funciones dentro de funciones. Por ejemplo:

c(19, 4, 2, 6, 2) # Concatena 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

# Un segundo ejemplo:
rep("Arriba la mano", times=2)

rep("Abajo la mano", times=2)

rep(c("Arriba la mano", "Abajo la mano"), each=2)

rep(c("Arriba la mano", "Abajo la mano"), times=2)

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

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


# LAS FUNCIONES EN EL INTERIOR DEL CÓDIGO SE EJECUTAN ANTES QUE LAS FUNCIONES EN EL
# EXTERIOR DEL CÓDIGO. Por lo tanto es útil leer líneas de código complejas desde el
# interior hacia el exterior. 

# Por ejemplo, considere la siguiente línea de código en R:
boxplot(x=list(rnorm(n=50, mean=0, sd=1), rnorm(n=500, mean=3, sd=1)))

# el código anterior se puede leer, en castellano, desde el interior hacia el exterior:
# A. Obtener 50 valores aleatorios a partir de una distribución normal con media = 0
#    y desviación estandar = 1. 
# B. Obtener 500 valores aleatorios a partir de una distribución normal media = 3
#    y desviación estandar = 1. 
# C. Incluir estos dos vectores de valores en una lista.
# D. Usar los dos vectores en la lista para hacer un gráfico de cajas y bigotes.


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

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

# 2. Búsque en la red

# 3. Pregunte en un foro en la red - www.r-project.org/mail.html

# 4. Estudie 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
#    sirve 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 lo que hace la función

# 2. USAGE - como implementar la función

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

# 4. DETAILS - detalles sobre lo que hacen la función y sus argumentos

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

# 6. SEE ALSO - lista de funciones relacionadas

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