Anexo E R Markdown

Actualmente existe una herramienta más avanzada que R Markdown: Quarto, la cual se presenta en el Anexo F. El presente anexo se mantiene únicamente como referencia para quienes ya vengan trabajando en R Markdown y no deseen realizar la migración. No obstante, a quienes tengan su primer acercamiento a estas herramientas, se les recomienda omitir el presente anexo y pasar directamente al Anexo F.

R Markdown es un entorno de trabajo que facilita construir un documento que reúne las salidas, tanto gráficas como de texto, junto con el código que las genera. Este entorno se basa en el lenguaje Markdown y está implementado a través del paquete rmarkdown, resultando particularmente eficiente cuando se usa dentro de RStudio.

El proceso involucra dos archivos: un archivo fuente y el documento de salida para la lectura. Los formatos más populares para documentos de salida son html, pdf y Word. Por su parte, el documento fuente de R Markdown es un archivo de texto plano con extensión Rmd, lo que lo hace identificable y procesable por RStudio. Los documentos fuente de R Markdown (.Rmd) son los equivalentes de los scripts clásicos de R. El proceso comienza con el documento R Markdown, a partir del cual se genera el documento de salida.

E.1 Documento R Markdown

Un documento de R Markdown puede incluir tres tipos de contenidos:

Un encabezado de metadatos en formato YAML
Fragmentos de código (code chunks)
Texto

El encabezado de metadatos en formato YAML (YAML Ain’t Markup Language) aparece al principio del documento de R Markdown. Aunque es optativo, bajo ciertas circunstancias se genera automáticamente durante el proceso de renderización que da lugar al archivo de salida. Tanto el inicio como la finalización del encabezado YAML están definidos por tres guiones aislados en una línea. La información contenida dentro de esas dos líneas constituye el encabezado de metadatos YAML. Allí suele incluirse título, autor, fecha y formato de salida.

---
title:  "VARIABLES FISIOLÓGICAS"
author: "Pepito Pérez"
date:   "2022-08-05"
output: pdf_document
---

Mediante la instrucción output, se indica el formato del documento de salida, así:

output: html_document
output: word_document 
output: pdf_document

La salida por defecto es en formato html, por lo que no haría falta especificarla si este fuera el formato deseado.

