Язык R для анализа данных

Утилита формирования отчётов Quarto

otus.ru

Проверить, идет ли запись

Меня хорошо видно & слышно?

Ставим “+”, если все хорошо “-”, если есть проблемы

Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Коллеги, рад вас видеть на вебинаре. У нас новая тема и экспериментальный формат.

Пожалуйста, поставьте плюс в чат, если меня хорошо видно и слышно.

Вебинар посвящен Quarto. Это система публикации и утилита создания отчетов и презентаций, следующее поколение Rmarkdown.

На прошлом занятии с Дмитрием вы создавали презентацию, сегодня мы будем пользоваться презентацией, созданной в Quarto в формате revealjs, допускающем интерактивный контент.

Поэтому я прошу вас открыть презентацию по ссылке, которую я кидаю в чат. Этой презентацией в вашем браузере могу управлять я удаленно, а можете листать вы сами.

Для записи вебинара нужно, чтобы презентация была также на экране Zoom. Поэтому презентацию вы можете смотреть там, где вам удобнее: в браузере или в Zoom. Но в любом случае иногда я буду привлекать ваше внимание в Zoom, чтобы расшарить окно RStudio и показать Quarto в действии.

Коллеги, у вас получилось открыть презентацию? Поставьте, пожалуйста, плюсы в чат, если получилось. Формат мультиплекса – экспериментальный, поэтому я буду периодически уточнять у вас, листается ли презентация без вашего участия.

Поставьте, пожалуйста, плюс, если видите слайд с правилами вебинара.

Тема вебинара

Утилита формирования отчётов Quarto

Андрей Павлюченко

Старший медиааналитик

Об опыте:

Мониторинг и исследования медиа (Brand Analytics, Медиалогия, R, Python)

Люблю делать: Text Mining, графовый анализ, интерактивные дэшборды

a.pawluczenko@gmail.com / @a.pawluczenko

Правила вебинара

Активно участвуем

Офф-топик обсуждаем в Telegram

Вопросы пишем в чат или поднимаем руку и говорим голосом

Включенная камера – желательно, но не обязательно

Вопросы вижу в чате, могу ответить не сразу

Маршрут вебинара

Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Мы начнем издалека: вы уже знаете главное из Rmarkdown, тогда что собственно нового нам предлагают разработчики Quarto и что с помощью этой утилиты можно сделать. Затем составим себе такую ментальную карту того, как в принципе создаются отчеты в Quarto. Затем посмотрим на некоторые из (огромного множества) возможностей наполнения отчетов контентом и настройки отображения. Наконец, посмотрим, как создавать сложные проекты на примере веб-сайта и убедимся, что создание сайтов и книг стало проще и ближе, чем раньше.

Цели вебинара

К концу вебинара вы сможете:

Разбираться в возможностях, форматах и опциях Quarto.
Создавать базовые документы в Quarto в разных форматах.
Наполнять их различным статическим и динамическим контентом.
Использовать возможности модульного и параметрического дизайна Quarto.
Использовать свои знания и документацию Quarto для создания продвинутых документов.

Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

[Зачитывает слайд своими словами]

На прошлом занятии вы уже научились создавать Rmarkdown-документы, которые затем программа pandoc рендерит в разные форматы. Эти знания и умения – основа того, что вы будете делать с Quarto. Но ребята из Posit долго втайне делали-делали Quarto и наделали столько, что возможностей системы хватило бы на целый курс. Поэтому на данном занятии нам важно именно разобраться. Даже начать разбираться. И тогда, если вам будет интересно, ничего невозможного в Quarto для вас не будет.

Смысл

Зачем это нужно? Для того, чтобы:

Готовить качественные отчеты с настраиваемым дизайном, чтобы эффективно представлять результаты анализа.
Создавать интерактивные документы, чтобы пользователи могли исследовать данные и принимать решения на основе интерактивных элементов.
Адаптировать документы под различные цели и требования, обеспечивая гибкость и персонализацию.

Знакомство с Quarto

Что за Quarto?

Источник: Tom Mock на GitHub

Quarto (отсылка к формату in quarto) – система публикации документов от Posit (бывшая RStudio, создатели Tidyverse).

Логотип Quarto

Логотип Posit

Что за Quarto?

Quarto – не библиотека R, а автономное приложение с интерфейсом командной строки. Например, даже без установленных R или Python вы можете:

Создать документ document.md в своем любимом редакторе.
Добавить YAML-метаданные (как Rmarkdown, но см. ниже).
Сверстать документ в нужном вам формате.

Terminal

quarto render document.md

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Quarto это автономное приложение. Его можно запускать из командной строки, а верстать можно не только ноутбуки с кодом, но и просто markdown-файлы.

Речь идет именно о статическом markdown-файле. Для того, чтобы исполнять ячейки с кодом, вам понадобятся соответственно R или Python.

К сожалению, я не готов рассказать, как хотел Дмитрий, как отправлять сверстанные документы по расписанию: никогда не интересовался такими вещами.

Сейчас мы посмотрим на особенности и возможности Quarto. Коллеги, я вас попрошу, даже настаиваю на этом: то, что мы будем обсуждать – возможности системы, форматы и настройки – примеряйте на себя. Представляйте себе, что бы вы могли написать на Quarto, какой свой проект реализовать, для какой аудитории, и что вам для этого нужно узнать.

Что за Quarto?

RStudio IDE новых версий включает Quarto, а также предоставляет для него редактор кода с автозаполнением и удобный визуальный редактор.

Quarto имеет более широкие по сравнению с Rmarkdown возможности. Можно воспринимать его как:

Rmarkdown++;
MS Word с гибридным интерфейсом;
Dreamweaver для аналитиков и ученых.

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

[Первый фрагмент]

Программа RStudio включает дистрибутив Quarto, если быть точным, переносную версию Quarto. Разработчики Quarto при этом советуют все-таки скачивать программу отдельно и устанавливать в систему. Именно это мне пришлось сделать в процессе подготовки из-за проблем с рендерингом plotly. Quarto сейчас релизится намного чаще, чем RStudio, и версия в RStudio содержит обидный баг, который в Quarto уже исправлен.

[Второй фрагмент]. Для простоты понимания.

Rmarkdown++ — по аналогии с C++: нечто новое, претендующее на обобщение своего предшественника, при этом сохраняющее с ним по возможности полную совместимость.

MS Word — это про визуальный редактор в RStudio. Мы глянем на него, но подробно останавливаться не будем. Там многое понятно интуитивно, но кое-что мы все же рассмотрим.

Dreamwever, как вы, возможно, знаете — тоже программа с гибридным интерефейсом для создания сайтов. То есть там тоже можно все прописывать кодом, а можно рисовать и перетаксивать вручную. На Quarto тоже можно создавать сайты. Сайт Quarto, скорее всего, тоже создан на Quarto: это можно предположить по характерной структуре, которую мы обсудим ближе к концу занятия.

