Options d’exécution

Introduction

Ce guide donne un aperçu des options d’exécution de code dans Quarto, un système de document computationnel polyvalent. Quarto supporte plusieurs moteurs, incluant Jupyter et Knitr, et offre une gamme d’options pour personnaliser les sorties de code dans vos documents.

Ce guide aborde les sujets suivants:

  • Options de sortie du code : Apprenez à personnaliser et à contrôler les sorties de code dans vos documents Quarto.
  • Différents formats : Configurez les paramètres d’exécution pour différents formats de documents, incluant HTML, PDF et diapositives.
  • Personnalisations avancées : Dimensionnement des figures et gestion des erreurs pour une présentation améliorée des documents.
  • Compatibilité avec les outils : Idéal pour les utilisateurs employant les outils Jupyter ou Knitr, assurant la fonctionnalité à travers différentes plateformes computationnelles.


Options de sortie

Masquer le code du document de sortie en utilisant echo : false dans les paramètres yaml du document:

---
title: "Mon document"
execute:
  echo: false
jupyter: python3
---

Remplacer cette option pour chaque bloc de code:

```{python}
#| echo: true

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

Les options des blocs de code sont incluses dans un commentaire spécial en haut du bloc. Les lignes précédées de #| sont considérées comme des options.

Options pour personnaliser la sortie:

Option de sortie Description de l’option
eval Évaluer le morceau de code (si false, le code est simplement répercuté dans la sortie).
echo Inclure le code source dans la sortie.
output Inclure les résultats de l’exécution du code dans la sortie (true, false, ou asis pour indiquer que la sortie est du markdown brute et ne devrait pas avoir de demarcation markdown standard dans Quarto).
warning Inclure les avertissements dans la sortie.
error Inclure les erreurs dans la sortie (notez que cela implique que les erreurs d’exécution du code n’interrompent pas le traitement du document).
include Utiliser pour empêcher toute sortie (code ou résultats) d’être incluse (par exemple, include : false supprime toute sortie du bloc de code).

Exemple de Knitr avec certaines de ces options supplémentaires incluses:

---
title: "Document 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)
```
Astuce

Lorsque vous utilisez le moteur Knitr, vous pouvez également utiliser n’importe laquelle des options natives disponibles (par exemple collapse, tidy, comment, etc.). Voir la documentation des options Knitr pour plus de détails. Vous pouvez inclure ces options natives dans des blocs de commentaires d’options comme indiqué ci-dessus, ou sur la même ligne que le {r} comme indiqué dans la documentation Knitr.

Options de figure

Largeur et hauteur des figures par défaut (exprimées en pouces par type de document):

Format du document Valeur par défaut
Défaut 7 x 5
Diapositives HTML 9.5 x 6.5
Diapositives HTML (reveal.js) 9 x 5
PDF 5.5 x 3.5
Diapositives 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

Changer les tailles par défaut en utilisant les options fig-width et fig-height:

---
title: "Mon document"
format: 
  html:
    fig-width: 8
    fig-height: 6
  pdf:
    fig-width: 7
    fig-height: 5
---
Mise en garde

Lorsque vous utilisez le moteur Knitr, fig-width et fig-height sont supportés sur une base par cellule. Mais lorsque vous utilisez le moteur Jupyter, ces options n’ont d’effet que si elles sont spécifiées dans les métadonnées au niveau du document ou du projet.

Légende et texte Alt

  • Utiliser les options fig-cap et fig-alt pour les légendes et le texte alt dans les figures générées par le code.
  • Exemple dans une cellule de code de graphique R:
```{r}
#| fig-cap: "Graphique de nuage de points"
#| fig-alt: "Un graphique de nuage de points à partir de R"

plot(1:10)
```

Sortie brute

  • Utiliser output : asis pour une sortie markdown brute sans les divs standards de Quarto.
  • Exemple : générer des titres avec output: asis.
```{python}
#| echo: false
#| output: asis

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

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

Sortie:

# Titre 1

## Titre 2
Astuce

Notez que nous incluons également l’option echo : false pour s’assurer que le code utilisé pour générer le markdown n’est pas inclus dans la sortie finale.

Pour le moteur Jupyter, vous pouvez également créer une sortie markdown brute en utilisant les fonctions de la section IPython.display:

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

Options Knitr

Si vous utilisez le moteur d’exécution de cellules Knitr, vous pouvez spécifier des [options de blocs Knitr] (https://yihui.org/knitr/options/) par défaut au niveau du document dans le langage YAML. Par exemple:

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

Vous pouvez également spécifier des options Knitr globales en utilisant opts_knit.

L’option de bloc R.options est un moyen pratique de définir des options R qui sont configurées temporairement via [options()] (https://rdrr.io/r/base/options.html) avant l’exécution du bloc de code, et qui sont immédiatement restaurées après.

Dans l’exemple ci-dessus, nous établissons des options de bloc Knitr par défaut pour un seul document. Vous pouvez également ajouter des options knitr partagées à un fichier _quarto.yml à l’échelle du projet ou à un fichier _metadata.yml à l’échelle du répertoire du projet.

Intermédiaires

Conserver les fichiers intermédiaires pendant le rendu avec ces options:

Option de rendu Description de l’option
keep-md Conserver le fichier markdown généré par l’exécution du code.
keep-ipynb Conserver le fichier Notebooks généré par l’exécution du code (applicable uniquement aux fichiers d’entrée markdown)

Par exemple, nous spécifions ici que nous voulons conserver le fichier intermédiaire jupyter après le rendu:

---
title: "Mon document"
execute:
  keep-ipynb: true
jupyter: python3
---

Echo clôturé

  • Utilisez echo : fenced pour afficher les délimiteurs de code (par exemple, ```{python}) dans les tutoriels ou la documentation.
  • Exemple:
```{python}
#| echo: fenced
1 + 1
```

Sortie:

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

Utile pour démontrer des options de cellule comme output and code-overflow:

Exemple:

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

Sortie:

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

Ce comportement peut également être spécifié au niveau du document si vous souhaitez que tous vos blocs de code exécutables incluent le délimiteur clôturé et les options YAML:

---
title: "Mon document"
format: html
execute:
  echo: fenced
---

Blocs non exécutés

Pour les blocs de code non exécutés, utilisez des accolades doubles autour du langage (par exemple, {python}):

Exemple:

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

Sortie:

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

Si vous voulez montrer un exemple avec plusieurs blocs de code et d’autres marques, il suffit d’entourer l’ensemble de l’exemple de 4 crochets (par exemple ````) et d’utiliser la syntaxe des deux accolades pour les blocs de code à l’intérieur. Par exemple:

---
title: "Mon document"
---

Un peu de contenu markdown.

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

Quelques contenus markdown supplémentaires.

Commandes Shell

L’utilisation des commandes shell (Bash, Zsh, etc.) dans les documents computationnels Quarto diffère selon le moteur.

Utiliser les magies du shell Jupyter:

---
title: "Utiliser Bash"
engine: jupyter
---

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

Notez que ! précédant echo est ce qui permet à une cellule Python d’être capable d’exécuter une commande shell.

Utiliser ```{bash} cellules:

---
title: "Utiliser Bash"
engine: knitr
---

```{bash}
echo "foo" 
```
Note

Le moteur Knitr supporte également ```{python} cellules, permettant la combinaison de R, Python, et Bash dans le même document

Références