Informes de tu trabajo

El primer ejemplo de informe que vimos se convirtió en un archivo html. Pero ¿qué pasa con los archivos Word o PDF, que pueden ser más útiles o esperados en algunas situaciones? Quarto, y todo un ecosistema de otras herramientas, permite generar documentos en múltiples formatos utilizando el mismo archivo de texto plano.

La forma de generar el formato del archivo de salida es cambiando la opción format del encabezado.

Vuelve al informe de ejemplo y busca el bloque format: del encabezado. Reemplazalo por format: pdf. Guarda el archivo y hacé clic en el botón Render (la flecha azul) en la parte superior del documento.

También podés tener varios formatos disponibles al mismo tiempo, sin necesidad de editar el encabezado cada vez que querés cambiar de uno a otro. Si escribís algo así en el YAML:

format:
  html: default
  pdf: default
  docx: default

el botón Render va a mostrar una flechita a la derecha con un menú desplegable donde podés elegir a qué formato renderizar.

Ahora agregá docx: default junto a los otros formatos en el encabezado y usá el menú del botón Render para generar un documento de Word. ¿Qué cambios ves en el encabezado del archivo?

Control del código

Nuestro ejemplo parece bastante ordenado. Hemos ocultado todo el código y los mensajes de R para que puedas concentrar tu atención en la tabla y las figuras. Pero este no es el comportamiento por defecto de un archivo Quarto. Por lo general, la salida tendrá tanto el código como su resultado, lo cual está bien cuando vos o la persona que leerá el informe quiere ver el código que genera esos resultados, pero podría no ser lo que la audiencia final del informe podría necesitar. Vos decidís si querés mostrar el código o no.

Para cambiar las opciones de un chunk de código en Quarto, se escriben dentro del mismo chunk, en líneas que empiezan con #| (se las conoce como opciones “estilo Quarto”). Por ejemplo:

```{r}
#| echo: false
#| message: false

```

Si estás trabajando con el editor visual de RStudio no necesitás escribir estas líneas a mano: cada chunk tiene, arriba a la derecha, un ícono con forma de engranaje ⚙️ que abre un panel con las opciones más comunes (mostrar u ocultar el código, los mensajes, las advertencias, etc.) para que las marques con un clic.

Un conjunto de opciones particularmente importante son las que controlan si el código se ejecuta y si el resultado del código permanecerá en el informe o no:

eval: false impide que se ejecute el código del chunk, por lo que tampoco mostrará los resultados. Es útil para mostrar código de ejemplo si estás escribiendo, por ejemplo, un documento para enseñar R.
echo: false ejecuta el código del chunk y muestra los resultados, pero oculta el código en el informe. Esto es útil para escribir informes para personas que no necesitan ver el código R que generó el gráfico o la tabla.
include: false ejecuta el código pero oculta tanto el código como los resultados. Es útil para configuración general donde se cargan las librerías.

Si estás escribiendo un informe en el que no quieres que se muestre ningún código, añadir #| echo: false a cada nuevo chunk se vuelve tedioso. La solución es cambiar la opción globalmente para que se aplique a todos los chunks. En Quarto esto se hace directamente en el encabezado YAML del documento, con la opción execute, sin necesidad de escribir ningún código de R:

execute:
  echo: false
  message: false
  warning: false

¿Tienes curiosidad por saber cómo funcionan las opciones? Agregá el bloque execute de arriba al encabezado de tu documento (junto a format), cambiá los valores de una en una y volvé a hacer clic en Render cada vez para ver qué cambia.

Automatización

Al principio de este taller te pedimos que cambiaras el cultivar en el informe de ejemplo. La tarea no fue fácil porque “ACA 861” aparece varias veces y es fácil equivocarse. Parametrizar un informe nos permite definir ese tipo de parámetros en un solo lugar y obtener diferentes análisis a partir del mismo archivo.

Para generar un informe parametrizado hay que añadir un elemento llamado params a la cabecera con la lista de parámetros y sus valores por defecto.

params:
  cultivar: ACA 861

A partir de ahora, tendrás acceso a una variable llamada params que es una lista que contiene los parámetros y su valor. Para acceder al valor de cada parámetro se utiliza el operador $ de la siguiente manera:

params$cultivar

[1] "ACA 861"

De este modo, el código original puede modificarse para utilizar el valor de la especie almacenada en params$cultivar.

cultivares |> 
  filter(Cultivar == params$cultivar) |> 
  ggplot(aes(x = Rendimiento_Ajustado, y = Aceite_porcentaje)) +
  geom_point(color = "darkorange",
             size = 3,
             alpha = 0.8) +
  geom_smooth(method = "lm", se = FALSE, color = "darkorange") +
  theme_minimal() +
  labs(title = "Rendimiento y porcentaje de aceite",
       subtitle = paste("Cultivar", params$cultivar),
       x = "Rendimiento Ajustado (kg/ha)",
       y = "Porcentaje de Aceite (%)",
       color = "Cultivar")

Aquí cambiamos el subtítulo para concatenar palabras con el valor almacenado en params$cultivar, de esta manera podemos construir el subtítulo de forma programática.

