Эта работа посвящена обзору основных возможностей инструмента Quarto.

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

Результаты работы: outputs

В современном мире науки и анализа данных, потребность в эффективном и удобном инструменте для создания публикаций, отчетов и презентаций постоянно растет. Quarto — это современная система публикации, которая объединяет в себе лучшие практики создания научных и технических документов. Она позволяет интегрировать текст, код, визуализации и интерактивные элементы в единый, хорошо структурированный документ, готовый для публикации в различных форматах.

Quarto – это больше чем просто инструмент для создания Markdown-документов; это мощная платформа для создания динамических и репродуктивных исследований. Вы сможете легко создавать интерактивные HTML-страницы, PDF-отчеты, презентации, и даже книги, все это из единого исходного документа. Quarto поддерживает множество языков программирования (Python, R, Julia, JavaScript) и может быть использован как для подготовки академических публикаций, так и для внутренних отчетов и документации.

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

Ссылка на официальную доку: https://quarto.org/

Предварительная подготовка к работе с Quarto

Чтобы приступить к работе с инструментом Quarto, выполните следующие предварительные шаги:

1. Создайте проект и виртуальное окружение.
2. Активируйте виртуальное окружение.
3. Установите Quarto CLI, выполнив команду pip install quarto-cli. Если вы планируете использовать отчет, расположенный в репозитории, то перед запуском необходимо разрешить все его зависимости, установив библиотеки из файла requirements.txt с помощью команды pip install -r requirements.txt

Настройка документа

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

В файле _quarto.yml необходимо определить директорию, в которую будут сохраняться сгенерированные Quarto отчеты. Для обеспечения более аккуратной структуры проекта рекомендуется настроить вывод отчетов в отдельную папку. Это делается с помощью параметра output-dir. После него следует указать имя папки, в которой будут размещаться выходные файлы.

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

Настройки документа (верхний уровень):

• title: "Заголовок":

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

Пример: title: "Анализ успеваемости студентов по регионам"

• subtitle: "Подзаголовок":

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

Пример: subtitle: "Исследование географических данных российских школ"

Настройка параметров:

• echo: False:

Описание: Этот параметр управляет отображением исходного кода в выводе отчета. Если установлено значение False, то код не будет показан в сгенерированном отчете, а отобразится только результат его выполнения (если есть). Если установлено значение True или опустить этот параметр, то код будет отображаться.

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

Пример: Используйте echo: False для того, чтобы показать только график, но не код, которым он был построен.

• error: False:

Описание: Этот параметр управляет отображением ошибок, возникающих при выполнении кода. Если установлено значение False, то ошибки будут скрыты, и отчет продолжит генерироваться. Если установлено значение True, ошибки будут отображены в отчете. Использование: Этот параметр полезен, если вы хотите скрыть ошибки, которые, например, не являются критическими или которые вы хотите отладить самостоятельно, без отображения их в финальном отчете.

Пример: Используйте error: False при тестировании кода, который может временно выдавать ошибки.

Внимание: Скрывание ошибок не рекомендуется в продакшн-отчетах, так как ошибки могут указывать на проблемы с данными или кодом.

• warning: False:

Описание: Этот параметр управляет отображением предупреждений (warnings), которые могут возникнуть при выполнении кода. Если установлено значение False, то предупреждения будут скрыты из сгенерированного отчета. Если установлено значение True, то предупреждения будут отображены.

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

Пример: Используйте warning: False, чтобы скрыть некритичные предупреждения, которые не влияют на результат.

Настройки форматирования (раздел format)

• format:

Описание: Раздел для определения параметров вывода документа. Здесь вы можете настроить формат, в котором будет сгенерирован отчет (например, PDF, HTML, DOCX).

• pdf:

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

• engine: lualatex:

Описание: Указывает LaTeX-движок, который будет использоваться для компиляции документа в формат PDF. lualatex — это современный движок, обладающий хорошей поддержкой Unicode и позволяющий использовать современные шрифты.

Альтернативы: pdflatex (старый движок), xelatex (альтернативный движок с хорошей поддержкой Unicode). Рекомендуется использовать lualatex или xelatex для лучшей совместимости с разными шрифтами и кодировками.

• documentclass: article:

