Documentos dinámicos, trabajo colaborativo y control de versiones con Rmarkdown y GitHub

class: center, middle, inverse, title-slide

# Documentos dinámicos, trabajo colaborativo y control de versiones con Rmarkdown y GitHub
### Natalia da Silva Instituto de Estadística-UDELAR

---

## Sobre mi 
.pull-left[ 
<img src = "portrait.png" width = 400 class = "center">

]

.pull-right[

- Profesora en el Instituto de Estadística de la Universidad de la República en Montevideo (UDELAR-IESTA)

- Doctorado y Maestría en Estadística: Iowa State University, USA

- Investigación: aprendizaje supervisado, estadística computacional, visualización estadística y meta-análisis

- Co-fundadora de R-Ladies Ames,  R-Ladies Montevideo y GURU::MVD

- Contacto:  
natalia@iesta.edu.uy 
@pacocuak 
http://natydasilva.com
]

---

## Sobre el taller

Disponible en:

https://natydasilva.github.io/Taller_ConectaR/#1

Este material está bajo licencia Creative Commons BY-NC-SA 3.0

<img src="cc.png" width="200">
---

## Sobre el taller

1. Investigación reproducible      
      + Reproducibilidad vs Replicabilidad
      + Relevancia
      + Integrar texto, análisis y código

2. Documentos dinámicos con RMarkdown

3. Control de Versiones, Git y GitHub

---
class: inverse, center, middle

## 1. Investigación reproducible

---

## Reproducibilidad vs Replicabilidad

**Reproducibilidad**: obtener los mismos resultados de una publicación anterior, usando los mismos datos, código y  análisis.

**Replicabilidad**: Obtener resultados similares o compatibles con los presentados en una publicación anterior, en un nuevo experimento (nuevos datos) y un análisis similar.

