Folio Writer

Figuras que se regeneran solas:
gráficos dinámicos con Quarto, Python y R

La figura más peligrosa de un manuscrito es la que se hizo a mano hace tres revisiones. Cuando el análisis cambia y el PNG no, el artículo miente sin hacer ruido. La solución: pon el código en el manuscrito y deja que cada compilación regenere el gráfico a partir de los datos. Quarto lo ejecuta y Folio Writer lo orquesta.

La idea en un bloque

En cualquier parte de un documento de Folio Writer, escribe una celda ejecutable en lugar de pegar una imagen:

```{python}
#| label: fig-eos
#| fig-cap: "Third-order Birch–Murnaghan fit to the P–V data."
import pandas as pd, matplotlib.pyplot as plt
d = pd.read_csv("Research/pv-data.csv")
plt.plot(d.V, d.P, "o"); plt.plot(d.V, fit(d.V))
plt.xlabel("V (ų)"); plt.ylabel("P (GPa)")
```

Compila con Motor de renderizado = Quarto y la celda se ejecuta: se lee el CSV, se dibuja el ajuste y la figura terminada llega al PDF (o al archivo de Word, o al HTML) numerada, con su leyenda y referenciada con @fig-eos como cualquier otra figura. R funciona exactamente igual:

Una celda {python} y su figura ejecutada, en vivo en la vista previa.
Una celda {python} y su figura ejecutada, en vivo en la vista previa.
```{r}
#| label: fig-spectra
#| fig-cap: "Raman spectra by pressure step."
library(ggplot2)
ggplot(read.csv("Research/spectra.csv"),
       aes(shift, intensity, color = factor(P))) + geom_line()
```

Actualiza el archivo de datos, vuelve a compilar y todas las figuras estarán al día. Sin paso de exportación, sin preguntarse «¿qué script hizo la figura 3?», sin gráficos obsoletos: el manuscrito es la cadena de procesamiento.

El mismo manuscrito habla R: motor knitr, echo: false, figura numerada.
El mismo manuscrito habla R: motor knitr, echo: false, figura numerada.

Configuración

  1. Instala Quarto (quarto.org, o brew install quarto) y el Folio Helper gratuito, que permite a la app aislada del App Store ejecutar tus herramientas locales.
  2. Celdas de Python: necesitas un Python con Jupyter (pip install jupyter matplotlib pandas). Folio Writer dirige Quarto automáticamente a un intérprete compatible con Jupyter, de modo que las celdas se ejecutan con un Python que de verdad puede ejecutarlas, y no con el python3 que resulte estar primero en el PATH.
  3. Celdas de R: instala R junto con knitr y rmarkdown, el motor de R estándar de Quarto.
  4. Guarda los datos y los scripts de análisis en la carpeta Research del proyecto, para que toda la cadena viaje (y se sincronice) con el manuscrito.
Nota sobre los niveles: ejecutar celdas de código forma parte del desbloqueo único de Pro, junto con la compilación (prueba completa de 7 días incluida). Escribir las celdas, y el renderizado simple de Quarto sin ejecución, no lo requieren.
Dónde se ejecuta el código: la vista previa en vivo es instantánea por diseño: compone el texto y las fórmulas, pero no ejecuta código. Las celdas se ejecutan al compilar, cuando Quarto renderiza el manuscrito unido. Para echar un vistazo rápido a una figura, compila solo la sección en la que estás trabajando (Alcance ▸ Documento seleccionado).

Las opciones de celda que importan en un manuscrito

Las opciones de celda de Quarto viajan como líneas de comentario #|. Cinco cubren casi todo lo que necesita un manuscrito:

```{python}
#| label: fig-eos          # cite it as @fig-eos
#| fig-cap: "Compression curve with third-order fit."
#| echo: false             # figure in the paper, code not
#| fig-width: 6.5          # inches, match the journal column
#| warning: false          # keep library chatter out of the PDF
...
```

Para un manuscrito entero en el que nunca debe imprimirse código, defínelo una sola vez en el documento de metadatos en lugar de celda por celda:

execute:
  echo: false
  warning: false
¿Análisis lento? Añade #| cache: true a una celda costosa: Quarto solo la vuelve a ejecutar cuando cambia su código, así que recompilar tras retocar la prosa no vuelve a ajustar tu modelo.
Un flujo de trabajo real: datos P–V leídos de un .xlsx en Research, ajuste de Birch–Murnaghan, anotado y numerado al compilar.
Un flujo de trabajo real: datos P–V leídos de un .xlsx en Research, ajuste de Birch–Murnaghan, anotado y numerado al compilar.

Si las celdas no se ejecutan

Tres causas cubren casi todos los casos. Motor de renderizado equivocado: el código solo se ejecuta cuando el motor de renderizado de la hoja de compilación es Quarto; con pandoc o Typst, las celdas pasan tal cual como bloques de código literales (por diseño: esas cadenas nunca ejecutan nada). Falta el motor: Compilar ▸ Configurar herramientas externas… comprueba tus herramientas; para las celdas de Python necesitas Jupyter en el intérprete (pip install jupyter), y para R, knitr + rmarkdown. Suposiciones sobre las rutas: las celdas se ejecutan con el proyecto como directorio de trabajo, así que lee los datos como Research/pv-data.csv, no con una ruta absoluta de tu otro equipo; mantener las rutas relativas al proyecto es también lo que hace que el manuscrito sea reproducible para tus coautores.

Estático cuando quieres, dinámico cuando importa

Las celdas ejecutables y las figuras normales conviven. Una fotografía o un esquema dibujado a mano siguen siendo una imagen Markdown normal; los gráficos derivados de datos se convierten en celdas. La comprobación del manuscrito de Folio Writer vigila incluso las estáticas, y señala una figura más antigua que el script que la dibuja, de modo que, sea cual sea el camino de una figura, no puede quedarse obsoleta sin que te enteres.

Resultados con calidad de revista incluidos

Como el motor de renderizado Quarto es el mismo que impulsa los formatos de revista, las figuras dinámicas también funcionan en las plantillas de las editoriales: añade una extensión de revista (AGU, Elsevier, Copernicus…), define quarto-to: en los metadatos y el envío compilado llevará figuras generadas a partir de tu análisis en vivo, reproducibles por cualquiera a partir de los archivos planos del proyecto con un solo comando.

Descarga Folio Writer gratis → · Más guías