appliedepi/introexercises

Package index
Search the appliedepi/introexercises package
Functions
0
Source code
2
Man pages
0
Home
/
GitHub
/
appliedepi/introexercises
/

In appliedepi/introexercises: 

# load packages ----------------------------------------------------------------
library(introexercises)
library(learnr)
library(gradethis)
library(dplyr)
library(flair)
library(ggplot2)
library(stringr)
library(epikit)
library(lubridate)
library(fontawesome)
library(janitor)
# library(RMariaDB)        # connect to sql database 

## set options for exercises and checking ---------------------------------------

## Define how exercises are evaluated 
gradethis::gradethis_setup(
  ## note: the below arguments are passed to learnr::tutorial_options
  ## set the maximum execution time limit in seconds
  exercise.timelimit = 60, 
  ## set how exercises should be checked (defaults to NULL - individually defined)
  # exercise.checker = gradethis::grade_learnr
  ## set whether to pre-evaluate exercises (so users see answers)
  exercise.eval = FALSE 
)

# ## event recorder ---------------------------------------------------------------
# ## see for details: 
# ## https://pkgs.rstudio.com/learnr/articles/publishing.html#events
# ## https://github.com/dtkaplan/submitr/blob/master/R/make_a_recorder.R
# 
# ## connect to your sql database
# sqldtbase <- dbConnect(RMariaDB::MariaDB(),
#                        user     = Sys.getenv("userid"),
#                        password = Sys.getenv("pwd"),
#                        dbname   = 'excersize_log',
#                        host     = "144.126.246.140")
# 
# 
# ## define a function to collect data 
# ## note that tutorial_id is defined in YAML
#     ## you could set the tutorial_version too (by specifying version:) but use package version instead 
# recorder_function <- function(tutorial_id, tutorial_version, user_id, event, data) {
#     
#   ## define a sql query 
#   ## first bracket defines variable names
#   ## values bracket defines what goes in each variable
#   event_log <- paste("INSERT INTO responses (
#                        tutorial_id, 
#                        tutorial_version, 
#                        date_time, 
#                        user_id, 
#                        event, 
#                        section,
#                        label, 
#                        question, 
#                        answer, 
#                        code, 
#                        correct)
#                        VALUES('", tutorial_id,  "', 
#                        '", tutorial_version, "', 
#                        '", format(Sys.time(), "%Y-%M%-%D %H:%M:%S %Z"), "',
#                        '", Sys.getenv("SHINYPROXY_PROXY_ID"), "',
#                        '", event, "',
#                        '", data$section, "',
#                        '", data$label,  "',
#                        '", paste0('"', data$question, '"'),  "',
#                        '", paste0('"', data$answer,   '"'),  "',
#                        '", paste0('"', data$code,     '"'),  "',
#                        '", data$correct, "')",
#                        sep = '')
# 
#     # Execute the query on the sqldtbase that we connected to above
#     rsInsert <- dbSendQuery(sqldtbase, event_log)
#   
# }
# 
# options(tutorial.event_recorder = recorder_function)

# hide non-exercise code chunks ------------------------------------------------
knitr::opts_chunk$set(echo = FALSE)

# data prep --------------------------------------------------------------------
surv <- rio::import(system.file("dat/surveillance_linelist_clean_20141201.rds", package = "introexercises"))

Introducción a R para Epidemiología Aplicada y Salud Pública

Bienvenido

Bienvenido al curso "Introducción a R para epidemiología aplicada", ofrecido por Epidemiología - una organización sin ánimo de lucro y el principal proveedor de formación, apoyo y herramientas de R para profesionales de primera línea de la salud pública.

knitr::include_graphics("images/logo.png", error = F)

R Markdown

Este ejercicio se centra en crear informes automatizados con R Mark. Concretamente, crearás un "informe de situación" Ébola utilizando el código que escribiste en los módulos anteriores.

Formato

Este ejercicio te guía a través de las tareas que debes realizar en RStudio en tu ordenador lo.

Obtener ayuda

Hay varias formas de obtener ayuda:

1) Busca a los "ayudantes" (ver más abajo) 2) Pide ayuda al instructor/facilitador de tu curso en directo 3) Programa una llamada 1 a 1 con un instructor para "Tutoría del curso". 4) Publica una pregunta en Comunidad Epi Aplicada

Este es el aspecto que tendrán esos "ayudantes":

r fontawesome::fa("lightbulb", fill = "gold") Haz clic para leer una pista

¡Aquí verás una pista útil!


r fontawesome::fa("check", fill = "red")Haz clic para ver una solución (¡pruébalo tú primero!) 

linelist %>% 
  filter(
    age > 25,
    district == "Bolo"
  )

Aquí tienes más explicaciones sobre por qué funciona la solución.


Preguntas del concurso

Responder a las preguntas del cuestionario te ayudará a comprender el material. Las respuestas no se registran.

Para practicar, responde a las siguientes preguntas:

quiz(
  question_radio("When should I view the red 'helper' code?",
    answer("After trying to write the code myself", correct = TRUE),
    answer("Before I try coding", correct = FALSE),
    correct = "Reviewing best-practice code after trying to write yourself can help you improve",
    incorrect = "Please attempt the exercise yourself, or use the hint, before viewing the answer."
  )
)

question_numeric(
 "How anxious are you about beginning this tutorial - on a scale from 1 (least anxious) to 10 (most anxious)?",
 answer(10, message = "Try not to worry, we will help you succeed!", correct = T),
 answer(9, message = "Try not to worry, we will help you succeed!", correct = T),
 answer(8, message = "Try not to worry, we will help you succeed!", correct = T),
 answer(7, message = "Try not to worry, we will help you succeed!", correct = T),
 answer(6, message = "Ok, we will get there together", correct = T),
 answer(5, message = "Ok, we will get there together", correct = T),
 answer(4, message = "I like your confidence!", correct = T),
 answer(3, message = "I like your confidence!", correct = T),
 answer(2, message = "I like your confidence!", correct = T),
 answer(1, message = "I like your confidence!", correct = T),
 allow_retry = TRUE,
 correct = "Thanks for sharing. ",
 min = 1,
 max = 10,
 step = 1
)

Licencia

Por favor, envía un correo electrónico a contact@appliedepi.org si tienes preguntas sobre el uso de estos materiales.

Objetivos de aprendizaje

En este ejercicio

Prepara

Abre el proyecto R "ebola", como de costumbre, haciendo clic en el icono del proyecto R de la carpeta "ebola". Abre tu script "ebola_análisis.R".

Crear un nuevo script R Markdown

Haz clic en "Archivo -> Nuevo Archivo -> R Markdown...".

knitr::include_graphics("images/1_gettingstarted.png", error = F)

En la ventana que aparece

Una vez que aparezca el nuevo script R Markdown, haz clic en "Archivo -> Guardar como" y guárdalo en la carpeta "ebola/scripts" con el nombre "ebola_sitrep.Rmd".

Este archivo es un plantilla genérica R Markdown genérica de R Markdown que puedes utilizar para empezar a crear tu propio script. Utiliza conjuntos de datos guardados dentro del software R base (por ejemplo cars y pressure) para demostrar las funcionalidades básicas de R Markdown.

En este ejercicio, exploraremos las funcionalidades de R Markdown y *transferir tu script R existente a este script R Markdown*.

Visión general de R Markdown

En esta sección, revisaremos las características clave de un script R Markdown.

Incluso si ya estás familiarizado con R Markdown, ¡puedes aprender algunos trucos nuevos!

Abre tu script R Markdown.

quiz(caption = "Quiz - YAML",
  question("What differences from a traditional R script do you see in an R markdown script?",
    allow_retry = T,
    answer("The top part has colons : and dashes ---", correct = T),
    answer("There are alternating background colours to different sections within the script (e.g grey, white)", 
           correct = T),
    answer("There are many tick marks... at the top/bottom certain sections (e.g. grey have them but white don't)",
           correct = T), 
    answer("There are text sentences, but also R code",
           correct = T),
    answer("R Markdown scripts allow you to draw pictures in the script",
           correct = F)
  )
)

Botones

r fontawesome::fa("eye", fill = "darkblue") Revisa el menú de nuevos que aparecen en la parte superior del script R Markdown:

Modos de visualización

knitr::include_graphics("images/buttons_visual.png", error = F)

Modos Fuente y Visual - En el extremo superior izquierdo de R Markdown dos botones te permiten cambiar o "alternar" entre los modos "Fuente" y "Visual" del script. Esta es una característica de los scripts R Markdown en RStudio que se ha hecho más popular en los últimos años.

Por ejemplo, para producir las viñetas anteriores, en modo Fuente escribimos siguiente sintaxis:

**Source and Visual Modes** - On the far upper-left of the R Markdown script, two buttons allow you to switch or "toggle" between "Source" and "Visual" views of the script. This is a feature of R Markdown scripts in RStudio that has become more popular just in recent years.  

  * **"Source" mode** - This is the traditional R Markdown script view. You write in Markdown syntax. For example, to produce bullet points you write asterisks ( * ) and to produce static tables you use bars ( | ).  
  * **"Visual" mode** - In this mode you see a quasi-preview of how the R Markdown report will appear when rendered. There are more buttons at the top, in a style similar to Microsoft Word, which will do the Markdown syntax formatting for you! E.g. to convert text to italics, bold, insert bullets, or even insert tables.

