Apéndice E — Los puntos de control de un vistazo, y respuestas

Palabras clave

Quarto, publicación reproducible, agentes de programación, Markdown, Python, EPUB, análisis de datos, k-means

Todos los puntos de control

Cada punto de control es una carpeta de quarto-workshop/checkpoints/ que contiene un proyecto tal como queda al final de un bloque práctico, con un README que enumera los pasos para ponerse al día: respalda tu carpeta (todo menos .venv/) en una carpeta nueva con fecha y hora, al lado; copia el punto de control (y, en el proyecto del agua, data/ si falta); renderiza y revisa una salida con nombre. Pega Catch me up: follow ../quarto-workshop/<path>/README.md en tu agente, o sigue el README a mano, y luego continúa desde la sección cuyo recuadro para ponerte al día usaste. El README nombra la diapositiva del taller en el mismo punto. No hay punto de control 03.

Si lees por tu cuenta, diagnostica antes de ponerte al día. Revisa dónde estás (pwd), qué cambió desde tu último commit (git status, luego git diff) y la primera línea del error (Leer un error, Apéndice D), y prueba la única solución a la que apunta. Ponte al día solo si eso falla. Después, abre la salida que nombra el README y comprueba que muestre lo que el libro describe en el recuadro para ponerte al día.

El Capítulo 5 tampoco tiene punto de control. Su proyecto es pequeño y se escribe a mano, y su punto de partida, starters/first-report/ en el mismo repositorio, es su comienzo desde cero: para empezar de nuevo, cambia el nombre de tu copia con mv ~/first-report ~/first-report-old y vuelve a copiar el punto de partida como en la Sección 5.1. Dentro del capítulo, tu último commit es el estado que sabes que funciona: git restore devuelve un archivo a él.

Tabla E.1: Los puntos de control de Londres, la sección cuyo recuadro para ponerte al día te lleva a cada uno, y lo que contiene.
Ruta Recuadro para ponerte al día Contiene
checkpoints/01-london-markdown Sección 6.10 london.md con cada construcción de Markdown, las reglas, el entorno, data/ e images/
checkpoints/02-london-qmd Sección 7.7 london.qmd con encabezado YAML, una oración y un gráfico calculados, y seis formatos
checkpoints/04-london-audiences Sección 8.3 el dashboard, el informe en Word y su correo, y el folleto A5
examples/london Sección 8.4, Sección 9.4 el proyecto de Londres terminado: sitio web, anuncio cuadrado y documento técnico
Tabla E.2: Los puntos de control del agua, la sección cuyo recuadro para ponerte al día te lleva a cada uno, y lo que contiene. Solo contienen fuentes: ponerte al día copia los datos.
Ruta Recuadro para ponerte al día Contiene
checkpoints/05-water-explore Sección 18.4 las reglas, el entorno y explore.qmd
checkpoints/06-water-prepare Sección 19.4 scripts/analysis.py con prepare()
checkpoints/07-water-cluster Sección 20.6 k-means en el script y clusters.qmd
checkpoints/08-water-interpret Sección 21.6 las reglas de las variables de resultado, los perfiles con nombre, y el mapa de calor y las variables de resultado en la página
checkpoints/09-water-causation Sección 22.4 la comprobación dentro de cada clúster en la página
checkpoints/10-water-report Sección 23.1 report.qmd en HTML, Word y PDF de Typst
checkpoints/11-water-slides Sección 23.2 slides.qmd en Reveal.js y PowerPoint
checkpoints/12-water-epub Sección 23.3 el EPUB opcional del informe
checkpoints/13-water-website Sección 23.4, Sección 23.5 el sitio web, su entrada de blog y el listado
examples/water Sección 23.7 el proyecto del agua terminado, con el dashboard y el documento técnico
Tabla E.3: Los puntos de control de la evaluación, de la vía rápida y de la Parte III. Llevan sus datos, y ponerte al día ejecuta scripts/evaluate.py antes de renderizar, porque outputs/ se calcula, no se guarda.
Ruta Recuadro para ponerte al día Contiene
starters/eval-repo Sección 3.2 (su inicio desde cero) el repositorio de la evaluación antes de Quarto: código, pruebas, datos y un notebook
checkpoints/14-eval-start Sección 3.6 las reglas, los paquetes que necesita Quarto, report.qmd y su guarda
checkpoints/15-eval-results Sección 10.3 model-card.qmd, references.bib y un informe con secciones numeradas
checkpoints/16-eval-slides Sección 11.6 la presentación, acme.scss y su prueba de contraste, scripts/deck_pdf.py y la plantilla de PowerPoint
checkpoints/17-eval-site Sección 12.5 _brand.yml y el logo, las plantillas de Word y PowerPoint, el sitio web y scripts/check_site.py
checkpoints/18-eval-whitepaper Sección 13.5 whitepaper.qmd, references.bib con un estilo CSL, scripts/check_refs.py y la plantilla de la casa
checkpoints/19-eval-params Sección 14.5 update.qmd, segment.qmd y scripts/render_params.py
checkpoints/20-eval-ci Sección 15.6 las reglas del equipo en AGENTS.md, una plantilla de pull request, y los workflows de comprobación, de publicación y mensual
examples/feedback Sección 14.5 las hojas de retroalimentación del caso docente, a partir de un registro de calificaciones sintético
examples/eval Sección 15.6 el proyecto de la evaluación terminado

