Apéndice E — Los puntos de control de un vistazo, y respuestas
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.
| 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 |
| 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 |
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:
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.