En cambio, si escribes las viñetas anteriores utilizando el Modo Visual, puedes simplemente escribir, y ajustar las viñetas, la negrita, etc. utilizando los botones de la parte superior.

knitr::include_graphics("images/visual_mode.png", error = F)

r fontawesome::fa("exclamation", fill = "red") ¡Ten cuidado! Visual es atractivo, pero la mayoría de los usuarios avanzados de R prefieren el modo Fuente para tener más control. En concreto, el manejo en Modo Visual de las tablas estáticas y las viñetas puede tener bastantes fallos, sobre todo si se cambia de un modo a otro. modos.

Teje

knitr::include_graphics("images/buttons_knit.png", error = F)

Cerca del centro, en la parte superior del script, hay un botón azul "Tejer". Este botón se puede pulsar para "renderizar" la salida de R Markdown (por ejemplo, un documento Word, PDF, HTML, etc.).

Practicaremos el tejido dentro de un momento. Ten en cuenta que este botón "Tejer" también tiene un menú desplegable a la derecha, que se abre haciendo clic en la flecha hacia abajo.

Insertar trozo

knitr::include_graphics("images/buttons_chunk.png", error = F)

Desplazándote a la derecha, un pequeño botón verde con un símbolo "+" te permite insertar un "fragmento de código" en el script R Markdown. Hablaremos de esto más adelante, pero un fragmento de código es donde puedes escribir código R que se ejecutará cuando se muestre el documento.

Fíjate en el menú desplegable de la derecha. ¡En un script R Markdown también puedes ejecutar código de otros lenguajes de programación como Python y SQL!

Ejecuta

knitr::include_graphics("images/buttons_run.png", error = F)

El botón Ejecutar es muy importante: puede utilizarse para ejecutar partes seleccionadas ("trozos de código") de tu script R Markdown.

Haz clic en la flecha situada junto a Ejecutar y verás el menú desplegable. Revisa todas las opciones. Podemos jugar con ellas más tarde.

Esboza

knitr::include_graphics("images/buttons_outline.png", error = F)

En el extremo derecho, hay un botón gris llamado "Esquema". Al pulsarlo, se abrirá una barra de Índice que te permitirá navegar rápidamente por tu guión. A medida que tu guión crece, puede ser útil navegar y asegurarte de que tus encabezados (las sangrías en la TdC) son correctos.

Elaborar un informe

La elaboración del informe se denomina "tejer" el informe. Puedes pensar en este proceso como la combinación o "costura" de componentes del script R Markdown, a saber:

El resultado se "renderiza" (produce) como archivo de salida. Puede ser un documento Word, PDF, HTML, etc.

Haz clic en el botón "tejer" en la parte superior del script R Markdown para renderizar el documento R Markdown como un archivo HTML.

Si no aparece ninguna salida o ves un error en la consola, avisa a tu instructor. En los ordenadores del lugar de trabajo, R markdown puede encontrar a veces errores debidos a los permisos de escritura. Hemos documentado algunos de ellos en capítulo del Manual Epi.

r fontawesome::fa("eye", fill = "darkblue") Observa el resultado. Observa cómo contiene elementos que corresponden a componentes del script R Markdown:

Pongámonos al día sobre estos componentes del script R Markdown...

YAML

Observa la sección situada en la parte superior del script R Markdown: las 6 primeras líneas. Es la sección "YAML".

Como usuario principiante de R, deberías tener sólo una sección YAML en tu script R Markdown en la parte superior.

La cabecera YAML

El YAML son los ajustes para el tipo de salida que se va a producir, las preferencias de formato y otros metadatos como el título del documento, el autor y la fecha. Esto se hace mediante clave: valor separados por dos puntos y un espacio después de los dos puntos.

YAML está delimitado por tres guiones en su parte superior e inferior. Las secciones YAML pueden ser muy sencillas, por ejemplo:

---
title: "Surveillance report"
output: html_document
---

Sin embargo, pueden llegar a ser mucho más complejas... ¡aprenderemos sobre YAML más avanzado a medida que avancemos en este ejercicio!

Formatos de salida

Puedes controlar la salida producida con la opción output: en el YAML. Aquí es donde controlas si el informe se produce como Documento Word, Documento PDF, Documento HTML, panel de control, etc.

La clave YAML output: puede editarse para producir muchos tipos de resultados. A continuación se indican algunos de los más comunes:

| valor | Tipo de salida | | ----------------------------- | ------------------------------------- | | documento_html | Documento HTML / página web básica | | documento_palabra | Documento de Word | | presentación_ppt | Diapositivas Powerpoint | | documento_pdf | Documento PDF (requiere LaTeX) | | flexdashboard::flex_dashboard | Cuadro de mandos básico (requiere el {flexdashboard} paquete) |

Cubriremos muchos de ellos en este curso.

HTML

Cuando tejiste el documento la primera vez, el valor por defecto output: html_document escrito en el YAML se utilizó, produciendo un archivo HTML.

Un archivo HTML es similar a una página web. Puede visualizarse mediante un navegador de Internet (aunque el ordenador esté desconectado) y, por tanto, puede incluir un aspecto personalizado y componentes interactivos como botones, pestañas, índice desplazable, etc. Un archivo HTML puede enviarse por correo electrónico como un archivo estático, similar a un documento PDF o Word. Cuando el destinatario lo reciba, el archivo se abrirá en el navegador de Internet, ¡pero el archivo no está en línea! Sólo se guarda localmente en su ordenador, pero el navegador de Internet se utiliza para mostrar el archivo. Es importante que sepas esto, si te preocupa compartir información sensible en un informe HTML.

Documento Word

Actualiza la clave de salida en tu sección YAML a:

output: word_document

¡¡¡Ten mucho cuidado con el espaciado y la ortografía exacta!!!

El formato de salida Word es muy útil si quieres automatizar el análisis, pero también que se escriba la interpretación humana después de que R genere el informe.

"Teje" el informe con esta configuración y revisa el resultado.

Ten en cuenta que para volver a tejer un Documento de Word necesitas cerrar primero el Documento de Word, de lo contrario verás este error:

Mensaje de error de que R no pudo sobrescribir un documento abierto:

pandoc.exe: ebola_sitrep.docx: withBinaryFile: permission denied (Permission denied)
Error: pandoc document conversion failed with error 1
Execution halted

Documento PDF

No intentes renderizar a PDF ahora mismo. Podría distraerte del resto del ejercicio. Tejer directamente a PDF puede ser difícil y puedes encontrar más dificultades con el formato.

Incluiremos instrucciones al final de este ejercicio para ayudarte a producir un PDF.

Recuerda que si tienes dificultades para tejer a PDF desde R, normalmente puedes tejer a Word y luego guardarlo como PDF.

Otros formatos

Existen muchos otros formatos, por ejemplo

Sintaxis YAML

YAML también puede ser más complejo. Mira a continuación un ejemplo...

¡NO ACTUALICES TU PROPIO CÓDIGO YAML PARA REFLEJAR ESTE EJEMPLO! Sólo míralo y responde a las preguntas que aparecen a continuación.

---
title: "Surveillance report"
subtitle: "Hepatitis A"
author: "Lisa Epi"
date: "`r Sys.Date()`"
output: 
  html_document:
    theme: cerulean
    code_folding: show
    toc: yes
    toc_float:
      collapsed: true
params:
  state: Nebraska
  year: 2019
  midwest: true
  report_date: !r lubridate::ymd("2023-12-09")
---

A ver si puedes responder a las siguientes preguntas sobre el YAML anterior:

quiz(caption = "Quiz - YAML",
  question("What is the default output type of this R Markdown?",
    allow_retry = T,
    answer("Word document", 
           correct = F),
    answer("Powerpoint slides",
           correct = F), 
    answer("HTML document", correct = T),
    answer("Shiny app",
           correct = F)
  ),
  question("What does the function Sys.Date() produce?",
    allow_retry = T,
    answer("The current date, as per your computer", correct = T),
    answer("The operating system being used", 
           correct = F),
    answer("The last date of symptom onset",
           correct = F), 
    answer("The last date of report of a case",
           correct = F)
  )
)

Hay muchos ajustes YAML opcionales. En el ejemplo YAML anterior

Lee más opciones YAML en Hoja de trucos Posit R Markdown entre otros sitios.

Errores YAML

Desgraciadamente, YAML es famoso por los errores y los mensajes de error confusos.

Revisa el YAML a continuación, pero NO lo copies en tu script. Contesta a las siguientes preguntas sobre el formato YAML (y el formato clave: valor ):

---
title: "Surveillance report"
subtitle: "Hepatitis A"
author: "Lisa Epi"
date: "`r Sys.Date()`"
output: 
  html_document:
    theme: cerulean
    code_folding: show
    toc: yes
    toc_float:
      collapsed: true
params:
  state: Nebraska
  year: 2019
  midwest: true
  report_date: !r lubridate::ymd("2023-12-09")
---

