43. Cuadernos y publicación científica {#43-cuadernos-y-publicación-científica}

En ciencia de datos y análisis reproducible, Markdown convive con código ejecutable. Los cuadernos combinan texto, fórmulas, gráficos y resultados en un mismo documento. Este capítulo cubre Jupyter, MyST, Quarto y R Markdown, y las prácticas para que el resultado sea reproducible.

43.1 Qué es un cuaderno {#431-qué-es-un-cuaderno}

Un cuaderno es una secuencia de celdas:

• Markdown: texto, títulos, listas, fórmulas y enlaces.
• Código: instrucciones que se ejecutan y producen salidas.
• Resultados: tablas, gráficos, texto e imágenes.

El orden de ejecución importa: una celda puede depender de otra ejecutada antes. Un cuaderno no es un documento estático hasta que se ejecuta y se exporta.

43.2 Jupyter {#432-jupyter}

Jupyter almacena los cuadernos en .ipynb, un archivo JSON con celdas, metadatos y salidas.

# Abrir la interfaz
jupyter notebook
jupyter lab

# Ejecutar y exportar
jupyter nbconvert --to html --execute analisis.ipynb
jupyter nbconvert --to pdf --execute analisis.ipynb
jupyter nbconvert --to markdown --execute analisis.ipynb
jupyter nbconvert --to slides analisis.ipynb

• Jupyter: https://jupyter.org/
• nbconvert: https://nbconvert.readthedocs.io/

43.2.1 MyST Markdown {#4321-myst-markdown}

MyST amplía Markdown con directivas y roles para documentos científicos:

```{figure} img/resultado.png
:name: fig-resultado
:alt: Gráfico de resultados

Resultados del experimento.
```

Como muestra {numref}`fig-resultado`, la tendencia es creciente.

MyST se usa en Jupyter Book y en el ecosistema mystmd:

• MyST: https://mystmd.org/
• Jupyter Book: https://jupyterbook.org/

43.2.2 Jupytext {#4322-jupytext}

Jupytext mantiene un .ipynb y un .md (o .py) sincronizados:

jupytext --to markdown analisis.ipynb
jupytext --sync analisis.ipynb

Ventaja: el Markdown se revisa en Git con diffs legibles; el cuaderno conserva las salidas para ejecutar.

• Jupytext: https://jupytext.readthedocs.io/

43.3 Quarto {#433-quarto}

Quarto es un sistema de publicación que ejecuta código y genera HTML, PDF, DOCX, presentaciones y sitios. Usa archivos .qmd con Front Matter YAML y bloques de código.

---
title: "Análisis de datos"
author: "Equipo"
format:
  html:
    toc: true
    code-fold: true
  pdf:
    documentclass: article
execute:
  echo: true
  warning: false
---

```{python}
import pandas as pd
datos = pd.read_csv("datos.csv")
datos.head()
```

El promedio es @fig-tendencia.

quarto preview
quarto render
quarto render --to pdf
quarto publish gh-pages

• Quarto: https://quarto.org/

43.4 R Markdown {#434-r-markdown}

R Markdown combina Markdown con chunks de R (y otros lenguajes) y knitr:

---
title: "Informe"
output:
  html_document:
    toc: true
  pdf_document: default
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

```{r grafico, fig.cap="Tendencia anual"}
plot(datos$anio, datos$valor)
```

rmarkdown::render("informe.Rmd")
rmarkdown::render("informe.Rmd", output_format = "pdf_document")

• R Markdown: https://rmarkdown.rstudio.com/
• knitr: https://yihui.org/knitr/
• bookdown: https://bookdown.org/

43.5 Reproducibilidad {#435-reproducibilidad}

Un cuaderno es reproducible si otra persona puede obtener el mismo resultado:

1. Fija el entorno: versiones de lenguajes y paquetes.
   • Python: requirements.txt, pyproject.toml o conda env export.
   • R: renv::init() y renv.lock.
   • Quarto: freeze y un entorno documentado.
2. Fija las semillas de aleatoriedad (set.seed(), numpy.random.default_rng(…).
3. Evita rutas absolutas; usa rutas relativas al proyecto.
4. No dependas de datos externos cambiantes; guarda una copia o una versión.
5. Documenta el orden de ejecución si no es lineal.
6. Ejecuta de cero antes de publicar (Restart & Run All, quarto render, rmarkdown::render).
7. Registra la sesión (sessionInfo(), pip freeze).

43.6 Control de versiones de cuadernos {#436-control-de-versiones-de-cuadernos}

Los .ipynb son JSON con salidas y metadatos; los diffs son ruidosos.

• Limpia las salidas antes de hacer commit, salvo que necesites conservarlas.
• Usa Jupytext para revisar el Markdown o el script.
• Usa nbdime para comparar cuadernos: https://nbdime.readthedocs.io/.
• No versiones datos pesados ni secretos; usa .gitignore.
• Revisa que las rutas y los tokens no queden en las salidas.

43.7 Publicación {#437-publicación}

Antes de publicar, comprueba licencias de datos, imágenes y código, y elimina información personal.

43.8 Seguridad {#438-seguridad}

• No ejecutes cuadernos de terceros sin revisar el código: pueden borrar archivos, exfiltrar datos o instalar paquetes.
• No incluyas tokens, contraseñas ni rutas privadas en las celdas.
• Revisa las salidas: pueden contener datos sensibles.
• Fija versiones de dependencias para evitar ataques de suministro.
• Ejecuta en un entorno aislado (contenedor, máquina virtual) si el origen no es de confianza.

43.9 Accesibilidad {#439-accesibilidad}

• Los gráficos necesitan texto alternativo o una tabla de datos equivalente.
• No uses solo el color para distinguir series.
• Estructura el documento con encabezados jerárquicos.
• Las tablas deben tener cabeceras.
• Los resultados interactivos deben tener una versión estática.
• Los PDF generados deben conservar el orden de lectura.

43.10 Lista de comprobación {#4310-lista-de-comprobación}

• El cuaderno se ejecuta de principio a fin sin errores.
• Las dependencias y versiones están documentadas.
• Las semillas y rutas son reproducibles.
• Las salidas no contienen secretos ni datos personales.
• El formato de publicación es el adecuado.
• Las figuras y tablas tienen alternativa textual.
• El repositorio incluye una licencia y un README.