Opciones de ejecución

Introducción

Esta guía ofrece una visión general de las opciones de ejecución de código en Quarto, un versátil sistema de documentos computacionales. Quarto soporta múltiples motores, incluyendo Jupyter y Knitr, y ofrece una gama de opciones para personalizar las salidas de código en tus documentos.

Esta guía cubre los siguientes temas:

  • Opciones de salida de código: Aprende a personalizar y controlar las salidas de código en tus documentos Quarto.
  • Formatos diversos: Adapte la configuración de ejecución para varios formatos de documento, incluyendo HTML, PDF y diapositivas.
  • Personalizaciones avanzadas: Tamaño de las figuras y manejo de errores para mejorar la presentación del documento.
  • Compatibilidad con herramientas: Ideal para usuarios que emplean herramientas Jupyter o Knitr, asegurando la funcionalidad a través de diferentes plataformas computacionales.


Opciones de salida

Oculta el código del documento de salida utilizando echo: false en la configuración del documento `yaml:

---
title: "Mi documento"
execute:
  echo: false
jupyter: python3
---

Anular esta opción para cada bloque de código:

```{python}
#| echo: true

import matplotlib.pyplot as plt
plt.plot([1,2,3,4])
plt.show()
```
Nota

Las opciones del bloque de código se incluyen en un comentario especial en la parte superior del bloque. Las líneas en la parte superior precedidas por #| se consideran opciones.

Opciones para personalizar la salida:

Opción de salida Descripción
eval Evalúa el fragmento de código (si es false, sólo resuena el código en la salida).
echo Incluir el código fuente en la salida.
output Incluir los resultados de ejecutar el código en la salida (true, false, o asis para indicar que la salida es markdown crudo y no debe tener ninguno de los markdowns estándar de Quarto).
warning Incluir advertencias en la salida.
error Incluir errores en la salida (tenga en cuenta que esto implica que los errores de ejecución de código no detendrán el procesamiento del documento).
include Se utiliza para evitar que cualquier salida (código o resultados) se incluya (por ejemplo, include: false suprime toda la salida del bloque de código).

Ejemplo Knitr con algunas de estas opciones adicionales incluidas:

---
title: "Documento Knitr"
execute:
  echo: false
---

```{r}
#| warning: false

library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess", se = FALSE)
```

```{r}
summary(airquality)
```
Tip

Cuando se utiliza el motor Knitr, también se puede utilizar cualquiera de las opciones nativas disponibles (por ejemplo, collapse, tidy, comment, etc.). Consulte la Documentación de opciones Knitr para más detalles. Puedes incluir estas opciones nativas en bloques de comentarios de opciones como se muestra arriba, o en la misma línea que {r} como se muestra en la documentación de Knitr.

Opciones de figura

Anchura y altura de las figuras por defecto (expresadas en pulgadas por tipo de documento):

Formato del documento Valor por defecto
Por defecto 7 x 5
Diapositivas HTML 9.5 x 6.5
Diapositivas HTML (reveal.js) 9 x 5
PDF 5.5 x 3.5
Diapositivas PDF (Beamer) 10 x 7
PowerPoint 7.5 x 5.5
MS Word, ODT, RTF 5 x 4
EPUB 5 x 4
Hugo 8 x 5

Cambie los tamaños por defecto usando las opciones fig-width y fig-height:

---
title: "Mi documento"
format: 
  html:
    fig-width: 8
    fig-height: 6
  pdf:
    fig-width: 7
    fig-height: 5
---
Precaución

Cuando se utiliza el motor Knitr, fig-width y fig-height se admiten por celda. Pero cuando se utiliza el motor Jupyter, estas opciones sólo tienen efecto si se especifican en los metadatos a nivel de documento o proyecto.

Leyenda y texto alternativo

  • Utiliza las opciones fig-cap y fig-alt para los subtítulos y el texto alternativo de las figuras generadas por código.
  • Ejemplo en una celda de código R plot:
```{r}
#| fig-cap: "Gráfico de dispersión"
#| fig-alt: "Un gráfico de dispersión de R"

plot(1:10)
```

Resultado bruto

  • Usar output: asis para una salida markdown en bruto sin los divs estándar de Quarto.
  • Ejemplo: generar encabezados con output: asis.
```{python}
#| echo: false
#| output: asis

