« Quarto » : différence entre les versions

Dernière version du 25 septembre 2024 à 13:09

Pensée computationnelle avec R

⚐ à finaliser	☸ débutant
⚒ 2024/09/25
Catégorie: R

Introduction

Quarto est un système open-source de publication d'articles scientifiques et techniques basé sur Pandoc. Il permet d'exploiter différents langages de programmation tels que R, Python, Julia ou JavaScript. Il applique le même principe de programmation lettrée comme par exemple Rmarkdown, dont il représente une version plus moderne et facile à adapter à différents cadres d'utilisations. Quarto peut être utilisé en ligne de commande ou à travers d'autres logiciels comme RStudio ou Visual studio code.

Cet article s'intéresse principalement à l'utilisation de Quarto avec R dans le contexte de la pensée computationnelle avec R. Pour les autres langages, vous pouvez pour l'instant vous référez à la documentation du site officiel.

Installation

Quarto peut être installé de différentes manières, par exemple :

En tant que logiciel qui s'active directement en ligne de commande. L'installation peut être nécessaire aussi pour les autres modalités d'utilisation.
En tant que paquet R qui s'intègre avec le logiciel RStudio
En tant qu'extension de Visual studio code

Logiciel en ligne de commande

Quarto CLI (Command Line Interface) est disponible directement depuis le site officiel pour Mac, Windows et Linux.

Une fois installé, Quarto CLI est disponible dans la ligne de commande directement en saisissant quarto. Par exemple, pour créer un document en HTML on peut utiliser la commande :

quarto render hello.qmd --to html

Paquet de R

Pour l'installation dans R/RStudio, il faut d'abord installer le paquet avec :

 install.packages("quarto")

À ce moment, on peut bénéficier dans l'interface de RStudio de différents projets et commandes à l'interface pour créer et transformer des fichiers Quarto dans d'autres formats d'output.

Pour plus d'informations, voir la page dédiée à RStudio dans le site officiel :

Get started avec Quarto et RStudio

Extension de Visual studio code

Il existe également une extension de Visual studio code qui peut être installée directement depuis le gestionnaire d'extension du logiciel ou depuis le marketplace. Pour plus d'informations, voir la page dédiée à Visual studio code dans le site officiel :

Get started avec Quarto et Visual studio code

Fonctionnement de Quarto

Quarto est basé sur un ou plusieurs fichiers avec extension .qmd dont le contenu mélange des éléments narratifs écrits en Markdown et des aspects computationnels issus d'un langage de programmation comme R, Python, Julia ou JavaScript.

Le fichier source .qmd est ensuite rendu dans un format de output qui peut être :

Une page, un site ou un blog HTML5
Un document/article PDF
Une présentation PowerPoint ou Reveal.js
Un document Word
Un livre électronique comme un Epub
...

Le rendering se fait selon le type d'installation appliquée, c'est-à-dire depuis la ligne de commande ou les interfaces graphiques des logiciels comme RStudio ou Visual studio code.

Un document Quarto se divise en deux grandes parties :

L'entête en YAML
Le corpus avec les contenus du documents

Entête en YAML

L'entête du document contient des informations utiles pour le rendering du document, comme par exemple le format et les options d'output. L'entête est écrite dans un format de marquage appelé YAML qui correspond à une série d'associations clé:valeurs qui peuvent aussi être emboitées à plusieurs niveaux.

Voici un exemple de simple entête YAML :

---
title: "Titre du document"
author: "Mattia A. Fritz"
format: html
---

L'entête permet de définir beaucoup d'options qui dépendent étroitement du type de format envisagé. Les différents options sont disponibles dans une référence sur le site officiel de Quarto :

Références pour les options de l'entête

Corpus avec les contenus

Le corpus du document propose le mélange entre éléments narratifs et computationnels qui définissent le document finalisé. Voici un exemple tiré de la documentation officiel de Quarto qui propose un document complet aussi avec l'entête :

---
title: "Penguins, meet Quarto!"
format: html
editor: visual
---

```{r}
#| label: load-packages
#| include: false

library(tidyverse)
library(palmerpenguins)
```

## Meet Quarto

Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.

## Meet the penguins

