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

Как человек, который создает работу как в R, так и в Python, я всегда хотел, чтобы было более приятное решение для превращения моих блокнотов Jupyter в профессионально выглядящие документы. Экосистема R некоторое время имела такую ​​возможность с R Markdown, которую я активно использую, и на самом деле я написал свой Python в среде R, чтобы я мог воспользоваться преимуществами, которые может предложить R Markdown.

У меня всегда были проблемы с внешним видом ноутбука Jupyter и отсутствием возможностей превратить его во что-то более «законченное» и визуально привлекательное. Конечно, интерактивное программирование полезно, но внешний вид никогда не урежет горчицу, когда дело доходит до публикации вашей работы для аудитории.

С выходом Quarto все изменилось. Quarto — это разработка R Markdown, которая теперь изначально работает с ноутбуками Jupyter. Процесс рендеринга такой же, за исключением того, что вместо knitr для генерации уценки Quarto теперь может использовать knitr и jupyter.

Благодаря внедрению некоторых очень умных функций вы теперь можете кодировать свои блокноты Jupyter, как обычно, но добавляя специальные инструкции, которые позволят отображать их в самых разных форматах (например, pdf, html, docx, вики, сайты, книги). Специальные комментарии позволяют в значительной степени контролировать выполнение и размещение кода в документе, а также дают больший контроль над форматированием и размещением вывода кода.

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

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

Настройка существующей записной книжки для Quarto — простой пример

Сначала вам нужно установить интерфейс командной строки Quarto в вашей системе — см. здесь. Если вы работаете в VSCode, уже есть надстройка Quarto, которую вы можете установить. Я уверен, что мы скоро увидим его и для PyCharm.

Теперь давайте возьмем существующий файл ipynb в соответствующей среде Python — назовем его my_notebook.ipynb. Вот простой пример, в котором я создал красивую коррелограмму.

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

Теперь вы создали свой первый базовый документ Quarto — вот и все! Давайте посмотрим на некоторые из основных параметров, которые мы поместили в заголовок YAML:

  • title — название вашего документа
  • format указывает формат вывода и любые дополнительные параметры, относящиеся к этому формату. В этом случае я указал, что мне нужен HTML-вывод со свернутым кодом, чтобы я мог видеть код, только если я нажму на соответствующие разделы (хорошая функция, когда ваша аудитория является как технической, так и нетехнической)
  • execute указывает, когда вы хотите, чтобы код выполнялся в документе. Установка enable: true означает, что код будет выполняться каждый раз при его рендеринге. В противном случае вывод кода сохраняется и код не выполняется повторно при последующих рендерингах. Это особенно полезно, если ваш код требует больших вычислительных ресурсов или требует много времени для выполнения.
  • jupyter указывает, что использовать для запуска кода. В данном случае это явно Python 3, но можно и другие движки типа Юлии с правильной конфигурацией.

Теперь все, что вам нужно сделать, это ввести quarto render my_notebook.ipynb в терминале, и вы получите этот простой вывод HTML со свернутым кодом (просто щелкните раздел кода, чтобы развернуть его и увидеть код).

Форматы, доступные в Quarto

Это был очень простой пример, и через секунду мы рассмотрим более интересный, но в Quarto доступно множество форматов. Простая замена html на pdf в заголовке YAML создаст аккуратный вывод в формате PDF, а замена на docx сгенерирует в MS Word. Есть также много выходных слайдов, веб-сайтов и прочего. Полный список доступен здесь. Вот пример рендеринга в формате PDF с аннотацией и автором (вывод разбит на другую страницу).

Использование параметров блока кода для управления выходами

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

В этом примере я собираюсь визуализировать свой документ в формате revealjs, который представляет собой аккуратную презентацию слайдов. На главном слайде я хочу, чтобы код и вывод отображались рядом в столбцах. Я также хочу дать ссылку на свой сюжет. Для этого я добавляю в свой блок кода различные параметры с помощью специального комментария, а затем ссылаюсь на fig-cap в своем тексте.

Обратите внимание, что в revealjs по умолчанию не отображается код, поэтому необходим явный параметр echo: true, если требуется эхо для определенного блока кода. Результат рендеринга выглядит следующим образом:

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

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