Важно: по словам разработчиков Posit Quarto призван заменить Rmarkdown. Rmarkdown будет поддерживаться, но не разрабатываться. То есть они будут фиксить ошибки Rmarkdown, но разработка новых «фич» ведется исключительно в рамках Quarto.

Не только R

Quarto умеет обрабатывать код на следующих языках:

R;
Python;
Julia;
JavaScript (Observable).

Многоформатность

Quarto поддерживает множество форматов вывода, включая HTML, PDF, EPUB и другие. В Rmarkdown для большинства этих форматов необходимы дополнительные библиотеки:

Возможности Quarto	Реализация в Rmarkdown
HTML	✓
PDF	✓
DOCX/ODT	✓
PowerPoint	✓
сайт/блог	`distill`, `blogdown`
HTML-презентация	`revealjs`
книга	`bookdown`
интерактивная презентация	`flexdashboard`

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины. Действие ниже↓

Коллеги, я вам скину сейчас ссылку на галерею Quarto, там как раз представлены документы в разных форматах: https://quarto.org/docs/gallery/

Коллеги, хорошо ли видно среду разработки? Поставьте плюс в чат, если видно хорошо или напишите, что не так

А теперь давайте откроем Quarto в RStudio и создадим самый базовый файл. Обратите внимание: знакомый нам клубочек Нитр сменился на стрелку с надписью Рендер. И сверстаем его. <…> А теперь посмотрим визуальный редактор. Тот самый MS Word для R. <…>

Создаем базовый файл quarto.qmd

Лично мне удобнее работать с кодом, чем в визуальном редакторе.

Но одна штука в нем точно полезна и на первых порах иногда даже незаменима. Вот как можно легко добавить ссылку на литературу в Quarto.

В визуальном редакторе добавляем ссылку на литературу в quarto.qmd

Quarto предоставляет поиск по нескольким базам данных публикаций, в том числе PubMed, позволяет добавить статью по ее идентификатору или сослаться на библиотеку R.

При этом Quarto создает нам список литературы в формате БибТеХ или CSL. В дальнейшем мы можем добавлять литературу в него таким же образом или редактировать вручную, например, скопировав запись на сайте публикации.

открываем файл .bib

Если вы не знакомы с такими форматами списков литературы, это хороший способ его изучить. Добавьте несколько ссылок через редактор, затем научитьесь создавать и редактировать такие файлы самостоятельно. Надеюсь, вам это еще пригодится!

А вот как можно добавить что-нибудь, набрав слэш.

Коллеги, есть ли вопросы по тому, что мы сейчас делали?

Давайте вернемся к презентации.

<…>

Отмечу, что PowerPoint что в Rmarkdown, что в Quarto, оставляет желать лучшего. В базовом исполнении получаются либо очень простые по структуре документы, либо требующие ручной правки в PowerPoint. Прогрессивные деятели в Posit и их партнеры не считают формат PowerPoint приоритетным для разработки.

По своему опыту скажу, что PowerPoint легче создавать руками. Но если есть необходимость создавать автоматизированные отчеты именно в этом офрмате, придется заморочиться. Rmarkdown (а в Quarto, судя по всему, остался ровно тот же движок для рендеринга pptx), распознает семь макетов слайдов, включая пустой (blank). Например, у нас даже типовые макеты включают более сложные варианты верстки.

Модульный дизайн

Quarto позволяет разбивать анализ на маленькие, повторно используемые компоненты, которые можно собирать в сложные документы. Это делает повторное использование и комбинирование частей вашего анализа легким.

Сложный проект на R может состоять из нескольких скриптов, содержащих загрузку и предобработку данных, специальные функции, моделирование и визуализацию.

source('data-wrangle.R', encoding = 'UTF-8')

Модульный дизайн

Как «настоящие» языки программирования, Quarto позволяет точно так же использовать сторонние файлы .qmd: собирать их в большие проекты, использовать вывод одной ячейки кода много раз.

Пример: включить содержимое из файла _data.qmd

{{{< include _data.qmd >}}}

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

[Читает слайд своими словами] Речь идет просто о том, что можно включать ноутбук Quarto в другой ноутбук Quarto.

Это в Quarto называется shortcodes. Кстати, синтаксис Quarto работает на разных уровнях, в том числе внутри блоков кода. Для того, чтобы избегнуть исполнение этого кода, нужно заключить его в дополнительную пару фигурных скобок. Другой вариант – добавить команду {shortcodes=false} в опциях ячейки кода (в фигурных скобках).

Именно так сделана и эта презентация. Например, у нее есть рабочая версия, версия для мультиплекса и версия для сохранения в PDF. Весь контент находится только в одном файле, остальные его только заимствуют.

Модульный дизайн

Quarto позволяет использовать параметры, c которыми можно готовить разные отчеты из одного и того же ноутбука, например:

отчеты для разных регионов;
отчеты для разных периодов;
моделирование с разными допущениями или алгоритмами.

---
title : "Анализ рынка труда"
…
params:
  job : "Бухгалтер"
  area: "Москва"
---

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

А еще можно создавать разные отчеты из одного ноутбука, меняя только параметры, влияющие на исполнение кода.

А выглядит это примерно так

Параметры располагаются на верхнем уровне YAML-преамбулы (это явление вам уже знакомо по Rmarkdown, но мы еще разберем его ниже, потому что роль YAML в Quarto только усилилась) и называются именно params. А названия самих параметров должны соответствовать названиям переменных в R, Потому что в основном через R мы к ним и обращаемся (то же справедливо, если мы работаем в Python или Julia). То есть, дефисы в названии недопустимы, в отличие от обычных YAML-опций. А вот кавычить строки не обязательно: в большинстве случаев Quarto разбирается, что строка.

Модульный дизайн

Значения параметров используются в качестве шаблона в коде ноутбука, например:

df <- open_dataset('data/db/meta', partitioning = 'job_id') |>
  filter(
    job  == params$job,
    area == params$area
  )

Затем документ можно сверстать с разными параметрами из R:

quarto::quarto_render(
    input = "doc.qmd",
    output_format = "pdf",
    execute_params = list(job = "Бухгалтер", area = "Москва")
  )

Или из командной строки:

Terminal

quarto render doc.qmd -P job:"Бухгалтер" -P area:"Москва" --output doc.pdf

Модульный дизайн

Некоторые преимущества модульных ноутбуков включают:

Повторное использование: можно повторно использовать те же ячейки в нескольких ноутбуках.
Гибкость: можно повторно комбинировать ячейки разными способами для разных выводов или целей.
Абстракция: скрывать детали реализации от читателей документа.
Удобство поддержки: нужно вносить изменения только в одном месте.

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Из преимуществ модульного дизайна для нас самым важным, наверное, является четвертое. Ссылаться на один готовый ноутбук в нескольких местах гораздо проще и безопаснее, чем копировать и вставлять.