quiz(caption = "Quiz - YAML",
    question("Where are colons placed? (select all that apply)",
    allow_retry = T,
    answer("After a key, followed by a single space",
           correct = T),
    answer("After any embedded R code", 
           correct = F),
    answer("After a value, if followed by an indented key",
           correct = F), 
    answer("After a value, only if followed by a *more* indented key",
           correct = T)
  ),
  question("Which ways are accepted to write that a YAML key should be set to 'true'?",
    allow_retry = T,
    answer("TRUE",
           correct = T),
    answer("'TRUE' (with quotation marks)",
           correct = F, message = "Quotation marks deactivate the logical status."),
    answer("true", 
           correct = T),
    answer("True",
           correct = F), 
    answer("TrUe",
           correct = F, message = "Random capital letters in the middle of a word prevent recognition as a special term")
  ),
      question("How many spaces are used in YAML indentation?",
    allow_retry = T,
    answer("4", correct = F),
    answer("3", 
           correct = F),
    answer("2",
           correct = T), 
    answer("1",
           correct = F)
  )
)

Los mensajes de error YAML suelen ser crípticos y difíciles de interpretar. A continuación encontrarás algunos ejemplos:

Has olvidado un espacio después de los dos puntos que separan la clave y el valor

Error in yaml::yaml.load(..., eval.expr = TRUE) : 
  Scanner error: while scanning a simple key at line 3, column 1 could not find expected ':' at line 4, column 1
Calls: <Anonymous> ... parse_yaml_front_matter -> yaml_load -> <Anonymous>
Execution halted

Sangría incorrecta

Error in yaml::yaml.load(..., eval.expr = TRUE) : 
  Scanner error: mapping values are not allowed in this context at line 7, column 15
Calls: <Anonymous> ... parse_yaml_front_matter -> yaml_load -> <Anonymous>
Execution halted

En los errores anteriores, a menudo se hace referencia a la "línea X" y a la "columna Y" (X e Y son números). Mira en el YAML en la línea X del YAML y el carácter Y en esa línea para identificar el error.

r fontawesome::fa("pen", fill = "brown") La verdad es que los errores en YAML son tan fáciles de cometer que la mayoría de los programadores de R no escriben su YAML desde cero. Copiamos y pegamos de un script que se sabe que funciona, y hacemos delicadas modificaciones sobre él, probando por punto cuando hacemos un pequeño cambio en el YAML.

El panel de renderizado

En RStudio, el progreso de la renderización (tejido) del informe, y cualquier mensaje de error se muestran en el panel Renderizado . Si te confundes, recuerda que siempre puedes hacer clic para volver a la pestaña Consola.

knitr::include_graphics("images/render_console.png", error = F)

¿Qué significa YAML, te preguntarás? La verdad es que significa "Otro Lenguaje Markdown". ¡Alguien se divirtió creando ese nombre!

Prepara tu YAML

Edita tu YAML para que tenga exactamente este (con tu nombre en el campo author: sección). Ten en cuenta que los dos puntos y la sangría deben ser exactamente correctos, con un espacio después de los dos puntos y dos espacios para la sangría.

---
title: "Situation Report"
subtitle: "Ebola outbreak in Sierra Leone"
author: "(Your name or agency here)"
output:
  word_document: default
date: "`r Sys.Date()`"
---

Ten en cuenta que para este ejercicio construiremos un documento Word informe.

Trozos de código

Mira la plantilla completa del script R Markdown. Aparte del YAML, los scripts R Markdown tienen dos componentes principales:

1) "Trozos" de código R 2) Secciones de texto (texto "Markdown")

El código de esta plantilla está dividido en varios trozos de código:

Nota: la cars y pressure son conjuntos de datos de ejemplo guardados en R.

Ahora editaremos esta plantilla para incluir el código de nuestro informe sobre la situación del ébola.

Ejecutar un fragmento de código

Rehacer el informe a medida que hacemos pequeños cambios puede ser tedioso, y es innecesario. A medida que editamos nuestro informe, podemos ejecutar trozos de código R específicos para ver el impacto de los cambios en el código R.

Ve al fragmento que contiene el summary() y pulsa la flecha verde de la esquina superior derecha.

knitr::include_graphics("images/chunk_play.png", error = F)

Esta acción ejecutará todo el código R escrito en el fragmento.

Ejecuta el siguiente fragmento, con el botón plot() de la misma manera.

quiz(caption = "Quiz - knitting Rmd",
  question("Where did the plot appear?",
    allow_retry = T,
    answer("In the RStudio Viewer pane", correct = F),
    answer("In the RStudio Environment pane", 
           correct = F),
    answer("In the R Markdown, below the code chunk",
           correct = T), 
    answer("In the R Console",
           correct = F)
  )
)

En R Markdown, debajo del fragmento de código aparece una vista previa de los gráficos y otros resultados. Si hay varios resultados de un fragmento de código, aparecerán uno al lado del otro, y podrás hacer clic en ellos.

Ejecutar el código línea por línea

Como en un script normal de R, puedes resaltar determinadas líneas de código R para ejecutarlas.

Para ejecutar la(s) línea(s) tienes las siguientes opciones:

1) Resalta las líneas y pulsa Ctrl+Enter en el teclado, o 2) Pulsa el menú desplegable "Ejecutar" en la parte superior derecha del guión, y selecciona "Ejecutar líneas seleccionadas".

Practica la ejecución del summary() y plot() utilizando uno de los métodos anteriores.

Crear un fragmento de código

Observa cómo un trozo de código comienza con tres "corchetes" y "llaves" con la letra R dentro, y termina también con tres corchetes.

Ten en cuenta que los corchetes NO son comillas simples. Observa la diferencia:

Puede que te lleve algún tiempo encontrar esta tecla en tu teclado. En los teclados de EE.UU. y Reino Unido suele estar cerca de la tecla ESC, 1 o ~ (para otras distribuciones de teclado, consulta esto guía.

Por suerte, ¡no hace falta que escribas puntos suspensivos para crear un trozo de código!

Para insertar fácilmente un nuevo frag coloca el cursor en la casilla en medio de algunas líneas vacías. A continuación, pulsa el pequeño botón verde (con el símbolo +) situado en la parte superior derecha del script para insertar un nuevo fragmento de código R.

knitr::include_graphics("images/buttons_chunk.png", error = F)

Alternativamente, pulsa Ctrl + Alt + i (o Option + Command + i en un Mac) para insertar un trozo.

Piensa en este fragmento como en un script R en miniatura. Escribe el código R entre las líneas de retroceso exactamente como lo harías en un script R tradicional.

También puedes escribir código R que no imprima una salida. Los trozos de la imagen siguiente cargan paquetes e importan un conjunto de datos. Ten en cuenta que se pueden añadir comentarios con # dentro de un fragmento, igual que en un script normal de R.

knitr::include_graphics("images/chunk_no_output.png", error = F)

Añadir trozos de código Ébola

¡Te toca! Practica añadiendo un fragmento de código al documento.

Debajo del fragmento "configuración", inserta un nuevo fragmento de código y pega tu pacman::p_load() comando de tu script ebola_analysis.R.

# This chunk loads packages
pacman::p_load(
     rio,          # for importing data
     here,         # for locating files
     skimr,        # for reviewing the data
     janitor,      # for data cleaning  
     epikit,       # creating age categories
     gtsummary,    # creating tables  
     RColorBrewer, # for colour palettes
     viridis,      # for more colour palettes
     scales,       # percents in tables  
     flextable,    # for making pretty tables
     gghighlight,  # highlighting plot parts  
     ggExtra,      # special plotting functions
     tidyverse     # for data management and visualization
)

A continuación, añade otro fragmento de código debajo, con tu código para importar el archivo surv_raw conjunto de datos.

# This chunk imports data
surv_raw <- import(here("data", "raw", "surveillance_linelist_20141201.csv"))

Intenta ejecutar estos trozos pulsando sus botones verdes de "reproducir".

¿Esperas alguna salida impresa debajo de los trozos? Pronto hablaremos de cómo gestionar los mensajes de advertencia.

Orden de marcha

Ahora, guarda tu script R Markdown.

A continuación, ve a la pestaña del menú "Sesión" de RStudio y haz clic en "Reiniciar R".

No se ha guardado nada de lo que has ejecutado antes. Es un borrón y cuenta nueva. No hay paquetes cargados ni conjuntos de datos en tu Entorno.

Ahora intenta ejecutar sólo el fragmento que contiene el import() comando.

quiz(caption = "Quiz - knitting Rmd",
  question("Where did the error message appear (select all that apply)?",
    allow_retry = T,
    answer("In the RStudio Viewer pane", correct = F),
    answer("In the RStudio Environment pane", 
           correct = F),
    answer("In the R Markdown, below the code chunk",
           correct = T), 
    answer("In the R Console",
           correct = T)
  ),
  question("Why did this error occur?",
    allow_retry = T,
    answer("Misspelling of import()", correct = F),
    answer("The rio package was not loaded before running import()", 
           correct = T),
    answer("The dataset does not exist",
           correct = F), 
    answer("R is occassionally angry and refuses to import data",
           correct = F)
  )
)

Esto refuerza el mensaje de que aunque cada trozo parece independiente siguen haciendo referencia al mismo Entorno de R. Además, cuando el script está en punto, el Entorno se borra y los trozos se ejecutan en orden.

En el import() chunk, haz clic en el icono situado junto al icono verde "Reproducir"; si pasas el ratón por encima dirá "Ejecutar todos los chunks anteriores". Es útil conocer este botón.

Ejecuta todos los trozos de arriba y luego ejecuta el botón import() trozo.

Formatear el texto

Un script R Markdown produce, ante todo, un documento. El texto que escribas en las líneas del script aparecerá como texto en la salida: frases, párrafos, viñetas, etc. Estas palabras se pueden personalizar en cursiva, negrita, tablas estáticas con celdas, etc.

Más adelante, te mostraremos cómo se puede incrustar código dentro del documento: ¡éste es el poder de R Markdown!

Añadir secciones

Puedes incluir secciones en el informe con "encabezamientos" utilizando símbolos #.

# Biggest heading
## A sub-heading
### A sub-sub-heading
#### An even smaller heading

Los encabezados aparecerán en el "esquema" del informe. Haz clic en el botón "esquema" de la parte superior derecha del guión para ver este esquema y las sangrías por nivel de encabezamiento.

quiz(caption = "Quiz - Headings",
  question("What are the headings in the template R Markdown script?",
    allow_retry = T,
    answer("Including plots", correct = T),
    answer("title", 
           correct = F, message = "No, title is part of the YAML."),
    answer("setup",
           correct = F, message = "No, setup is a chunk name not a heading. There is no # symbol in front of it."),
    answer("cars",
           correct = F, message = "No, cars is a chunk name not a heading. There is no # symbol in front of it."),
    answer("pressure",
           correct = F, message = "No, pressure is a chunk name not a heading. There is no # symbol in front of it."),
    answer("R Markdown",
           correct = T)
  )
)

Haz una sección "Resumen" de tu informe

Añade los siguientes títulos en tu informe, *debajo de import() fragmento de código*.

# Summary

## About this report

## Key numbers

Añade texto y viñetas

Dar formato al texto en el modo Fuente funciona así:

Aquí tienes un ejemplo (haz no tienes que escribirlo):

knitr::include_graphics("images/2_text.png", error = F)

Ahora, escribe este texto en las nuevas secciones de tu informe:

1) En la sección "Resumen", escribe

