(Para profundizar contenidos de este curso, o aprender otros aspectos no incluidos, sugerimos tener en cuenta este tutorial de RMarkdown).
De acuerdo a Wikipedia:
Markdown es un lenguaje de marcado ligero creado por John Gruber que trata de conseguir la máxima legibilidad y facilidad de publicación tanto en su forma de entrada como de salida, inspirándose en muchas convenciones existentes para marcar mensajes de correo electrónico usando texto plano.
Por que es:
Brevemente, los usuarios normales lo encontrarán útil en cualquier caso, especialmente cuando necesitas algo mejor que el texto plano pero menos funcional que MS Word. Para desarrolladores, si tienes pereza de escribir código HTML, amarás Markdown. Más aún, Github y muchos sitios favorecen markdown para archivos README en proyectos. Eso significa que necesitarás Markdown en tu vida de una manera u otra.
Los archivos rmarkdown son texto plano, con extensión .rmd.
El código se ejecuta clickeando en Knit, en el area de programación. El botón está al lado de la lupa. Se hace click en la flechita de opciones (al lado del ícono) se podrá observar que Knit genera reportes en formato html, pdf o word.
Knit ejecuta todos los fragmentos de código y crea un nuevo markdown (.md) que incluye el código y su salida.
El archivo .md es luego procesado por pandoc que es responsable de generar el formato final.
Para crear un nuevo .rmd, en RStudio, lo más facil es File -> New File -> R Markdown....
Los documentos .rmd tienen una estrcutura muy simple: 1. Encabezado 2. Cuerpo: en donde se desarrolla todo el documento. 3. Bibliografía o citas finales. (sección opcional).
Los archivos .rmd deben comenzar con un encabezado que define un conjunto de parámetros del reporte.
Por ejemplo, el siguiente encabezado pertenece al .rmd que genera este html:
---
title: 'Reportes con RMarkdown'
author: "Ignacio Cassol"
date: '2020-06-29'
output:
html_document: # El output será un html.
highlight: textmate # Resalto de sintaxis
keep_md: yes # Compilar a formato .md
number_sections: yes # Que las secciones/subsecciones tengan número
self_contained: false # Usar dependencias almacenadas localmente
theme: flatly # definición del look&feel del output.
toc: yes # Tabla de contenidos
toc_depth: 2 # profundidad de tabla de contenidos
---Aquí encontrarás los posibles valores que pueden tomar los parámetros para el formato de salida HTML.
el comando output: del encabezado admite dos tipos de documentos: documents y presentations. Listamos los formatos disponibles:
Dependiendo del formato, cada parámetro tiene sus propias opciones.
Aquí encontrarás los formatos soportados de salida. La galería ejectua utiliza el comando
render()para generar la salida. Es una opción válida. Nosotros estamos usando la opción de hacer click sobre el botón “Knit”.
Aquí encontrarás una galería de temas (themes) para los outputs.
Te sugerimos explorar el formato de salida
flexdashboard::flex_dashboard, útil para hacer presentaciones que simulan ser una web.
Luego del encabezado, ya estás en condiciones de comenzar a programar el documento. Para esto, tendrás que conocer la sintáxis básica.
Aquí encontrarás una guía de toda la sintaxis básica de R Markdown.
Las secciones se señalan con #:
# Sección 1
## Sección 1.1
### Sección 1.1.1Y se mostrará:
Las secciones pueden tener asociado un id para que se pueda hacer un link de referencia dentro del documento.
Ejemplo:
### Cabecera 1 {#cabecera1 .unnumbered}
[Enlace a Cabecera 1](#cabecera1)* Item 1
* Item 1.1
* Item 2
* Item 3Y se mostrará:
1. Item 1
2. Item 2
3. Item 3Y se mostrará:
El texto en cursiva va decorado de guiones bajos o asteriscos, por ejemplo, _text_ o *texto*. El texto en negrita se programa utilizando un par de asteriscos dobles, por ejemplo, **texto**. Un par de tildes ~ convierte el texto en un subíndice, por ejemplo, H~3~PO~4~ representa H3PO4. Un par de ^ produce un superíndice, por ejemplo, Cu^2+^ produce Cu2+.
Ejemplos:
_text_ -> text
*text* -> text
**text** -> text
***text*** -> text
Las expresiones matemáticas se escriben con la sintaxis del lenguaje latex entre $. Por ejemplo:
$f(k) = {n \choose k} p^{k} (1-p)^{n-k}$ -> \(f(k) = {n \choose k} p^{k} (1-p)^{n-k}\).
Aquí puedes encontrar una cheat sheet con la sintaxis de Latex.
También se pueden definir entornos matemáticos entre $$. Por ejemplo:
$$X = \begin{bmatrix}1 & x_{1}\\
1 & x_{2}\\
1 & x_{3}
\end{bmatrix}$$Y se mostrará:
\[X = \begin{bmatrix}1 & x_{1}\\ 1 & x_{2}\\ 1 & x_{3} \end{bmatrix}\]
Es posible organizar contenidos en pestañas como el siguiente ejemplo:
###Autos {.tabset .unnumbered}
Un Super Telsa!
Falta pintura…
Esto se realiza agregando el atributo {.tabset} a una sección o subsección.
Por ejemplo, el codigo correspondiente a los tabs anteriores es:
##Autos {.tabset .unnumbered}
### Auto Nuevo {- .unnumbered}
### Auto Viejo {- .unnumbered}
## {.unnumbered}Es posible modificar el aspecto y el comportamiento de la sección de pestañas. El atributo .tabset-fade apaga/enciende el bloque seleccionado/deseleccionado. Y el atributo .tabset-pills le da formato de botones a las pestañas.
Por ejemplo:
## Autos {.tabset .tabset-fade .tabset-pills .unnumbered}
### Auto Nuevo {- .unnumbered}
### Auto Viejo {- .unnumbered}
## {.unnumbered}Y se mostrara:
Un Super Telsa!
Falta pintura…
Para marcar el texto como código en programación, usa un par de comillas invertidas, por ejemplo, `código` -> código.
Los hipervínculos se crean utilizando la sintaxis [texto](enlace), por ejemplo, [RStudio](https://www.rstudio.com).
La sintaxis de las imágenes es similar: sólo agrega un signo de exclamación, por ejemplo,.
Las notas al pie se colocan dentro de los corchetes después de ^[], por ejemplo, ^[Esta es una nota al pie.].
Las líneas horizontales se generan con tres caracteres seguidos de -, * o _.
Para los desarrolladores, este servicio es de mucha importancia. En R Markdown se pueden copiar partes de código de muchos lenguajes y setear su ejecución. Los bloques de código deberán estar decoradas con ```{} …código… ```.
Los bloques de código -según el seteo que se realice en el header del bloque- se ejecutan en el momento en que se compila el .rmd.
Hay muchas cosas que puede hacer en un bloque de código: puede producir salida de texto, tablas o gráficos. Tendrás un control preciso sobre todas estas salidas a través de las opciones que se pueden setear dentro de los corchetes. Por ejemplo, puede elegir ocultar la salida de texto a través de la opción results = 'hide', o configurar la altura de una imagen insertada en 4 pulgadas a través de fig.height = 4. Las opciones deben estar separadas por comas, por ejemplo:
```{r, chunk-label, results=‘hide’, fig.height=4}
```
En el ejemplo anterior, el bloque de código recibió el nombre chunk-label.
Hay una gran variedad de opciones de configuración de los bloques de código. Además, combinados, ofrecen muchas más posibilidades. Aquí puedes ver algunas descripciones.
Esas opciones de salida se pueden personalizar indicando parámetros dentro del encabezado del bloque, que está entre {} Destacamos 5 argumentos:
include = FALSE evita que el código y los resultados aparezcan en el archivo finalizado. R Markdown aún ejecuta el código en el fragmento y los resultados pueden ser utilizados por otros fragmentos.echo = FALSE evita que el código, pero no los resultados, aparezcan en el archivo finalizado. Esta es una manera útil de incrustar figuras.message = FALSE evita que los mensajes generados por el código aparezcan en el archivo finalizado.warning = FALSE evita que las advertencias generadas por el código aparezcan en el final.fig.cap = "..." agrega un título a los resultados gráficos.Aquí puede ver qué lenguajes soporta RMarkdown.
En .rmd las tablas se escrbien de esta manera:
| Distribución | Nombre en R | | Distribución | Nombre en R |
|-------------------|-------------|---|---------------|-------------|
| Binomial | binom | | Uniforme | unif |
| Poisson | pois | | Normal | norm |
| Geométrica | geom | | t Student | t |
| Hipergeométrica | hyper | | F Fisher | F |
| Binomial Negativa | nbinom | | Chi-Cuadrado | chisq |
| | | | Exponencial | exp |
| | | | Gamma | gamma |
| | | | Weibull | weibull |
| | | | W de Wilcoxon | wilcox |Y se mostrará:
| Distribución | Nombre en R | Distribución | Nombre en R | |
|---|---|---|---|---|
| Binomial | binom | Uniforme | unif | |
| Poisson | pois | Normal | norm | |
| Geométrica | geom | t Student | t | |
| Hipergeométrica | hyper | F Fisher | F | |
| Binomial Negativa | nbinom | Chi-Cuadrado | chisq | |
| Exponencial | exp | |||
| Gamma | gamma | |||
| Weibull | weibull | |||
| W de Wilcoxon | wilcox |
Hay diferentes páginas web que permiten generar tablas para .rmd:
Markdown Table Generator: pegando tablas de excel o archivos csv, genera el texto para copiar/pegar en RMarkdown.
Tables Generator: permite diseñar tablas con un editor propio y generar código para diferentes lenguajes: Latex, tablas HTML, Rmarkdown entre otras.
kableUna de las maneras más simples de administrar tablas en RMarkdown es con el paquete kable
Por ejemplo:
if (!is.element("kableExtra", installed.packages()[,1])){
install.packages("kableExtra", repos = "http://mirror.fcaglp.unlp.edu.ar/CRAN/")
}
library(kableExtra)##
## Attaching package: 'kableExtra'## The following object is masked from 'package:dplyr':
##
## group_rowsknitr::kable(iris[1:5, ], caption = 'A Caption')| Sepal.Length | Sepal.Width | Petal.Length | Petal.Width | Species |
|---|---|---|---|---|
| 5.1 | 3.5 | 1.4 | 0.2 | setosa |
| 4.9 | 3.0 | 1.4 | 0.2 | setosa |
| 4.7 | 3.2 | 1.3 | 0.2 | setosa |
| 4.6 | 3.1 | 1.5 | 0.2 | setosa |
| 5.0 | 3.6 | 1.4 | 0.2 | setosa |
Aquí encontrarás excelente tutorial para aprovechar todas las potencialidades de kable.
datatableOtra opción, para hacer tablas, es utilizando el paquete DT.
Ejemplo:
if (!is.element("DT", installed.packages()[,1])){
install.packages("DT", repos = "http://mirror.fcaglp.unlp.edu.ar/CRAN/")
}
library(DT)
datatable(mtcars, rownames = FALSE, filter="top", options = list(pageLength = 5, scrollX=T) )Aquí puedes encontrar un tutorial que muestras las potencialidades de DT.
La sintaxis vista hasta ahora es para generar archivos HTML ya que así lo indicamos en la cabecera a través de la instrucción
output:
html_document:
...En esta sección presentaremos muy brevemente otros formatos de salida:
slidyPara conocer esta manera de presentar la salida, abre un nuevo documento RMarkdown, pega y ejecuta el siguiente código:
---
title: "Habits"
author: John Doe
date: March 22, 2005
output: slidy_presentation
---
# In the morning
## Getting up
- Turn off alarm
- Get out of bed
## Breakfast
- Eat eggs
- Drink coffee
# In the evening
## Dinner
- Eat spaghetti
- Drink wine
---
<!-- ```{r, cars, fig.cap="A scatterplot.", echo=FALSE} -->
plot(cars)
<!--```
## Going to sleep
- Get in bed
- Count sheeprevealjsPrimero deberás instalar el paquete:
install.packages("revealjs")
library("revealjs")Una vez instalado el paquete, abre un nuevo documento RMarkdown, pega y ejecuta el siguiente código:
---
title: "Habits"
author: John Doe
date: March 22, 2005
output: revealjs::revealjs_presentation
---
# In the morning
## Getting up
- Turn off alarm
- Get out of bed
## Breakfast
- Eat eggs
- Drink coffee
# In the evening
## Dinner
- Eat spaghetti
- Drink wine
## Going to sleep
- Get in bed
- Count sheepRecomendamos que pruebes el paquete learnr, que tiene una gran potencialidad y facilidad para crear tutoriales interactivos. No es la finalidad de este curso, explicar su funcionamiento pero destacamos que, con learnr es posible:
Aquí puedes encontrar un excelente tutorial de learnr. Te sugerimos ver, este ejemplo.
Luego de finalizar la construcción del reporte, en algunos casos, es necesario mostrarlo online desde una dirección URL. La actividad de subir la página a un servidor se denomina deployment. En esta sección vamos a ver una manera de hacer pública y disponible el output de un documento rmd.
Hay varias maneras de realizar el deployment de un .rmd. Señalamos dos:
Debe tener una cuenta en GitHub y un repositorio para su reporte. Si no lo tiene, cree (la cuenta y/o el repositorio).
En el mismo working directory de su .rmd (y de su espacio actual de trabajo) debe generar un archivo _site.yml. Este archivo contiene especificaciones y definiciones que el Render necesita para construir la web (estática).
El formato del _site.yml es el siguiente:
name: 'Curso-R'
output_dir: '.'
navbar: # Definir un navigation bar
title: "Curso R"
type: inverse
left: # Orientación de las pestañas
- text: "Home" # Titulo de pestaña
href: index.html # Path al archivo de pestaña
- text: "Introducción"
href: Mod1.html
- text: "Lenguaje R"
href: Mod2.html
- text: "Estadística"
href: Mod3.html
- text: "Gráficos"
href: Mod4.html
- text: "Reportes"
href: Mod5.html
- text: "Web"
href: Mod6.html
- text: "Regresión"
href: Mod7.html
output: # Output gobal
html_document: # Variables globales
self_contianed: true
theme: flatly
highlight: textmatermarkdown::render_site()Luego de este paso, su página web estará lista para el deployment, en su working directory.
Github Pages es una platforma que facilita el desarrollo e hosting de Páginas Web Estáticas.
Crear una branch gh-pages en su repositorio. A este branch subir: los .Rmd, _site.yml, y los archivos generado por el render (del paso 3).
Activar el servicio Github Pages: Settings -> Options.
Seleccionar la branch gh-pages.
La página podrá ser accedida por:
https://{Tu-Usuario}.github.io/{Nombre-de-Repository}/