Документы Quarto имеют расширение *.qmd. Основными составляющими Quarto-документа являются:
Ниже приведен пример элементов Quarto-документа.
Метаданные в Quarto реализованы на основе YAML и могут быть включены в Quarto-документ в преамбуле в начале файла и/или в отдельном _quarto.yml-файле (либо ином *.yml-файле, скажем, _extension.yml, _metadata.yml). Если данные YAML включены в документ, в этом случае YAML-часть отделяется от документа тройным дефисом ---. Например, метаданные могут содержать информацию об авторе, формате документа и визуальном режиме редактора:
---
# пример YAML-метаданных:
# заголовок, дата, формат документа, режим редактора
title: "Заголовок документа"
date: today
format: html
editor: visual
---Метаданные обрабатываются на многих этапах процесса рендеринга и могут влиять на конечный документ многими различными способами: на код, содержимое документа и процесс рендеринга. Базовый синтаксис YAML-файлов использует систему отступов и систему пар ключ-значение в формате key: value. Другие поля YAML, обычно встречающиеся в заголовках документов, включают метаданные, такие как author для автора, subtitle для подзаголовка, date для даты, а также параметры настройки, такие как theme, fontcolor, fig-width и т. д.
_quarto.ymlНиже показан пример для простейшего файла конфигурации. Здесь указаны: тип проекта (параметр type), название (параметр title), формат (в данном случае html), тема веб-страницы (параметр theme), стилевой файл (параметр css) и наличие содержания на странице (параметр toc).
_quarto.yml
# параметры уровня проекта
project:
# тип проекта
# возможные типы: default, website, book и manuscript
type: website
# папка для выходных HTML-данных
output-dir: docs
website:
title: "Название веб-сайта"
format:
html:
theme: cosmo
css: styles.css
toc: trueВообще говоря, любая папка, содержащая файл _quarto.yml, считается проектом Quarto, при этом в самом _quarto.yml задаются параметры верхнего уровня проекта и позволяет выполнять рендер всего проекта без указания конкретного файла
Terminal
quarto render и в дальнейшем публиковать проект.
Параметры, заданные в _quarto.yml, будут применены ко всем файлам Quarto в проекте и сократят повторение за счет указания общих параметров в одном месте. Например, пусть файл _quarto.yml имеет следующий вид
_quarto.yml
project:
type: website
author: Автор Фамилия
format:
html:
toc: trueТогда если в документе указывает другой параметр из _quarto.yml, он переопределит значение по умолчанию.
file_0.qmd
---
author: Другой Автор
format:
html:
toc: false
---Кроме того, вместо того, чтобы полностью расписывать YAML-преамбулу, глобальные настройки позволяют воспользоваться упрощенным вариантом.
file_1.qmd
---
author: Автор Фамилия
title: Заголовок 1
format:
html:
toc: true
---
## Текст 1file_2.qmd
---
author: Автор Фамилия
title: Заголовок 2
format:
html:
toc: true
---
## Текст 2Представление выше эквивалентно следующему
file_1.qmd
---
title: Заголовок 1
---
## Текст 1file_2.qmd
---
title: Заголовок 2
---
## Текст 2вместе с файлом _quarto.yml:
_quarto.yml
---
author: Автор Фамилия
format:
html:
toc: trueВид YAML-файла зависит от вида документа (веб-страница, блог и т. д.), а также формата выходного документа (HTML, MS Word, PDF и т. д.). Мы рассмотрим в последующих частях книги соответствующие YAML настройки для веб-страниц, блогов, книг и т. д. Список известных HTML-опций для полей YAML можно посмотреть на странице документации, аналогичные настройки есть и для PDF, MS Word, Typst и других форматов.
Markdown — это достаточно простой язык разметки для форматирования текста. Quarto основан на Pandoc (см. также Pandoc User’s Guide) и использует вариацию Markdown в качестве базового синтаксиса документа. Pandoc Markdown, по сути, — это расширенная и слегка переработанная версия синтаксиса Markdown.
| Синтаксис Markdown | Вывод |
|---|---|
|
курсив, полужирный, полужирный курсив |
|
курсив, полужирный, полужирный курсив |
|
пример кода |
|
|
|
надстрочный2 / подстрочный2 |
Заголовки разделов, глав, параграфов и т. д. устанавливаются с помощью символа #. Форматирование зависит от общего стиля документов. Несколько примеров показано ниже.
| Синтаксис Markdown | Вывод |
|---|---|
|
Раздел 1 |
|
Раздел 2 |
|
Раздел 3 |
| Синтаксис Markdown | Вывод |
|---|---|
|
|
|
|
|
|
|
|
|
цитата
|
Синтаксис Markdown:
Quarto
| Правое форматирование | Левое | По определению | По центру |
|----------------------:|:------|----------------|:---------:|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1 | 1 | 1 |Вывод:
| Правое форматирование | Левое | По определению | По центру |
|---|---|---|---|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1 | 1 | 1 |
Форматирование таблиц в Markdown может быть более сложным.
Quarto
+---------------------+-------------------------+
| Место | Температура поверхности |
| измерения | |
| +---------+------+--------+
| | min | mean | max |
+=====================+=========+======+========+
| Антарктика | 89,2°C | N/A | 19,8°C |
+---------------------+---------+------+--------+
| Земля | 89,2°C | 14°C | 56,7°C |
+---------------------+---------+------+--------+| Место измерения | Температура поверхности | ||
|---|---|---|---|
| min | mean | max | |
| Антарктика | 89,2°C | N/A | 19,8°C |
| Земля | 89,2°C | 14°C | 56,7°C |
Размеры ширины колонок таблиц можно изменять используя параметр tbl-colwidths="[A,B]", указав пропорции, например, в пропорции A% | B% таким образом, что A + B = 100.
Quarto
::: {#tbl-panel layout-ncol=2}
| буква | USD |
|------------|----------|
| альфа | $1,11 |
| бета | $2,12 |
| гамма | $3,13 |
: Первая таблица {#tbl-first tbl-colwidths="[20,80]"}
| буква | USD |
|------------|----------|
| альфа | $1,11 |
| бета | $2,12 |
| гамма | $3,13 |
: Вторая таблица {#tbl-second tbl-colwidths="[80,20]"}
Общий заголовок
:::| буква | USD |
|---|---|
| альфа | $1,11 |
| бета | $2,12 |
| гамма | $3,13 |
| буква | USD |
|---|---|
| альфа | $1,11 |
| бета | $2,12 |
| гамма | $3,13 |
Также таблицы можно стилизовать с помощью Bootstrap-классов.
Quarto
::: {#tbl-panel layout-ncol=2}
| фрукт | количество |
|----------|------------|
| яблоко | 2 |
| мандарин | 11 |
| апельсин | 8 |
: Первая таблица {#tbl-first .striped .hover .secondary}
| фрукт | количество |
|----------|------------|
| яблоко | 2 |
| мандарин | 11 |
| апельсин | 8 |
: Вторая таблица {#tbl-second .striped .hover .primary}
Общий заголовок
:::| фрукт | количество |
|---|---|
| яблоко | 2 |
| мандарин | 11 |
| апельсин | 8 |
| фрукт | количество |
|---|---|
| яблоко | 2 |
| мандарин | 11 |
| апельсин | 8 |
Список возможных опций для работы с таблицами можно найти на странице документации. Отметим, что в Quarto также можно вставлять различные таблицы на основе библиотек языков программирования, например, статические таблицы с помощью библиотек {gt}, {gtsummary}, {gtExtras}, {tinytable}, {flextable}, {kableExtra}, {gtUtils} и других языка R, {Great Tables} языка Python, {SummaryTables.jl} языка Julia, а также интерактивные таблицы, например, {reactable}, {DT}.
R
head(mtcars) |>
gt::gt()| mpg | cyl | disp | hp | drat | wt | qsec | vs | am | gear | carb |
|---|---|---|---|---|---|---|---|---|---|---|
| 21.0 | 6 | 160 | 110 | 3.90 | 2.620 | 16.46 | 0 | 1 | 4 | 4 |
| 21.0 | 6 | 160 | 110 | 3.90 | 2.875 | 17.02 | 0 | 1 | 4 | 4 |
| 22.8 | 4 | 108 | 93 | 3.85 | 2.320 | 18.61 | 1 | 1 | 4 | 1 |
| 21.4 | 6 | 258 | 110 | 3.08 | 3.215 | 19.44 | 1 | 0 | 3 | 1 |
| 18.7 | 8 | 360 | 175 | 3.15 | 3.440 | 17.02 | 0 | 0 | 3 | 2 |
| 18.1 | 6 | 225 | 105 | 2.76 | 3.460 | 20.22 | 1 | 0 | 3 | 1 |
Сноски представляют собой примечания к тексту, обычно помещаемые в конце страницы, это могут быть комментарий, библиографическая сноска, перевод и т. п. Сами сноски необязательно размещать в конце документа. Они могут размещаться в любом месте, кроме как внутри других текстовых элементов (списков, текстовых цитат, таблиц и т. д.). Каждая сноска должна быть отделена от окружающего содержимого (включая другие сноски) пустыми строками.
Quarto
Пример первой сноски[^1], а также сноски имеющей название[^named-footnote].
[^1]: Это текст первой сноски.
[^named-footnote]: Это текст второй сноски.| Синтаксис Markdown | Вывод |
|---|---|
|
https://www.r-project.org/ |
|
R Project |
|
 |
Приведем некоторые возможные примеры вставки рисунков в документы, общая структура конструкции: .
| Синтаксис Markdown | Изображение рисунка |
|---|---|
|
|
|
|
|
 |
|
|
|
|
Для придания определенного эффекта при увеличении рисунка можно воспользоваться расширением Lightbox, которое встроено в Quarto как функция.
Quarto
{.lightbox description="Лесные пожары в РФ за период 2012-2021 гг. Более подробно можно посмотреть на странице [Графики на досуге](https://data-visualization-blog.netlify.app/posts/wildfires/)"
desc-position="left"}
Рисунки можно организовывать с помощью перекрестных ссылок. При этом формула для организации ссылки {#fig-название рисунка}, а ссылка в тексте должна иметь вид @fig-название рисунка. Про организацию перекрестных ссылок будет рассказано далее.
Quarto
{#fig-Moscow}
Ссылка на рисунок @fig-Moscow.
Ссылка на рисунок Рисунок 3.2.
Организовать несколько рисунков можно по-разному. Например, можно указать количество строк/столбцов в итоговом рисунке с помощью параметра layout-ncol=* или layout-nrow=*.
Quarto
::: {layout-ncol=2}
:::
Другой способ размещения рисунков состоит в настройке размеров/пропорций, например, как ниже с указанием расстояния между рисунками layout="[*,*,*], вертикальным выравниванием можно управлять с помощью параметра layout-valign.
Quarto
::: {#fig-Russia-fires layout="[15,-2,20]" layout-valign="bottom"}
{#fig-fires}
{#fig-wildfires}
Лесные пожары
:::
Quarto
Общее положение дел отражает @fig-Russia-fires, в частности, @fig-wildfires.Общее положение дел отражает Рисунок 3.3, в частности, Рисунок 3.3 (b).
Подписи к рисункам располагаются по умолчанию под рисунками. Если требуется изменить это поведение в форматах HTML и PDF, то необходимо глобально изменить параметр fig-cap-location на top (по умолчанию сверху), bottom (внизу) или margin (на полях).
_quarto.yml
---
fig-cap-location: bottom
---Вставка в документ рисунков на основе блоков исполняемого кода происходит автоматически. Внутри кода можно выставлять параметры рисунка: например, ширину fig.width и высоту fig.height рисунка, label для указания метки рисунка (чтобы в дальнейшем ссылаться на рисунок), а также иные параметры, которые начинаются с префикса fig- (все возможные опции описаны на странице форматов) как показано в примере ниже. Параметры внутри блока кода должны предваряться #|.
R
#| fig.width: 6
#| fig.height: 4
#| fig-align: center
#| fig-cap: "Название графика"
#| fig-cap-location: top
#| label: fig-ggplot2-example
library(ggplot2)
ggplot(mpg, aes(displ, hwy, colour = class)) +
geom_point()
Пример ссылки на @fig-ggplot2-example.Пример ссылки на Рисунок 3.4.
Таблицы и рисунки возможно размещать на полях, используя опцию column: margin внутри блока кода.
#| label: fig-penguins-margins
#| fig-cap: "Пример графика на полях"
#| column: marginR
library(tidyverse)
library(palmerpenguins)
penguins |>
na.omit() |>
ggplot(aes(x = bill_length_mm,
y = bill_depth_mm,
fill = species,
size = body_mass_g)) +
geom_point(pch = 21,
color = "white",
alpha = 0.7) +
labs(x = "", y = "") +
scale_fill_manual(
values = c(Adelie = "#0072B2",
Chinstrap = "#D55E00",
Gentoo = "#018571")) +
theme(legend.position = "none")
Пример таблицы на полях документа.
#| column: marginR
head(mtcars, 5) |>
dplyr::select(mpg, cyl, disp, hp) |>
knitr::kable()| mpg | cyl | disp | hp | |
|---|---|---|---|---|
| Mazda RX4 | 21.0 | 6 | 160 | 110 |
| Mazda RX4 Wag | 21.0 | 6 | 160 | 110 |
| Datsun 710 | 22.8 | 4 | 108 | 93 |
| Hornet 4 Drive | 21.4 | 6 | 258 | 110 |
| Hornet Sportabout | 18.7 | 8 | 360 | 175 |
В Quarto можно вставлять элементы исполняемого кода на языках R, Python, Julia и Observable JS. При этом соответствующее ядро (движок knitr или jupyter) будет определяться автоматически. Используемое ядро определяется на основе языка первого обнаруженного исполняемого блока кода.
| Расширение файла | Блок кода | Ядро |
|---|---|---|
*.qmd |
{r} |
knitr |
*.qmd |
{python}, {julia}, {bash}, и т. д. |
jupyter |
*.rmd |
knitr | |
*.ipynb |
jupyter |
В случае, если документ Quarto включает в себя блоки кода как {python}, так и {r}, то Quarto автоматически будет использовать движок knitr и библиотеку reticulate языка R для выполнения содержимого Python.
Для файлов *.qmd можно переопределить используемый движок с помощью опции engine.
---
title: "Документ Python"
engine: jupyter
------
title: "Документ R"
engine: knitr
---Использование опции knitr или jupyter также переопределит движок по умолчанию:
---
knitr: true
------
jupyter: python3
------
jupyter: julia-1.11
---Блоки кода должны начинаться с ```{language} и завершаться ```, где {language}, в зависимости от языка:
{language} |
Язык программирования |
|---|---|
{r} |
R |
{python} |
Python |
{julia} |
Julia |
{ojs} |
Observable JS |
Внутри ячеек с кодом также могут находиться параметры, которые следуют за #|. Покажем пример блока с кодом и результат его выполнения. Таким образом выглядит код в Quarto:
```{r}
# пример графика в R
#| label: fig-diamonds-example
#| fig-cap: "Пример графика в ggplot2"
#| message: false
#| warning: false
#| fig.width: 6
#| fig.height: 5
library(tidyverse)
diamonds |>
ggplot(aes(x = carat, y = price,
fill = clarity)) +
geom_hex(alpha = 0.7, bins = 40) +
theme(legend.position = "none")
```Ниже показан пример оформления кода и результат исполнения кода.
R
# пример графика в R
#| label: fig-diamonds-example
#| fig-cap: "Пример графика в ggplot2"
#| message: false
#| warning: false
#| fig.width: 6
#| fig.height: 6
library(tidyverse)
diamonds |>
ggplot(aes(x = carat, y = price,
fill = clarity)) +
geom_hex(alpha = 0.8, bins = 40) +
theme(legend.position = "bottom")
В том случае, если код занимает много места на веб-странице, либо в изложении материала стоит избегать вывода кода, чтобы сконцентрироваться на результатах, можно сворачивать ячейки с кодом, чтобы пользователь мог отобразить их по требованию.
R
#| eval: false
#| code-fold: true
#| code-line-numbers: true
#| code-summary: "Нажмите, чтобы показать код"
library(tidyverse)
diamonds |>
ggplot(aes(x = carat, y = price,
fill = clarity)) +
geom_hex(alpha = 0.8, bins = 40) +
theme(legend.position = "bottom")Результат на странице будет выглядеть следующим образом.
Если строки кода слишком широки для своего контейнера в текстовом представлении, то переполнение кода можно регулировать с помощью параметра code-overflow, используя значения scroll для прокрутки и wrap для переноса длинных строк кода. Кроме того, значения code-line-numbers позволяют указывать в презентациях Revealjs строки для выделения и/или анимации между наборами выделенных строк. Например, диапазоны выделяются как 1,2,4-5, шаги анимации разделяются символом |, например: 1-3|1-3,5 для показа строк (сначала 1-3, потом 1-3,5).
Опция code-link позволяет создавать для HTML-документов, которые рендерятся с помощью knitr, гиперссылки на функции внутри блоков кода. Для включения гиперссылок необходимо предварительно установить библиотеку downlit и добавить в преамбулу документа YAML-часть как ниже.
---
format:
html:
code-link: true
---Тогда все функции будут связаны с помощью гиперссылок с соответствующими веб-страницами.
Внутри ячейки кодом можно указывать параметры настройки вывода как в таблице, где указаны значения параметров по умолчанию:
| Параметр | Значение | Описание |
|---|---|---|
echo |
true |
false: скрыть код в выводе fenced: включить синтаксис ячейки кода в вывод (кроме echo: fenced) |
eval |
true |
false: код не будет запускаться |
warning |
true |
false: не включать предупреждения в выводе |
include |
true |
false: не включать код и результаты вывода |
output |
true |
false: не включать результаты вывода asis: интерпретировать результат как Markdown |
error |
false |
true: в случае ошибки, ошибка будет отображена, при этом рендеринг не останавливается |
Помимо параметров настройки вывода, в Quarto имеется довольно внушительный список параметров, которые зависят от ядра, используемого для их обработки. Приведем список некоторых полезных параметров для ячеек с кодом, ориентируясь на *.qmd-документы.
| Параметр | Описание | Значения параметров |
|---|---|---|
| Рисунки | ||
fig-width |
ширина рисунка | |
fig-height |
высота рисунка | |
fig-cap |
заголовок рисунка | |
fig-subcap |
подзаголовок рисунка | |
fig-link |
гиперссылка рисунка | |
fig-align |
горизонтальное выравнивание рисунка | default, left, right, center |
fig-format |
формат вывода для рисунков по умолчанию | retina, png, jpeg, svg, pdf |
fig-dpi |
DPI рисунка по умолчанию | |
fig-asp |
соотношение сторон рисунка по умолчанию | fig-height = fig-width * fig-asp |
fig-cap-location |
место размещения рисунка | top, bottom, margin |
| Таблицы | ||
tbl-cap |
заголовок таблицы | |
tbl-subcap |
подзаголовок таблицы | |
tbl-colwidths |
ширина колонок таблицы | auto, true, false или явное значение в процентах: [25,45,30] и т. п. |
tbl-cap-location |
место размещения таблицы | top, bottom, margin |
Также, отметим что для перекрестных ссылок используется параметр label, который является уникальной меткой для ячейки кода.
Исполняемые блоки кода в Quarto могут включать аннотации, которые представляют собой построчные пояснения к коду. Каждая аннотированная строка должна заканчиваться пробелом, после которого следует номер аннотации, заключенный в угловые скобки, например, #<1>. Сразу после блока кода должен следовать список аннотаций с текстом пояснения.
Quarto
```{r}
library(tidyverse) #<1>
diamonds |>
ggplot(aes(x = carat, y = price, #<2>
fill = clarity)) + #<2>
geom_hex(alpha = 0.8, bins = 40) + #<3>
theme(legend.position = "bottom")
```
1. подключение библиотеки
2. отрисовка в ggplot2
3. заполнение шестиугольными ячейкамиДля отображения текста аннотации наведите курсор на соответствующий номер аннотации.
R
library(tidyverse)
diamonds |>
ggplot(aes(x = carat, y = price,
fill = clarity)) +
geom_hex(alpha = 0.8, bins = 40) +
theme(legend.position = "bottom")Для вывода HTML существует три стиля аннотаций, которые можно задать с помощью параметра code-annotations задаваемого в YAML.
_quarto.yml
---
code-annotations: below
---below
Этот параметр стоит по умолчанию, текст аннотации кода будет отображаться под ячейкой кода.
hover
Текст аннотации кода будет отображаться при наведении курсора на маркер аннотации строки кода (как в примере выше).
select
Текст аннотации кода будет отображаться, когда пользователь нажимает на маркер аннотации (выбирает его). Текст аннотации можно убрать, нажав на маркер аннотации еще раз.
Помимо вычислений в ячейках, код можно вставлять в в рамках Markdown-разметки. Quarto предоставляет синтаксис встроенного кода, который работает во всех трех движках (jupyter, knitr и OJS) для автоматического использования вычислений в повествовательном тексте. Формат вставки имеет вид `{language} code`.
Сохраняйте приоритет вычислений за ячейками с кодом, встроенные выражения должны быть ограничены простыми значениями, как правило, это вывод результата, а не, скажем, вызовами функций, которые выполняют нетривиальную работу. Это также связано с тем, что протокол, используемый для встроенных выражений, несовместим с некоторыми библиотеками языков программирования (особенно с теми, которые используют многопоточность или многопроцессорность).
Автоматическая привязка ядра работает для блоков, но не для встроенных вычислений, поэтому если вы используете встроенные выражения в документе, который не имеет исполняемых блоков кода, то вам следует явно задать параметр engine документа, чтобы гарантировать, что встроенные выражения будут выполнены.
---
title: "Заголовок"
engine: jupyter
---
`{python} 2 + 2`Для того, чтобы осуществить рендер части проекта, можно использовать инкрементный рендеринг для пошаговой обработки одного файла или подкаталога.
Terminal
quarto render one_file.qmd
quarto render subdir/Тем не менее, даже в случае рендеринга части проекта, при визуализации любой связанный с этой частью код все равно будет выполняться. Более того, для больших проектов или в том случае, если работа с документами происходит в течение длительного времени или имеется много вычислительных документов, существует необходимость в оптимизации рендеринга документов, например, чтобы использовать повторно результат предыдущего рендеринга. Такого рода оптимизация осуществляется с помощью кэширования (опция cache) или заморозки (опция freeze). Обе опции схожи по цели, но они решают несколько разные задачи.
Отметим, что можно также сделать рабочих процессов воспроизводимым, а также изолировать использование библиотек, с помощью различных
пишем про renv