Este es un informe de situación de demostración sobre un hipotético brote de ébola en Sierra Leona en 2014. Utiliza datos simulados.

2) En la sección "Acerca de este informe", escribe:

Este informe se elaboró en FECHA_ACtual.

En el lugar de FECHA_ACtual anterior, escribe la fecha actual (en el formato que prefieras).

3) En la sección "Números clave", escribe (en viñetas):

Puntos clave sobre este brote:

¡Presta atención al formato de las viñetas! Vuelve a unirlas para comprobar que funcionan. No olvides poner una nueva línea entre la frase superior y la primera viñeta, ¡y dos espacios después de cada viñeta!

Vuelve a tejer tu informe y visualiza el documento Word resultante. Recuerda que si recibes el mensaje "Error 1", es probable que tengas que cerrar el documento de Word antes de tejer.

Opciones de troceado

¿Presentarías este informe a un responsable de la toma de decisiones? Seguramente no.

Un problema es que el código R y los mensajes de advertencia se imprimen en el informe ¡junto con los resultados!

La visualización del código en la salida del informe se controla mediante el botón echo = de cada trozo. La forma más sencilla de controlar esta opción para todos los trozos es establecer un valor por defecto.

Desplázate hasta la parte superior del guión y verás el fragmento superior de "configuración" con este código:

knitr::opts_chunk$set(echo = TRUE)

Este fragmento de "configuración" aparece por defecto en cualquier plantilla R Markdown. Esta función establece las opciones por defecto para todos los chunks.

Has visto el código R en el informe porque el echo = por defecto es TRUE.

Cambia este ajuste a echo = FALSE y vuelve a tejer el informe para ver el resultado. Deberías ver que el código R que se está ejecutando ya no aparece ("haciendo eco") en la salida del informe.

Trozos individuales

Incluso después de especificar los valores por defecto, puedes ajustar las opciones de los trozos para trozos individua dentro de sus llaves { } después de r y después de una coma.

knitr::include_graphics("images/chunk4.png", error = F)

quiz(caption = "Quiz - Test your understanding of chunk options",
  question("In the example above, what will appear in the knitted report?",
    allow_retry = T,
    answer("Only the math equations will show.", correct = F),
    answer("The math equations and their answers will show.", correct = F),
    answer("Only the answers will show", correct = T), 
    answer("Neither the equations, nor the answers will show.", correct = F)
  )
)

En el ejemplo anterior, la opción echo = se establece en FALSE sólo para este fragmento. En significa que:

El icono de engranaje

Si prefieres un enfoque de "apuntar y hacer clic", establece las opciones de un trozo haciendo clic en el pequeño icono de "Engranaje" situado a la derecha del trozo y seleccionando en el menú desplegable "Salida". Se establecerán las opciones correspondientes al fragmento.

knitr::include_graphics("images/chunk_options.png", error = F)

Prueba a ajustar las opciones de los trozos. Observa las diferencias entre los fragmentos que contienen un comando sin salida (por ejemplo, importar datos) y los que tienen salida (por ejemplo, el comando plot() ). Vuelve a tejer el informe tantas veces como necesites para entender cómo funcionan estas opciones.

quiz(caption = "Quiz - chunk options",
  question("Which option is listed if you select ‘Show code and output'?",
    allow_retry = T,
    answer("show = TRUE", correct = F),
    answer("output = TRUE", 
           correct = F),
    answer("echo = TRUE",
           correct = T), 
    answer("include = TRUE",
           correct = F)
  )
)

quiz(caption = "Quiz - chunk options",
  question("What does the option ‘include = FALSE' do?",
    allow_retry = T,
    answer("Prevents the report from knitting", correct = F),
    answer("Makes the document non-inclusive of visually-impaired readers", 
           correct = F),
    answer("The code will be run, but no outputs will be shown",
           correct = T), 
    answer("This code is not run",
           correct = F)
  )
)

¿Puedes editar ahora tu código para que el valor por defecto sea ocultar todos los mensajes y advertencias?

r fontawesome::fa("check", fill = "red")Haz clic para ver una solución (prueba ¡primero tú mismo!)


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

Las opciones message = y warning = se establecen en FALSE.


Las opciones que selecciones pueden variar mucho según el contexto:

  • Para una breve actualización de la situación o un documento público, probablemente el código R en el informe.
  • Para un informe analítico con un público técnico, podrías hacer que el código disponible para que otros científicos o lectores puedan rápidamente tu proceso.

Antes de continuar, asegúrate de que tu fragmento de configuración (en la parte superior del script) tiene este aspecto, y de que ningún otro fragmento tiene ajustes diferentes:

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

Nombres de los trozos

Existe una función opcional para "poner nombre" a los trozos de código. Recomendamos a los principiantes en R Markdown que no utilicen esta función, ya que puede dar lugar a errores frecuentes si no se tiene cuidado.

Al final de este ejercicio te explicamos más sobre esta funcionalidad.

Construye tu informe

Ahora que ya conoces YAML, el tejido, los trozos de código y el texto... ¡empieza a hacer tu informe sobre la situación del ébola!

Elimina todos los encabezados, texto y trozos de ejemplo restantes de la plantilla R Markdown (por ejemplo, el plot() y summary() que utilizan los comandos cars y pressure datos).

Asegúrate de mantener el YAML, el chunk de configuración, los encabezados y el texto de "Resumen" del brote que hayas añadido, y los chunks que creaste para cargar paquetes e importar la lista de líneas sin procesar.

Transfiere el código R importante de tu script "ebola_analysis.R" a este script R Markdown. Algunos consejos:

  • Utiliza trozos para organizar tu código: no pongas TODO el código en un solo trozo.
  • Comprueba a menudo tu progreso tejiendo tu informe después de añadir un trozo
  • Mantén tus # comentarios en los trozos de código para informar a los lectores
  • Sé consciente del conjunto de datos con el que estás trabajando (por ejemplo surv_raw o surv) y el orden de los trozos

Sigue este orden para tus trozos de código, donde cada número representa un trozo de código:

1) Configuración (configuración del fragmento) 2) Cargar paquetes 3) Importar la lista de líneas de vigilancia en bruto 4) (opcional) Análisis exploratorio (conjunto eval = FALSE en las opciones de este fragmento, para que no se imprima ningún resultado en el informe final) 5) Limpia y exporta la lista de líneas de vigilancia 6) Crea e imprime tablas descriptivas (pon cada tabla en su propio chunk) 7) Crea e imprime gráficos (coloca cada gráfico en su propia sección) 8) (opcional) Trozo de prueba (set eval = FALSE para que no se imprima ninguna salida en el informe)

Para los gráficos y tablas, elige sólo 3-5 tablas y gráficos de tu script R ebola para resaltarlos en este informe. Ponles títulos/subtítulos apropiados.

No incluyas todo el análisis exploratorio o el código de prueba de tu script "ebola_analysis.R". Mantén el informe relativamente al mínimo.

Pide ayuda a tu facilitador si te quedas atascado.

Además, ¡no olvides guardar tu informe R Markdown mientras trabajas!

Código en línea

El texto que has escrito en la sección "Resumen" es estático. No cambiará cuando se añadan nuevos casos a la lista y se vuelva a ejecutar el informe (a menos que hagas cambios manuales en el script R Markdown).