Resultados no reproducibles son difíciles de validar, resultados no replicables son difíciles de creer. La aproximación a RR (reproducible research) está basada en [paper:](https://www.tandfonline.com/doi/pdf/10.1198/106186007X178663?needAccess=true) 
 Statistical Analyses and Reproducible Research, <a name=cite-gentleman2007statistical></a>[Gentleman and Temple Lang (2007)](#bib-gentleman2007statistical).

---

## Relevancia

Medicina personalizada en Duke

+ <a name=cite-potti2006genomic></a>[Potti, Dressman, Bild, Riedel, Chan, Sayer, Cragun, Cottrill, Kelley, Petersen, and others (2006)](#bib-potti2006genomic) publican un artículo en que proponen tratamiento médico de cáncer basados en datos genéticos (específicos del paciente)

+ Baggerly y Coombes: Comienzan a estudiar la propuesta, para aplicar el tratamiento en Cáncer Centre en Houston. No son capaces de reproducir los resultados.

+ ... pasaron unos años ....

+ <a name=cite-baggerly2009deriving></a>[Baggerly and Coombes (2009)](#bib-baggerly2009deriving): Deriving Chemosensitivity from Cell Lines: Forensic Bioinformatics and Reproducible Research in High-Throughput Biology. **Annals of Applied Statistics** 
---

## Relevancia 
Deuda pública y crecimiento.

+ <a name=cite-reinhart2010growth></a>[Reinhart and Rogoff (2010)](#bib-reinhart2010growth) publican artículos estudiando la relación entre Deuda pública y crecimiento.

+ <a name=cite-herndon2014does></a>[Herndon, Ash, and Pollin (2014)](#bib-herndon2014does), revisan el trabajo anterior y encuentran: errores de código, exclusión de datos disponibles, ponderaciones no convencionales en estadísticas de resumen.

+ ''A coding error in the RR working spreadsheet entirely excludes five countries, Australia, Austria, Belgium, Canada, and Denmark, from the analysis (RR averaged cells in lines 30 to 44 instead of lines 30 to 49.)''
---

## Relevancia

+ Hace posible **validar** resultados

+ Facilita la **colaboración**

+ Principal herramienta: 
    - integrar texto, análisis y código
    - reproducibilidad de paquetes: para asegurar las versiones de paquetes
    packrat, rbundler, checkpoint
   
    
https://cran.r-project.org/web/views/ReproducibleResearch.html

---
class: inverse, center, middle

## 2. Documentos dinámicos con R Markdown

---

## Instalación

- RStudio IDE no se requiere pero es recomendable porque facilita el uso de R Markdown entre otras herramientas

- Si no tenés RStudio necesitás instalar Pandoc (http://pandoc.org),

- Instalar el paquete `rmarkdown` en R

- Para generar documentos en PDF, necesitamos instalar LaTeX.

- Si nunca instalaste LaTeX, instalá TinyTeX (https://yihui.name/tinytex/):

---

## Qué es Markdown? 
- Markdown is un tipo particular de lenguaje de marcado (markup lenguage)

- Estos lenguajes son diseñados para producir documentos de texto plano.

- Por ejemplo LaTeX es otro "markup language" para crear documentos pdf.

- LaTeX te da mucho más control pero tiene una curva de aprendizaje mayor.

- Markdown se está volviendo un standard y muchas web están generando HTML con Markdown.
---

## ¿Qué es R Markdown?

- R Markdown: Markdown + `chunks` de código R

- Formato que es capaz de crear documento dinámicos presentaciones
y reportes desde R

- Diseñado para facilitar la reproducibilidad ya que texto y código están en el mismo documento y los resultados son generados desde el código

- Documentos en R Markdown son documentos en Markdown.

- Muchos formatos estáticos y dinámicos  HTML, PDF, MS Word, Beamer, aplicaciones shiny, páginas web entre otros.

---

## ¿Porqué usar R Markdown?

- Es **simple**. Se enfoca en la escritura más que depurar errores.

- Es **flexible**. Markdown fue creado para simplificar la escritura de HTML, pero gracias a `pandoc` Markdown se convierte a muchos formatos.

- Es **dinámico**. Arreglar errores y modificar datos. Regenerar tu reporte sin copiar y pegar. Incentiva la transparencia y el trabajo colaborativo.

- Permite la **interactividad/reactividad**, permite a los usuarios explorar tu análisis en vez de solamente leerlo pasivamente.
---

## Hola R Markdown 
File -> New File -> R Markdown
<img src="createdmd.png" height="500px" width="660px" />

---

## Seleccionar el formato

<img src="formatrmd.png" height="500px" width="660px" />
---

## ¿Cómo funciona?

![](rmd.png)

- R Markdown pasa el archivo .Rmd a knitr donde se ejecutan los códigos y crea un archivo markdown (.md) que contiene el código en la salida.

- El .md generado por knitr se procesa con pandoc que genera distintos formatos de salida.

---

## Componentes del Rmd

Tres componentes básicos:

- Metadatos, YAML escrito entre un par de `---`

- Texto, escrito en Markdown

- Código, dos tipos:  bloque de código o código en el texto

---
## metadata YAML

`  --- `

` title: "Primer ejemplo" `

` author: "Natalia da Silva" `

` date: "26/01/2019" `

` output: html_document `

` ---  `
- Define la metadata

- Define el formato de salida

- Define las opciones del formato de salida
---

## Componentes del Rmd

---

## Comandos de texto básicos

- **Itálica**, encerrar una palabra o frase en asteriscos simples *

- **Negrita**, encerrar un mensaje o una frase en asteriscos dobles **

- **Resaltar código en una linea**, encerrándolo en ` `` `

- **Crear encabezado de sección**, incluyendo al inicio del la sección `#`

- **Otros encabezados**, incluyendo de 2 a 6 `#` son subsecciones y sub títulos.

- **Listas** (no ordenadas `*`, `-`, `+`  inicio de cada linea. Ordenadas 1. , 2. etc al inicio de cada linea)

- **Links** (`[link en una linea](https://www.google.com)`)

- **Imágenes** (`![](smallorb.png)`)

- Y más ...

---

## Opciones de código 
- Los chunks de código empiezan y termina con ` ``` `

`     ```{r nombre del chunk, opciones del chunk}    `

` 1 + 1  `

`  ```   `

`{r }` r indica el lenguaje de programación. Entre los ` ``` `  va código de R, a su vez podemos ponerle nombre al chunk y escribir otras opciones del chunk

- Código en texto  `  `r `  `  va luego de la r

---

## Más opciones de código 
Si queremos que no se evalúe (ó corra) el código de R:

`  ```{r nombre, eval = FALSE} `

` ```  `

- ` message = FALSE ` no se imprimen los mensajes, por ejemplo cuando cargamos un paquete.

- ` warning = FALSE ` no se imprimen los ` warnings `, ej: conflicto de versiones

- ` error = FALSE ` puede ser usado para hacer que compile el documento incluso si algún chunk tiene problemas.

-  ` echo = FALSE ` no muestra el código

- ` tidy =  TRUE ` formatea el código

---

## Más opciones de código

Opciones específicas para gráficos:

- `fig.align`(`left`, `right`, o `center`)  controla la posición

- `fig.cap` (`default = NULL`): leyenda de la figura como cadena de caracteres

- `fig.height`, `fig.width`: dimensiones del gráfico en inches

---

## Lenguajes
Se pueden ejecutar códigos de distintos lenguajes a parte de R

- Python
- SQL
- Bash
- Rcpp
- Stan
- JavaScript
- CSS
---
## Ejemplo plot
` ````` ```{r, echo = TRUE, fig.width = 3, fig.height = 3, fig.align = "right", fig.cap = "Puntos aleatorios"}

library(ggplot2)

dat <- data.frame(x = rnorm(100), y = rnorm(100))

ggplot(dat, aes(x, y)) + geom_point()

```  `

---

## Ejemplo plot

```r
library(ggplot2)
dat <- data.frame(x = rnorm(100), y = rnorm(100))
ggplot(dat, aes(x, y)) + geom_point() 
```

<div class="figure" style="text-align: right">
<img src="RMarkdown_GitHub_files/figure-html/unnamed-chunk-1-1.png" alt="Puntos aleatorios" />
Puntos aleatorios
</div>

---

## Más opciones de código 
Podemos fijar al inicio del documento algo como:

`  ```{r fijar}  `  
`  knitr::opts_chunk$set(echo = TRUE)  `

`  ```  `

esto fija en todo el documento la opción de mostrar todo el código  R en el documento final.

---

## Tablas

- [xtable](https://cran.r-project.org/web/packages/xtable/)
- [stargazer](https://cran.r-project.org/web/packages/stargazer/)
- [pander](https://github.com/Rapporter/pander)
- [tables](https://cran.r-project.org/web/packages/tables/)
- [ascii](https://github.com/eusebe/ascii)
- otros
---

## Tablas con `xtable`

```r
library(xtable)
tb <- xtable(mtcars[1:3,1:5])
print(tb, type = "html")
```

<table border=1>
<tr> <th> </th> <th> mpg </th> <th> cyl </th> <th> disp </th> <th> hp </th> <th> drat </th> </tr>
 <tr> <td align="right"> Mazda RX4 </td> <td align="right"> 21.00 </td> <td align="right"> 6.00 </td> <td align="right"> 160.00 </td> <td align="right"> 110.00 </td> <td align="right"> 3.90 </td> </tr>
 <tr> <td align="right"> Mazda RX4 Wag </td> <td align="right"> 21.00 </td> <td align="right"> 6.00 </td> <td align="right"> 160.00 </td> <td align="right"> 110.00 </td> <td align="right"> 3.90 </td> </tr>
 <tr> <td align="right"> Datsun 710 </td> <td align="right"> 22.80 </td> <td align="right"> 4.00 </td> <td align="right"> 108.00 </td> <td align="right"> 93.00 </td> <td align="right"> 3.85 </td> </tr>
 </table>

---

## Tablas con `kable`

```r
library(knitr)
kable(mtcars[1:3,1:5],format = "html")
```

<table>
 <thead>
 <tr>
 <th style="text-align:left;"> </th>
 <th style="text-align:right;"> mpg </th>
 <th style="text-align:right;"> cyl </th>
 <th style="text-align:right;"> disp </th>
 <th style="text-align:right;"> hp </th>
 <th style="text-align:right;"> drat </th>
 </tr>
 </thead>
<tbody>
 <tr>
 <td style="text-align:left;"> Mazda RX4 </td>
 <td style="text-align:right;"> 21.0 </td>
 <td style="text-align:right;"> 6 </td>
 <td style="text-align:right;"> 160 </td>
 <td style="text-align:right;"> 110 </td>
 <td style="text-align:right;"> 3.90 </td>
 </tr>
 <tr>
 <td style="text-align:left;"> Mazda RX4 Wag </td>
 <td style="text-align:right;"> 21.0 </td>
 <td style="text-align:right;"> 6 </td>
 <td style="text-align:right;"> 160 </td>
 <td style="text-align:right;"> 110 </td>
 <td style="text-align:right;"> 3.90 </td>
 </tr>
 <tr>
 <td style="text-align:left;"> Datsun 710 </td>
 <td style="text-align:right;"> 22.8 </td>
 <td style="text-align:right;"> 4 </td>
 <td style="text-align:right;"> 108 </td>
 <td style="text-align:right;"> 93 </td>
 <td style="text-align:right;"> 3.85 </td>
 </tr>
</tbody>
</table>
---

## Proyectos de RStudio

- Organizar cada análisis de datos en un proyecto (Carpeta en tu compu que contiene todos los archivos relevantes para tu trabajo particular).

- En RStudio es sencillo de implementar.

- El código se escribe asumiendo que el directorio de trabajo queda fijado al directorio del proyecto, código reproducible.

- Nos garantiza que el proyecto puede ser movido y el código aún funciona.

- Trabajar con proyectos para evitar usar `setwd()` que hace tu código frágil, y no reproducible.
---

## Materiales

- [Libro](https://bookdown.org/yihui/rmarkdown/basics.html)
 R Markdown: The Definitive Guide, <a name=cite-xie2018r></a>[Xie, Allaire, and Grolemund (2018)](#bib-xie2018r)

- [Guia de referencia](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf)

- [R Markdown Cheat Sheet](https://www.rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf)

- [Página](http://rmarkdown.rstudio.com/index.html)

[Yihui](https://yihui.name)
 (escribió `knitr` entre otros) tienen una muy buena página con mucha info sobre esto y más.

---

## Tu turno

1. Crear un archivo de R Markdown que compile a html.

2. En YAML metadata:

- Título del documento: Primer R Markdown 
  - Autor: Nombre y apellido

3. Compilar (render) y ver que el documento sale bien en html

4. Incluir una sección que se llame "Incluir imagen".

5. Seleccioná una imagen que te guste de Internet y guardarla en la carpeta donde está el proyecto.

6. Incluir una nueva sección que se llame "Chunk con código de R"

7. Incluir un chunk con código en R que haga un diagrama de dispersión de `hwy` vs `cty` usando los datos `mpg` disponibles en `ggplot2`

8. La figura tiene que tener 5 de alto y 5 de ancho

9. Cuando compile el archivo asegúrate que salga el código de R

---

## Tu turno: Solución
1 a 3:

`  --- `

` title: "Primer R Markdown" `

` author: "Natalia da Silva" `

` date: "26/01/2019" `

` output: html_document `

` ---  `

---

## Tu turno: Solución
4 y 5

`## Incluir imagen`

`![](rmdsticker.png)`

![](rmdsticker.png)

---

## Tu turno: Solución
6

` ## Chunk con código de R`

`     ```{r, fig.width = 5, fig.height = 5 }    `

` ggplot(data = mpg, aes(x = hwy, y = cty)) + geom_point() `

` ``` `
![](RMarkdown_GitHub_files/figure-html/unnamed-chunk-4-1.png)
---

class: inverse, center, middle

## 3. Control de Versiones, Git y GitHub 
---

## Git es...

- Sistema de control de versionado

- Diseñado (originalmente) para desarrollo de software

- Lo usamos para manejar la colección de archivos que hacen a un proyecto
(datos, figuras, reportes, código fuente).

---

## GitHub

- Lugar en la web

- Canal de distribución

- Colaboración
---

## ¿Qué necesitamos? 
- Cuenta en GitHub: https://github.com

- Instalar Git

- Conectar Git con GitHub

- Lograr que RStudio se comunique con Git y GitHub

http://happygitwithr.com
---

## Como luce
Ejemplo:

https://github.com/natydasilva
---

## ¿Qué ganamos?

- Mostrar tu trabajo públicamente

- Seguir de cerca proyectos interesantes

- Colaboradores predeterminados y hasta externos

---

## ¿Quién hace qué?

- Repositorios públicos disponible para que cualquiera lo lea. Propietario puede establecer niveles de permisos altos para `push commits`

- Repositorios privados son invisibles para todos. Propietario puede establecer privilegios y acceso a otros
---

## Especiales de GitHub

- **Issues**
 Es una lista de cosas, bugs, pedidos de cambios, comentarios, etc.  
Integrados con emails, pueden asignarse a personas y ver el progreso.  
Integrado con los `commits` permite registrar que los cambios de un commit resuelven el problema.

- **Pull requests**
Permite que un proyecto tenga múltiples ramas de desarrollo independiente.
Algunas ramas pueden pegarse a la versión de desarrollo original.

Un "pull request" es una propuesta formal de proponer cambios puede estar relacionados a la solución de un problema (issue).

---

## Detectar Git con RStudio

![](gitconn.png)
---

## ¿Qué hacer?

- Hacer un repositorio nuevo de Git.

- Dedicar una carpeta para cada proyecto.

- Que el proyecto sea de RStudio.

- Trabajar en el proyecto y en vez de salvar hago `commit` de uno o múltiples archivos.

- `push`  el `commit` al repositorio de GitHub, esto lo hace disponible en el repositorio
---

## Configurar GitHub
- Fijo mi usuario de git usando:

`git config --global user.name "tu usuario"`

- Fijo mi email de git para hacer los commits usando:

`git config  --global user.email "email@example.com"`

- Alternativamente puedo hacerlo usando el pkg `usethis`

```r
library(usethis)
use_git_config(user.name = "Tu nombre", user.email = "tucorreo@edu")
```

```
## ✔ Writing to global git config file
```

```
## $user.name
## [1] "Tu nombre"
## 
## $user.email
## [1] "tucorreo@edu"
```
---

## Más GitHub

- Cuando trabajo en distintos equipos o con otras personas los primero es hacer `pull` para tener la versión más actualizada del repositorio.

- Muchas veces hay que arreglar conflictos cuando más de un colaborador modifica la misma parte del trabajo.

---

## Mostrar el paso a paso
- Ver los pasos para tener un repo en GitHub conectado a RStudio .
- Hacer un pequeño cambio en un Rmarkdown y mostrar como hacer un `commit` y `push`.

---

## Tu turno!

- **1.** Hacer una cuenta de GitHub https://github.com
- **2.** Crear un repositorio  GitHub llamado conectaR
- **3.** Hacer un proyecto de RStudio para conectar con GitHub (Version control). Clonar su repositorio de GitHub.
- **4.** Fijá tu usuario de git

`git config --global user.name "tu usuario"`

- **5.** Fijá tu email de git para hacer los commits

`git config  --global user.email "email@example.com"`

- **6** Reiniciá tu sesión de R

- **7.** Copiar el archivo R Markdown que hicimos anteriormente en la carpeta del proyecto

- **8.** Hacer tu primer commit y push

- **9.** Poner una foto en tu perfil de GitHub

---

## FIN

GRACIAS POR LA ATENCIÓN !

- natalia@iesta.edu.uy
 
- @pacocuak
 
- http://natydasilva.com

---

# References

<a name=bib-baggerly2009deriving></a>[Baggerly, K. A. and K. R.
Coombes](#cite-baggerly2009deriving) (2009). "Deriving
chemosensitivity from cell lines: Forensic bioinformatics and
reproducible research in high-throughput biology". In: _The Annals
of Applied Statistics_, pp. 1309-1334.

<a name=bib-gentleman2007statistical></a>[Gentleman, R. and D.
Temple Lang](#cite-gentleman2007statistical) (2007). "Statistical
analyses and reproducible research". In: _Journal of Computational
and Graphical Statistics_ 16.1, pp. 1-23.

<a name=bib-herndon2014does></a>[Herndon, T, M. Ash and R.
Pollin](#cite-herndon2014does) (2014). "Does high public debt
consistently stifle economic growth? A critique of Reinhart and
Rogoff". In: _Cambridge journal of economics_ 38.2, pp. 257-279.

<a name=bib-potti2006genomic></a>[Potti, A, H. K. Dressman, A.
Bild, et al.](#cite-potti2006genomic) (2006). "Genomic signatures
to guide the use of chemotherapeutics". In: _Nature medicine_
12.11, p. 1294.

<a name=bib-reinhart2010growth></a>[Reinhart, C. M. and K. S.
Rogoff](#cite-reinhart2010growth) (2010). "Growth in a Time of
Debt". In: _American Economic Review_ 100.2, pp. 573-78.

<a name=bib-xie2018r></a>[Xie, Y, J. Allaire and G.
Grolemund](#cite-xie2018r) (2018). _R Markdown: The Definitive
Guide_. CRC Press.