Ahora el informe está listo para funcionar como un informe parametrizado.

Por último, cambia “ACA 861” en el yaml para generar un nuevo informe para una de las otras especies y hacé clic en Render.

Publicación

Querés compartir tus resultados y tenés un archivo Quarto en el que estuviste trabajando. Podrías compartir la carpeta del proyecto o un link a un repositorio pero sería ideal que cualquier persona pueda ver esos hermosos resultados sin necesidad de correr código. La otra alternativa es renderizar el documento (con el botón Render) para compartir un PDF o archivo de Word. Las opciones no terminan ahí, Quarto abre un mundo de posibilidades para trabajar con código de R (¡o de Python, Julia u Observable!), texto y además compartir los resultados (y cualquier otra cosa!).

Sitio web de una sola página

Si sabés cómo generar un reporte en formato html usando Quarto, ¡ya sabés todo lo que necesitás para publicar un sitio web simple! Lo único que hace falta es un servicio que hostee el archivo y lo muestre a los visitantes. Uno de ellos es Netlify, que permite crear un sitio web con sólo arrastrar una carpeta.

Pequeño detalle: seguramente tu reporte (tu archivo Quarto) tiene algún nombre descriptivo consistente con su contenido. Para que convertirlo en una página web el archivo tiene que tener un nombre especial: “index.html”. Adelante, nombrá a tu documento como index.qmd y hacé clic en Render para generar el HTML como de costumbre.

Ahora deberías tener como resultado archivo llamado “index.html” en la carpeta de tu proyecto. ¡Felicitaciones! Creaste tu primer página web.

Publicación

Solo falta publicar tu página web para no viva solo en tu computadora. Veamos como se hace en Netlify.

Entrá a https://app.netlify.com/drop y arrastrar la carpeta que contiene el archivo index.html en el recuadro. Netlify va a crear una página web con un nombre aleatorio y posiblemente imposible de deletrear, pero está publicada!

Aqui hay un video con los pasos a seguir

Tal vez notaste que Netlify borra los sitios web luego de 24 horas. Para que tu sitio sea permanente tenés que crearte una cuenta en Netlify. Eso además te va a permitir cambiarle el nombre a tu página, por ejemplo agroreporte.netlify.app

Publiquemos nuestro reporte en la web! Compartan el link a su pagina web :-)

