Mientras seguía una de esas horribles «guías para autores», ese caótico documento donde las revistas nos indican cómo debemos hacer el trabajo que ellos deberían realizar, me encontré con la necesidad de que Quarto interpretara algunas figuras y tablas como «Figura S1» o «Tabla S1». A pesar de que la guía de Quarto es una de las mejores que he leído y cuenta con secciones que explican cómo hacerlo, me encontré con algunas limitaciones que no están explícitamente detalladas. Aunque estas sí se mencionan en otros apartados. Esta publicación sirve como un tutorial para usar las referencias cruzadas personalizadas de Quarto, como un recordatorio personal y como una solución/explicación para quienes se enfrenten al mismo problema y busquen una solución en español.
Entre las características más potentes de Quarto, las referencias cruzadas destacan por su simplicidad y utilidad a la hora de escribir documentos académicos, como artículos científicos. Las referencias cruzadas pueden aplicarse a imágenes, tablas, ecuaciones, secciones, entre otros elementos. Además, pueden ser utilizadas tanto en elementos generados por código como en el mismo código. Para usarlas, es indispensable etiquetar cada elemento con un identificador único1 adecuada. En este post, utilizaré una imagen como ejemplo, pero el proceso es aplicable a otros elementos con mínimas diferencias.
Para referenciar una imagen en Quarto, se usa la sintaxis #fig-element, donde element es el identificador que asignamos. Por ejemplo, para hacer referenciable una imagen:
{#fig-cecropia}
La presencia de #fig-cecropia permite referenciar esta imagen en cualquier momento usando @fig-cecropia. Por ejemplo:
La @fig-cecropia es de un yarumo.Quarto también permite referenciar imágenes generadas por código. En este caso, las etiquetas se añaden usando las opciones del chunk de código, label y fig-cap. Por ejemplo, generemos una figura con {ggplot2} y los datos de iris:
```{r}
#| label: fig-iris
#| fig-cap: Un gráfico de dispersión.
#| fig-alt: Gráfico de dispersión de las variables petal width y petal length del conjunto de datos Iris, agrupado por especies. Se muestra una correación lineal entre ambas variables.
iris |>
ggplot2::ggplot(
ggplot2::aes(
Petal.Length,
Petal.Width,
shape = Species
)
) +
ggplot2::geom_point()
```
En la opción fig-cap tenemos la descripción de nuestra imagen, mientras que en label usamos fig-iris, que utilizaremos para referirnos a esta imagen. Si escribimos @fig-iris, obtendremos: Figura 2.
Con #fig-element y #tbl-element cubrimos la mayoría de las necesidades para referenciar elementos en un trabajo académico. Sin embargo, si necesitamos incluir material suplementario, estos métodos no funcionan correctamente, ya que seguirán la numeración del texto principal. Afortunadamente, desde la versión 1.4 de Quarto, es posible crear referencias cruzadas personalizadas.
Como ejemplo, crearemos una referencia cruzada para que las figuras suplementarias aparezcan en el texto como «Figura S1», «Figura S2», etc. Para ello, añadimos el siguiente código en el YAML del documento o proyecto de Quarto:
crossref:
custom:
- kind: float
key: suppfig
reference-prefix: Figure S
space-before-numbering: falseLas tres primeras opciones crossref, custom, kind son obligatorias. crossref se utiliza para personalizar las referencias cruzadas; custom, para indicar que será un tipo de referencia cruzada personalizado; y kind, para especificar el tipo de referencia (actualmente solo se admite float). Además, key es la clave que usaremos para referenciar el elemento (en este ejemplo, #suppfig-element); reference-prefix es el prefijo que aparecerá en la referencia (en este caso, Figura S). Finalmente, space-before-numbering define si se añade o no un espacio entre el prefijo y la numeración de la imagen (si es false, no se añade espacio). Con esto configurado3, probaremos con otras imágenes.
Al crear una referencia cruzada personalizada, es importante tener cuidado con los prefijos elegidos, ya que Quarto tiene algunos prefijos reservados: fig, tbl, lst, tip, nte, wrn, imp, cau, thm, lem, cor, prp, cnj, def, exm, exr, sol, rem, eq, y sec. También es recomendable evitar el uso de guiones bajos (_), ya que esto puede causar problemas al renderizar un PDF usando LaTeX. Más información.
Haremos algo similar a lo mostrado más arriba, pero cambiaremos fig por suppfig:
{#fig-cecropia}
Ahora podemos referenciar esta imagen en cualquier momento usando @suppfig-cecropia. Si escribimos:
La @suppfig-cecropia es de otro yarumo.Si quisiéramos hacer lo mismo para una imagen generada por código, podríamos intentar lo siguiente:
```{r}
#| label: suppfig-iris
#| fig-cap: Un boxplot.
#| fig-alt: Un boxplot de la variable petal length de las espcies del conjuto de datos Iris.
iris |>
ggplot2::ggplot(
ggplot2::aes(
Species,
Petal.Length
)
) +
ggplot2::geom_boxplot()
```
Sin embargo, esto no genera el prefijo en la descripción de la imagen. Además, si intentamos referenciarla usando @suppfig-iris, veremos que aparece el error ?@suppfig-iris. Esto se debe a cómo está configurado actualmente Quarto. Para que Quarto interprete correctamente esta imagen utilizando referencias cruzadas personalizadas, debemos usar la sintaxis de Divs, que consiste en encerrar el código entre dos grupos de ::: y realizar algunos pequeños cambios:
::: {#suppfig-iris fig-alt="fig-alt="n boxplot de la variable petal length de las espcies del conjuto de datos Iris.""}
```r
iris |>
ggplot2::ggplot(
ggplot2::aes(
Species,
Petal.Length
)
) +
ggplot2::geom_boxplot()
```
Gráfico de dispersión.
:::
Ahora sí podemos usar @suppfig-iris sin problema, como se muestra en Figura S2.
Como hemos visto, Quarto es muy potente y sumamente útil para realizar referencias cruzadas, una tarea tediosa cuando escribimos un artículo científico o un trabajo académico. Aunque referenciar material suplementario puede resultar confuso al principio, sobre todo cuando son elementos generados por código, con un poco de práctica se vuelve sencillo y se ahorra mucho tiempo al evitar problemas con las referencias. Solo nos queda esperar que sigan apareciendo más plantillas de Quarto para revistas académicas, y estaremos un paso más cerca de decir ¡adiós, maldito .doc!
Identificador único para cada tipo de referencia cruzada.↩︎
Hay muchísimas más opciones.↩︎
@online{espinosa-correa2024,
author = {Espinosa-Correa, Álex},
title = {Las referencias cruzadas personalizadas de Quarto},
date = {2024-08-10},
url = {https://alexespinosaco.github.io/aerovagante/2024-08-10_quarto-referencias-cruzadas/},
langid = {es}
}