Коллеги, мы с вами проработаем пример такой верстки документов с параметрами после того, как рассмотрим другие элементы и настройки ноутбука. В материалы к занятию я приложил и пример, аналогичный тому, который мы будем делать, и пример несколько более сложный, который я делал для себя, когда осваивал эти возможности. Там есть даже интересный набор данных. Можете потом посмотреть.

Расширенное форматирование

Quarto изначально включает все необходимое для научных публикаций и воспроизводимого анализа:

обширную поддержку перекрестных ссылок и цитат;
расширенное аннотирование рисунков, таблиц и кода;
нативную поддержку графов и блок-схем (mermaid и Graphviz);
расширенные возможности написания формул \(\LaTeX\).

Пример: Запись матрицы (пакет amsmath)

\begin{equation}
A = \begin{pmatrix}
    4 & -3 & -3 \\
    1 &  2 &  1 \\
    1 &  1 &  2
  \end{pmatrix}
\end{equation}

Здесь будет матрица, нарисованная в \(\LaTeX\)

\[\begin{equation} A = \begin{pmatrix} 4 & -3 & -3 \\ 1 & 2 & 1 \\ 1 & 1 & 2 \end{pmatrix} \end{equation}\]

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Воспроизводимый анализ – как раз то, ради чего люди делятся ноутбуками с кодом вместо того, чтобы просто опубликовать статью. Quarto как раз заточен под такие публикации, где есть формулы и список литературы, где изображения и таблицы пронумерованы и на них тоже можно ссылаться.

Вот пример «сырого» латеха. Библиотека уже прилагается к дистрибутиву Quarto.

Пихает латех в quarto.qmd

Что со всем этим делать?

Quarto «из коробки» позволяет создавать более 40 форматов документов (format: ваш-формат).
Для каждого формата доступны по нескольку десятков опций.
Знание CSS/SASS, \(\LaTeX\) или Pandoc дает почти безграничные возможности настройки внешнего вида отчетов.
Quarto динамично развивается, появляются новые возможности.

Так что, «читайте руководство»?

Безусловно. Но сейчас вы получите карту для ориентации во вселенной Quarto.

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Хочу обратить ваше внимание на то, что материал по Quarto практически необъятен для одной лекции.

Цитата: существует слишком много способов настроить Quarto, Настройки в YAML избыточны.

И тем не менее, наша цель сегодня в том, чтобы вы могли записать себе в навыки пункт Quarto.

Повторюсь: достаточно будет, если вы будете в курсе того, что в принципе можно сделать в Quarto. И будете знать как в принципе это сделать. Например, не обязательно, чтобы у вас от зубов отскакивало, например, как расположить изображения в шахматном порядке. Но желательно, чтобы про некоторые фичи вы помнили, что можно сделать и так. И тогда крутизна отчетов, которые вы сможете создавать в Quarto, будет ограничена только вашей усидчивостью.

Алгоритм работы

Общий алгоритм проектов Quarto

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

На самом деле, нет никакого жесткого алгоритма. Но мы постараемся весь этот темный лес упорядочить. Чтобы у нас создание проектов больше было похоже на поваренную книгу, как сейчас модно говорить. Правда, говорить в отрицательном смысле, но на самом деле это не всегда плохо.

Определитесь, что вы будете делать. Quarto поддерживает верстку многих форматов из одного ноутбука, но к сожалению не все полностью переносимо. Именно поэтому обычно опции указывают отдельно для каждого из форматов.

Следующие шаги вам известны по Rmarkdown. Но мы все равно слегка их коснемся. Конечно, markdown все тот же, но в Quarto принято использовать синтаксис pandoc где возможно, вместо HTML.

Отображение элементов можно настраивать как в теле ноутбука, так и возвращаясь к заголовкам. Это самая обширная сфера информации про Quarto.

Смотрим на нативную поддержку диаграмм (графов, флоучартов и т. д.). В Quarto, как я уже говорил можно взять и написать диаграмму на mermaid или Graphviz. Здесь пример флоучарта, написанного на mermaid. Очень базовый пример, с базовым оформлением. Добавлено только одно определение класса, чтобы не было совсем скучно и вы увидели, что так можно делать.

Общий алгоритм проектов Quarto

Кстати, код диаграммы:

```{mermaid}
%%| eval: false
flowchart LR
  A{Выбираем тип проекта} --> B(Редактируем YAML)
  B --> C(Пишем текст и код)
  B --> D(Добавляем изображения)
  C --> E(Настраиваем отображение)
  D --> E
  E <--> B
  E --> F[Публикация]
  
  classDef optional stroke-dasharray:10;
  class D optional
  class E optional
```

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Кстати, в блоках кода mermaid опции начинаются с двух знаков процента, как в самом mermaid

Графы Graphviz я планировал показать дальше. Коллеги, есть ли у вас вопросы по диаграмме mermaid?

Добавлю только, что по умолчанию в формате HTML русалочья диаграмма загружается в своем родном формате — как элементы на странице. В них можно выделять и копировать текст, они адаптируются под изменения размера окна и так далее. В других форматах диаграмма добавляется в виде изображения .png. Формат mermaid можно настроить, указав, например, svg или png для HTML, если вам будет мешать чрезмерная гибкость нативного формата.

Как работает Quarto

При работе с R система Quarto сначала создает markdown-документ, который затем конвертируется в нужный формат программой pandoc.

Источник: Tom Mock на GitHub

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Немного остановимся на том, что происходит «под капотом», когда мы верстаем документы из ноутбуков Quarto. Это пригодится вам, когда вы будете создавать свои сложные, кастомизированные, документы: если что-то пойдет не так, как вам нужно, вы сможете разобраться, на каком этапе происходит ошибка.

Напомню, что pandoc — программа, конвертирующая документы между разными форматами, на что и намекает ее название.

Что здесь нового по сравнению с Rmarkdown?

Во-первых, возможность верстать документы, сгенерированные в Jupyter Notebook. Python сейчас можно запускать и в RStudio, но кому-то Jupyter просто привычнее. Кроме того, Julia на данный момент намного проще запускать именно в Jupyter.

Конечно, для генерации документов с кодом нам потребуется соответственно R для «Нитр» и Python для Jupyter. Но если у вас уже есть документ в формате markdown (напомню, это статичный документ: на втором шаге Нитр или Юпитер жестко кодируют в markdown вывод, сгенерированный кодом: строят markdown-таблицу, если это таблица или датафрейм, а если это диаграмма — сохраняют ее как изображение в отдельный файл и вставляют ссылку) — так вот, если у вас уже есть статичный документ, то для его верстки в любой формат вам понадобится только Quarto.