R Markdown te permite incrustar código R en el texto para que los números se actualicen automáticamente.

Al escribir "código en línea", creas un pequeño segmento de código R dentro de un texto:

1) Inicia el código con un único y la letra r y un espacio. 2) Continúa escribiendo tu código R. 3) Termina la parte de código en línea con otra marca.

r fontawesome::fa("exclamation", fill = "red") Recuerda que un "punto y aparte" no es lo mismo que una comilla simple ('). Si no estás seguro de dónde encontrar un "punto y aparte" en tu teclado, pregunta a un profesor. A veces está en la misma tecla que la tilde ~.

Fecha de hoy

Un ejemplo sencillo de código inline consiste en insertar la fecha actual en una frase, de forma que se actualice automáticamente cada vez que se toque el informe.

La función Sys.Date() imprime la fecha actual (fíjate en la "D" mayúscula). Ésta es de {base} R y no depende de ningún objeto, por lo que puede colocarse en cualquier parte del script.

Actualiza la frase de la sección "Acerca de este informe" para que se lea:

### About this report
This report was produced on `r Sys.Date()`.

Ahora, vuelve a redactar el informe y comprueba si aparece la fecha correcta en la frase.

Número de filas de la lista de líneas

En la sección "Números clave", el primer punto incluye el número de casos (filas). ¿Cómo utilizarás el código en línea para que este número se actualice automáticamente?

r fontawesome::fa("lightbulb", fill = "gold") Haz clic para leer una pista

Utiliza la función base de R nrow() para imprimir el número de filas del surv lista de líneas.


r fontawesome::fa("check", fill = "red")Haz clic para ver una solución (¡prueba ¡inténtalo tú primero!) 

* In total, there have been `r nrow(surv)` cases reported.




¿Has visto un mensaje de error como éste?

knitr::include_graphics("images/execution_halted.png", error = F)

Haz clic en el botón "Problemas" para ver el mensaje de error detallado y la(s) línea(s) que causaron el problema.

knitr::include_graphics("images/render_issues.png", error = F)

r fontawesome::fa("exclamation", fill = "red") Piensa un momento: el script R Markdown renderiza de arriba abajo. Por tanto, ¿DÓNDE en el script R Markdown puedes ejecutar este código que hace referencia al *limpia surv conjunto de datos*?

quiz(caption = "Quiz - Order",
  question("What should you do to fix this problem?",
    allow_retry = T,
    answer("Not have a Summary section of this report", correct = F),
    answer("Manually adjust the Summary section in the R Markdown each time",
           correct = F), 
    answer("Edit the Summary section in the Word output each time",
           correct = F),
    answer("Move the Summary section below the data cleaning chunk", 
           correct = T)
  )
)

Este código inline debe colocarse debajo de ¡del fragmento de limpieza! De lo contrario, el código no podrá encontrar el trozo limpio surv limpio.

Desplaza toda la sección "Resumen debajo de del fragmento de código R de limpieza de datos. Puesto que todos los fragmentos están ajustados a echo = FALSE el Resumen seguirá apareciendo en la parte superior de la salida de Word.

El nuevo orden de tu script debería ser

1) Configuración (ajustes del fragmento) 2) Cargar paquetes 3) Importar la lista de líneas de vigilancia en bruto 4) Análisis exploratorio (opcional) 5) Limpia y exporta la lista de líneas de vigilancia 6) Resumen del brote 7) Crea e imprime tablas descriptivas 8) Crea e imprime gráficos

Asegúrate de que este código funciona volviendo a tejer el informe.

Max y min

Convierte las viñetas "Números clave" segunda y tercera para que muestren los valores mínimo y máximo del date_report de la columna surv marco de datos.

r fontawesome::fa("lightbulb", fill = "gold") Haz clic para leer una pista

Utiliza las funciones básicas de R max() y min(). Haz referencia a la columna como surv$date_report
No olvides el argumento na.rm = TRUE para asegurarte de que las fechas del informe que falten no aparezcan en la salida NA.


r fontawesome::fa("check", fill = "red")Haz clic para ver una solución (¡prueba ¡inténtalo tú primero!) 

* The first case was reported on `r min(surv$date_report, na.rm=T)`.   
* The last case was reported on `r max(surv$date_report, na.rm=T)`.


Devuelve un número concreto de casos y su porcentaje

En el resumen del brote, queremos destacar el número de niños menores de 5 años que son casos confirmados.

¿Cómo añadirías texto a la primera viñeta que informa del número de casos de menores de 5 años?

Aquí tienes algunas opciones:

1) Opción 1: Podrías escribir un más largo R más largo en el código inline, utilizando tuberías, filter() y nrow() por ejemplo:

* In total, there have been `r nrow(surv)` cases reported, including `r surv %>% filter(age_years < 5) %>% nrow()` children under 5 years.

2) Opción 2: Podrías crear un trozo de código R aparte del anterior, para crear y almacenar el número para su uso posterior:

under_5_count <- surv %>%
  filter(age_years < 5) %>%
  nrow()

Luego, en la viñeta, haz referencia al valor dentro del código R en línea, como por ejemplo

* In total, there have been `r nrow(surv)` cases reported, including `r under_5_count` children under 5 years.

3) Opción 3 (recomendada): Para este caso concreto, te sugerimos que utilices la útil función llamada fmt_count() desarrollada por algunos miembros de nuestro equipo de Epi Aplicada. Se encuentra en la {epikit} paquete. Te devolverá el número Y el porcentaje de esas filas, ¡con un formato muy bonito!

fmt_count() # from the {epikit} package is built for exactly this scenario

Asegúrate de {epikit} paquete está en tu pacman::p_load() y que está cargado para su uso. Ahora, busca "fmt_count" en el panel de Ayuda de RStudio y lee cómo funciona. Utilízalo en tu código inline.

r fontawesome::fa("check", fill = "red")Haz clic para ver una solución (prueba ¡primero tú mismo!)


Aquí tienes tu texto markdown, con el código R en línea:

* In total, there have been `r nrow(surv)` cases reported, including `r fmt_count(surv, age_years < 5)` children under 5.


Vuelve a tejer el informe y verás que el número de estos casos, y su porcentaje sobre el total de filas, se han impreso automáticamente: ¡qué bien!

En pull() función

¿Y si quieres añadir una viñeta con el número de hospitales que han notificado casos?

Añade un nuevo punto estático (cuarto):

* There are X hospitals that have reported cases.

Si aún no estás familiarizado con ella, explora la función tidyverse pull(). Extrae una sola columna de un marco de datos (como una versión tidyverse de la función $ del operador)

Añade un nuevo fragmento de código a la sección "Números clave", justo debajo de su encabezamiento. Puedes hacerlo con (Ctrl+Alt+i), o con el botón verde de insertar fragmento.

En este fragmento, crea un objeto que almacene el código número de hospitales afectados, llamado hosp_num. Utiliza la tubería, pull() y las funciones base de R unique(), na.omit() y length() para conseguirlo. Inténtalo tú mismo y luego mira la solución.

r fontawesome::fa("check", fill = "red")Haz clic para ver una solución (prueba ¡primero tú mismo!)


# extract the hospital column, reduce to the unique values, then return the length of that vector (i.e. the number of unique hospital names)
hosp_num <- surv %>% # begin with the surv dataset
  pull(hospital) %>%  # extract only the hospital column
  unique() %>%        # use the unique values
  na.omit() %>%       # remove NA
  length()            # return only the number


Explora cómo cada línea está cambiando el hosp_num salida resaltando y ejecutando el comando para incluir cada línea posterior (añade una línea cada vez). Recuerda que puedes resaltar y ejecutar líneas concretas de un fragmento de código utilizando Ctrl y Intro.

Ahora, actualiza el texto de la cuarta viñeta con código en línea para que el número de hospitales se presente dinámicamente

r fontawesome::fa("check", fill = "red")Haz clic para ver una solución (prueba ¡primero tú mismo!)


* There are `r hosp_num` hospitals that have reported cases.


pegar()

¿Cómo ampliarías el último punto para incluir los nombres de los hospitales informantes?

Utiliza las funciones enseñadas anteriormente para extraer un vector de nombres únicos de hospitales y guárdalo como hosp_names.

A continuación, en el texto de la viñeta, dentro del código en línea, utiliza el comando paste() de R base y su función collapse = argumento (recuerda el jurisdictions ejercicio del Módulo 1) para imprimir los nombres.

r fontawesome::fa("check", fill = "red")Haz clic para ver una solución (prueba ¡primero tú mismo!)


# number of hospitals
hosp_num <- surv %>% 
  pull(hospital) %>% 
  unique() %>%
  na.omit() %>% 
  length()

# names of the hospitals
hosp_names <- surv %>% 
  pull(hospital) %>% 
  unique() %>% 
  na.omit()           # remove NA from the vector

Luego, en el texto de la viñeta

* There are `r hosp_num` hospitals that have reported cases: `r paste(hosp_names, collapse = ", ")`.


Algunos consejos avanzados para este tipo de informes:

  • Como alternativa a na.omit() convertir NA en una palabra como "Desconocido" dentro de mutate() utilizando la función fct_na_value_to_level() de {forcats}
  • Utiliza fct_infreq() de {forcats} para convertir la columna en una clase "factor" - esto establece un orden intrínseco específico a los valores, en este caso por su frecuencia. Hablaremos más sobre los factores en módulos posteriores.