print("# Encabezado 1\n")
print("## Encabezado 2\n")
```
```{r}
#| echo: false
#| output: asis

cat("# Encabezado 1\n")
cat("## Encabezado 2\n")
```

Salida:

# Encabezado 1

## Encabezado 2
Tip

Tenga en cuenta que también incluimos la opción echo: false para garantizar que el código utilizado para generar markdown no se incluya en la salida final.

Para el motor Jupyter, también puede crear una salida markdown sin procesar utilizando las funciones en IPython.display:

```{python}
#| echo: false
radius = 10
from IPython.display import Markdown
Markdown(f"The _radius_ of the circle is **{radius}**.")
```

Opciones Knitr

Si estás usando el motor de ejecución de celdas Knitr, puedes especificar opciones predeterminadas a nivel de documento Knitr chunk options en YAML. Por ejemplo:

---
title: "Mi documento"
format: html
knitr:
  opts_chunk: 
    collapse: true
    comment: "#>" 
    R.options:
      knitr.graphics.auto_pdf: true
---

Puedes especificar adicionalmente opciones globales de Knitr usando opts_knit.

La opción R.options es una forma conveniente de definir las opciones de R que se establecen temporalmente a través de options() antes de la ejecución del fragmento de código, y se restauran inmediatamente después.

En el ejemplo anterior, establecemos las opciones por defecto de Knitr chunk para un único documento. También puedes añadir opciones compartidas knitr a un archivo _quarto.yml para todo el proyecto o a un archivo _metadata.yml para el directorio del proyecto.

Intermedios

Mantener archivos intermedios durante el renderizado con estas opciones:

Opciones de representación Descripción
keep-md Mantener el archivo markdown generado al ejecutar el código.
keep-ipynb Mantener el archivo notebook generado a partir de la ejecución de código (aplicable sólo a archivos de entrada markdown)

Por ejemplo, aquí especificamos que queremos mantener el archivo intermedio jupyter después de la renderización:

---
title: "Mi documento"
execute:
  keep-ipynb: true
jupyter: python3
---

Eco Vallado

  • Utilice echo: fenced para mostrar delimitadores de código (por ejemplo, ```{python}) en tutoriales o documentación.
  • Ejemplo:
```{python}
#| echo: fenced
1 + 1
```

Salida:

```{python}
1 + 1
```
2

Útil para demostrar opciones de celda como output and code-overflow:

Ejemplo:

```{python}
#| echo: fenced
#| output: false
#| code-overflow: wrap
1 + 1
```

Salida:

```{python}
#| output: false
#| code-overflow: wrap
1 + 1
```

Este comportamiento también puede ser especificado a nivel de documento si quieres que todos tus bloques de código ejecutable incluyan el delimitador cercado y las opciones YAML:

---
title: "Mi documento"
format: html
execute:
  echo: fenced
---

Bloques no ejecutados

Para bloques de código no ejecutados, utilice llaves dobles alrededor del lenguaje (por ejemplo, {python}):

Ejemplo:

```{{python}}
1 + 1
```

Salida:

```{python}
1 + 1
```

Si desea mostrar un ejemplo con múltiples bloques de código y otras marcas, simplemente encierre todo el ejemplo entre 4 comillas (por ejemplo, ````) y utilice la sintaxis de dos llaves para los bloques de código dentro del ejemplo. Por ejemplo:

---
title: "Mi documento"
---

Algunos contenidos markdown.

```{python}
1 + 1
```

Contenido adicional de markdown.

Comandos Shell

El uso de comandos shell (de Bash, Zsh, etc.) en los documentos computacionales de Quarto varía según el motor.

Usando Jupyter shell magics:

---
title: "Usando Bash"
engine: jupyter
---

```{python}
!echo "foo"
```

Tenga en cuenta que ! que precede a echo es lo que permite a una celda Python ser capaz de ejecutar un comando shell.

Uso de las celdas ```{bash}:

---
title: "Usando Bash"
engine: knitr
---

```{bash}
echo "foo" 
```
Nota

El motor Knitr también admite las celdas ```{python}, lo que permite combinar R, Python y Bash en el mismo documento

Referencias