Потому что, во-вторых, Rmarkdown использует на четвертом шаге при работе с pandoc команды R для управления процессом, в частности, условные операторы. Quarto использует команды, написанные на языке Lua, как указано на диаграмме. Фильтры на Lua поставляются нам вместе с Quarto. Благодаря этому начиная с этапа с markdown-документом мы не зависим от R.

Типы проекта

Проекты других доступных типов можно создать вручную, прописав format: [наш-формат]

Также можно создавать комплексные публикации (проекты), состоящие из многих (обычно HTML) документов.

Типы проекта

Из одного ноутбука можно сверстать несколько документов в разных форматах. При этом отображение можно настроить отдельно для каждого формата.

format:
  html:
    theme: pulse
  pdf:
    fig-format: png

Обратите внимание

Только формат HTML позволяет создавать интерактивные документы.

При этом компоненты Shiny требуют хостинга на удаленном сервере. Компоненты, основанные на JavaScript, будут интерактивными у читателей без дополнительных сложностей.

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины. Действие ниже↓

Добавляет несколько форматов в quarto.qmd

А теперь давайте сверстаем наш проект сразу в нескольких форматах. <…> Если форматов несколько, определение каждого из них должно иметь тип списка, как мы бы сказали в R, или объекта, как это называется в языке разметки YAML. Это значит, что у них должны быть какие-то значения. Если мы не знаем, что написать, пишем default

Коллеги, есть ли у вас вопросы по тому, как из одного ноутбука сверстать несколько форматов документов?]

Типы проекта

Обратите внимание

Для верстки PDF нужно установить \(\TeX\)-дистрибутив. Лучше всего tinytex:

Terminal

quarto install tinytex --update-path

format:
  html:
    theme: united
  pdf:
    papersize: A5
    fig-format: png
    include-in-header: 
      - file: packages.tex

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Если мы запрашиваем использование библиотек Латех в заголовке ноутбука или во внешней инструкции, Quarto (как и Rmarkdown) ищут и загружают их для нас.

А если тайнитех уже установлен, стоит время от времени запускать quarto update tinytex. Каждый год в апреле TeXlive, разработчики тайнитех, обновляют репозиторий библиотек, после чего прошлогодние версии движка не смогут скачивать библиотеки. Поэтому обновлять его все равно понадобится.

Элементы Quarto: контент и оформление

Структура ноутбука

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

В эту картинку я постарался вместить как можно больше разных элементов типичного ноутбука, поэтому она получилась трудно читаемой. Но нас сейчас интересует не его конкретное содержание, а структура. Это как вид на город из иллюминатора самолета. С markdown, блоками кода и Латехом вы уже умеете работать. Другие элементы мы рассмотрим подробнее дальше.

Кстати, в блоках кода изменились правила оформления. Опции внутри фигурных скобок поддерживаются, но от них постепенно отказываются впользу опций внутри блока, которых может быть пара, а может быть и дюжина.

Коллеги, дальнейшие слайды разработаны так, чтобы в случае необходимости послужить вам шпаргалкой или напоминанием. На некоторых из них мы не будем долго останавливаться. Если только вы не попросите рассказать подробнее или показать пример.

YAML-заголовки

YAML («YAML Ain’t Markup Language») – язык сериализации данных, как JSON и XML. Используется Quarto для записи конфигурации проекта. Формат записи – опция: значение.

Код конфигурации YAML отделяется тремя дефисами сверху и снизу:

---
title : "Hello, Quarto"
author: "otus.ru"
format:
  pptx:
    reference-doc: ../templates/template.pptx
    mermaid-format: png
---

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Заголовок в формате YAML – это то место, где хранятся глобальные настройки всего нашего ноутбука или целого сайта.

Опции Quarto делятся на:

общие;
формат-специфичные (записываются под format: [ваш формат]:.

То, что указано для одного формата, не будет работать для другого, если вы не добавите эти же параметры в этот формат или не сделаете их общими. Да, так тоже можно.

Для каждого из форматов существует до нескольких десятков опций. Я вам сейчас скину список опций, классифицированный по форматам: (https://quarto.org/docs/reference/).

YAML-заголовки

В качестве значения может быть указан список:

опция:
  - элемент1
    опция-элемента1: значение
  - элемент2

Многострочный текст печатается с новой строки после знака |: источник: Mickaël Canouil на GitHub

---
format:
  html:
    html-math-method: mathjax
    include-in-header:
     - text: |
          <script>
          window.MathJax = {
            loader: {
              load: ['[tex]/upgreek', '[tex]/boldsymbol', '[tex]/physics']
            },
            tex: {
              packages: {
                '[+]': ['upgreek', 'boldsymbol', 'physics']
              }
            }
          };
          </script>
---

YAML-заголовки

К метаданным можно обращаться через синтаксис Quarto {{<…>}} с ключевым словом meta:

[{{< meta author >}}]{style="font-family:Courier;font-size:3em;float:right;"}

![Otus: R для анализа данных]({{< meta format.revealjs.logo >}}){#fig-otus-r-owl}

otus.ru

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Мы можем обратиться к метаданным проекта внутри ноутбука и использовать его как текст или как ссылку. Это делается через синтаксис Quarto, как и при включении внешнего ноутбука: две пары фигурных скобок, а внутри них пара угловых.

В данном случае мы использовали название автора документа и ссылку на изображение.

Этот синтаксис, как и команда включения стороннего файла, называется шорткод (shortcodes). Обращение к метаданным в шорткодах обозначается ключевым словом meta. Вложенные параметры (в подразделах) можно получить, используя в качестве разделителя точку. Как в Питоне например. В нашем примере это format затем revealjs, затем logo.

YAML-заголовки

Можно создать в папке с ноутбуком файл _variables.yml и наполнить его данными в YAML-формате:

_variables.yml

lecturer:
  name: Андрей Павлюченко
  role: Старший медиааналитик

Тогда к значениям из этого файла можно будет обращаться с ключевым словом var:

[Вебинар ведет {{< var lecturer.name >}}]{style="font-size:0.75em;"}

Вебинар ведет Андрей Павлюченко

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

То же можно делать для любых произвольных переменных, в том числе списков, которые вы можете поместить в файл _variables.yml. Пользуясь случаем, напомню, как меня зовут.

Можно поместить их в параметры и писать meta, но на это ругается рендерер (выдает предупреждение), значит, видимо, лучше этого не делать. Стараемся быть zero warning. В R это не принципиально, но если наш проект компилируется или рендерится, лучше следовать культуре zero warning.

https://helloacm.com/zero-warning-culture-in-development-team/

Пример настройки: HTML

Опции HTML позволяют настраивать макет страницы, базовые элементы стиля и многое другое.

---
format:
  html:
    theme:
      light: pulse
      dark: cyborg
    css: styles.css
    mainfont: corbel
    fontsize: 1.1rem
    fontcolor: "#090103"
    linkcolor: "#E81444"
    monofont: consolas
    title-block-style: plain
    title-block-banner: "#DDBEED"
    title-block-banner-color: "#AA26EE"
    margin-top: 40px
---

Готовые темы Quarto представлены на сайте Bootswatch.

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

[Читает слайд своими словами]

Что мы тут видим? Внешний вид большинства элементов, шрифты и цвета можно настроить в YAML-заголовках. Все остальное можно прописать во внешнем css-файле.

Для большинства некоммерческих отчетов в формате HTML неплохо подойдут темы семейства Bootswatch. Их можно указывать просто по названию, Quarto сам их находит. Я кину вам ссылку в чат, можете посмотреть галерею: https://bootswatch.com/

Пример настройки: PDF

В PDF тоже можно настраивать макет (и размер) страницы, базовые элементы стиля, а также добавлять файлы \(\TeX\) для более тонкой настройки.

---
lang: ru
format:
  pdf:
    mainfont: Corbel
    monofont: Consolas
    linkcolor: Bittersweet
    citecolor: Mahogany
    urlcolor: MediumOrchid
    papersize: A5
    fig-format: png
    include-in-header:
      - text: |
          \usepackage{fontspec}
          \setsansfont{Courier New}
          \usepackage{icomma}
---

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины. Действие ниже↓

[Читает слайд своими словами]

Что мы тут видим? Шрифты, цвета гиперссылок и отдельно ссылок внутри документа (citecolor) и даже размер бумаги. A5, как в каокй-нибудь настоящей статье.

И возможность передать дополнительный опции Латеха текстом или файлом. Обычно они нужны для загрузки дополнительных библиотек или определения пользовательских функций.

А сейчас я вам расскажу, для чего тех-скрипт вам точно понадобится. Речь идет о подводных камнях с форматом PDF (и, соответственно, презентациями Beamer). Давайте перейдем в RStudio

Добавляет заголовки и абзацы на русском в quarto.qmd

Давайте добавим в наш документ немного текста на русском. <…> Смотрите, что получается. Это очень старая проблема, унаследованная еще от Rmarkdown

Добавляет ссылку на русский текст в заголовок quarto.qmd

Вместо text можно передать на включение файл .tex с загрузкой библиотек, шрифтами и определениями собственных функций. В силу того, что TeX далеко не всегда дружит с кириллическими текстами, я советую иметь под рукой TeX-код Данила Федоровых: https://ru.overleaf.com/latex/templates/5-dot-2-2-russkii-iazyk-v-latex-xelatex/skfzmvgdgvnk.

Добавим команды из файла Федоровых. На самом деле опция lang: ru при создании PDF уже загружает библиотеку Бабель с русским языком. Но как минимум нужно установить шрифт без засечек.

Другой вариант: библиотека R azbuka, которая содержит шаблоны документов Rmarkdown на русском языке с соответствующими настройками для PDF. Я кину ссылку в чат: https://github.com/bdemeshev/azbuka

Правда, опции Rmarkdown придется адаптировать для Quarto вручную. Библиотека не обновлялась 6 лет, вряд ли автор переработает ее для Quarto, хотя все может быть.

Коллеги, есть ли у вас вопросы по настройке формата PDF?

Тогда давайте вернемся к презентации

Пример настройки: форматы MS Office

Форматы приложений MS Office в значительной мере опираются на файлы-шаблоны с настроенными стилями, макетами и темами:

---
lang: ru
format:
  pptx:
    reference-doc: tools/template.pptx
    incremental: true
    mermaid-format: png
  docx:
    toc: true
    reference-doc: tools/template.docx
    highlight-style: breeze
---

Интересно ваше мнение:

Какой формат вам кажется самым интересным для работы?

Какой формат, по вашему мнению, вам больше всего пригодится в работе?

Фрагменты кода

Как и для Rmarkdown, возможность интерпретировать код и встраивать результаты его исполнения в документ является основной функциональной особенностью Quarto.

В Quarto опции для отдельного фрагмента кода, если они нужны, записываются внутри блока в формате YAML и начинаются с #|:

#| label: load-packages
#| include: false

library(tidymodels)

Можно спрятать код под спойлер:

Показать код

```{r}
#| label: ex-fold
#| code-fold: show
#| code-summary: 'Показать код'
x <- rchisq(1e3, 13)
```

Фрагменты кода

В Quarto очень легко подсвечивать строки кода:

```{r}
#| code-line-numbers: "2|3-4|6|7"
#| label: ex-highlight
#| eval: false

hist(x)
ggplot2::qplot(x, geom = 'histogram')
```

Также можно выбрать или настроить оформление кода

---
format:
  html: 
    code-block-bg:          "#fef"
    code-block-border-left: "#faf"
    highlight-style:        breeze
execute: 
  echo: fenced
---

Как будет выглядеть код?

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Опция code-line-numbers позволяет компактно записать последовательность подсвечиваемых строк кода. Обратите внимание: в зависимости от того, чему равно значение echo (показывать ли код и если показывать, то вместе с «забором» или нет) номера строк могут отличаться от того, что кажется нам. Подсвечивание строк желательно всегда проверять.

Если вы в своем отчете активно делитесь кодом, вы, возможно, захотите настроить внешний вид блоков кода. Для этого есть набор опций, как приведено на слайде. Выбраны по наитию два похожих цвета, из которых один насыщенее другого. Получилось как-то так.

Контейнеры pandoc

При работе в Quarto рекомендуется использовать универсальный формат контейнеров pandoc

Блочный контейнер – аналог <div> ограничивается двоеточиями (не менее 3) с опциональными атрибутами в фигурных скобках:

::: {style="border: 1px solid;font-size:0.2em;"}
Этот маленький текст будет окружен прямоугольной рамкой
:::

::: {.callout-note title="Обратите внимание"}
А это будет примечание
:::

Этот маленький текст будет окружен прямоугольной рамкой

Обратите внимание

А это будет примечание

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

[Читает слайд своими словами]

В Quarto есть ряд готовых классов контейнеров. В том числе так называемые выноски (callout). Одну из них вы видите перед собой. Кроме Note есть Danger, Success, Warning. Знакомые названия для пользователей Shiny.

Кстати, с PDF не все всегда просто. Некоторые фрагменты могут выглядеть так же, как в HTML, например, те же блочные контейнеры со встроенными в Quarto классами, как выноски. Потому что они прописаны и для pandoc. Но чаще всего манипуляции со стилями CSS не отражаются на PDF-документах.

Если нам нужно, чтобы документы PDF были максимально приближены к HTML и мы могли манипулировать их внешним видов с помощью CSS, нужно будет в качестве pdf-engine: указать один из движков, которые верстают файл сначала в HTML, а затем уже в PDF со страницами. Я знаю два: weasyprint (https://weasyprint.org/) и pagedjs-cli (https://www.npmjs.com/package/pagedjs-cli). Оба нужно ставить самим, и на Windows они ставятся нетривиально. Визипринт устанавливается через Питон, а для пейджед-джей-эс нужен установщик библиотек джаваскрипта npm (https://www.npmjs.com/package/npm). И при этом при использовании этих рендеров теряется часть возможностей встроенного в Quarto рендеринга PDF. Но зато не нужно волноваться насчет кириллицы.

Но почему бы вместо всех этих сложностей не сверстать HTML, а затем не сохранить PDF из меню печати?

Контейнеры pandoc

При работе в Quarto рекомендуется использовать универсальный формат контейнеров pandoc

Строчный контейнер – аналог <span> записывается в квадартных скобках, за которыми следуют атрибуты в фигурных скобках:

[Сначала id, потом класс, потом все остальное]{#id .class key1="val1" key2="val2"}

[Красный текст]{style="color:#d00;"}

Красный текст

Форматирование изображений

Синтаксис изображений похож на гиперссылки, но с восклицательным знаком в начале:

![Собачка](doge.png "Изображение собаки"){height=2cm}

Надпись в квадратных скобках считается подписью к изображению. Ее можно оставить пустой.

Текст в кавычках после url изображения – его всплывающее название (<img … title=…>)

Форматирование изображений

Можно добавлять атрибуты, например, выравнивание:

![Собачка](doge.png "Изображение собаки побольше"){fig-align="left" fig-alt="Изображение собаки"}

Собачка

Форматирование изображений

Можно сгруппировать несколько изображений и расположить их определенным образом:

::: {#fig-two-triangles layout-ncol=2}

![Первая картинка](tred.png){#fig-triangle-red width=20}

![Вторая картинка](tblue.png){#fig-triangle-blue width=20}

Две картинки
:::

Форматирование изображений

В качестве макета можно указать массив, каждый элемент которого – ряд в сетке:

::: {#fig-images layout="[[20,20], [40]]" style="font-size:0.5em;"}
![Первая картинка](quarto.png){#fig-01 width=40}

![Вторая картинка](quarto.png){#fig-02 width=40}

![Картинка во втором ряду](quarto.png){#fig-long width=80}

Три картинки
:::

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

В качестве макета можно указать массив, каждый элемент которого – ряд в сетке. К понятию сетки мы будем иногда возвращаться.

Сетка, grid, вам уже знакома по Shiny. По умолчанию весь документ разверстан строками и колонками. Просто таким синтаксисом, как в этом примере, мы явно управляем размещением элементов, а в остальное время Quarto решает за нас. Как правило, просто помещая следующий элемент на следующую строку.

Отрицательные значения в массиве добавляют пространство между соседними колонками в ряду.

Так можно распределять по сетке (grid) не только изображения, но и текст, диаграммы и все остальное. Просто каждый следующий элемент (например, строку markdown, то есть отделенную пустым абзацем, заголвок markdown, фрагмент кода или таблицу) помещается в следующую ячейку сетки: сначала в том же ряду, затем в следующем и так далее.

Форматирование изображений

Если назвать контейнер с изображениями #fig-…, Quarto представит его как одно изображение из нескольких частей (как на предыдущем слайде) и пронумерует соответственно.

На изображения можно ссылаться: Рис. 2

Кстати, по умолчанию названия сопровождаются префиксом «Figure». Это можно изменить в настройках проекта:

crossref:
  fig-title: Рис.         # Подпись к изображению (по умолчанию "Figure")
  tbl-title: Таблица      # Подпись к таблице (по умолчанию "Table")
  subref-labels: arabic   # (по умолчанию "a, b, …, z")
  fig-prefix: Рис.        # Префикс ссылки на изображение
  tbl-prefix: Таблице     # Префикс ссылки на таблицу

Форматирование изображений

Для изображений, генерируемых кодом, параметры задают внутри блока:

```{r}
#| fig-cap: "Две диаграммы"
#| fig-subcap:
#|   - "Первая диаграмма"
#|   - "Вторая диаграмма"
#| layout: "[20, 10]"
#| fig-width: 30

hist(mtcars$mpg)
hist(mtcars$disp)
```

Две диаграммы

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Обратите внимание, параметры, которые указываются внутри блоков кода, пишутся немного по-другому: как YAML, через двоеточие. А еще то, что в блоках мы указываем без имени, например, подпись или название, здесь нужно называть, как fig-cap, например.

Здесь мы указали, что первая гистограмма размещается в колонке, которая в два раза шире, чем у второй. Это, разумеется, не имеет смысла, если одно изображение на самом деле не шире другого.

Обратите внимание: здесь изображения не пронумерованы: для того, чтобы они были пронумерованы, необходимо дать блоку кода название, начинающееся с fig-

Форматирование изображений

Блок кода, чье название начинается с fig-, генерирует пронумерованные изображения, на которые можно ссылаться:

```{r}
#| label: fig-two-plots
#| fig-cap: "Две диаграммы"
#| fig-subcap:
#|   - "Первая диаграмма"
#|   - "Вторая диаграмма"
#| fig-width: 50
#| layout: "[10, 10]"
hist(mtcars$mpg)
hist(mtcars$disp)
```

Диаграммы

Диаграмма (граф) в Graphviz. Опции начинаются с \\|:

```{dot}
//| label: ex-graphviz-code
//| eval: false
// Комментарий
digraph G {
  fontname="Roboto"
  node [fontname="Roboto"]
  G [color=royalblue];
  x1, x2, x3, x4, x5, x6, x7, x8, x9 [shape=square];
  F1 -> {x1, x2, x3};
  F2 -> {x4, x5, x6};
  F3 -> {x7, x8, x9};
  G  -> {F1, F2, F3};
  
  label = "Граф";
}
```

Диаграммы

Пример графа в Graphviz:

Интерактивные элементы

Формат HTML и производные от него (как revealjs) позволяют добавлять в документ интерактивные элементы семейства htmlwidgets

Интерактивная диаграмма plotly:

library(plotly)
library(dplyr)
library(forcats)

# Небольшая предобработка: сделаем категориальную переменную явно категориальной
mtcars <- mtcars |>
  mutate(am = fct_recode(as.character(am), 'Automatic' = '0', 'Manual' = '1'))

plot_ly(
  mtcars,
  x = ~wt,
  y = ~hp,
  z = ~qsec,
  color = ~am,
  colors = c('#BF382A', '#0C4B8E'),
  width = 550, height = 450
) |>
  add_markers()

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

В HTML и основанные на HTML форматы можно добавлять интерактивные элементы. В других форматах Quarto постарается сделать скриншот и вставить стационарную картинку, но может не получиться или получиться не так, как нам надо. Будьте внимательны! Причем в офисных форматах (docx, pptx получается лучше, чем в PDF)

А лучше всего для PDF делать скриншот и вставлять стационарную картинку.

Капризному (на самом деле пытающемуся быть суперадаптивным) формату plotly лучше явно прописывать размеры.

Интерактивные элементы

Интерактивная карта leaflet:

library(leaflet)

leaflet() |>
  addTiles() |>  # По умолчанию загружает карту OpenStreetMap, и норм 
  addMarkers(lng=37.560826, lat=55.722685, popup="Я разговариваю с вами отсюда")

Интерактивные элементы

Макеты страниц

Макет страницы – это то, как по умолчанию располагаются элементы на странице и друг относително друга.

По умолчанию Quarto использует Article layout: макет, оптимизированный для записей блога и других веб-публикаций, а также для статей в формате PDF.

---
format: 
  html:
    page-layout: article
---

Другие доступные макеты:

full: как article, но заполняет контентом поля, если они не используются;
custom: не содержит grid-макета, заполняет всю доступную ширину.

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

[Читает слайд своими словами]

В макете типа «статья» контент по возможности центрирован и занимает по ширине не более 700 пикселей.

Grid, решетка – это, как вы, наверное, видели в Shiny, упорядочивание содержимого страницы по строкам и столбцам. В раскладке full этого нет, элементы просто следуют один за другим, поэтому вам придется позаботиться о структуре самим (например, используя CSS Grid) и как минимум задать поля (margin-top и прочие).

Коллеги, то, о чем мы говорим сейчас, применяется идеально к HTML. Для форматов, основанных на ТеХ, Quarto старается, но не всегда справляется. При том, что вообще изменение раскладки для них не предусмотрено.

Макеты страниц

Можно делать исключения по местоположению для отдельных блоков, например:

::: {.column-screen}
![Изображение на весь экран](image.png)
:::

#| column: screen-inset

# Иллюстрация на всю ширину экрана с маленькими полями
leaflet() |>
  addTiles() |>
  addMarkers(lng=174.768, lat=-36.852, popup="Родина R")

::: {.column-margin}
![Картинка на полях](image.png)
:::

[Заметка на полях]{.aside}

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Помимо общей для документа раскладки можно «делать исключение» для отдельных фрагментов. В теле ноутбука положение, как и любая особая верстка, оформляется в свойствах контейнера. В блоке кода – параметром column.

На всю или почти всю ширину часто размещают карты. На полях можно размещать формулы, примечания и т. п. Есть еще несколько видов ширины блока, тем или иным образом выходящего за рамки тела статьи: body-outset, page и др.

В презентацию трудно вставить то, как выглядят эти фрагменты, а тем более, чем они отличаются от обычных. Так что давайте поэкспериментируем в RSTudio

Меняем раскладку для отдельных абзацев или изображений в quarto.qmd

На полях можно автоматически размещать ссылки и примечания:

---
reference-location: margin
citation-location: margin
---

<…>

Коллеги, есть ли у вас вопросы?

Возвращаемся к презентации

Макеты для интерактивного взаимодействия

Если вы используете интерактивные элементы с возможностью управления их отображения пользователем (как в Shiny), можно использовать раскладку, облегчающую интерактивное взаимодействие:

.panel-input: контейнер для элементов управления, располагающийся над контентом;
.panel-tabset: помещает контент в несколько вкладок, между которыми можно переключаться;
.panel-sidebar и .panel-fill или .panel-center: боковая панель для элементов управления и широкая панель для отображаемого контента.

Макеты для интерактивного взаимодействия

Как и ширину блока контента, панель можно задать:

в теле ноутбука через контейнер:

::: {.panel-sidebar}
[элементы]
:::

во фрагментах кода, чтобы указать, куда отправятся сгенерированные кодом элементы:

---
…
format: 
  html:
    page-layout: custom
server: shiny
---

#| panel: sidebar
vars <- setdiff(names(iris), "Species")
selectInput('xcol', 'X Variable', vars)
selectInput('ycol', 'Y Variable', vars, selected = vars[[2]])
numericInput('clusters', 'Cluster count', 3, min = 1, max = 9)

#| panel: fill
plotOutput('plot1')

Условный контент

Иногда вам понадобится настроить видимость того или иного фрагмента документа в зависимости от формата, в котором он будет сверстан. Например, загружать интерактивные элементы для HTML, но прятать их или заменять статичным контентом для PDF.

Для этого в Quarto предусмотрено две пары команд (точнее, два класса и два атрибута для контейнеров с контентом), которые можно комбинировать:

.content-visible или .content-hidden: показать или скрыть контент в зависимости от условия в п. 2.
when-format= или unless-format=: показать или скрыть контент (в зависимости от класса в п. 1) при условии, что формат соответствует или не соответствует значению после знака равно.

::: {.content-visible when-format="html"}

Содержание этого блока будет видно только в формате HTML

:::

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

[Читает слайд своими словами]

Если ноутбук предполагает несколько форматов документа. Мы с вами уже видели, что это обычная практика.

Соответственно, можно написать, например, .content-visible unless-format="pdf" и так далее.

Наверное, вы уже догадались, как создать ноутбук, из котором на одном и том же месте загружается, скажем, интерактивная диаграмма plotly в формате HTML и статичный ggplot в формате PDF? Пожалуйста, скажите голосом или напишите в чат, как этого добиться?

Условный контент

Для удобства несколько распространенных названий форматов считаются псевдонимами, обобщающими ряд других доступных в Quarto форматов. Вот таблица соответствия:

Псевдоним	Форматы
`latex`	`latex`, `pdf`
`pdf`	`latex`, `pdf`
`epub`	`epub`
`html`	`html`, `epub`, `revealjs`
`html:js`	`html`, `revealjs`
`markdown`	`markdown`, `commonmark`, `gfm`, `markua`

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

Эту таблицу стоит понимать буквально. Если вы скроете контент для формата HTML, то он не будет виден ни на сайте, ни в презентации revealjs, ни в электронной книге epub. Если вместо этого вы напишите .content-hidden when-format="html:js", то контент в блоке не будет виден ни на HTML-страницах и, соответственно, на сайтах, ни в презентациях revealjs вроде этой (то есть, в форматах, которые допускают интерактивные элементы), но будет виден в книгах epub.

Ну и напомню, что Quarto динамично развивается. Условный контент в зависимости от формата – это отлично. Надеюсь, они со временем добавят больше условий, например, зависимость от другого контента, стиля и т. д.

В принципе, что-то из этого можно сделать самому в Lua, но это для тех, кто хочет быть богом отчетов.

Вообще многое им еще предстоит. Например, многие YAML-команды работают и в заголовке, и во фрагментах кода, но некоторые работают только из заголовка. Или, например, обращение к метаданным и включения: можно было бы расширить их функционал, например, тоже добавить условные выражения. Если вам нравится Quarto, стоит следить за его развитием.

Видео

В форматах HTML в документ можно встроить видео из локального файла или по url. В презентации revealjs видео можно добавить в качестве фона.

Кроме заголовка фрейма можно настраивать такие параметры, как:

соотношение сторон (aspect-ratio="4x3");
ширина и высота (width="250" height="175");
таймкод (start="26").

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины. Действие ниже↓

Можно вставлять видео по url или из локального файла.

Коллеги, мы с вами посмотрели много вариантов добавления элементов в наш ноутбук Quarto и вариантов настройки их отображения для разных форматов. В теории, а кое-что и на практике. Есть ли у вас вопросы по тому, что мы с вами видели? Например, нужно ли показать еще что-нибудь из этого в RStudio?

А теперь давайте сверстаем документ с параметрами. Для простоты будем использовать всеми любимых пингвинов. А раз они у нас на английском, то и заголовки будут на английском, чтобы смотрелось органично то, что мы хотим провернуть. Если вы не против.

Комплексные публикации

Сайты, блоги, книги

Quarto содержит нативную поддержку создания комплексных публикаций:

сайты;
блоги;
книги.

Любой сайт, блог или книга состоит из основных элементов:

метаданные проекта;
контент (файлы .qmd);
элементы навигации (содержание, меню, вкладки, поиск и т. п.);
ресурсы (изображения, темы, скрипты и т. п.).

Создание сайта в Quarto – Заготовка

Проще всего создать сайт, блог или книгу как проект RStudio:

Выбираем Quarto…

RStudio создает для нас необходимые файлы и пару файлов для примера

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины. Действие ниже↓

На слайде показано, как создать проект в RStudio,

А мы с вами перейдем туда и создадим сайт

Создаем сайт Quarto как новый проект и дальше работаем уже в нем

Необходимые файлы – это _quarto.yml, в котором хранятся настройки проекта, в том числе параметры отображения, общие для всех документов. index.qmd, который сверстается в index.html, тоже необходим любому сайту. Также для примера добавлен шаблон страницы About и пустой файл со стилями.

Вернемся в презентацию.

Создание сайта в Quarto – Метаданные

Информация о проекте, в том числе ссылки на контент, описание структуры и общий стиль, содержится в файле _quarto.yml:

---
project:
  type: website

website:
  title: "quartosite"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd

format:
  html:
    theme:
      light: united
      dark: vapor
    css: styles.css
    toc: true
---

Создание сайта в Quarto – Навигация

В Quarto можно легко создать следующие элементы навигации:

navbar (навигационная панель сверху);
sidebar (боковая навигационная панель);
page-footer (подвал сайта);
search (поисковый виджет).

Создание сайта в Quarto – Навигация

Пример задания верхней навигационной панели:

website:
  <…>
  # Верхняя панель («шапка»)
  navbar:
    title: "QuartoWebsite" # Переписывает website: title
    logo: www/owls_R.png
    logo-alt: "Otus: R for Data Analysis"
    # Элементы слева
    left:
      - href: index.qmd
        text: Home
      - about.qmd
    # Элементы справа
    right: 
      - href: https://otus.ru
        icon: mortarboard
        target: _blank
      - href: https://github.com
        icon: github
        target: _blank

Создание сайта в Quarto – Навигация

Пример задания боковой панели:

website:
  <…>
  # Боковая панель (боковое меню):
  sidebar:
    background: dark  # Один из стандартных цветов текущей темы оформления
    foreground: light # Еще один цвет темы. Они изменятся, если изменить тему
    style: docked     # Прикреплена к своему краю
    contents:
      - section: "Первый раздел"
        contents:
          - entry-01.qmd
          - entry-02.qmd
      - section: "Второй раздел"
        contents:
          - entry-03.qmd
          - entry-04.qmd

Внимание на чат! Медленно. Акцентированно. Четко. С интонацией. Без отсебятины.

[Читает слайд своими словами]

Здесь мы видим описание боковой навигационной панели:

Цвета оформления
Указание на то, что панель должна быть прикреплена к краю, а не плавать
Разделы и ссылки на файлы, из которых будут сверстаны страницы, на которые будут ссылки на боковой панели.

Давайте добавим такую панель на наш сайт. Нам придется создать пару, то есть 4, файла для примера меню

Создание сайта в Quarto – Навигация

Пример задания нижней панели (подвала):

website:
  <…>
  # Подвал
  page-footer:
    background: primary  # «Ведущий» цвет выбранной темы оформления
    foreground: "#eee"
    # Элементы посередине (также можно указать right и left):
    center: 
      - about.qmd

Создание сайта в Quarto – Навигация

Пример задания поискового виджета:

website:
  <…>
  # Поиск
  search:
    location: navbar # К чему прикрепляется виджет
    type: overlay    # Тип: overlay – иконка со всплывающим виджетом, textbox – стандартный text input
    limit: 5         # Максимальное количество результатов для показа

Создание сайта в Quarto – Рендеринг

Для предпросмотра нашего сайта находим:

Меню проекта
Вкладку Build
Кнопку Render Website

Создание сайта в Quarto – Публикация

Помимо собственного сервера, опубликовать сайт можно на Quarto Pub, Posit Connect, GitHub Pages, Netlify и некоторых других платформах.

Например, если мы назовем проект и репозиторий на GitHub username.github.io, где username – наше имя на GitHub, мы создадим свой персональный сайт на GitHub Pages.

Если мы назовем проект и репозиторий name, где name – любое название, мы создадим сайт по адресу username.github.io/name.

Создание сайта в Quarto – Публикация

Рассмотрим публикацию на GitHub Pages:

Прописываем, что папка с сайтом должна называться “docs” (по умолчанию “_site”)

project:
  type: website
  output-dir: docs

Заходим в свой аккаунт на GitHub и создаем пустой репозиторий (без README)
Связываем свой локальный проект с репозиторием:

git init
git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/username/name.git
git push -u origin main

Создание сайта в Quarto – Публикация

В настройках репозитория в меню Pages разрешаем развертывание на Pages: выбираем ветку и папку (Рис. 5)

Рис. 5: Настройка отображения на GitHub Pages

Рефлексия

Спросите себя. Расскажите в чате или голосом:

Хотите ли вы применять Quarto в своей работе?
Считаете ли вы, что это сложно?
О каких еще возможностях системы вы хотите узнать?
Какой проект вам хочется оформить в Quarto первым? В каком формате вы бы его сверстали?