El código avanzado que aparece a continuación almacena los nombres de los hospitales por orden de su frecuencia en los datos.

# names of the hospitals in order of frequency
hosp_names <- surv %>% 
  mutate(hospital = fct_infreq(hospital)) %>%  # convert to factor and order by frequency
  mutate(hospital = fct_na_value_to_level(hospital, "Unknown")) %>% # convert NA to "Unknown"
  pull(hospital) %>%  # extract the column only
  levels()   # extract the levels of the factor

Texto dinámico dentro de un comando R

Como se ha comentado anteriormente, código en línea se utiliza para colocar comandos cortos de R dentro de un texto Markdown normal.

Pero, ¿y si combinamos texto y código? en la salida de un comando de R como una tabla o el título de un gráfico? En el módulo ggplot hemos introducido brevemente la función str_glue() de la función {stringr} para hacerlo.

Observa la diferencia:

  • Código R en línea - Usado en markdown texto (no en un fragmento de código)
  • str_glue() - Utilizado dentro de un comando R (por ejemplo, en un fragmento de código)

Como su nombre indica, str_glue() ayuda a "pegar" cadenas de caracteres (texto) con código R en el contexto de un comando R. A menudo se utiliza para crear leyendas gráficas dinámicas como parte de un comando de ggplot() comando.

Cosas que debes recordar con str_glue():

  • La frase completa se escribe entre comillas dobles dentro de la función, como str_glue(" TEXT AND CODE HERE ")
  • Cualquier código o valor predefinido se coloca entre llaves { } entre comillas dobles. Puede haber muchas llaves dentro de la misma str_glue() comando.

A continuación se muestra un ejemplo sencillo de un título de gráfico dinámico:

ggplot(
  data = surv,
  mapping = aes(x = date_onset))+
geom_histogram()+
labs(caption = str_glue("The data include {nrow(surv)} cases."))

Observa por un momento sólo el str_glue() del comando anterior:

str_glue("The data include {nrow(surv)} cases.")

Observa lo siguiente:

  • El contenido de str_glue() está entre comillas dobles
  • El código R nrow(surv) está entre llaves { } entre comillas

Avanzado str_glue() comandos

Más complejos str_glue() pueden contener varias partes de código, como ésta:

ggplot(
  data = surv,
  mapping = aes(x = date_onset))+
geom_histogram()+
labs(caption = str_glue("The data include {nrow(surv)} cases and are current to {format(max(surv$date_report, na.rm=T), '%d %b %Y')}."))

Observa lo siguiente:

  • Hay dos partes de código incrustado, ambas entre llaves { }. La segunda devuelve la última fecha del informe, formateada para imprimirse como DÍA MES AÑO.
  • Dado que el format() función requiere el uso de comillas, simple para no "romper" las comillas circundantes. doble utilizadas por str_glue()

Un formato alternativo para str_glue() que puede ser más fácil de leer, es utilizar marcadores de posición dentro del { } y define cada uno de ellos en argumentos separados al final de la función str_glue() como se indica a continuación. \n se utiliza para forzar una nueva línea.

ggplot(
  data = surv,
  mapping = aes(x = date_onset))+
geom_histogram()+
labs(
  caption = str_glue(
    "Data include {num_cases} cases and are current to {current_date}.\n{n_missing_onset} cases are missing date of onset and not shown",
    num_cases = nrow(surv),
    current_date = format(Sys.Date(), "%d %b %Y"),
    n_missing_onset = fmt_count(surv, is.na(date_onset))
    )
  )

Explora el uso de format() y símbolos strptime % para ajustar la visualización de la fecha en nuestro capítulo sobre Fechas del Manual de Epi.

r fontawesome::fa("terminal", fill = "black") ¡Te toca!

Practica añadiendo un título o subtítulo a un gráfico de tu informe, utilizando el código que elijas. Escribe el código tú mismo (no copies y pegues) para que entiendas bien la sintaxis.

Parámetros

R Markdown parámetros ("params") te permiten adaptar un informe genérico, o una sección de informe, a una jurisdicción, periodo de tiempo u otro aspecto c que puedas controlar con el YAML.

Esto se hace con params en el YAML. Por ejemplo, podríamos añadir un param a nuestro YAML que contenga el nombre de un distrito, y luego utilizar ese param para filtrar todo el informe para analizar sólo los datos de ese distrito.

Añade más líneas a tu YAML como se muestra a continuación. Ten en cuenta que los dos puntos y la sangría deben ser exactamente correctos.

---
title: "Situation Report"
subtitle: "Ebola outbreak in Sierra Leone"
author: "(Your name or agency here)"
output:
  word_document: default
date: "`r Sys.Date()`"
params:
  district: "West II" 
---

Esto crea un objeto "param" oculto llamado params$district con el valor "Oeste II" que puedes utilizar en tu informe. Puedes establecer este valor en la parte superior del script -en el YAML- y los efectos pueden aparecer en cascada en todo el informe.

Filtrar los datos por distrito

En el YAML, has escrito el parámetro district: "West II". Puedes acceder a este valor en el script mediante params$district.

Añade una sección cerca de la parte inferior de tu script R Markdown que contenga un "análisis de foco" sobre el distrito que se establece en el YAML params.

  • Haz un Encabezamiento y una frase introductoria que presente esta sección como un foco de atención sobre X distrito. Utiliza código en línea para que el nombre del distrito se actualice dinámicamente al imprimirse params$district.
  • En un trozo de código debajo de este texto, empieza con la limpieza surv y pásalo a un marco de datos filter() que la limite sólo a las filas en las que la columna district sea igual a params$district.
  • A continuación, introduce este marco de datos filtrado en un tabyl() que muestre el desglose por hospital y por sexo.

r fontawesome::fa("check", fill = "red")Haz clic para ver la solución (¡pruébalo tú primero!)

En el texto R Markdown escribirías algo como

A continuación se muestran los ingresos hospitalarios de los pacientes notificados en
r knitr::inline_expr("params$district") distrito.

Y en el trozo de código podrías tener un código como éste:

# Spotlight on district defined at top of script in YAML  
surv %>% 
  filter(district == params$district) %>%   # filter data frame to the district in YAML
  tabyl(hospital, sex) %>%                  # begin the cross-tabulation    
  adorn_totals("both") %>%                  # add totals for both rows and columns
  qflextable()

Observa la doble igualdad para comprobar la equivalencia, ==


Ahora tú, o un colega, podéis actualizar el parámetro en el YAML y hacer que el distrito destacado cambie automáticamente.

Tejer con parámetros

Puedes hacer que este proceso sea más fácil de usar utilizando la opción "Tejer con parámetros".

Primero, edita tu YAML para que sea exactamente así. Presta atención a las sangrías (2 espacios cada una) y a la colocación de los dos puntos.

Esto permitirá al usuario elegir un valor para params$district de una lista predefinida.

---
title: "Situation Report"
subtitle: "Ebola outbreak in Sierra Leone"
author: "(Your name or agency here)"
output:
  word_document: default
date: "`r Sys.Date()`"
params:
  district:
    input: select
    value: "West II"
    choices: ["West I", "West II", "West III", "Mountain Rural"] 
---

Ahora haz clic en la opción "Tejer con parámetros".

knitr::include_graphics("images/knit_params.png", error = F)

Deberías ver una ventana emergente que te permite seleccionar uno de los distritos de la lista choices clave YAML.

Con esta interfaz, uno de tus colegas que no sepa R ¡podría incluso ejecutar el informe!

Fin

¡Enhorabuena! ¡Has escrito un informe de situación R Markdown con un montón de código R interesante!

Puedes comparar tu R Markdown con nuestro "backup" en la subcarpeta "scripts/backup".

Continúa con los Extras si tienes tiempo e interés... En particular, ¡para un uso más avanzado de los parámetros!

Extra - Parámetros de fecha

Ésta es una sección algo avanzada. Si te confunde, simplemente céntrate en comprender las técnicas básicas de R Markdown tratadas en secciones anteriores.

Una técnica más avanzada es tener parámetros que manejen fechas. Añade el parámetro publish_date param a tu YAML y pruébalo.

---
title: "Situation Report"
subtitle: "Ebola outbreak in Sierra Leone"
author: "(Your name or agency here)"
output:
  word_document: default
date: "`r Sys.Date()`"
params:
  district:
    input: select
    value: "West II"
    choices: ["West I", "West II", "West III", "Mountain Rural"] 
  publish_date: !r lubridate::ymd("2014-12-01")
---

Fíjate en el uso de !r para indicar el uso de código R en un parámetro. Ten en cuenta también que cualquier función utilizada para interpretar un parámetro (por ejemplo ymd() de {lubridate}) debe llamarse explícitamente con la sintaxis anterior de dos puntos dobles (::). Esto se debe a que el YAML se ejecuta antes de tu comando de carga del paquete. La sintaxis de los dos puntos dobles carga el paquete para utilizarlo en esa línea.

Ahora puedes utilizar params$publish_date de clase "Fecha", en tu informe.

Cambia la viñeta Resumen "Acerca de este informe" para que muestre params$publish_date en lugar de Sys.Date().

