R para Ciencia de Datos de Salud

Capítulo 12 Cuadernos y Markdown

Me preguntas si llevo un cuaderno para anotar mis grandes ideas. Solo he tenido uno.
Albert Einstein

12.1 ¿Qué es un cuaderno (Notebook) ?

R es todopoderoso para la manipulación, visualización y análisis de datos. Lo que a menudo se subestima es la flexibilidad con la que se pueden exportar o informar los análisis.

Por ejemplo, se puede escribir fácilmente un artículo científico completo, un informe de la industria o una actualización mensual para acomodar un conjunto de datos subyacente variable, y todas las tablas y gráficos se actualizarán automáticamente.

Esta idea se puede extender a un flujo de trabajo en el que todos los análisis se realizan principalmente dentro de un documento que funciona como el informe final.

¡Ingrese a “Cuadernos de datos”! Los cuadernos son documentos que combinan código y elementos de texto enriquecido, como encabezados, párrafos y enlaces, en un solo documento. Combinan análisis e informes en un documento legible por humanos para proporcionar una interfaz intuitiva entre el investigador y su análisis (Figura 12.1 ). Esto a veces se denomina “programación alfabetizada”, dado que la estructura lógica resultante de la información se puede leer fácilmente de la misma manera que un humano leería un libro.

FIGURA 12.1: Programación tradicional versus alfabetizada usando Notebooks.

En nuestro propio trabajo, ahora hemos pasado a realizar la mayoría de nuestros análisis en un archivo de Notebook, en lugar de usar un archivo de “script”. Puede que no lo hayas adivinado, pero todo este libro está escrito de esta manera.

Algunas de las ventajas de la interfaz de Notebook son:

• el código y la salida son adyacentes entre sí, por lo que no está cambiando constantemente entre “paneles”;
• más fácil de trabajar en una pantalla más pequeña, por ejemplo, una computadora portátil;
• la documentación y los informes se pueden realizar junto con el código, los elementos de texto se pueden formatear por completo;
• el código en sí se puede mostrar u ocultar;
• el código no se limita a R; puede usar Python, SQL, etc.;
• facilitar la colaboración compartiendo fácilmente documentos de análisis legibles por humanos;
• se puede generar en varios formatos, incluidos HTML (página web), PDF y Microsoft Word;
• la salida se puede extender a otros formatos como presentaciones;
• la capacitación/aprendizaje puede ser más fácil ya que los materiales del curso, los ejemplos y las notas de los estudiantes están todos en el mismo documento.

12.2 ¿Qué es Markdown?

Markdown es un lenguaje ligero que se puede utilizar para escribir documentos con formato completo. Es texto sin formato y utiliza un conjunto simple de reglas para producir resultados bastante sofisticados. ¡Nos encanta!

Es fácil formatear encabezados, texto en negrita, cursiva, etc. Dentro de RStudio hay una guía de referencia rápida (Figura 12.2 ) y se pueden encontrar enlaces a las hojas de trucos de RStudio en el menú desplegable Ayuda.

FIGURA 12.2: Guía de referencia rápida de RStudio Markdown.

Markdown existe independientemente de R y es utilizado por una variedad de técnicos y similares. Una combinación de Markdown (que es texto con caracteres especiales para indicar el formato deseado) y el código R que contiene (generalmente para producir tablas y gráficos) se denomina R Markdown. Los scripts R tienen la extensión de archivo .R,los documentos Markdown tienen una extensión de archivo .md, por lo tanto, los documentos R Markdown son.Rmd.

12.3 ¿Cuál es la diferencia entre un Notebook y un archivo R Markdown?

La mayoría de la gente usa los términos R Notebook y R Markdown indistintamente y eso está bien. Técnicamente, R Markdown es un archivo, mientras que R Notebook es una forma de trabajar con archivos R Markdown. Los cuadernos R no tienen su propio formato de archivo, todos usan .Rmd. Todos los cuadernos de R se pueden ‘tejer’ a las salidas de R Markdown, y todos los documentos de R Markdown se pueden interconectar como un cuaderno.

Una diferencia importante está en la ejecución del código. En R Markdown, cuando el archivo es Knit, también se ejecutan todos los elementos (fragmentos). Knit es para R Markdown lo que Source es para un script R (Source se presentó en el Capítulo 1, esencialmente significa ‘Ejecutar todas las líneas’).

