Quarto+Markdown
El lenguaje básico de la ciencia de datos y la docencia interactiva
Introducción
En esta sesión vamos a conocer algunas de las características básicas de Quarto y Markdown, dos lenguajes de marcado que permiten crear documentos dinámicos e interactivos para la docencia y la investigación reproducible.
Sé por ciencia cierta que muchos de vosotros emplean modelos de inteligencia artificial. Todos esos modelos utilizan un lenguaje para generar sus textos o para recibir instrucciones. Algunos me preguntan: “Rodrigo, por qué usas # para referirte a las partes del prompt.” Bueno, llegó la hora de saber exactamente porqué.
¿Para qué sirve?
¿Tienes una asignatura y querías crear una página web rápidamente sin aprender html? ¿Quieres hacer un informe de notas de los 50 estudiantes que tienes de forma rápida y automática? ¿Quieres crear una presentación de Powerpoint con gráficos interactivos? ¿Quieres escribir un artículo académico de forma que se ajuste a distintos formatos de revista y citación de modo rápido? ¿Quieres que tu informe cambie y se adapte a los datos que tienes? Bueno, Quarto sirve para todo esto. En este curso introductorio veremos algunas aplicaciones de Quarto que son particularmente útiles para docentes e investigadores.
Quarto: ¿qué es?
Además de habitación y un número ordinal en portugués, Quarto es una fusión ampliada y extendida de RMarkdown y Jupyter Notebooks. Se trata de un programa, una extensión a RStudio y otros editores de texto, diseñado para científicos de datos que trabajen tanto con Python como con R y que deseen generar documentos empleando los dos lenguajes de programación sin problemas de compatibilidad. Aunque parezca confuso a la primera vista, se trata de un esfuerzo de estandarización en el formato de creación de documentos en esos dos lenguajes del que nos beneficiamos todos.
El lenguaje básico de Quarto es Markdown, un lenguaje de marcado ligero que permite crear documentos con formato de texto plano. Quarto añade a Markdown la capacidad de incluir bloques de código en R, Python y otros lenguajes, así como la posibilidad de generar documentos en múltiples formatos (HTML, PDF, Word, etc.) a partir del mismo archivo fuente.
La magia está en poder programar directamente en el documento. Si quieres hacer un gráfico, no necesitar crear el gráfico, exportar en formato imagen y pegarlo en el documento. El programa integra todo. Si cambian los datos, el gráfico se actualiza automáticamente. Por ejemplo, si cambio los datos de Brasil a Perú, el gráfico pasa de reflejar los indicadores de un país al otro.
El video abajo ofrece una primera introducción:
Markdown
El lenguaje Markdown es un lenguaje de marcado ligero que permite crear documentos con formato de texto plano. Fue creado por John Gruber en 2004 con el objetivo de facilitar la escritura y lectura de documentos en formato HTML sin necesidad de conocer el lenguaje HTML en profundidad. Su sencillez lo convierte en un instrumento potente de escritura, puesto que permite formatear un texto de forma rápida y sencilla utilizando caracteres especiales. Por ejemplo, para crear un encabezado de nivel 1, se utiliza el símbolo # seguido del texto del encabezado. Para crear una lista con viñetas, empleamos - o * seguido del texto de cada elemento de la lista.
Por ejemplo, el siguiente texto:
Este texto está escrito para incluir formatación y ecuaciones \(\overline{x}=\sum{x_i}/N\). De ese modo, podemos resaltar la utilidad de un lenguaje que permite configurar el texto.
Incluso podemos tener una tabla:
| ID | Ciudad |
|---|---|
| 1 | Salamanca |
| 2 | Madrid |
| 3 | Barcelona |
Podemos también citar directamente a autores como Benoit (2020) sobre el análisis cuantitativo de textos.
En su formato en markdown sería:
Este **texto** está escrito para incluir *formatación* y ecuaciones $\overline{x}=\sum{x_i}/N$. De ese modo, podemos resaltar la utilidad de un [lenguaje que permite configurar el texto]{style=“background-color:red;color:white”}
Incluso podemos tener una tabla:
| ID | Ciudad |
| –: |:——-|
| 1 | Salamanca |
| 2 | Madrid |
| 3 | Barcelona |
Podemos también citar directamente a autores como Benoit [-@benoit2020] sobre el análisis cuantitativo de textos.
Con la IA, Markdown incluso ayuda a estructurar de forma más clara las instrucciones que le damos a los modelos. También los resultados de la IA son generados en Markdown.
Copia y pega este texto en chatGPT o en otro modelo de lenguaje:
Cuenta el cuento de la lechera en un párrafo imitando el estilo de Iker Jiménez. Añade énfasis y títulos.
Una vez terminado de generar el texto, haz clic en el botón de copiar que aparece abajo de la respuesta y pega el texto generado en un editor de texto (Notepad o similar).
Verás que el texto generado está en formato Markdown. Puedes pegarlo directamente en un editor de Quarto o RMarkdown y generar un documento con formato automáticamente.
Además, es sencillo de aprender. En Quarto, se convierte en un ambiente muy agradecido. Puedo meter código html, latex, R, Python, Javascript, todo en un script Quarto y simplemente funciona.
Ahorra nuestro tiempo y evita preguntas del tipo:
“Si ya sé Word, ¿por qué debo aprender Markdown?”
Si tienes esta duda existencial, creo que debes mudarte al Tibet y hacer meditación profunda por unos años hasta encontrar el chacra o cosa parecida. Sobre todo, debes preguntar en tu más profundo interior: “¿por qué me he matriculado en un curso de markdown si creo que me vale con Word?”
Quizás ahí encuentres el nirvana.
Recomiendo que veas este vídeo para entender por qué resulta útil aprender Markdown:
Si aún así no te convence, siempre nos quedará Katmandu. ¡Namasté!
Porque aquí… Aquí solo hay café.
No os preocupéis. Quarto tiene un editor visual que permite escribir en formato WYSIWYG (What You See Is What You Get) sin necesidad de conocer el lenguaje Markdown. Casi un Word, vamos. Sin embargo, conocer Markdown puede ser útil para personalizar el formato del documento y aprovechar al máximo las capacidades de Quarto.
Empecemos
Para empezar a usar Quarto (y ya lo tenemos instalado), simplemente abrimos RStudio y creamos un nuevo documento de Quarto: File…New File……Quarto Document…
Aparecerá una pantalla en la que podemos elegir el formato (html, PDF, Word, sí, Word…). Mejor lo vemos juntos…
El resultado es un documento con un encabezado YAML y un bloque de código RMarkdown de ejemplo. Podemos escribir texto en formato Markdown y ejecutar bloques de código R directamente en el documento.
Encabezado YAML
En el entorno de R, los documentos de R Markdown utilizan un encabezado YAML para controlar el proceso de renderizado (transformación del código en un archivo formateado) y los metadatos del documento de salida, ya sea HTML, PDF o Word. Se pueden especificar diversas opciones, como el formato (si html, PDF, Word), la lengua, el tamaño de página, el estilo de citas, el archivo con las referencias bibliográficas, la fecha, el título, el autor, entre otras opciones. Funciona como las instrucciones básicas del documento.
Por ejemplo, el documento actual contiene un encabezado YAML que especifica el título, el subtítulo y el archivo de referencias bibliográficas:
---
title: “<b>Quarto+Markdown</b>”
subtitle: “*El lenguaje básico de la ciencia de datos y la docencia interactiva*”
bibliography: references.bib
---
Como se trata de una página web, el formato de salida es HTML por defecto. Podemos cambiarlo a PDF o Word modificando el encabezado YAML. El resultado sería:
---
title: “<b>Quarto+Markdown</b>”
subtitle: “*El lenguaje básico de la ciencia de datos y la docencia interactiva*”
bibliography: references.bib
format: pdf
---
En este caso, perdería todos los elementos interactivos, pero el formato sería más adecuado para imprimir o compartir como documento estático.
Cuerpo del documento
Una vez definido el encabezado YAML, podemos escribir el cuerpo del documento en formato Markdown. Podemos incluir texto, encabezados, listas, tablas, imágenes y bloques de código R.
La gramática básica de Markdown es sencilla. Por ejemplo, para crear un encabezado de nivel 1, utilizamos el símbolo # seguido del texto. Para palabras en negrita empleamos un doble asterisco ** para cursivas un solo asterisco *. Podemos emplear también el editor visual de Quarto para ello.
En el Cheat Sheet de Markdown puedes encontrar una guía rápida de los elementos básicos de Markdown. Sugiero que echéis un buen vistazo al documento y empezad a escribir. Cualquier cosa, por más sencilla que sea, para practicar el lenguaje.
Bloques de código
Finalmente, podemos incluir bloques de código R, Python, html, css, javascript entre otros en el documento utilizando la sintaxis de R Markdown. Los bloques de código se indican con tres tildes invertidas (``) seguidas de la palabrar` para indicar que se trata de código R. Por ejemplo:
```{r}
print(1+1)
```
Podrás también encontrar información sobre ecuaciones matemáticas en RMarkdown. Se trata de un recurso útil cuando estamos escribiendo un artículo que requiera formalización matemática.