13  Quarto Manuscripts и Marimo

Основным итоговым документом для научной публикации является текст рукописи статьи. Тем не менее, в научной практике, где используются вычисления на языках программирования, в ходе рабочего процесса создания статьи часто применяются блокноты — промежуточные документы, объединяющие код и текст (например, в форматах *.ipynb или *.rmd/*.qmd в Jupyter и R Markdown/Quarto).

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

Например, целью пилотного проекта Notebooks Now! является повышение роли вычислительных блокнотов в качестве основных элементов научной документации, разработку сквозного научного издательского рабочего процесса, который будет рассматривать блокноты (такие как Jupyter) как основной элемент научной публикации, доступный для рецензирования. Авторы проекта осознают, что для обеспечения такого рабочего процесса возможно потребуются определенные стандарты в отношении блокнотов, например, в отношении редактирования и создания платформ.

13.1 Обзор Quarto Manuscript

Quarto Manuscript — это специальный тип проекта в Quarto, предназначенный для создания воспроизводимых научных рукописей, объединяющий ноутбуки с текстом публикации, что позволяет публиковать код вместе со статьей и объединять несколько выходных форматов. В качестве источников может быть один или несколько документов в формате Quarto (*.qmd) и/или Jupyter-ноутбуки (.ipynb).

Документы Quarto Manuscript публикуются как веб-сайт статьи с возможностью перехода по гиперссылкам: читатель может просмотреть и исходный код и результат, не покидая браузер, посмотреть данные или код с результатами вывода того, как создавались те или иные рисунки или таблицы. Помимо HTML-версии текста основной публикации, через через боковое меню «Другие форматы» также могут быть доступны и другие форматы статьи (PDF, DOCX и др.).

Кроме того, Quarto Manuscript поддерживает интеграцию с внешними сервисами, например, вставку ссылок на внешние ноутбуки (Binder, NBViewer и др.). Система также обеспечивает возможность выгрузки материалов в архивы, например, Manuscript Exchange Common Approach (MECA)-архив для подачи в журнал, а также поддерживает расширения для подключения шаблонов журналов.

В качестве хорошего вводного примера Quarto Manuscript можно посмотреть статью A personal history of the tidyverse, которую написал Hadley Wickham, а также пример от создателей Quarto.

13.2 Начало работы с Quarto Manuscript

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

возможно сделать шаблоны из IDE + terminal

Для создания простейшего проекта Quarto Manuscript в Visual Studio Code (соответственно, Positron) на основе шаблона, нужно выбрать в меню File : New File… : Quarto Project : Manuscript Project.

Рисунок 13.1: Пример создания Quarto Manuscript-страницы в Visual Studio Code / Positron

Для того, чтобы создать Quarto Manuscript проект в RStudio, необходимо выбрать в меню в последовательности: File : New Project… : New Directory : Quarto Manuscript, как на рисунке ниже.

Рисунок 13.2: Пример создания веб-страницы в Quarto в RStudio

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

Terminal
quarto create project

Рисунок 13.3: Пример создания Quarto Manuscript в терминале

Альтернативно, можно использовать команду:

Terminal
quarto create project manuscript manuscript-project

Проект Quarto Manuscript должен содержать файл _quarto.yml следующего вида:

_quarto.yml
project: 
  type: manuscript

Одновременно с основным HTML-файлом index.html проекта Quarto Manuscript также создается файл index-preview.html, который содержит блокнот с кодом и результатами вычислений.

Код файла _quarto.yml примера проекта Quarto Manuscript 
_quarto.yml
project:
  type: manuscript

manuscript:
  article: index.qmd
  code-links: repo

format:
  html:
    comments:
      hypothesis: true
  docx: default
  jats: default
  pdf: default

execute:
  freeze: true

lang: ru
language:
  title-block-affiliation-single: "Организация"
  title-block-published: "Дата"
  section-title-references: "Список литературы"
  related-notebooks-title: "Блокноты статьи"
bibliography: references.bib
csl: gost-r-7-0-5-2008-numeric.csl

title: Пример Quarto Manuscript
date: today
authors:
  - name: Автор
    affiliation: Университет
    roles: writing
    corresponding: true
abstract: >
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce eu tellus vel tellus porta dapibus eu sit amet sapien.
Код файла index.qmd примера проекта Quarto Manuscript 
index.qmd
## Параграф
Это простой заполнитель для основного документа рукописи [@knuth84].

> Dolor sapien, montes porttitor, habitant, duis ultricies felis, condimentum urna netus cursus et. Mattis purus commodo; accumsan ultricies metus elementum gravida. 

Vulputate convallis orci rutrum primis sodales, euismod ligula neque per? Nec ornare in mi quis nisl himenaeos hac vitae maecenas habitant. Quisque pretium aliquet sociis lobortis, non vestibulum dictumst feugiat leo dignissim. Eu donec nostra morbi porttitor.

```{r}
#| echo: false
#| warning: false
#| message: false
library(tidyverse)
ggplot(diamonds, aes(x = carat, 
                     y = price, 
                     color = clarity)) +
  geom_point(alpha = 0.4)
```

Проект Quarto Manuscript должен содержать основные файлы статьи index.qmd либо index.ipynb (если это Jupyter Notebook), которые можно заменить на любое другое название, отличное от index.*, если прописать это в YAML явным образом:

_quarto.yml
manuscript:
  article: my_manuscript.qmd

Все файлы (.qmd или блокноты .ipynb), находящиеся в каталоге проекта, станут частью Quarto Manuscript проекта. Эти блокноты будут отображаться в формате HTML и будут связаны ссылками с основной веб-страницей Quarto Manuscript в разделе «Блокноты». Также можно включить блокноты в проект, явно указав относительный путь к блокноту или внешнюю ссылку на блокнот.

_quarto.yml
manuscript:
  notebooks:
    - notebook: notebooks/my_notebook.ipynb
      title: Блокнот статьи

    - notebook: index.ipynb
      title: Исходные вычисления
      url: https://notebooks.marimo.org/notebook.ipynb
Рисунок 13.6: Пример использования нескольких блокнотов в Quarto Manuscript

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

_quarto.yml
manuscript:
  notebooks:
    - notebook: notebooks/data-notebook.ipynb
      title: Исходные вычисления
      download-url: notebooks/data-notebook-raw.ipynb

Для добавления ссылок на код, который будет отображаться на странице, можно использовать опцию code-links для добавления ссылок на файлы с кодом:

_quarto.yml
manuscript:
  code-links:
    - text: Ссылки на код
      icon: file-code
      href: Python-code.py
Рисунок 13.7: Пример использования ссылок на код в проекте

Для добавления ссылки на Git-репозиторий (скажем, GitHub-репозиторий) проекта, необходимо указать:

_quarto.yml
manuscript:
  code-links: repo
ОсторожностьЗамечание

Указать репозиторий Git через YAML невозможно. Quarto автоматически определяет URL-адрес ссылки на основе настроек Git вашего проекта, для корректной работы code-links: repo проект должен быть репозиторием Git.

Аналогичным образом можно добавить ссылки на блокноты Binder, чтобы они могли взаимодействовать с вашими Quarto Manuscript блокнотами в облачной вычислительной среде (см. также Использование Binder с Quarto).

Помимо доступа к вычислениям и коду, в Quarto Manuscript существует возможность добавлять на основной HTML-веб-сайт ресурсы, необходимые для преобразования ваших блокнотов, для чего нужно будет указать путь в опции resources:

_quarto.yml
manuscript:
  resources:
    - data/my_data.csv

Доступ к данным будет организован как {domain}/data/my_data.csv, где {domain} — это основной URL-адрес проекта.

В Quarto Manuscript возможно использовать подход к обмену рукописями MECA (Manuscript Exchange Common Approach) или NISO MECA, целью которого является создание общего, простого в реализации протокола для переноса научных статей из одной системы в другую, чтобы этим различным системам не приходилось разрабатывать множество парных решений для каждой соответствующей системы. Это единый способ упрощения передачи рукописей между различными системами обработки рукописей, такими как системы, используемые издательствами и серверами препринтов. Чтобы использовать MECA, необходимо указать формат jats в качестве выходного формата:

_quarto.yml
format:
  html: default
  jats: default

либо указать

_quarto.yml
manuscript:
  meca-bundle: true

В этом случае на основной странице проекта будет создана ссылка на MECA Bundle в разделе «Другие форматы», при нажатии на которую можно будет скачать архив вида index-meca.zip, внутри которого содержатся все файлы, относящиеся к проекту, включая ноутбуки.

Отметим, что на сайте Quarto Manuscript можно оставлять комментарии. Чтобы включить комментирование, используйте соответствующую опцию comments в настройках HTML-формата. Например, чтобы включить комментарии на Hypothes.is, можно добавить hypothesis: true:

_quarto.yml
format:
  html: 
    comments:
      hypothesis: true

сделаем скриншот Binder + выделано несколько форматов в правом углу

13.3 Ноутбуки Marimo

13.3.1 Обзор Marimo

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

Основные особенности Marimo следующие:

  1. Реактивность блокнотов: в отличие от Jupyter, где необходимо запускать каждую ячейку вручную, Marimo автоматически обновит и отреагирует при запуске всех зависимых ячеек, изменит значения соответствующих переменных.1

  1. Интерактивность: для взаимодействия с пользователем, в Marimo имеются встроенные интерактивные элементы, например, такие как ползунки или выпадающие списки. Таким блокнотом можно поделиться через HTML с помощью WebAssembly.

  2. Python-ориентированный подход, дружественный к Git: Блокноты Marimo написаны на чистом Python, хранятся в виде файлов с расширением .py и запускаются как скрипты Python. Такой файл удобно хранить в Git, использовать как обычный скрипт или импортировать как модуль в другой проект. Среда выполнения при этом остаётся воспроизводимой. Это главное отличие от Jupyter (.ipynb).

  3. Работа с SQL: блокноты Marimo интегрируются с Polars, Pandas, PyArrow, DuckDB, SQLite, Postgres, MySQL и многими другими бэкэндами. SQL-запросы можно писать непосредственно внутри блокнота, что удобно для анализа данных.

  4. Удобство для разработчиков: Редактор Marimo включает в себя автозаполнение в стиле GitHub Copilot, всплывающие подсказки при наведении курсора, клавиатурные сочетания, форматирование кода, панели отладки и расширенный набор горячих клавиш. Marimo имеет интерфейс командной строки (CLI), собственную библиотеку и расширение для VS Code. Также, можно подключить ИИ-агента (на основе облачной или локальной модели) к запущенным сессиям блокнотов Marimo для встроенного редактирования и контекстно-зависимого чата.

Помимо сказанного, можно отметить, что Marimo имеет собственный бесплатный облачный сервис для создания блокнотов molab как аналог Google Colab, а также Marimo сделали довольно содержательные уроки на основе своих блокнотов.

Рисунок 13.8: Интерактивные уроки в Marimo

Marimo можно установить несколькими способами, предпочтительный для нас — с помощью инструмента uv. Чтобы установить Marimo, достаточно набрать в терминале

Terminal
uvx marimo

# Альтернативно:
# pip install marimo  
# либо
# conda install -c conda-forge marimo

# Для установки определенных зависимостей, например, SQL:
# pip install 'marimo[sql]'
Рисунок 13.9: Установка Marimo
Рисунок 13.10: Список CLI-команд Marimo по uvx marimo --help

Для запуска руководства по Marimo:

Terminal
uvx marimo tutorial intro

Начать работу с ноутбуком Marimo можно, набрав

Terminal
 uvx marimo edit --sandbox notebook.py

13.3.2 Взаимодействие Marimo с Quarto

Если уже установлен Quarto2, uv и непосредственно Marimo, добавить расширение quarto-marimo к проекту командой:

Terminal
quarto install extention marimo-team/quarto-marimo

Далее необходимо добавить в Quarto-проект использование Marimo:

Quarto
---
title: Пример документа Marimo
---

## Проект Quarto c использованием Marimo

```python {.marimo}
#| echo: true
import marimo as mo
slider = mo.ui.slider(1, 10, 1, label = "Посмотрите на слайдер!")
slider
```

```python {.marimo}
# Отсутствие опции echo: true 
# означает, что код не будет показан
mo.md(" слово = " * slider.value + " Дело!")
```
Рисунок 13.13: Использование Marimo в Quarto

Одна из самых мощных функций Marimo — это поддержка интерактивных элементов пользовательского интерфейса (UI): взаимодействие с элементом UI автоматически запускает ячейки, которые на него ссылаются. В частности, модуль marimo.ui содержит библиотеку готовых элементов. Репозиторий examples содержит примеры, демонстрирующие все элементы пользовательского интерфейса (см. также список элементов).

Более подробно почитать о взаимодействии Marimo и Quarto можно на странице marimo + quarto.

Рисунок 13.14: Страница репозитория использования Marimo и Quarto

Также, хороший обзор по основам работы Marimo, включая работу с Quarto, можно посмотреть в видео How marimo adds reactivity to your Quarto documents.

Заключение

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

  • Quarto Manuscript — тип проекта в Quarto, объединяющий ноутбуки с текстом публикации и позволяющий воспроизводить несколько форматов одновременно.

  • Marimo — особый тип блокнотов для программирования на Python, который обладает реактивностью: при изменении одной ячейки все зависимые ячейки обновляются автоматически.

В этой главе мы рассмотрели процесс создания и работы с Quarto Manuscript, а также интеграцию Marimo с Quarto.

  1. При необходимости, можно настроить Marimo так, чтобы обновление ячеек не происходило автоматически.↩︎

  2. версии >= 1.9.20 на момент написания книги↩︎