41  Структурирование рутинных отчетов

Эта страница рассматривает пакет reportfactory, который является дополнением к использованию R Markdown для отчетов.

В сценариях, где отчеты выполняются регулярно (ежедневно, еженедельно и т.д.), он облегчает компиляцию нескольких R Markdown-файлов и организацию их выходных данных. По сути, это “фабрика”, из которой можно запускать отчеты в формате R Markdown, получать автоматически маркированные по дате и времени папки для выходных данных и “легко” контролировать версии.

reportfactory - один из пакетов, разработанных RECON (R Epidemics Consortium). Вот их веб-сайт и Github.

41.1 Подготовка

Загрузка пакетов

Внутри RStudio установите последнюю версию пакета reportfactory с Github.

Вы это можете сделать с помощью пакета pacman с p_load_current_gh(), которая принудительно устанавливает самую последнюю версию с Github. Задайте текстовую цепочку “reconverse/reportfactory”, которая уточняет организацию Github (reconverse) и репозиторий (reportfactory). Вы можете также использовать install_github() из пакета remotes в качестве альтернативы.

# Устанавливаем и загружаем самую последнюю версию пакета из Github
pacman::p_load_current_gh("reconverse/reportfactory")
#remotes::install_github("reconverse/reportfactory") # альтернатива

41.2 Новая фабрика

Чтобы создать новую фабрику, выполните функцию new_factory(). Это создаст новую автономную папку проекта R. По умолчанию:

  • Фабрика будет добавлена в вашу рабочую директорию
  • Имя фактора проекта R будет называться “new_factory.Rproj”
  • Ваша сессия RStudio “перейдет” в этот проект R
# Это создаст фабрику в рабочей директории
new_factory()

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

  • Папка report_sources будет содержать ваши скрипты, которые создают ваши отчеты
  • Папка outputs будет содержать выходные данные отчета (например, HTML, Word, PDF, и т.п.)
  • Папка scripts может быть использована для хранения других скриптов R (например, которые вызывают ваши скрипты Rmd)
  • Папка data может быть использована для хранения ваших данных (включены подпапки “raw” (сырые) и “clean” (чистые))
  • Файл .here, чтобы вы могли использовать пакет here, чтобы вызывать файлы из подпапок по отношению к этой корневой папке (см. детали на странице проекты R)
  • Файл gitignore был создан, чтобы связать ваш проект R с репозиторием Github (см. Контроль версий и совместная работа с помощью Github)
  • Пустой файл README, если вы используете репозиторий Github

ВНИМАНИЕ: в зависимости от настроек вашего компьютера, могут существовать такие файлы как “.here”, но будут невидимыми.

Ниже представлены несколько настроек из настроек по умолчанию, которые вы, возможно, откорректируете внутри new_factory():

  • factory = - Задайте имя для папки фабрики (по умолчанию “new_factory”)
  • path = - Укажите путь к файлу для новой фабрики (по умолчанию - рабочая директория)
  • report_sources = Задайте альтернативное имя для подпапки, в которой будут содержаться скрипты R Markdown (по умолчанию “report_sources”)
  • outputs = Задайте альтернативное имя для папки, в которой содержатся выходные результаты отчетов (по умолчанию “outputs”)

См. ?new_factory, где вы можете найти полный список аргументов.

Когда вы создаете новую фабрику, ваша сессия R переводится в новый проект R, поэтому нужно снова загрузить пакет reportfactory.

pacman::p_load(reportfactory)

Теперь вы можете выполнить команду factory_overview(), чтобы увидеть внутреннюю структуру (все папки и файлы) фабрики.

factory_overview()            # печать обзора на консоли фабрики

Следующее “дерево” папок и файлов фабрики печатается в консоли R. Обратите внимание, что в папке “data” есть подпапки для “сырых” и “чистых” данных, а также примеры CSV данных. Также есть файл “example_report.Rmd” в папке “report_sources”.

41.3 Создание отчета

Изнутри проекта фабрики R создайте отчет R Markdown, как вы это обычно делаете, и сохраните его в папку “report_sources”. См. страницу R Markdown для инструкций. В качестве примера мы добавили следующее к фабрике:

  • Новый скрипт R markdown под названием “daily_sitrep.Rmd”, сохраненный в папку “report_sources”
  • Данные для отчета (“linelist_cleaned.rds”), сохраненные в подпапку “clean” внутри папки “data”

Используя factory_overview(), мы можем видеть наш R Markdown в папке “report_sources” и файл с данными в папке “clean” (чистые данные) (выделено):

Ниже вы видите снимок экрана начала R Markdown “daily_sitrep.Rmd”. Вы можете видеть, что формат выходных данных установлен как HTML, через заголовок YAML output: html_document.

В этом простом скрипте есть команды для:

  • загрузки нужных пакетов
  • импорта данных построчного списка, используя путь к файлу из пакета here (более детально читайте на странице [Импорт и экспорт])
linelist <- import(here("data", "clean", "linelist_cleaned.rds"))
  • Печати суммарной таблицы случаев, экспорта с помощью export() в виде файла .csv
  • Печати эпидкривой и ее экспорта с помощью ggsave() в виде файла .png

Вы можете изучить список отчетов R Markdown в папке “report_sources” с помощью следующей команды:

list_reports()

41.4 Компиляция

В фабрике отчетов, “компиляция” отчета R Markdown означает, что скрипт .Rmd будет выполнен и будет создан выходной результат (как указано в скриптах YAML, например, HTML, Word, PDF, и т.п.).

Фабрика автоматически создаст папку с меткой даты и времени для выходных результатов в папке “outputs”.