De nuevo, haz clic en "Tejer con parámetros", y verás cómo este parámetro puede ser seleccionado por el usuario mediante una interfaz de calendario.

Selecciona una fecha límite adecuada

Añadamos un filtro en surv utilizando params$publish_date tal que sólo los casos notificados antes de una fecha se incluyan en el informe.

Supongamos lo siguiente

  • Las semanas epidemiológicas de este brote comienzan el Lunes
  • Suele haber 3 días de retraso en la notificación de casos a esta lista.

Aplicaremos este umbral: Sólo incluye casos de los últimos completo y fiable semana epidemiológica, teniendo en cuenta un retraso de 3 días en la notificación.

Utiliza el calendario siguiente:

knitr::include_graphics("images/calendar.png", error = F)
  • Si el informe se publica la mañana del jueves 27 de noviembre, el último día fiable de datos es el domingo 23 de noviembre, y el último día completo semana epi más reciente es del 17 al 23 de noviembre.
  • Si el informe se publica la mañana del miércoles 3 de diciembre, el último día fiable de datos es el sábado 29 de noviembre, y el último completo semana epi sigue siendo del 17 al 23 de noviembre.
  • Si el informe se publica el jueves 4 de diciembre, la semana epi completa más reciente es del 24 al 30 de noviembre.

Lógica del filtro

Para aplicar un filtro de fecha a surv basta con añadir un filter() línea al final de tu comando de limpieza.

Inicia el filtro de forma sencilla, incluyendo sólo fechas sin informar de retrasos. Incluimos fechas anteriores a ( < ) 3 días antes de la fecha de publicación):

(your cleaning pipe chain...) %>% 
filter(date_report < params$publish_date - 3)

Si tu fecha de publicación es el 3 de diciembre, esto debería mantener sólo los casos notificados el sábado 29 de noviembre o antes. Puedes comprobarlo ejecutando max(surv$date_report, na.rm=TRUE).

Redondea a la semana

Puedes utilizar el botón floor_date() de la función {lubridate} para "redondear" al principio de la semana (o del mes, día, año, etc.).

  • Establece el unit = "week" para redondear hacia abajo al inicio de la semana
  • Establece el week_start = argumento a 1 para que las semanas empiecen los lunes
(your cleaning pipe chain...) %>% 
filter(date_report < floor_date(params$publish_date - 3,
                                 unit = "week",
                                 week_start = 1))

Con una fecha de publicación del 3 de diciembre, el máximo date_report debe ser el 23 de noviembre. Si la fecha de publicación es el 4 de diciembre, el máximo debe ser el 30 de noviembre.

Incluir o excluir las fechas que faltan

¿Qué hizo tu filtro con las filas a las que les faltaba la fecha del informe? Se excluían por defecto, porque no se trataban específicamente en la declaración lógica del filtro.

Observa que no quedan filas NA.

summary(surv$date_report)

Para conservar estas filas, añade | is.na(date_report) a tu comando de filtro, como se indica a continuación. Esto se traduce como "...O, donde date_report es NA"

(your cleaning pipe chain...) %>% 
filter(date_report < floor_date(params$publish_date - 3,
                                unit = "week",
                                week_start = 1) | is.na(date_report))

Observa cómo al volver a ejecutar ahora la orden de limpieza se obtienen más observaciones.

summary(surv$date_report)

Más extras

Cuarto

La empresa Posit, que fabrica RStudio y ayudó a desarrollar R Markdown, está produciendo ahora un nuevo tipo de script llamado Quarto.

La sintaxis Quarto es muy similar a R Markdown. Hemos optado por enseñarte R Markdown porque Quarto aún es relativamente nuevo. Sin embargo, en los próximos años Quarto será donde se produzca la mayor parte de las nuevas innovaciones.

Aunque puedes escribir código Python, SQL y Julia en trozos de R Markdown, esto será más ágil en los scripts de Quarto.

Lee sobre Quarto ¡y pruébalo si quieres! Sólo tienes que ir a "Nuevo archivo" y seleccionar "Documento Quarto".

Matices de la importación/exportación de datos en R Markdown

R Markdown es un ámbito en el que utilizar el paquete {here} y su función here() para importar/exportar datos es muy útil.

Muchos usuarios antiguos de R aprendieron el concepto de "directorio de trabajo", es decir, la ubicación en tus carpetas que es el punto de partida de las rutas de los archivos para importar/exportar. También aprendieron el {base} funciones de R getwd() (para imprimir tu directorio de trabajo actual) y setwd() (para definir un nuevo directorio de trabajo). Applied Epi anima a los participantes en nuestros cursos a que conozcan estas dos funciones, pero que en su lugar utilicen proyectos de RStudio y las funciones here() del proyecto {here} paquete. Utilizadas conjuntamente, todas las rutas de archivos comienzan desde un punto de partida coherente (la parte superior/"raíz" del proyecto RStudio).

Con los guiones Markdown de R se utiliza here() es especialmente ventajoso por dos razones:

El directorio de trabajo

La primera razón es que simplifica la forma de especificar las rutas de los archivos en tu script RMD. A diferencia de los scripts .R normales, el directorio de trabajo de un script R Markdown es la carpeta que contiene el script .Rmd. Esto significa que si tus datos están almacenados en una carpeta "data/" separada, puede ser difícil escribir un comando que dirija R hacia el conjunto de datos.

¡Compruébalo tú mismo! Ejecuta el comando getwd() desde dentro de un fragmento de código R - deberías ver que esta ruta continúa hasta la carpeta "rmd_course/scripts/" (donde se encuentra este .Rmd). Compáralo con abrir un nuevo script .R "normal" y ejecutar getwd() - allí sólo deberías ver la raíz del proyecto RStudio.

Intenta ejecutar este comando en el trozo para importar datos (observa la ausencia de here()):

# this will NOT work to import your data, from an Rmd in the scripts subfolder
surv <- import("data/clean/surveillance_linelist_clean_20141201.rds")

Este comando no funciona porque desde el punto de partida del directorio de trabajo del trozo (la carpeta scripts) no hay ninguna carpeta "datos" en la que entrar.

Una mala forma de resolver este problema

¿Cómo le dirías a R que navegue hacia atrás de la carpeta "scripts/" e importar el archivo en "course_rmd/data/clean/surveillance_linelist_clean_20141201.rds"?

El comando siguiente es un método "alternativo" que es frágil y se romperá fácilmente. Sólo te lo mostramos porque puede que te lo encuentres con otros programadores de R.

Los dos puntos "../" en la ruta del archivo indican a R que "suba" una carpeta desde el directorio de trabajo (ubicación del archivo .Rmd), y que luego vaya a la carpeta "data/", a la carpeta "clean/" y al conjunto de datos. ¡Atención! Si el script .Rmd se mueve a cualquier otro lugar, ¡este comando puede no funcionar!

# fragile import command that goes "up" one folders from the Rmd location
surv <- import("../data/clean/surveillance_linelist_clean_20141201.rds")

Una solución mejor con here()

A continuación encontrarás un comando mejor. Utiliza here() para iniciar siempre la ruta del archivo desde la carpeta raíz del proyecto RStudio. Esto es flexible: ¡este comando navegará correctamente a la carpeta "data/raw/" independientemente de dónde se encuentre el script!

# robust, relative import command that always starts from the R project root
surv <- import(here("data", "clean", "surveillance_linelist_clean_20141201.rds"))

Puedes leer más sobre here() en este capítulo del Manual de Epi R y en el documentación del paquete.

here() tal y como se han escrito anteriormente (sin barras), tienen la ventaja añadida de que se adaptan automáticamente a la dirección de las barras del ordenador que ejecuta el comando.

setwd() no es persistente en R Markdown

En segundo razón por la que es mejor utilizar here() dentro de los scripts R Markdown, es que utilizando setwd() para cambiar el directorio de trabajo en un trozo ¡no lo cambia para todos los chunks!

Poniendo setwd() en un trozo de R Markdown sólo cambiará el directorio de trabajo para ese fragm ¡!

Hay formas más complejas de solucionar esto, pero utilizando here() es una forma mucho más fácil y sólida de resolver este problema.

Nombres de trozos

Existe una función opcional para nombrar los trozos de código. Animamos a los principiantes en R Markdown a no utilicen esta función porque puede dar lugar a más errores, si no tienes cuidado.

Para dar un nombre al trozo, escribe el nombre en la línea que inicia el trozo (que comienza con tres puntos suspensivos). Dentro de las llaves { }, escribe el nombre después de la "r" pero antes de la coma ¡! Puedes escribir los nombres que desees, siempre que respeten ciertas reglas.

Los nombres de los trozos NO aparecen en la salida de tu informe. Se trata de un malentendido habitual.

Ventajas de utilizar nombres de trozos

  • Pueden ayudarte a organizar tu código
  • Puedes ver los nombres en la herramienta de navegación por fragmentos, que puedes pulsar en la parte inferior de tu script
  • Si hay un mensaje de error, devolverá el nombre del trozo. Si no hay nombres, devolverá el número de línea.

Haz clic en la herramienta de navegación por fragmentos de la parte inferior del guión para revisar todos los fragmentos de tu guión".

knitr::include_graphics("images/names1.png", error = F)

Desventajas de utilizar nombres de trozos

  • Pueden dar lugar a más errores al tejer, si no tienes cuidado de seguir sus reglas de denominación.