En un Notebook, cuando el archivo se procesa con el Preview botón, no se vuelve a ejecutar ningún código, solo se incluye en la salida el que ya se ha ejecutado y está presente en el documento. Además, en el archivo detrás de escena de Notebook ( .nb), siempre se incluye todo el código. Algo a tener en cuenta si su código contiene información confidencial, como una contraseña (¡que nunca debería!).

12.4 Cuaderno vs HTML vs PDF vs Word

En RStudio, se puede crear un Notebook yendo a: Archivo -> Nuevo archivo -> R Notebook

Alternativamente, puede crear un archivo Markdown usando: Archivo -> Nuevo archivo -> R Markdown…

No te preocupes cuál eliges. Como se mencionó anteriormente, son esencialmente lo mismo pero vienen con diferentes opciones. Es fácil cambiar de un Notebook a un archivo Markdown si desea crear un documento PDF o Word, por ejemplo.

Si realiza análisis principalmente en el entorno de Notebook, elija Notebook. Si está creando principalmente un documento PDF o Word, elija el archivo R Markdown.

12.5 La anatomía de un archivo Notebook / R Markdown

Cuando crea un archivo, se proporciona una plantilla útil para que pueda comenzar. La figura 12.3 muestra los elementos esenciales de un archivo de Notebook y cómo se traducen en la HTML vista previa.

12.5.1 Encabezado YAML

Cada archivo de Notebook y Markdown requiere un “encabezado YAML”. ¿De dónde obtienen estos términos que pides? Originalmente, se decía que YAML significaba otro lenguaje de marcas, haciendo referencia a su propósito como lenguaje de marcas. Más tarde se reutilizó como YAML Ain’t Markup Language, un acrónimo recursivo, para distinguir su propósito como orientado a datos en lugar de marcado de documentos (gracias Wikipedia).

Aquí es simplemente donde se colocan muchas de las configuraciones/opciones para la creación de archivos. En RStudio, estos a menudo se actualizan automáticamente a medida que se invocan diferentes configuraciones en el menú Opciones.

12.5.2 Fragmentos de código R

El código R dentro de un archivo Notebook o Markdown se puede incluir de dos maneras:

• en línea: por ejemplo, el número total de naranjas fue `r sum(fruit$oranges)`;
• como un “chunk (trozo)”.

Los fragmentos R son flexibles, vienen con muchas opciones y pronto aprenderá a usarlos.

La figura 12.3 muestra cómo encaja un trozo en el documento.

# Esta es una parte básica.
# Siempre comienza con ```{r}
# Y termina con ```
# El código va aquí
sum(fruit$oranges)

Esto puede parecer desagradable, pero sigue adelante por ahora. Puede escribir los cuatro acentos graves manualmente o usar el Insert botón y elegir R. También notará que los fragmentos no se limitan al código R. Es particularmente útil que Python también se pueda ejecutar de esta manera.

Al realizar un análisis en un cuaderno, casi siempre querrá ver el código y el resultado. Cuando esté creando un documento final, es posible que desee ocultar el código. El comportamiento de los fragmentos se puede controlar a través Chunk Cogdela parte derecha del fragmento (Figura 12.3 ).

La tabla 12.1 muestra las diversas permutaciones de código y opciones de salida que están disponibles. El código se coloca en el encabezado del fragmento, pero las opciones emergentes ahora lo hacen automáticamente, por ejemplo,

12.5.3 Configuración de opciones de fragmentos predeterminados

Podemos establecer opciones predeterminadas para todos nuestros fragmentos en la parte superior de nuestro documento agregando y editando knitr::opts_chunk$set(echo = TRUE) en la parte superior del documento.

knitr::opts_chunk$set(echo = TRUE,
                      warning = FALSE)

12.5.4 Configuración de opciones de figuras predeterminadas

Es posible establecer diferentes tamaños predeterminados para diferentes tipos de salida incluyéndolos en el encabezado YAML (o usando el engranaje del documento):

---
title: "R Notebook"
output: 
  pdf_document: 
    fig_height: 3
    fig_width: 4
  html_document: 
    fig_height: 6
    fig_width: 9
---

El encabezado YAML es muy sensible a los espacios/tabulaciones, así que asegúrese de que sean correctos.

12.5.5 Elementos de Markdown