![](https://raw.githubusercontent.com/quarto-dev/quarto-web/main/docs/get-started/hello/rstudio/lter_penguins.png){style="float:right;" fig-alt="Illustration of three species of Palmer Archipelago penguins: Chinstrap, Gentoo, and Adelie. Artwork by @allison_horst." width="401"}

The `penguins` data from the [**palmerpenguins**](https://allisonhorst.github.io/palmerpenguins "palmerpenguins R package") package contains size measurements for `r nrow(penguins)` penguins from three species observed on three islands in the Palmer Archipelago, Antarctica.

The plot below shows the relationship between flipper and bill lengths of these penguins.

```{r}
#| label: plot-penguins
#| warning: false
#| echo: false

ggplot(penguins, 
       aes(x = flipper_length_mm, y = bill_length_mm)) +
  geom_point(aes(color = species, shape = species)) +
  scale_color_manual(values = c("darkorange","purple","cyan4")) +
  labs(
    title = "Flipper and bill length",
    subtitle = "Dimensions for penguins at Palmer Station LTER",
    x = "Flipper length (mm)", y = "Bill length (mm)",
    color = "Penguin species", shape = "Penguin species"
  ) +
  theme_minimal()
```

Le document source doit être ensuite rendu pour obtenir le format final. Dans ce cas, ce serait un document en HTML5 qui peut être ensuite publié sur le web.

Cadres d'utilisations de Quarto

Quarto peut être utilisé dans plusieurs contextes scientifiques et techniques. Ici nous proposons une brève liste avec des références directement dans la documentation officielle.

Documents générés dynamiquement

Ces documents appliquent des pratiques liées à la science ouverte en termes de transparence et documentation du processus en s'appuyant sur la computation. Les documents mélangent en effet des éléments narratifs avec des éléments qui sont calculés/crées automatiquement à travers des scripts/algorithmes qui peuvent être inclus ou incorporés par référence dans le document. De cette manière, le document finalisé peut être analysé dans une perspective de rétro-ingénierie pour savoir exactement comme il a été créé. Pour plus d'informations voir :

Créer des documents dynamiques avec R

Créer des publications de qualité en différents formats

Quarto permet de créer des documents en différents formats en utilisant potentiellement le même fichier source. À travers la définition d'options de publication générales ou spécifiques au type de format envisagé, les documents finalisés peuvent être adaptés au niveau de la structure ou de l'esthétique.

Étant spécifiquement pensé pour les documents scientifiques et techniques, Quarto facilite l'intégration de contenus souvent utilisé dans ce contexte tels que :

Les tableaux
Les graphiques
Les équations
Les résultats d'analyse statistiques
Les diagrammes

Ces contenus sont incrustés directement dans le document source et peuvent être modifiés directement à travers du code. De cette manière, il n'est pas nécessaire de copier/coller des éléments depuis d'autres logiciels ou devoir créer des images externes à incorporer ensuite dans le document.

Voir la liste des formats supportés

Sites, blogs ou livres en ligne

Il y a de plus en plus la tendance à publier des documents scientifiques et techniques en HTML5 plutôt qu'en PDF. Ceci présente plusieurs avantages, notamment en ce qui concerne la lecture sur écrans. Quarto permet de créer facilement des contenus web comme des sites, des blogs, ou des livres en ligne. Les auteurs doivent se concentrer sur les contenus et peuvent ensuite décider les différents options pour déterminer le produit final.

Documents interactifs

Avec Quarto il est également possible de créer des documents interactifs, sur lesquels les utilisateurs peuvent effectuer des manipulations directes. Ce type de documents peuvent être exploités par exemple pour :

des finalités pédagogiques, par exemple pour poser des questions ou permettre des manipulations directes à l'interface
mettre à dispositions des utilisateurs des applications pour effectuer des tâches
proposer des visualisations de données interactives et progressives
...

Selon la complexité des documents interactifs, il est parfois nécessaire de disposer d'une structure hardware correspondante ou publier les documents sur des serveurs spécifiques.

Interactivité avec Quarto

Ressources

Site officiel de Quarto
Announcing Quarto, a new scientific and technical publishing system : post d'annonce de l'introduction de la technologie en 2022
Beautiful reports and presentations with Quarto : vidéo d'environ 1h45 par Tom Mock
Building a blog with Quarto : vidéo d'environ 1h15 par Isabelle Velàsquez
Awesome Quarto : une collection de ressources à propos de Quarto

@@ Ligne 1 : / Ligne 1 : @@
-{{ En construction }}
+{{tutoriel
+|fait_partie_du_cours=Pensée computationnelle avec R
+|module_suivant=
+|pas_afficher_sous-page=Non
+|page_suivante=
+|statut=à finaliser
+|difficulté=débutant
+|cat tutoriels=R
+}}
 == Introduction ==
-[https://quarto.org/ Quarto] est un système open-source de publication d'articles scientifiques et techniques basé sur [https://pandoc.org/ Pandoc]. Il permet d'exploiter différents langages de programmation tels que [[R]], Python, Julia ou [[JavaScript]]. Il applique le même principe de programmation lettrée comme par exemple [[Introduction à Rmarkdown|Rmarkdown]], dont il représente une version plus moderne et facile à adapter à différents cadres d'utilisations.
+[https://quarto.org/ Quarto] est un système open-source de publication d'articles scientifiques et techniques basé sur [[Pandoc]]. Il permet d'exploiter différents langages de programmation tels que [[R]], Python, Julia ou [[JavaScript]]. Il applique le même principe de programmation lettrée comme par exemple [[Introduction à Rmarkdown|Rmarkdown]], dont il représente une version plus moderne et facile à adapter à différents cadres d'utilisations. Quarto peut être utilisé en ligne de commande ou à travers d'autres logiciels comme [[RStudio]] ou [[Visual studio code]].
-Il peut être utilisé en ligne de commande ou en
 Cet article s'intéresse principalement à l'utilisation de Quarto avec [[R]] dans le contexte de la [[pensée computationnelle avec R]]. Pour les autres langages, vous pouvez pour l'instant vous référez à la documentation du [https://quarto.org/ site officiel].
@@ Ligne 19 : / Ligne 24 : @@
 === Logiciel en ligne de commande ===
-[https://quarto.org/docs/get-started/ Quarto CLI] (Command Line Interface) est disponible directement depuis le site officiel. Quarto CLI est disponible pour Mac, Windows et Linux.
+[https://quarto.org/docs/get-started/ Quarto CLI] (Command Line Interface) est disponible directement depuis le site officiel pour Mac, Windows et Linux.
+Une fois installé, Quarto CLI est disponible dans la ligne de commande directement en saisissant <code>quarto</code>. Par exemple, pour créer un document en HTML on peut utiliser la commande :
+ quarto render hello.qmd --to html
 === Paquet de R ===
@@ Ligne 31 : / Ligne 40 : @@
 Pour plus d'informations, voir la page dédiée à RStudio dans le site officiel :
-{{ Goblock | [https://quarto.org/docs/get-started/hello/rstudio.html Get started avec Quarto et RStudio]] }}
+{{ Goblock | [https://quarto.org/docs/get-started/hello/rstudio.html Get started avec Quarto et RStudio] }}
 === Extension de Visual studio code ===
@@ Ligne 37 : / Ligne 46 : @@
 Il existe également une extension de [[Visual studio code]] qui peut être installée directement depuis le gestionnaire d'extension du logiciel ou depuis le [https://marketplace.visualstudio.com/items?itemName=quarto.quarto marketplace]. Pour plus d'informations, voir la page dédiée à Visual studio code dans le site officiel :
-{{ Goblock | [https://quarto.org/docs/get-started/hello/vscode.html Get started avec Quarto et Visual studio code]] }}
+{{ Goblock | [https://quarto.org/docs/get-started/hello/vscode.html Get started avec Quarto et Visual studio code] }}
+== Fonctionnement de Quarto ==
+Quarto est basé sur un ou plusieurs fichiers avec extension <code>.qmd</code> dont le contenu mélange des éléments narratifs écrits en Markdown et des aspects computationnels issus d'un langage de programmation comme [[R]], Python, Julia ou [[JavaScript]].
+Le fichier source <code>.qmd</code> est ensuite ''rendu'' dans un format de output qui peut être :
+* Une page, un site ou un blog [[HTML5]]
+* Un document/article PDF
+* Une présentation PowerPoint ou [[Reveal.js]]
+* Un document Word
+* Un livre électronique comme un [[Epub]]
+* ...
+Le ''rendering'' se fait selon le type d'installation appliquée, c'est-à-dire depuis la ligne de commande ou les interfaces graphiques des logiciels comme [[RStudio]] ou [[Visual studio code]].
+Un document Quarto se divise en deux grandes parties :
+# L'entête en YAML
+# Le corpus avec les contenus du documents
+=== Entête en YAML ===
+L'entête du document contient des informations utiles pour le ''rendering'' du document, comme par exemple le format et les options d'output. L'entête est écrite dans un format de marquage appelé YAML qui correspond à une série d'associations clé:valeurs qui peuvent aussi être emboitées à plusieurs niveaux.
+Voici un exemple de simple entête YAML :
+<syntaxhighlight lang="YAML">
+---
+title: "Titre du document"
+author: "Mattia A. Fritz"
+format: html
+---
+</syntaxhighlight>
+L'entête permet de définir beaucoup d'options qui dépendent étroitement du type de format envisagé. Les différents options sont disponibles dans une référence sur le site officiel de Quarto :
+{{ Goblock | [https://quarto.org/docs/reference/ Références pour les options de l'entête] }}
+=== Corpus avec les contenus ===
+Le corpus du document propose le mélange entre éléments narratifs et computationnels qui définissent le document finalisé. Voici un exemple tiré de la documentation officiel de Quarto qui propose un document complet aussi avec l'entête :
+<syntaxhighlight lang="Markdown">
+---
+title: "Penguins, meet Quarto!"
+format: html
+editor: visual
+---
+```{r}
+#| label: load-packages
+#| include: false
+library(tidyverse)
+library(palmerpenguins)
+```
+## Meet Quarto
+Quarto enables you to weave together content and executable code into a finished document. To learn more about Quarto see <https://quarto.org>.
+## Meet the penguins
+![](https://raw.githubusercontent.com/quarto-dev/quarto-web/main/docs/get-started/hello/rstudio/lter_penguins.png){style="float:right;" fig-alt="Illustration of three species of Palmer Archipelago penguins: Chinstrap, Gentoo, and Adelie. Artwork by @allison_horst." width="401"}
+The `penguins` data from the [**palmerpenguins**](https://allisonhorst.github.io/palmerpenguins "palmerpenguins R package") package contains size measurements for `r nrow(penguins)` penguins from three species observed on three islands in the Palmer Archipelago, Antarctica.
+The plot below shows the relationship between flipper and bill lengths of these penguins.
+```{r}
+#| label: plot-penguins
+#| warning: false
+#| echo: false
+ggplot(penguins,
+       aes(x = flipper_length_mm, y = bill_length_mm)) +
+  geom_point(aes(color = species, shape = species)) +
+  scale_color_manual(values = c("darkorange","purple","cyan4")) +
+  labs(
+    title = "Flipper and bill length",
+    subtitle = "Dimensions for penguins at Palmer Station LTER",
+    x = "Flipper length (mm)", y = "Bill length (mm)",
+    color = "Penguin species", shape = "Penguin species"
+  ) +
+  theme_minimal()
+```
+</syntaxhighlight>
+Le document source doit être ensuite ''rendu'' pour obtenir le format final. Dans ce cas, ce serait un document en [[HTML5]] qui peut être ensuite publié sur le web.
+== Cadres d'utilisations de Quarto ==
+Quarto peut être utilisé dans plusieurs contextes scientifiques et techniques. Ici nous proposons une brève liste avec des références directement dans la documentation officielle.
+=== Documents générés dynamiquement ===
+Ces documents appliquent des pratiques liées à la science ouverte en termes de transparence et documentation du processus en s'appuyant sur la [[computation]]. Les documents mélangent en effet des éléments narratifs avec des éléments qui sont calculés/crées automatiquement à travers des scripts/[[algorithme|algorithmes]] qui peuvent être inclus ou incorporés par référence dans le document. De cette manière, le document finalisé peut être analysé dans une perspective de rétro-ingénierie pour savoir exactement comme il a été créé. Pour plus d'informations voir :
+* [https://quarto.org/docs/computations/r.html Créer des documents dynamiques avec R]
+=== Créer des publications de qualité en différents formats ===
+Quarto permet de créer des documents en différents formats en utilisant potentiellement le même fichier source. À travers la définition d'options de publication générales ou spécifiques au type de format envisagé, les documents finalisés peuvent être adaptés au niveau de la structure ou de l'esthétique.
+Étant spécifiquement pensé pour les documents scientifiques et techniques, Quarto facilite l'intégration de contenus souvent utilisé dans ce contexte tels que :
+* Les tableaux
+* Les graphiques
+* Les équations
+* Les résultats d'analyse statistiques
+* Les diagrammes
+Ces contenus sont incrustés directement dans le document source et peuvent être modifiés directement à travers du code. De cette manière, il n'est pas nécessaire de copier/coller des éléments depuis d'autres logiciels ou devoir créer des images externes à incorporer ensuite dans le document.
+* [https://quarto.org/docs/output-formats/all-formats.html Voir la liste des formats supportés]
+=== Sites, blogs ou livres en ligne ===
+Il y a de plus en plus la tendance à publier des documents scientifiques et techniques en [[HTML5]] plutôt qu'en PDF. Ceci présente plusieurs avantages, notamment en ce qui concerne la lecture sur écrans. Quarto permet de créer facilement des contenus web comme des sites, des blogs, ou des livres en ligne. Les auteurs doivent se concentrer sur les contenus et peuvent ensuite décider les différents options pour déterminer le produit final.
+* [https://quarto.org/docs/websites/ Créer un site web avec Quarto]
+* [https://quarto.org/docs/websites/website-blog.html Créer un blog avec Quarto]
+* [https://quarto.org/docs/books/ Créer un livre en ligne avec Quarto]
+=== Documents interactifs ===
+Avec Quarto il est également possible de créer des documents interactifs, sur lesquels les utilisateurs peuvent effectuer des manipulations directes. Ce type de documents peuvent être exploités par exemple pour :
+* des finalités pédagogiques, par exemple pour poser des questions ou permettre des manipulations directes à l'interface
+* mettre à dispositions des utilisateurs des applications pour effectuer des tâches
+* proposer des visualisations de données interactives et progressives
+* ...
+Selon la complexité des documents interactifs, il est parfois nécessaire de disposer d'une structure hardware correspondante ou publier les documents sur des serveurs spécifiques.
+* [https://quarto.org/docs/interactive/ Interactivité avec Quarto]
+== Ressources ==
+* [https://quarto.org/ Site officiel de Quarto]
+* [https://posit.co/blog/announcing-quarto-a-new-scientific-and-technical-publishing-system/ Announcing Quarto, a new scientific and technical publishing system] : post d'annonce de l'introduction de la technologie en 2022
+* [https://www.youtube.com/watch?v=hbf7Ai3jnxY&list=PL9HYL-VRX0oRupficE2l5DGgVIzpypTHs&index=3 Beautiful reports and presentations with Quarto] : vidéo d'environ 1h45 par Tom Mock
+* [https://www.youtube.com/watch?v=CVcvXfRyfE0&list=PL9HYL-VRX0oRupficE2l5DGgVIzpypTHs&index=2 Building a blog with Quarto] : vidéo d'environ 1h15 par Isabelle Velàsquez
+* [https://github.com/mcanouil/awesome-quarto Awesome Quarto] : une collection de ressources à propos de Quarto
 [[Catégorie: R]]

« Quarto » : différence entre les versions

Dernière version du 25 septembre 2024 à 13:09

Sommaire

Introduction

Installation

Logiciel en ligne de commande

Paquet de R

Extension de Visual studio code

Fonctionnement de Quarto

Entête en YAML

Corpus avec les contenus

Cadres d'utilisations de Quarto

Documents générés dynamiquement

Créer des publications de qualité en différents formats

Sites, blogs ou livres en ligne

Documents interactifs

Ressources

Menu de navigation

« Quarto » : différence entre les versions

Dernière version du 25 septembre 2024 à 13:09

Introduction

Installation

Logiciel en ligne de commande

Paquet de R

Extension de Visual studio code

Fonctionnement de Quarto

Entête en YAML

Corpus avec les contenus

Cadres d'utilisations de Quarto

Documents générés dynamiquement

Créer des publications de qualité en différents formats

Sites, blogs ou livres en ligne

Documents interactifs

Ressources

Menu de navigation

Rechercher

« Quarto » : différence entre les versions