Respuesta: cambiar un dato de entrada de Londres

La tarea (Sección 9.5): cambiar el visits_2025 de la Tower of London a 8,000,000.

Qué cambia. Cada página que carga attractions.csv (Tabla 9.3) se reconstruye con el conteo nuevo, y lo que muestra depende de su código. La guía, en cada formato que escribe (página web, Word y PDF, y PowerPoint, diapositivas y EPUB si se hicieron), los cuadros de valor y el gráfico de barras del dashboard, y el informe para socios (london-email.docx) encuentran la atracción más visitada con idxmax() y el total con .sum(), así que la Tower of London pasa a ser la atracción más visitada y el total sube. El anuncio cuadrado, si se hizo, usa solo idxmax(), así que también nombra a la Tower. El documento técnico no nombra ninguna atracción más visitada: sus sumas por tipo de entrada cambian, pero su tabla conserva la columna rank_uk de ALVA tomada del archivo, así que seguiría ubicando a la Tower en el noveno puesto del Reino Unido al lado de la mayor cantidad de visitas de las diez. Una columna copiada también queda vieja.

Qué no cambia. El folleto, que copia sus datos y no cita ningún conteo de visitas; el correo de presentación (london-email-message.md), que no cita ningún número y no se renderiza; el gráfico de líneas del dashboard y el mapa 3-D, que leen visits.csv y no attractions.csv; cualquier salida que no se reconstruyó; y el sitio en vivo, hasta que se vuelva a publicar.

Por qué. Cada renderizado vuelve a ejecutar el código de cada página (freeze: false), y cada salida que cambió está conectada con el dato de entrada por una línea de código que lo carga. Una respuesta sólida nombra esa línea.

Preguntas de seguimiento que vale la pena hacerse. ¿Dónde aparecería el cambio si el número se hubiera escrito a mano en la prosa en lugar de calcularse? (En ninguna parte: el número escrito a mano contradiría en silencio al gráfico.) ¿Qué cambiaría si en cambio se editara visits.csv? (El gráfico de líneas del dashboard, el mapa 3-D y la tendencia del documento técnico.) ¿Por qué el renderizado vuelve a ejecutar cada celda? (Porque nada está en caché; ver la Sección 23.4.)

Respuesta: cambiar una opción del agua

La tarea (Sección 23.6): fijar MAX_MISSING = 1 en lugar de 2 en scripts/analysis.py. Calculado aquí ejecutando el análisis terminado de las dos maneras:

Tabla E.4: El análisis del agua con cada opción.
MAX_MISSING = 2 MAX_MISSING = 1
filas descartadas por características faltantes 2 654
filas conservadas 11,235 10,583
municipios 1,090 1,088
k 4 4

La predicción. Se va cada fila a la que le falta más de una de las nueve características. Las capitales de departamento no tienen cobertura por zona, así que sus zonas rurales llegan a esa regla con los dos valores de cobertura faltantes (la imputación viene después de la regla): se van todas sus zonas-año rurales, entre ellas las ocho de Tunja, mientras que la zona urbana de Tunja, que toma el total municipal, se queda.

Lo que muestra la reconstrucción. La opción más estricta descarta 652 filas más, a todas les faltan los dos valores de cobertura: las 135 zonas-año rurales de las capitales y otras 517 zonas-año a las que les falta la separación de la cobertura ese año, siete de ellas zonas urbanas de capitales sin un total municipal tampoco. No se va nada más. La zona urbana de Tunja se queda en el clúster 1 en todos los años. k sigue siendo 4, así que el assert k == 4 de la entrada de blog sigue pasando (una opción que cambiara k haría fallar el renderizado de la entrada, por diseño), los nombres se mantienen y el 98% de las filas que quedan conserva su clúster.

Qué cambia. pre-render vuelve a ejecutar scripts/analysis.py, que reescribe cada archivo de outputs/ (clusters.parquet, cluster_profiles.csv, k_selection.csv, stability.csv, outcomes_by_year.csv, irca_infant.csv, irca_infant_bins.csv y summary.json), y freeze: false vuelve a ejecutar cada página, así que cambia cada página que lee outputs/ (Tabla 23.1): la página de los clústeres, el informe en cada formato, las diapositivas, la entrada de blog, el dashboard y el documento técnico, que además cita la opción misma.

Qué no cambia. data/, las fuentes de las páginas, el título de la entrada (k sigue siendo 4) y, hasta que se vuelva a publicar, el sitio en vivo. Tampoco la página de exploración: se vuelve a ejecutar, pero lee solo data/water_municipal.csv.

Por qué. Calcular una vez, publicar muchas: una opción en un script, leída por cada publicación. Las respuestas sólidas nombran el mecanismo (pre-render, outputs/, freeze: false) y revisan al menos dos salidas contra los nuevos conteos de filas. Deshaz el cambio con git restore scripts/analysis.py.