--- title: "Informes de tu trabajo" format: html: code-tools: true toc: true toc-location: body highlight-style: tango --- ```{r setup, include=FALSE} knitr::opts_chunk$set(echo = TRUE) chunk <- "```" ``` El primer ejemplo de informe que vimos se convirtió en un archivo html. Pero ¿qué pasa con los archivos Word o PDF, que pueden ser más útiles o esperados en algunas situaciones? Quarto, y todo un ecosistema de otras herramientas, permite generar documentos en múltiples formatos utilizando el mismo archivo de texto plano. La forma de generar el formato del archivo de salida es cambiando la opción `format` del encabezado. > Vuelve al informe de ejemplo y busca el bloque `format:` del encabezado. Reemplazalo por `format: pdf`. Guarda el archivo y hacé clic en el botón **Render** (la flecha azul) en la parte superior del documento. También podés tener varios formatos disponibles al mismo tiempo, sin necesidad de editar el encabezado cada vez que querés cambiar de uno a otro. Si escribís algo así en el YAML: ```yaml format: html: default pdf: default docx: default ``` el botón **Render** va a mostrar una flechita a la derecha con un menú desplegable donde podés elegir a qué formato renderizar. > Ahora agregá `docx: default` junto a los otros formatos en el encabezado y usá el menú del botón Render para generar un documento de Word. ¿Qué cambios ves en el encabezado del archivo? ## Control del código Nuestro ejemplo parece bastante ordenado. Hemos ocultado todo el código y los mensajes de R para que puedas concentrar tu atención en la tabla y las figuras. Pero este no es el comportamiento por defecto de un archivo Quarto. Por lo general, la salida tendrá tanto el código como su resultado, lo cual está bien cuando vos o la persona que leerá el informe quiere ver el código que genera esos resultados, pero podría no ser lo que la audiencia final del informe podría necesitar. Vos decidís si querés mostrar el código o no. Para cambiar las opciones de un chunk de código en Quarto, se escriben dentro del mismo chunk, en líneas que empiezan con `#|` (se las conoce como opciones "estilo Quarto"). Por ejemplo: `r chunk`{r} #| echo: false #| message: false `r chunk` Si estás trabajando con el editor visual de RStudio no necesitás escribir estas líneas a mano: cada chunk tiene, arriba a la derecha, un ícono con forma de engranaje ⚙️ que abre un panel con las opciones más comunes (mostrar u ocultar el código, los mensajes, las advertencias, etc.) para que las marques con un clic. Un conjunto de opciones particularmente importante son las que controlan si el código se ejecuta y si el resultado del código permanecerá en el informe o no: * `eval: false` impide que se ejecute el código del chunk, por lo que tampoco mostrará los resultados. Es útil para mostrar código de ejemplo si estás escribiendo, por ejemplo, un documento para enseñar R. * `echo: false` ejecuta el código del chunk y muestra los resultados, pero oculta el código en el informe. Esto es útil para escribir informes para personas que no necesitan ver el código R que generó el gráfico o la tabla. * `include: false` ejecuta el código pero oculta tanto el código como los resultados. Es útil para configuración general donde se cargan las librerías. Si estás escribiendo un informe en el que no quieres que se muestre ningún código, añadir `#| echo: false` a cada nuevo chunk se vuelve tedioso. La solución es cambiar la opción globalmente para que se aplique a todos los chunks. En Quarto esto se hace directamente en el encabezado YAML del documento, con la opción `execute`, sin necesidad de escribir ningún código de R: ```yaml execute: echo: false message: false warning: false ``` > ¿Tienes curiosidad por saber cómo funcionan las opciones? Agregá el bloque `execute` de arriba al encabezado de tu documento (junto a `format`), cambiá los valores de una en una y volvé a hacer clic en **Render** cada vez para ver qué cambia. ## Automatización Al principio de este taller te pedimos que cambiaras el cultivar en el informe de ejemplo. La tarea no fue fácil porque "ACA 861" aparece varias veces y es fácil equivocarse. Parametrizar un informe nos permite definir ese tipo de parámetros en un solo lugar y obtener diferentes análisis a partir del mismo archivo. Para generar un informe parametrizado hay que añadir un elemento llamado `params` a la cabecera con la lista de parámetros y sus valores por defecto. ```yaml params: cultivar: ACA 861 ``` ```{r, include=FALSE} params <- list(cultivar = "ACA 861") ``` A partir de ahora, tendrás acceso a una variable llamada `params` que es una lista que contiene los parámetros y su valor. Para acceder al valor de cada parámetro se utiliza el operador `$` de la siguiente manera: ```{r} params$cultivar ``` De este modo, el código original puede modificarse para utilizar el valor de la especie almacenada en `params$cultivar`. ```{r eval=FALSE} cultivares |> filter(Cultivar == params$cultivar) |> ggplot(aes(x = Rendimiento_Ajustado, y = Aceite_porcentaje)) + geom_point(color = "darkorange", size = 3, alpha = 0.8) + geom_smooth(method = "lm", se = FALSE, color = "darkorange") + theme_minimal() + labs(title = "Rendimiento y porcentaje de aceite", subtitle = paste("Cultivar", params$cultivar), x = "Rendimiento Ajustado (kg/ha)", y = "Porcentaje de Aceite (%)", color = "Cultivar") ``` Aquí cambiamos el subtítulo para concatenar palabras con el valor almacenado en `params$cultivar`, de esta manera podemos construir el subtítulo de forma programática. Ahora el informe está listo para funcionar como un informe parametrizado. > Por último, cambia "ACA 861" en el yaml para generar un nuevo informe para una de las otras especies y hacé clic en **Render**. ## Publicación Querés compartir tus resultados y tenés un archivo Quarto en el que estuviste trabajando. Podrías compartir la carpeta del proyecto o un link a un repositorio pero sería ideal que cualquier persona pueda ver esos hermosos resultados sin necesidad de correr código. La otra alternativa es renderizar el documento (con el botón **Render**) para compartir un PDF o archivo de Word. Las opciones no terminan ahí, Quarto abre un mundo de posibilidades para trabajar con código de R (¡o de Python, Julia u Observable!), texto y además compartir los resultados (y cualquier otra cosa!). ## Sitio web de una sola página Si sabés cómo generar un reporte en formato html usando Quarto, ¡ya sabés todo lo que necesitás para publicar un sitio web simple! Lo único que hace falta es un servicio que *hostee* el archivo y lo muestre a los visitantes. Uno de ellos es [Netlify](https://www.netlify.com/), que permite crear un sitio web con sólo arrastrar una carpeta. **Pequeño detalle:** seguramente tu reporte (tu archivo Quarto) tiene algún nombre descriptivo consistente con su contenido. Para que *convertirlo* en una página web el archivo tiene que tener un nombre especial: "index.html". Adelante, nombrá a tu documento como `index.qmd` y hacé clic en **Render** para generar el HTML como de costumbre. Ahora deberías tener como resultado archivo llamado "index.html" en la carpeta de tu proyecto. ¡Felicitaciones! Creaste tu primer página web. ### Publicación Solo falta publicar tu página web para no viva solo en tu computadora. Veamos como se hace en Netlify. Entrá a <https://app.netlify.com/drop> y arrastrar la carpeta que contiene el archivo index.html en el recuadro. Netlify va a crear una página web con un nombre aleatorio y posiblemente imposible de deletrear, pero está publicada! [Aqui hay un video con los pasos a seguir](https://www.youtube.com/watch?v=hZ8TpfcL1l8) Tal vez notaste que Netlify borra los sitios web luego de 24 horas. Para que tu sitio sea permanente tenés que crearte una cuenta en Netlify. Eso además te va a permitir cambiarle el nombre a tu página, por ejemplo agroreporte.netlify.app > Publiquemos nuestro reporte en la web! Compartan el link a su pagina web :-)