Описание: Определяет класс LaTeX-документа. article является стандартным классом для большинства научных и технических документов, но вы также можете выбрать report, book и другие.

• mainfont: "Times New Roman":

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

Важно: Для корректного отображения кириллицы нужно использовать шрифты с поддержкой кириллицы и соответствующий движок LaTeX(xelatex или lualatex). Как посмотреть шрифты см. ниже.

Настройки Jupyter (раздел jupyter):

• jupyter: python3:

Описание: Указывает ядро (kernel) Jupyter, которое будет использоваться для выполнения кода в документе, если таковой имеется. В данном случае интерпретатор python3 обозначает.

Примечание: Если ваш отчет не содержит исполняемого кода, этот параметр можно опустить.

Общие замечания:

• Эти настройки располагаются в так называемом YAML frontmatter в начале файла вашего Quarto-документа. YAML frontmatter — это блок настроек, заключенный между тремя дефисами (---) в начале файла.

• Данные параметры используются для настройки внешнего вида и функциональности вашего отчета.

• Настройка этих параметров позволяет вам адаптировать отчет под ваши конкретные требования.

Команды

Просмотр подходящих шрифтов для корректного отображения:

fc-list :lang=<lang> family

<lang> - код языка ISO 639.

Описание команд Quarto:

quarto render report.ipynb

Описание: Эта команда используется для генерации отчета из файла report.ipynb. Команда quarto render преобразует этот файл в формат вывода, который определяется настройками в самом файле report.ipynb (например, в его YAML frontmatter) или в файле _quarto.yml в папке проекта.

Функциональность: Читает файл report.ipynb. Выполняет код, если таковой имеется, в соответствии с настройками, и включает результаты выполнения в отчёт. Форматирует текст и код в соответствии с заданными стилями. Создает готовый отчет в формате, который указан в разделе format.

Пример использования: Если в report.ipynb указано format: pdf, то команда сгенерирует PDF-отчёт.

quarto render report.ipynb --to docx

Описание: Эта команда также используется для генерации отчета. Однако, в отличие от предыдущей команды, здесь явно указывается формат вывода с помощью параметра --to docx. Это означает, что команда преобразует файл report.ipynb в формат Microsoft Word Document (.docx).

Ключевые параметры: --to docx: Явно указывает, что вывод должен быть в формате .docx.

Общие замечания:

quarto render - это основная команда для преобразования Quarto-документов в различные форматы.

Команды выполняются в командной строке или терминале в папке, где расположен Quarto проект.

--to - это параметр командной строки, который позволяет явно указать формат вывода. Quarto поддерживает множество различных форматов вывода, включая html, pdf, docx, epub, revealjs и другие. Вы можете использовать другие флаги и опции с командой quarto render, чтобы настроить генерацию отчета. Если в файле, который вы рендерите, уже есть настройки формата, то --to переопределяет их.

Команда для просмотра подходящих шрифтов:

fc-list :lang=<lang> family

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

Функциональность:

fc-list: Вызывает утилиту fontconfig, которая управляет шрифтами в системе.

:lang=<lang>: Фильтрует список шрифтов, отображая только те, которые помечены как поддерживающие указанный язык.

family: Показывает только названия шрифтов (их “семейства”) без дополнительной информации о файлах.

<lang>:

Описание: Этот параметр — это код языка ISO 639. Замените на соответствующий код языка, для которого вы хотите просмотреть шрифты. Например:

• ru - для русского языка (кириллица).
• en - для английского языка.
• de - для немецкого языка.
• ar - для арабского языка.

Примеры использования:

• fc-list :lang=ru family: Показать список шрифтов, поддерживающих русский язык (кириллицу).
• fc-list :lang=ar family: Показать список шрифтов, поддерживающих арабский язык.
• fc-list :lang=ja family: Показать список шрифтов, поддерживающих японский язык.

Применение в Quarto:

Эта команда часто используется при настройке отчетов в Quarto, особенно когда нужно обеспечить корректное отображение текста на разных языках, в том числе кириллицы в PDF. Результат команды помогает определить, какие шрифты установлены в вашей системе и подходят для использования в вашем отчёте. После получения списка подходящих шрифтов, вы можете использовать их в конфигурационных файлах _quarto.yml, например, через mainfont. После этого пересобрать отчет. Где использовать:

• В терминале (Linux/macOS)