El texto de Markdown se puede incluir como desee alrededor de sus fragmentos. La Figura 12.3 muestra un ejemplo de cómo se puede hacer esto. Esta es una excelente manera de adquirir el hábito de documentar explícitamente su análisis. Cuando regresa a un archivo dentro de 6 meses, todo su pensamiento está ahí frente a usted, en lugar de tener que averiguar qué diablos estaba haciendo a partir de una colección de código aleatorio.

12.6 Interfaz y salida

12.6.1 Ejecución de codigo ,chunks y knitting

La figura 12.4 muestra los diversos controles para ejecutar fragmentos y producir un documento de salida. El código se puede ejecutar línea por línea usando Ctrl+Enter como está acostumbrado. Hay opciones para ejecutar todos los fragmentos por encima del fragmento actual en el que está trabajando. Esto es útil ya que un fragmento en el que está trabajando a menudo se basará en objetos creados en fragmentos anteriores.

FIGURA 12.4: Opciones de fragmentos y documentos en archivos de Notebook/Markdown.

Es una buena práctica usar la Restart R and Run All Chunks opción en el Run menú cada cierto tiempo. Esto garantiza que todo el código en su documento sea autónomo y no dependa de un objeto en el entorno que haya creado en otro lugar. Si este fuera el caso, fallará al renderizar un documento Markdown.

Probablemente el motor más importante detrás de la funcionalidad RStudio Notebooks es el paquete knitr de Yihui Xie.

No tejer como lo hace tu abuela, sino convertir un documento de Markdown en un archivo de salida, como HTML, PDF o Word. Hay muchas opciones que se pueden aplicar para lograr el resultado deseado. Algunos de estos se han codificado específicamente en RStudio (Figura 12.4 ).

La creación de documentos PDF requiere LaTeX que se instale una distribución en su computadora. Dependiendo del sistema que esté utilizando, es posible que esto ya esté configurado. Una manera fácil de hacer esto es usando el paquete tinytex .

install.packages("tinytex")
# Restart R, then run
tinytex::install_tinytex()

En el próximo capítulo nos centraremos en los detalles de la producción de un documento final pulido.

12.7 Estructura de archivos y flujo de trabajo

A medida que los proyectos crecen, es importante que estén bien organizados. Esto evitará errores y facilitará la colaboración.

Lo que es absolutamente obligatorio es que su análisis debe residir dentro de un Proyecto RStudio y tener un nombre significativo (¡no MiProyecto! o Análisis1). La creación de un nuevo proyecto en RStudio creará automáticamente una nueva carpeta para sí mismo (a menos que elija “Carpeta existente”). Nunca trabaje dentro de un directorio Inicio o Documentos genérico. Además, no cambie el directorio de trabajo usando setwd(): no hay razón para hacerlo y, por lo general, hace que su análisis sea menos reproducible. Una vez que empiece a familiarizarse con R, debe iniciar todos los proyectos con un repositorio Git para el control de versiones (consulte el Capítulo 13 ).

Para proyectos más pequeños con 1-2 archivos de datos, un par de scripts y un documento R Markdown, está bien mantenerlos todos en la carpeta Proyecto (pero repetimos, cada Proyecto debe tener su propia carpeta). Una vez que la cantidad de archivos crezca más allá de eso, debe agregar carpetas separadas para diferentes tipos de archivos.

Aquí está nuestro enfoque sugerido. Según la naturaleza de sus análisis, la cantidad de carpetas puede ser menor o mayor que esto, y pueden tener un nombre diferente

proj/
- scripts/
- data_raw/
- data_processed/
- figures/
- 00_analysis.Rmd

scripts/ contiene todos los .R archivos de script utilizados para la limpieza/preparación de datos. Si solo tiene algunos scripts, está bien no tener este y simplemente mantener los .R archivos en la carpeta del proyecto (donde 00_analysis .Rmd está en el ejemplo anterior). data_raw /contiene todos los datos sin procesar, como .csv archivos, data_processed/contiene datos que ha tomado sin procesar, limpiados, modificados, unidos o cambiados de otro modo mediante scripts R. figures/puede contener gráficos (p. ej., .png, .jpg, .pdf) 00_analysis.Rmd o 00_analysis.R es el archivo de trabajo principal real, y lo mantenemos en el directorio principal del proyecto.

Sus scripts R deben numerarse con dos dígitos y deben tener nombres significativos, por ejemplo:

scripts/00_source_all.R
scripts/01_read_data.R
scripts/02_make_factors.R
scripts/03_duplicate_records.R

Por ejemplo, 01_read_data.R puede verse así.

# Proyecto de melanoma
## extracción de datos
# Obtener datos
library(readr)
melanoma <- read_csv(
  here::here("data_raw", "melanoma.csv")
)

# Other basic reccoding or renaming functions here

# Save
save(melanoma, file = 
  here::here("data_processed", "melanoma_working.rda")
)

Tenga en cuenta el uso de here::here(). Los proyectos de RStudio administran los directorios de trabajo de una mejor manera que setwd(). here::here() es útil cuando se comparten proyectos entre máquinas Linux, Mac y Windows, que tienen diferentes convenciones para las rutas de los archivos.

Por ejemplo, en una Mac lo haría de otra manera read_csv("data/melanoma.csv")y en Windows tendría que hacer read_csv("data\melanoma.csv"). Tener que incluir /(GNU/Linux, macOS) o \ (Windows) en su secuencia de comandos significa que tendrá que cambiarse a mano cuando se ejecute en un sistema diferente. Lo que here::here("data_raw", "melanoma.csv"), sin embargo, funciona en cualquier sistema, ya que utilizará uno apropiado ‘detrás de escena’ sin que tengas que cambiar nada.

02_make_factors.Res nuestro segundo archivo de ejemplo, pero podría ser cualquier cosa que desee. Podría verse algo como esto.

# Proyecto Melanoma 
## Creando factores
library(tidyverse)
load(
  here::here("data_processed", "melanoma_working.rda")
)
## Recode variables
melanoma <- melanoma %>%
  mutate(
    sex = factor(sex) %>% 
      fct_recode("Male" = "1", 
                 "Female" = "0")
  )
# Salvar
save(melanoma, file = 
  here::here("data", "melanoma_working.rda")
)

Todos estos archivos se pueden reunir en un solo archivo en formato source(). Esta función se utiliza para ejecutar código desde un archivo.

00_source_all.R podría verse así:

# Melanoma project
## Source all
source( here::here("scripts", "01_data_upload.R") )
source( here::here("scripts", "02_make_factors.R") ) 
source( here::here("scripts", "03_duplicate_records.R") ) 
# Save
save(melanoma, file = 
  here::here("data_processed", "melanoma_final.rda")
)

Ahora puede traer sus datos sólidamente preparados a su archivo de análisis, que puede ser .R o .Rmd si está trabajando en un cuaderno. Llamamos a esto 00_analysis.Rmd y siempre se encuentra en el directorio raíz del proyecto. Tiene dos opciones para traer los datos.

1.source("00_source_all.R")para volver a cargar y procesar los datos de nuevo + esto es útil si los datos están cambiando + puede llevar mucho tiempo si se trata de un gran conjunto de datos con muchas manipulaciones 2.load("melanoma_final.rda") de la data_processed/carpeta + generalmente más rápido, pero carga el conjunto de datos que se creó la última vez que ejecutó00_source_all.R

Recuerda: Para .R archivos usa source(), para .rda archivos usa load().

Las dos opciones se ven así:

---
title: "Melanoma analysis"
output: html_notebook
---

```{r get-data-option-1, echo=FALSE}
load(
  here:here("data", "melanoma_all.rda")
)
```

```{r get-data-option-2, echo=FALSE}
source(
  here:here("R", "00_source_all.R")
)

12.7.1 ¿Por qué darse todas estas molestias?

Viene de muchos años de encontrar errores debido a proyectos mal organizados. No es necesario para un pequeño proyecto rápido, pero es esencial para cualquier trabajo importante.

Al comienzo de un análisis (como en el primer día), comenzaremos a trabajar en un solo archivo. Moveremos rápidamente fragmentos de código de limpieza/preparación de datos en archivos separados a medida que avanzamos.

La compartimentación de la limpieza de datos ayuda a encontrar y tratar los errores (“depuración”). Los archivos originales se pueden ‘comentar’ (agregando un # a una línea en el 00_source_all.R archivo) si desea excluir las manipulaciones en ese archivo en particular.

Lo más importante, ayuda con la colaboración. Cuando varias personas trabajan en un proyecto, es esencial que la comunicación sea buena y que todos trabajen según el mismo plan general.