14 Informes que se generan solos
Quarto, publicación reproducible, agentes de programación, Markdown, Python, EPUB, análisis de datos, k-means
Buena parte de lo que publica una organización es el mismo documento con números distintos: el informe mensual para inversionistas, un informe por cliente, región, equipo o modelo, una hoja de retroalimentación para cada grupo de un curso. Hecha a mano, cada copia es una oportunidad de pegar la cifra del mes pasado en el archivo de este mes. Hecha a partir de una sola fuente con un parámetro, un valor que se da al renderizar, cada copia es el mismo documento probado, ejecutado con otro valor, y un script puede hacerlas todas y revisarlas.
Este capítulo hace tres: el informe mensual de Acme para inversionistas, un informe de una página para cada segmento de clientes y, para docentes, una hoja de retroalimentación para cada grupo de un curso. El informe para inversionistas lleva las cifras de negocio de la empresa, que en este libro son sintéticas y están marcadas así en cada número; las cifras del modelo que las acompañan son las de la evaluación real.
- Explicar qué es un parámetro, dónde vive su valor predeterminado y cómo se pasa un valor al renderizar.
- Pedir un documento parametrizado que valide su valor y elija por código, con guardas, las palabras que dependen de ese valor.
- Renderizar un documento para cada valor con un script que nombre y revise cada salida.
- Decir dónde quedan las salidas de un documento parametrizado en un proyecto de sitio web, y por qué.
14.1 Un documento, muchos valores
| Pide | Quarto lo llama | Revisa |
|---|---|---|
| un valor fijado al renderizar, con un valor predeterminado | una celda etiquetada parameters, #| tags: [parameters] |
los valores predeterminados se renderizan por sí solos |
| este valor, ahora | quarto render update.qmd -P month:2026-06 |
la salida muestra ese mes |
| muchos valores desde un archivo | --execute-params params.yml |
cada valor llega al documento |
| una salida con el nombre de su valor | -M output-file:update-2026-06 |
un archivo por valor, ninguno sobrescrito |
| el motor que inyecta los valores | papermill, en el entorno del proyecto | sin él, el renderizado se detiene |
Los valores predeterminados son parte del documento: el month del informe para inversionistas terminado tiene como valor predeterminado “latest”, que el documento lee como el último mes de sus datos, así que su valor predeterminado nunca se vuelve viejo; el informe por segmento usa por defecto age_band 60+, y la hoja de retroalimentación, el grupo A. Pasar -P month:2026-06 reemplaza un valor predeterminado durante un renderizado: Quarto agrega, después de la celda de parámetros, una celda que fija el valor nuevo, y el documento se ejecuta como antes. Esa celda se ejecuta mediante papermill, un paquete de Python que el proyecto tiene que tener: sin él, un renderizado con -P se detiene con “The papermill package is required for processing –execute-params” (se necesita el paquete papermill para procesar –execute-params).
Dos reglas hacen seguro un documento parametrizado. Valida el valor: un mes o un segmento que no está en los datos tiene que detener el renderizado con un mensaje que enumere los válidos, no producir un informe sobre nada. Deja que el código elija cada palabra que depende del valor, a partir de los números tal como se imprimen: “subió” o “bajó”, “por encima” o “por debajo”, “el primer mes de los datos, así que no hay cambio”. Elegida a partir de los números impresos, la palabra no puede contradecirlos; pon una guarda en lo que el código no puede elegir, como un pie de figura escrito a mano, y revisa que el texto impreso concuerde, como hace el informe para inversionistas terminado. Una guarda que repite la comparación que eligió la palabra nunca puede fallar, y no protege nada. Un documento renderizado para una docena de valores es una docena de oportunidades de que una palabra escrita a mano esté mal.
14.2 El informe para inversionistas
Agrega papermill con `uv add papermill` y luego crea update.qmd, un informe mensual para inversionistas, en inglés, parametrizado por `month` (una celda etiquetada `parameters` cuyo valor predeterminado es "latest", que significa el último mes de data/synthetic_business.csv): las cifras de negocio de ese mes, cada una marcada como sintética, la versión en producción ese mes y sus métricas reales del modelo desde outputs/, y el cambio respecto al mes anterior, con su redacción elegida por código y con una guarda. Detente con un mensaje claro si el mes no está en los datos. Formatos html, docx y typst; renderízalo para 2026-06 con `-P month:2026-06` y dime a dónde fueron los archivos.uv add papermill · escribe update.qmd · uv run quarto render update.qmd -P month:2026-06
Revísalo como lo haría quien invierte, y como lo haría quien audita. Cada cifra de negocio dice que es sintética, aquí; en tu propio informe, cada cifra nombra su fuente. Las cifras del modelo vienen de outputs/ y son las de la evaluación real. Un mes anterior a la primera versión lo dice, en lugar de inventar una cifra del modelo. Y un mes que no está en los datos detiene el renderizado: prueba -P month:2027-01.
La trampa está en a dónde fueron los archivos. El proyecto es un sitio web, pero el informe para inversionistas no está en su lista render, y no debe estarlo: una página del sitio muestra un solo valor, y un informe para inversionistas no es una página pública. Así que Quarto lo renderiza como un archivo suelto, junto a su fuente, no en _site/, y los pasos posteriores al renderizado del sitio no se ejecutan para él. En la prueba, --output-dir reports se rechazó para un archivo así, y --output aceptó un nombre de archivo pero no una carpeta, así que el script de abajo mueve él mismo cada archivo a reports/.
14.3 Un informe por segmento
El mismo patrón hace el informe por cliente, por región o por equipo: un documento, un parámetro por dimensión.
Crea segment.qmd, en inglés: un informe de una página para un segmento de clientes, parametrizado por `factor` (age_band o job) y `segment` (valor predeterminado 60+), con las métricas de la mejor versión para ese segmento desde outputs/segments.csv frente a la lista completa, con guardas en la redacción, y una nota cuando el segmento tiene pocos suscriptores. Renderízalo con `-P factor:job -P segment:student`.Los números de un segmento merecen más cautela que los de la lista completa: un segmento con pocos suscriptores tiene tasas amplias y ruidosas. El informe terminado agrega su nota por debajo de 50 suscriptores, un ajuste con nombre, FEW_SUBSCRIBERS, en el código del proyecto; el umbral correcto es decisión tuya, y su lugar es un ajuste como ese, no una oración.
14.4 Cada valor, revisado
Escribe scripts/render_params.py: renderiza update.qmd para cada mes de data/synthetic_business.csv y segment.qmd para cada franja de edad, en html, docx y typst, cada archivo con el nombre de su valor, en reports/; revisa que cada archivo exista y contenga su valor; imprime una tabla.Para el proyecto terminado son diez meses y cinco franjas de edad en tres formatos: 45 archivos, cada uno con el nombre de su valor y cada uno revisado para comprobarlo. La revisión es lo que hace confiable un lote: un archivo que en silencio muestra el mes predeterminado, porque no se pasó un valor, saldría si no junto con los demás.
De la prueba: una revisión del PDF para la franja de edad “18-29” falló, porque el texto del PDF devolvía el guion como un guion suave; el script terminado quita los guiones suaves y trata cualquier tipo de raya como un guion antes de comparar. Y el HTML autocontenido, que lleva sus bibliotecas dentro, es mucho más grande que el mismo informe en PDF; envía el PDF, y deja el HTML para el sitio.
14.5 El caso docente: una hoja por grupo
El mismo método le sirve a quien enseña en varios grupos de un mismo curso: una hoja de retroalimentación por grupo, que compara el grupo con el curso, a partir de un solo registro de calificaciones. El registro del ejemplo es sintético, generado con una semilla aleatoria fija: tres grupos de estudiantes identificados solo por número.
Crea feedback.qmd, en inglés: una hoja de retroalimentación por grupo de data/gradebook.csv, parametrizada por `section`, con la media y la dispersión de ese grupo en cada tarea frente al curso, un gráfico con texto alternativo, cada oración marcada como sintética y con una guarda en su redacción, y ningún identificador de estudiantes. Luego escribe scripts/render_sections.py para renderizar feedback-<section>.pdf para cada grupo y revisar cada uno. Ejecútalo.Las calificaciones son datos personales, así que la hoja muestra solo totales del grupo, nunca a una persona, y nunca un subgrupo tan pequeño que alguien pueda deducir de quién se trata; la hoja terminada se detiene si cualquier subgrupo que describe, incluidas las entregas de cada tarea, tiene menos de 5. Con calificaciones reales, las reglas de la Sección 2.10 y la política de datos de tu institución van primero: construye el documento sobre un registro de calificaciones sintético con las mismas columnas, como este, y renderiza tú el real.
¿Dos minutos sin avanzar? Pega esto en tu agente. Respalda tu trabajo y lleva el proyecto hasta este punto; luego sigue leyendo desde aquí.
Catch me up: follow ../quarto-workshop/checkpoints/19-eval-params/README.mdResumen
- Un parámetro es un valor que se da al renderizar; su valor predeterminado vive en una celda etiquetada
parameters, y-P name:valuelo reemplaza, mediante papermill. - Valida cada valor, deja que el código elija cada palabra que depende de él a partir de los números tal como se imprimen, y pon una guarda en lo que el código no puede elegir.
- Nombra cada salida por su valor, y renderízalas y revísalas todas con un solo script.
- Un documento parametrizado que queda fuera de la lista de renderizado de un sitio se renderiza junto a su fuente; mueve sus salidas a donde corresponden.
- Marca las cifras sintéticas en cada número, y limita los datos personales a totales de grupo.
Lecturas adicionales
- Quarto, Parameters (consultado el 2026-11-18).
- papermill, documentation (consultado el 2026-11-18).