Reglas sobre la denominación de los trozos

  • Nombres de trozos no pueden contener espacios. Knitting devolverá un error si hay espacios.
  • En no puede haber dos trozos con el mismo nombre. Este es un error común, porque los usuarios suelen copiar y pegar trozos dentro del script.

Tejer en PDF

Tejer directamente a PDF puede ser más difícil y puedes encontrar más problemas con el formato. Para probarlo, ejecuta los siguientes comandos en tu Consola para instalar el software "tinytex" (si los escribes en un trozo de código R en tu script, pon un # para desactivarlos después de ejecutarlos):

# installs tinytex, to C: location
tinytex::install_tinytex() 

# checks for installation; should return TRUE (note three colons)
tinytex:::is_tinytex()

Recuerda que siempre puedes tejer a Word, y luego convertir a PDF.

Añadir una tabla manual

Sólo para tu información, revisa el contenido a continuación. No es necesario que lo introduzcas en tu informe.

Puedes añadir tablas "manuales" o "estáticas" en un informe. Puedes hacerlo fácilmente en modo Visual (pero cuidado con cambiar después entre modo Visual y Fuente), o en modo Fuente utilizando | para designar las columnas y guiones - para separar la fila de cabecera e indicar la anchura que debe tener cada columna.

| Agencia de respuesta | Dirección | Punto de contacto | | ----------------------------- | ------------------------------------- | --------------------- | | Departamento de Sanidad | 107 S. Broad Street | Malaya Gonzales | | Servicios Médicos de Urgencia | 89 Rue de l'Independence | François Cartier | | Cuerpo de bomberos | 2000 Center Drive | Sargento Kamala Brown |

La tabla anterior fue creada en Modo Fuente con el siguiente código. Prueba a pegarlo en tu script y ajustar el número de - guiones. Observa cómo cambia la anchura de la columna.

| Response Agency        | Address             | Point of Contact |
| ---------------------- | ------------------- | -----------------|
| Department of Health   | 107 S. Broad Street | Malaya Gonzales |
Emergency Medical Services | 89 Rue de l'Independence | Francois Cartier
|Fire Department | 2000 Center Drive | Sgt. Kamala Brown

Ten en cuenta que este enfoque de las tablas es estática. Estas tablas no cambian automáticamente y no están vinculadas a ningún objeto R o conjunto de datos.

Más adelante, revisaremos las opciones para presentar tablas de datos o tablas resumen utilizando paquetes R, dentro de trozos de código R.

Consejos de formato

Si quieres insertar líneas o espacios vacíos adicionales en tu documento, inserta </br> en las partes de texto de tu Rmd. Puedes escribir varias de estas líneas para obtener más espacio.

Si quieres designar un salto de página (no se aplica a HTML), inserta \pagebreak en una línea Markdown texto (no en un fragmento de código).

Personalización de informes HTML

Si quieres renderizas tu informe en H prueba las siguientes personalizaciones

Índice (TOC)

Puedes añadir un índice de contenidos utilizando el YAML toc y especifica la profundidad de las cabeceras con toc_depth.

Si no se especifica explícitamente la profundidad del índice, por defecto es 3 (lo que significa que todos los encabezados de nivel 1, 2 y 3 se incluirán en el índice).

TOC flotante

Para informes largos, puede que quieras poder ver el índice de contenidos aunque te desplaces hacia abajo. Puedes especificar el toc_float para que el índice de contenidos esté siempre visible aunque se desplace el documento.

---
title: "Surveillance Report"
author: "Your name or agency here"
date: "`r Sys.Date()`"
output: 
  html_document:
    toc: TRUE
    toc_float: TRUE
---

Numeración de secciones

Puedes añadir numeración de secciones a los encabezados utilizando number_sections: TRUE en el YAML, debajo del html_report con las demás opciones.

Ten en cuenta que si decides utilizar number_sections es probable que también quieras hacer los encabezados de nivel superior con una sola almohadilla # (H1), porque los encabezados ## (H2) incluirán un punto decimal si no hay encabezados H1 (0,1, 0,2, etc.).

Tabulaciones

Para crear pestañas clicables en el documento, basta con añadir .tabset entre llaves { } que se colocan después de un encabezamiento. Todos los subtítulos situados bajo ese encabezamiento (hasta otro encabezamiento del mismo nivel) aparecerán como pestañas en las que el usuario puede hacer clic.

Esta función puede hacer que el informe tenga un aspecto muy elegante.

¡Pruébalo! Añade {.tabset} al encabezamiento # Resumen, cerca de la parte superior de tu informe.

Cuando vuelvas a unir, los encabezamientos de segundo nivel (##) de "Acerca de este informe", "Importación y limpieza de datos" y "Números clave" ¡deberían aparecer como pestañas en las que se puede hacer clic!

Mayor personalización

Practiquemos personalizando algunos aspectos de nuestro informe:

  • Añade un subtítulo añadiendo un subtitle: campo
  • En html_document: añade una tabla de contenido utilizando toc opción
  • Utiliza toc_float para que tu tabla de contenido esté siempre visible

Tu YAML tendrá un aspecto similar al siguiente:

---
title: "Surveillance Report"
subtitle: "Using Advanced R Markdown Options"
author: "Your name or agency here"
date: "`r Sys.Date()`"
output: 
  html_document:
    toc: TRUE
    toc_float: TRUE
---

r fontawesome::fa("eye", fill = "darkblue") Observa la colocación de sangrías de 2 espacios debajo de output:. El espaciado correcto es importante para la sintaxis YAML, de lo contrario tu código no se ejecutará.

quiz(caption = "Quiz - YAML",
  question("What does `toc_depth: 2` do? ",
    allow_retry = T,
    answer("Shows level 1 and level 2 headers in table of contents",
           correct = T,
           message = ""),
    answer("Makes table of contents visible throughout a long document", 
           correct = F,
           message = "This is what `toc_float:` option does"),
    answer("Shows only two code chunks",
           correct = F), 
    answer("All of the above",
           correct = F)
  )
)

Plegado del código

Dependiendo de tu público, a veces puedes querer tener una opción de mostrar el código R de tu análisis en el informe.

Si estableces echo = FALSE en el trozo de código R "configuración", puede resultar abrumador mostrar TODO el código.

Una buena opción intermedia es el code_folding para salidas HTML.

1) Ajusta tu YAML para que en html_document: tengas code_folding: hide

---
title: "Surveillance Report"
subtitle: "Using Advanced R Markdown Options"
author: "Your name or agency here"
date: "`r Sys.Date()`"
output: 
  html_document:
    toc: TRUE
    toc_float: TRUE
    code_folding: hide
---

2) Es importante que también cambies el fragmento de código R "configuración" para que echo = TRUE.

3) Knit tu documento.

Deberías ver pequeños iconos "Mostrar" a la derecha de las secciones del informe, que al hacer clic revelarán el código de esa sección. Por ejemplo, mira la sección "Números clave", cerca de la parte superior.

knitr::include_graphics("images/code_folding.png", error = F)

En la parte superior derecha del informe también verás un botón "Código" que ofrece un menú para "Mostrar todo el código" u "Ocultar todo el código".

Puedes leer más sobre el plegado de código aquí

Temas

Puedes utilizar theme para cambiar el tema por defecto de tu documento. Los temas válidos son por defecto, bootstrap, cerulean, cosmo, darkly, flatly, journal, lumen, paper, readable, sandstone, simplex, spacelab, united y yeti.

r fontawesome::fa("terminal", fill = "black") ¡Te toca!

Ahora, sigue adelante y edita tu YAML para cambiar al tema por defecto de tu que elijas.

r fontawesome::fa("check", fill = "red")Haz clic para ver una solución (prueba ¡primero tú mismo!)


---
title: "Surveillance Report"
subtitle: "Using Advanced R Markdown Options"
author: "Your name or agency here"
date: "`r Sys.Date()`"
output: 
  html_document:
    toc: TRUE
    toc_float: TRUE
    theme: "cerulean"
    code_folding: hide
---


Archivos README

La mayoría de las carpetas deberían tener un archivo README que explique qué contiene la carpeta, cómo se actualiza, cómo se utiliza, etc.

  • En un proyecto acabado, el LÉAME debe ayudar a los usuarios a navegar y comprender el contenido.
  • En una plantilla de proyecto, ¡el LÉAME contiene instrucciones para que puedas configurar el proyecto!

Para practicar, añade un archivo .txt llamado README.txt a la carpeta raíz del proyecto o a la carpeta de scripts. Escribe una breve descripción de cómo un colega puede ejecutar correctamente el informe utilizando los datos de casos más actualizados.

Puedes hacerlo abriendo NotePad o un programa similar, introduciendo el texto y guardándolo en la carpeta. Si no encuentras un editor de texto plano, puedes utilizar Microsoft Word.



appliedepi/introexercises documentation built on April 22, 2024, 1:01 a.m.

R Package Documentation

rdrr.io home R language documentation Run R code online

Browse R Packages

CRAN packages Bioconductor packages R-Forge packages GitHub packages

We want your feedback!

Note that we can't provide technical support on individual packages. You should contact the package authors for that.
GitHub issue tracker
ian@mutexlabs.com
Personal blog

 
Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.

Close