В этой папке будет сохранен сам отчет и все экспортированные файлы, созданные скриптом (например, csv, png, xlsx). Кроме того, в эту папку будет сохранен сам скрипт Rmd, так что у вас будет запись о данной версии скрипта.

Это отличается от обычного поведения R Markdown, сформированного с помощь “knit”, который сохраняет выходные данные в месте сохранения скрипта Rmd. Это поведение по умолчанию может привести к папке с большим количеством хаотично расположенных папок. Фабрика нацелена на улучшение организации, если вы часто повторяете отчеты.

Компиляция по имени

Вы можете компилировать конкретный отчет, выполнив compile_reports() и задав имя скрипта Rmd (без расширения .Rmd) в reports =. Для простоты вы можете пропустить reports = и просто написать имя R Markdown в кавычках, как ниже.

Эта команда будет компилировать только отчет “daily_sitrep.Rmd”, сохраняя отчет HTML, а таблица .csv и эпидкривая .png экспортируется в подпапку с маркировкой даты и времени, конкретную для отчета, внутри папки “outputs”.

Обратите внимание, что если вы решите задать расширение .Rmd, вам нужно правильно напечатать расширение, так как оно сохраняется в имени файла (.rmd vs. .Rmd).

Также обратите внимание, когда вы проводите компиляцию, вы можете увидеть, что несколько файлов временно появятся в папке “report_sources” - но они скоро исчезнут, так как они будут перенесены в правильную папку “outputs”.

Компиляция по номеру

Вы также можете указать скрипт Rmd для компиляции, указав номер или вектор номеров в reports =. Номера будут соответствовать порядку, в котором отчеты появляются, когда вы выполняете list_reports().

# Компиляция второго и четвертого Rmd в папку "report_sources"
compile_reports(reports = c(2, 4))

Компилировать все

Вы можете компилировать все отчеты R Markdown в папке “report_sources”, установив аргумент reports = как TRUE (ИСТИНА).

Компилировать из подпапки

Вы можете добавить подпапки в папку “report_sources”. чтобы выполнить отчет R Markdown из подпапки, просто укажите имя папки в subfolder =. Ниже приведен пример кода для компиляции отчета Rmd, который находится в подпапке “report_sources”.

compile_reports(
     reports = "summary_for_partners.Rmd",
     subfolder = "for_partners")

Вы можете компилировать отчеты Rmd внутри подпапки, задав имя подпапки в reports =, со слэшем на конце, как показано ниже.

compile_reports(reports = "for_partners/")

Параметризация

Как указано на странице [Отчеты с помощью R Markdown], вы можете выполнить отчеты с указанными параметрами. Вы можете передать эти параметры как список в compile_reports() через аргумент params =. Например, в этом выдуманном отчете в отчеты R Markdown задается три параметра.

compile_reports(
  reports = "daily_sitrep.Rmd",
  params = list(most_recent_data = TRUE,
                region = "NORTHERN",
                rates_denominator = 10000),
  subfolder = "regional"
)

Использование “файла выполнения”

Если вам надо выполнить несколько отчетов, рассмотрите возможность создания скрипта R, который содержит все команды compile_reports(). Пользователь может просто выполнить все команды в этом скрипте R и все отчеты будут компилированы. Вы можете сохранить этот “файл выполнения” в папке “scripts”.

41.5 Выходные данныые

После того, как мы компилировали отчеты несколько раз, папка “outputs” может выглядеть так (выделение добавлено для наглядности):

  • Внутри “outputs” созданы подпапки для каждого отчета Rmd
  • В них созданы дополнительные подпапки для каждой уникальной компиляции
    • Эти папки имеют маркировку даты и времени (“2021-04-23_T11-07-36” что означает 23 апреля 2021 в 11:07:36)
    • Вы можете редактировать формат штампа даты/времени. См. ?compile_reports
  • Внутри каждой компилированной папки с датой/временем созраняется выходной отчет (например, HTML, PDF, Word), а также скрипт Rmd (контроль версий!) и другие экспортированные файлы (например, table.csv, epidemic_curve.png)

Вот вид внутри одной из папки с маркировкой даты/времени для ежедневного ситуационного отчета “daily_sitrep”. Путь к файлу для наглядности выделен желтым.

Наконец, ниже приведен снимок экрана с выходными данными в формате HTML.

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

41.6 Разное

Knit

Вы все еще можете сформировать ваши отчеты R Markdown, нажав кнопку “Knit”, если хотите. Если вы это сделаете, по умолчанию выходные данные появятся в папке, где сохранен Rmd - в папке “report_sources”. В предыдущих версиях reportfactory, наличие файлов не в формате Rmd в “report_sources” мешало компилированию, но теперь это не так. Вы можете выполнить compile_reports() и ошибок не будет.

Скрипты

Мы призываем вас использовать папку “scripts” для хранения “файлов выполнения” или скриптов .R, к которым обращаются ваши скрипты .Rmd. См. страницу [R Markdown][Отчеты с помощью R Markdown], где есть советы о том, как структурировать ваш код по нескольким файлам.

Дополнительно

  • В reportfactory вы можете использовать функцию list_deps(), чтобы указать список всех пакетов, которые нужны для всех отчетов во всей фабрике.

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

    • load_scripts() - обращается к/загружает все скрипты .R в указанной папке (по умолчанию папка “scripts”)
    • find_latest() - находит последние версии файла (например, последний набор данных)

41.7 Ресурсы

См. пакет reportfactory на странице Github

См. пакет rfextras на странице Github