Apunte 3 — Quarto: reportes reproducibles

Analítica de Personas · Semestre otoño 2026 · Semana 1 · Prof. René Gempp

1. ¿Qué es Quarto y por qué lo usamos?

Quarto es un sistema de publicación que combina texto narrativo, código R y resultados (tablas, gráficos) en un solo documento. Escribes un archivo .qmd, haces click en "Render", y obtienes un reporte profesional en HTML, PDF o Word.

¿Por qué importa para people analytics? Porque el entregable nunca es "un script de R". El entregable es un reporte para alguien que no sabe R: el VP, el directorio, un gerente de línea. Quarto te permite producir ese reporte sin salir de RStudio, y si los datos cambian, solo vuelves a renderizar.

2. Anatomía de un archivo .qmd

Todo documento Quarto tiene tres partes que se alternan:

Este patrón se repite tantas veces como necesites: texto → código → texto → código → ...

3. El encabezado YAML en detalle

El YAML (las líneas entre ---) configura todo el documento. Es muy sensible a la indentación: cada nivel se indenta con exactamente 2 espacios.

---
title: "Diagnóstico de Fuerza Laboral — InnovaCo SpA"
subtitle: "Reporte para el VP de Personas"
author: "Tu nombre"
date: "2025-03-11"
format:                          # ← nivel 0
  html:                          # ← nivel 1 (2 espacios)
    theme: cosmo                 # ← nivel 2 (4 espacios)
    toc: true                   # tabla de contenidos
    toc-depth: 2                # hasta qué nivel de título
    code-fold: true             # código colapsado por defecto
    code-summary: "Ver código"  # texto del botón para expandir
    number-sections: true       # numerar secciones
execute:
  echo: true                    # mostrar código en el output
  warning: false                # ocultar warnings de R
  message: false                # ocultar mensajes de R
---

Opciones YAML más usadas

4. Texto en Markdown

El texto fuera de los chunks de código se escribe en Markdown, un formato de texto simple que se convierte automáticamente a HTML con formato:

## Título de sección

### Subtítulo

Texto normal de un párrafo.

Texto en **negrita** y en *cursiva*.

- Primer punto
- Segundo punto

1. Paso uno
2. Paso dos

> Cita textual o destacado

[Enlace a Google](https://google.com)

`código_en_línea()`

Callouts: cajas de destaque

Quarto tiene cajas especiales para destacar información. Se usan mucho en reportes ejecutivos:

::: {.callout-note}
## Hallazgo clave
La tasa de rotación en Soporte Técnico (35%)
duplica la del resto de la empresa.
:::

::: {.callout-warning}
## Señal de alerta
La satisfacción en Ventas cayó 8 puntos respecto
al período anterior.
:::

::: {.callout-tip}
## Recomendación
Se sugiere realizar entrevistas de salida
focalizadas en Soporte Técnico durante marzo.
:::

5. Chunks de código R

Los chunks son los bloques donde va el código R. Abren con ```{r} y cierran con ```. Todo lo que está entre esos delimitadores se ejecuta cuando renderizas el documento.

Estructura de un chunk

```{r}
#| label: mi-analisis
#| fig-cap: "Distribución de edad en InnovaCo"
#| fig-width: 8
#| fig-height: 4.5

ggplot(innovaco, aes(x = edad)) +
  geom_histogram(binwidth = 3, fill = "#2C5F2D") +
  theme_minimal()
```

Las líneas que empiezan con #| (hashpipe) son opciones del chunk. Controlan cómo se ejecuta y se muestra ese bloque específico.

Opciones de chunk más usadas

El primer chunk: siempre setup

Por convención, el primer chunk de todo documento .qmd carga los paquetes y los datos. Se llama setup:

```{r}
#| label: setup
#| message: false

library(tidyverse)
innovaco <- read_csv("innovaco_empleados.csv")
```

6. Insertar un chunk: el atajo de teclado

Nunca escribas los ```{r} a mano. Usa el atajo:

Esto inserta automáticamente un chunk completo con apertura y cierre. Solo tienes que escribir el código adentro.

Ejecutar chunks mientras trabajas

7. Archivos y carpetas: la regla de oro

Cuando renderizas un .qmd, Quarto busca los archivos (como el CSV) relativo a donde está el .qmd, no al working directory de RStudio. La forma más simple de evitar problemas:

Pon todo en la misma carpeta:

mi_proyecto/
├── clase01_reporte_vp.qmd     # Tu documento Quarto
├── clase01_script.R            # Tu script de trabajo
└── innovaco_empleados.csv      # Los datos

Dentro del .qmd, la ruta es simplemente:

innovaco <- read_csv("innovaco_empleados.csv")

# Ruta absoluta:
read_csv("C:/Users/Juan/datos.csv")

# Archivo en otra carpeta:
read_csv("../Descargas/datos.csv")

# Mismo directorio que el .qmd:
read_csv("innovaco_empleados.csv")

# Subcarpeta dentro del proyecto:
read_csv("datos/innovaco_empleados.csv")

8. Código en línea: insertar resultados dentro del texto

Puedes insertar resultados de R directamente dentro del texto narrativo usando la sintaxis `r expresión`. Esto es muy poderoso para reportes porque los números se actualizan automáticamente:

InnovaCo cuenta con `r nrow(innovaco)` empleados.
La edad promedio es de `r round(mean(innovaco$edad), 1)` años.
La tasa de rotación global alcanza el
`r scales::percent(mean(innovaco$rotacion == "Sí"), accuracy = 0.1)`.

En el HTML renderizado esto aparecería como:

InnovaCo cuenta con 1.200 empleados. La edad promedio es de 34.4 años. La tasa de rotación global alcanza el 27.2%.

9. Renderizar: de .qmd a HTML

Cuando haces click en Render (o Ctrl + Shift + K), Quarto:

1. Lee el YAML y configura el documento
2. Ejecuta todos los chunks de arriba hacia abajo, en orden
3. Convierte el Markdown a HTML con formato
4. Inserta los resultados (tablas y gráficos) donde corresponde
5. Genera el archivo .html en la misma carpeta que el .qmd

10. Los 7 errores más comunes y cómo resolverlos

11. Checklist de debugging

Si tu .qmd no renderiza, sigue estos pasos en orden:

1. Lee el mensaje de error. Indica el número de línea donde falló.
2. Revisa el YAML. ¿Los --- están completos? ¿La indentación es correcta?
3. Revisa los chunks. ¿Todos abren con ```{r} y cierran con ```?
4. Revisa la ruta del CSV. ¿El archivo está donde el .qmd espera encontrarlo?
5. Revisa el primer chunk. ¿Tiene library(tidyverse) y read_csv()?
6. Ejecuta chunk por chunk. Usa el botón ▶ de cada chunk para encontrar cuál falla.
7. Si nada funciona: cierra RStudio, abre de nuevo y vuelve a intentar.

12. Referencia rápida de Markdown

13. Atajos de teclado: resumen