El documento R Markdown puede incluir tantos fragmentos de código como se requieran. Cada fragmento de código debe iniciarse con tres comillas invertidas seguidas de la letra r dentro de llaves. El fragmento finaliza con tres comillas invertidas aisladas en una línea. Todas las instrucciones incorporadas entre la línea de inicio y la de finalización constituyen un fragmento de código (code chunk) y, a no ser que alguna línea esté antecedida por el símbolo numeral (#), se trata de código que es ejecutado por R. Los fragmentos de código tienen exactamente las mismas características que el código de los scripts clásicos de R.

```{r}  
# Aquí va código
5 + 3
```

Para facilitar la creación de un nuevo fragmento de código, puede usarse la combinación de teclas Ctrl + Alt + i (o el ícono Insert a new code chunk , seguido del ícono de R), con lo cual se incluye un fragmento de código vacío en el documento.

```{r}

```

Cada fragmento de código puede incluir de manera opcional un nombre o identificador, el cual puede constar de una o más palabras, sin que sea necesario entrecomillarlas. En caso de incluir nombres, estos deben ser únicos.

Dos o más fragmentos de código no pueden tener el mismo nombre.

```{r resumen}
# código
```

Aunque nombrar los fragmentos de código pueda resultar un tanto más dispendioso que dejarlos sin nombre, tales nombres pueden facilitar la navegación en documentos con muchos fragmentos de código. Cuando se omite el nombre de los fragmentos de código, estos aparecen con un identificador genérico: chunk 5, chunk 6, chunk 7…

Para acceder al panel de navegación, se hace clic en el ícono que aparece la parte inferior izquierda de la ventana que contiene el documento R Markdown.

Es posible incluir comentarios dentro de los fragmentos de código, mediante el uso del símbolo numeral (#). Al igual que en los scripts clásicos, tales comentarios se usarían como guía dentro del correspondiente fragmento o para desactivar temporalmente alguna instrucción sin borrarla. No obstante, para comentar sobre algún procedimiento o resultado particular, con la intención de que tales comentarios aparezcan luego en el documento de salida, se usa el componente texto.

El texto es el tercer tipo de contenido de los documentos R Markdown. Cualquier contenido que no forme parte del encabezado YAML, ni esté dentro de un fragmento de código se toma como texto y aparecerá como tal en el documento de salida.

Mediante códigos de marcas es posible asignar formatos particulares al texto, los cuales se verán reflejados en los archivos de salida.

Existen 6 niveles de títulos, que se indican anteponiendo el correspondiente número de símbolos numeral (#) a la línea. En general, el nivel 1 es el título de mayor rango, mientras que el de nivel 6 es el título de menor rango; no obstante, la apariencia final de los títulos de cada nivel, en términos de color, tipo de letra, tamaño, negrilla, cursiva, etc., dependerá del tipo de documento de salida que se genere (Word³², pdf, html).

# TÍTULOS DE NIVEL 1
## TÍTULOS DE NIVEL 2
### TÍTULOS DE NIVEL 3
#### TÍTULOS DE NIVEL 4
##### TÍTULOS DE NIVEL 5
###### TÍTULOS DE NIVEL 6

Para que los títulos sean reconocidos como tal, es necesario dejar al menos un espacio entre los símbolos numeral y el texto.

Nótese que el símbolo # desemepeña un rol diferente dependiendo de si se encuentra ubicado dentro de un fragmento de código o si forma parte del texto. Dentro de los fragmentos de código se usa al principio de una línea para indicar que se trata de un comentario (o de código que no se ejecuta). Cuando aparece al inicio de una línea de texto actúa como marcador de título.

El texto que no lleve antepuesto ningún símbolo numeral se maneja como texto ordinario.

Mediante etiquetas, puede indicarse que cualquier texto sea formateado en itálica, negrilla o una combinación de ambas. También puede formatearse un texto como tachado.

*itálica* (también: _itálica_)
**negrilla** (también: __negrilla__)
***negrilla e itálica*** (también: ___negrilla e itálica___)
~~tachado~~

Igualmente, usando etiquetas, puede indicarse el formato de subíndice o superíndice.

~subíndice~
^superíndice^

Así, cuando se escribe lo siguiente en el documento fuente de R Mardown,

Y = c~1~X + c~2~X^2^ + c~3~X^3^

aparece así en el documento final:

Y = c₁X + c₂X² + c₃X³

También es posible incluir comentarios en el texto, es decir, fragmentos de texto que se mostrarán en el documento fuente de R Markdown, pero que no el documento final (Word, pdf, html…). Los símbolos .

<!-- Comentario que no aparecerá en el documento final -->

Es importante anotar que, como parte del contenido tipo texto, R Markdown también admite contenidos alimentados mediante código LaTeX, a través de los cuales es posible incluir ecuaciones, tablas y figuras. Los contenidos admitidos y la calidad en la que estos se presentan dependen del formato del documento de salida, siendo los documentos pdf los que mejor manejan los contenidos basados en LaTeX.

Para generar archivos pdf es necesario tener instalado un procesador de LaTeX. Para la mayoría de usos basta con instalar el paquete tinytex (tinytex::install_tinytex()). Si esto fuera insuficiente, habría que instalar una distribución completa de LaTeX, tal como MiKTeX (https://miktex.org/download). Este último es un software externo; no un paquete para R.

Existen dos modos de inclusión de ecuaciones usando código LaTeX: dentro de la línea (inline equation) y en línea aparte (display equation).

Para escribir una ecuación dentro de una línea, basta con rodearla con símbolos dólar.

La varianza poblacional $\sigma^2$ se estima…

El texto final mostrará lo siguiente:

La varianza poblacional $\sigma^2$ se estima…

Igualmente, puede iniciarse con los símbolos $ y cerrarse con los símbolos $.

La varianza poblacional $\sigma^2$ se estima…

Para escribir una ecuación en línea aparte (display equation) usando código LaTeX, basta con rodearla de doble símbolo dólar o abrir con \[ y cerrar con \].

El estimador mínimo cuadrático de la varianza es:

$$
S^2=\frac{\sum\limits_{i=1}^{n}{(X_i-\bar{X})^2}}{n-1}
$$

O así:

El estimador de máxima verosimilitud de la varianza es:

\[
\widehat{\sigma^2}=\frac{\sum\limits_{i=1}^{n}{(X_i-\bar{X})^2}}{n}
\]

En el documento final aparece así:

El estimador mínimo cuadrático de la varianza es:

\[ S^2=\frac{\sum\limits_{i=1}^{n}{(X_i-\bar{X})^2}}{n-1} \]

En el documento de R Markdown, tras el encabezado de metadatos YAML opcional que aparece al comienzo del documento, pueden alternarse todos los fragmentos de código y texto que se desee, sin restricción alguna ni en número ni en orden.

Un documento de R Markdown podría tener el siguiente aspecto:

---  
title: "Ensayo primer semestre"  
---

### Lectura de datos

Se incluyen únicamente los registros del primer semestre    
<!-- Aún no se ha terminado la cosecha del segundo semestre -->

```{r importación}
library(readxl)
data <- read_excel("etapas.xlsx")
```

## Fotosíntesis

```{r FOTO}  
anova <- aov(foto ~ etp, data)
shapiro.test(resid(anova))
```

Puesto que no se satisface normalidad (p-value = 0.001977),
se evalúan diferentes transformaciones

En este documento R Markdown, la primera sección es el encabezado de metadatos YAML, la cual, para el presente caso, contiene únicamente el título. A continuación se intercalan secciones de texto, código, texto, código y texto.

Este intercalamiento de código y texto es la razón de ser de los fragmentos de código. El texto puede usarse, bien sea a manera de título o como texto ordinario, para anunciar algún análisis particular, el cual se realiza a continuación mediante un fragmento de código. Luego del fragmento de código, puede incluirse texto adicional para comentar sobre los resultados obtenidos y quizá para justificar los análisis posteriores.

Cada uno de los fragmentos de código puede ejecutarse individualmente. De hecho, esta es la práctica recomendada al analizar información e ir construyendo el reporte, a fin de comentar los resultados (mediante texto) a medida que estos se generan e ir adaptando los análisis en función de los resultados obtenidos.

Un fragmento de código puede ejecutarse en su totalidad o línea por línea. Al igual que en los scripts clásicos, la combinación de teclas Ctrl + Enter permite ejecutar una instrucción o el conjunto de instrucciones seleccionadas. Mediante la combinación de teclas Ctrl + Shift + Enter, se ejecuta todo el fragmento de código, acción que igualmente puede realizarse presionando el triángulo verde que se ubica en la parte superior derecha de cada fragmento de código ( Run Current Chunk).

Durante la construcción del documento R Markdown es usual que los fragmentos de código se ejecuten de manera secuencial, lo que da lugar a un proceso fluido, siempre que el código se haya escrito adecuadamente. Debe tenerse presente, sin embargo, que toda nueva sesión de R Markdown inicia con un ambiente de trabajo vacío, en el que no se habrá creado ningún objeto. Luego, cuando, partiendo de una nueva sesión de trabajo, se revisa algún fragmento de código particular, podría ser que este dependiera de fragmentos anteriores, en los que, por ejemplo, se hubieran importado o cargado los datos, definido nuevas variables, ajustado modelos, etc. Para garantizar la correcta ejecución del fragmento de interés, podrían ubicarse y ejecutarse aquellos fragmentos previos de los cuáles dependa el fragmento de interés. Otra posibilidad, que en la mayoría de los casos puede ser más expedita, consiste en ejecutar el fragmento de interés junto con todos los fragmentos previos, en orden de aparición. Para ello se usa el ícono conformado por un triángulo gris sobre una barra horizontal verde, el cual está ubicado en la parte superior derecha de cada fragmento: Run All Chunks Above.

Las salidas que se generen con la ejecución de un fragmento de código se muestran a continuación del correspondiente fragmento, bien sean salidas gráficas o de texto. Esto facilita la estructuración del informe final, mediante la incorporación de los comentarios que sean del caso.

También es posible combinar texto y código, mediante el denominado código en línea (inline code), el cual consiste en una expresión de código R inmersa dentro de un texto.

El código en línea inicia con una comilla invertida y la letra r (`r) y finaliza con una comilla invertida (`):

`r código en línea`

El código en línea resulta útil para concatenar texto fijo con algún resultado variable, al estilo de las salidas generadas por la función cat (cf. capítulo 15).

Considérese la siguiente adaptación de una parte del documento presentada anteriormente, en la que se guarda el resultado de la prueba Shapiro-Wilk en un objeto (sw), para extraer posteriormente el valor p:

```{r FOTO}  
anova <- aov(foto ~ etp, data)  
sw <- shapiro.test(resid(anova))  
```

Puesto que no se satisface normalidad (p-value = `r sw[2]`), se evalúan diferentes transformaciones.

En ocasiones se desea insertar código no ejecutable dentro del texto, es decir, un fragmento que tenga el mismo formato del código, de manera que resalte dentro del texto normal, pero que no se ejecute. Para tal efecto, basta con encerrar el fragmento en cuestión entre comillas invertidas. Así, por ejemplo, en el documento fuente de R Markdown se escribiría lo siguiente:

El supuesto de normalidad se evalúa así: `shapiro.test(resid(anova))`.

En el documento de salida se verá similar a lo siguiente:

El supuesto de normalidad se evalúa así: shapiro.test(resid(anova)).

El formato particular en el que se muestre este código no ejecutable dependerá del tipo de documento de salida.

Para insertar un bloque no ejecutable en línea(s) aparte, se inicia el bloque con una línea de tres comillas invertidas y se finaliza con otra línea de tres comillas invertidas. El bloque puede constar de una o más líneas.

```
anova <- aov(foto ~ etp, data)
sw <- shapiro.test(resid(anova))
```

Las dos líneas del bloque anterior se mostrarán tal cual en el documento de salida, en el formato propio del código, pero sin generar ninguna acción ni resultado.

Lo mismo puede lograrse, sin necesidad de las dos líneas con comillas invertidas, usando una indentación de 4 espacios para cada línea.

Creación de un nuevo documento R Markdown

Existen varias formas de crear un nuevo documento de R Markdown. Mediante el sistema de menús, se elige “File”, “New File”, “R Markdown…”. Equivalentemente, puede usarse el ícono , seguido del ícono . En cualquier caso, estos pasos llevan a una caja de diálogo, en la que se deja marcada la opción Document (que viene por defecto), y puede personalizarse la información contenida en los campos título, autor y fecha, así como el tipo de documento de salida. Esta es la información que irá en el encabezado de metadatos YAML.

Los nuevos documentos de R Markdown contienen información que pretende servir de plantilla. Al comienzo incluyen un encabezado de metadatos YAML, el cual puede editarse o eliminarse. Seguidamente traen una combinación de textos y fragmentos de código, que hacen las veces de un minitutorial para ilustrar diferentes posibilidades.

Opciones de los fragmentos de código que determinan las salidas

Los elementos que se visualicen u oculten en el documento de salida se controlan mediante los argumentos lógicos include y echo en los fragmentos de código. El argumento echo controla la visualización de los fragmentos de código, mientras que el argumento include controla la visualización tanto del código como de los resultados generados. Por defecto, ambos argumentos vienen preestablecidos con valor TRUE, lo que significa que en el documento de salida se muestran tanto el código como los correspondientes resultados.

La visualización que se elija para el documento de salida dependerá de los objetivos y el estado del reporte. Si el objetivo del reporte es compartir el análisis con otros usuarios, mostrando no solo los resultados, sino también la manera en que se generaron, deberá incluirse el código. Esto posibilita que todos los usuarios revisen los procedimientos con detalle e indiquen las modificaciones que sean del caso. Desde luego, si hubiera lugar a modificaciones, estas no se aplicarían sobre el documento de salida, sino sobre el documento R Markdown.

En una etapa final, en la que ya se hayan depurado todos los procedimientos, podrá eliminarse la visualización del código, manteniendo únicamente los resultados y el texto.

Los argumentos que afectan un fragmento de código se incluyen a continuación de la letra r (o del nombre del fragmento si lo hubiera), separados por coma (,). Así, por ejemplo, para evitar que el fragmento de código FOTO que se presentó anteriormente aparezca en el documento de salida, manteniendo, sin embargo, sus resultados, se incluiría el argumento echo = FALSE, así:

```{r FOTO, echo = F}
anova <- aov(foto ~ etp, data)  
shapiro.test(resid(anova))  
```

Cuando el documento R Markdown incluye muchos fragmentos de código, el paso desde las versiones iniciales en las que se desea visualizar el código, hacia la versión final, en la que se omite la visualización de todo el código, podría resultar muy dispendioso, por cuanto exigiría incluir el argumento echo = F en cada uno de los fragmentos de código. No obstante, esto puede realizarse eficientemente, incluyendo este argumento de manera global, con lo cual afecta a todos los fragmentos de código, a no ser que en alguno particular se especifique lo contrario. Para ello basta con modificar el fragmento de código setup, que se incluye a continuación del encabezado YAML en los nuevos documentos de R Markdown, cambiando echo = TRUE por echo = FALSE, así:

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = F)
```

E.2 Documento de salida

Una vez depurado el documento fuente R Markdown, se procede a generar el documento de salida, en cualquiera de los formatos html, pdf o Word. Para ello basta con presionar la combinación de teclas Ctrl + Shift+ k, o el ícono de la funcionalidad Knit (tejer) , con lo cual se generará un documento acorde con la opción indicada en el parámetro output del encabezado YAML. Asimismo, podría elegirse un formato diferente al especificado en el encabezado YAML, bastando con presionar el triángulo que se ubica en la parte derecha del ícono y elegir el formato deseado. R Markdown realiza el cambio necesario en el encabezado YAML antes de generar el documento de salida.

La manera en la que se visualizan los diferentes elementos (fragmentos de código, texto, resultados) en el documento de salida puede variar en función del tipo de documento (html, pdf o Word). No obstante, en general, el código aparece dentro de una caja, con fondo gris. Cada una de las líneas de los resultados de texto aparece antecedida de uno o dos símbolos numeral: así ## o así #>. El texto aparece como tal, incluyendo las especificaciones de formato que se hubieran elegido para el mismo.

Cada uno de los principales formatos de salida tiene sus ventajas y especificidades:

E.2.1 Documentos html

El formato html es el más ventajoso para el lector final, por las posibilidades que le ofrece; muy particularmente, cuando se aplica a contenidos de gran extensión —como el de este libro— que estén divididos en capítulos y secciones:

Pueden visualizarse en cualquier navegador de internet.
Los paneles de navegación facilitan moverse fluidamente a través de los diferentes temas.
El contenido se adapta al tamaño del dispositivo de lectura, resultando cómodo incluso desde un teléfono móvil. Dependiendo del espacio disponible, los paneles de navegación se muestran o se ocultan. Cuando la lectura se realiza desde un teléfono móvil, el contenido y los paneles de navegación se adaptan al giro de la pantalla.
Todos los vínculos externos son funcionales, dirigiendo a los recursos citados: páginas, instaladores, libros en línea…
Todos los vínculos internos también son funcionales, facilitando ir rápidamente a alguna otra sección o recurso (tablas, figuras o ecuaciones) dentro del mismo libro y regresar al sitio de origen.
Puesto que no hay cortes de página, las figuras y tablas pueden incluirse justo después de citarlas.
Igualmente, por no haber cortes de página, las tablas se muestra completas y los bloques de código se muestran de manera compacta.
Al no haber páginas físicas, las denominadas ‘notas de pie de página’ ya no aparecen al ‘pie de la página’. Dependiendo del estilo html que se elija, pueden aparecer al final de la sección³³ o ‘in situ’, como en el presente libro³⁴.
Cuando se trate de un libro que incluya código R (no es obligatorio que sea así), es fácil copiarlo y llevarlo a R para realizar la correspondiente verificación y/o adaptación.
Pueden disponerse vínculos o botones para bajar material complementario: bases de datos, scripts, paquetes, figuras…
Cuando el libro se encuentra en algún repositorio, v. gr. bookdown.org, es probable que su autor realice constantes actualizaciones, con lo cual los lectores tendrán la certeza de estar accediendo siempre a la versión más reciente.

E.2.2 Documentos pdf

Son los más adecuados cuando su destino final es un soporte físico. Este formato considera las restricciones que impone la impresión en páginas de un tamaño definido, dando lugar a resultados bastante estéticos. Internamente, el proceso de generación del documento pdf se da a partir de un documento intermedio LaTeX.

E.2.3 Documentos Word

Tienen la ventaja de su versatilidad para edición e incorporación en otros documentos. Es el formato ideal para compartir con otros usuarios, facilitándoles el proceso de incluir correcciones y comentarios, sin que tengan que entenderse con ninguna herramienta ‘esotérica’.

Para conocer más sobre las posibilidades de R Markdown, se invita a estudiar el libro en línea R Markdown: The Definitive Guide, escrito por Xie et al. (2018). Luego puede continuarse con el libro R Markdown Cookbook, escrito por Xie et al. (2022) y también disponible en línea.

Para construir un documento más estructurado, que incluya capítulos y/o secciones, tal como un artículo, una tesis o un libro, se invita a estudiar el paquete bookdown, que amplía las posibilidades de R Markdown, permitiendo, por ejemplo, un mejor manejo de ecuaciones, teoremas, figuras y tablas, en cuanto a referenciación interna. Un buen punto de partida es el libro bookdown: authoring books and technical documents with R Markdown, escrito por Xie (2023), y que igualmente cuenta con una versión en línea.

El presente libro fue escrito con base en la herramienta bookdown, usando el formato three-column bootstrap style o bs4.

D Formateo de data frames

F Quarto