# Устанавливаем и загружаем самую последнюю версию пакета из Github
::p_load_current_gh("reconverse/reportfactory")
pacman#remotes::install_github("reconverse/reportfactory") # альтернатива
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 в качестве альтернативы.
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.
::p_load(reportfactory) pacman
Теперь вы можете выполнить команду 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 (более детально читайте на странице [Импорт и экспорт])
<- import(here("data", "clean", "linelist_cleaned.rds")) linelist
- Печати суммарной таблицы случаев, экспорта с помощью
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
- Эти папки имеют маркировку даты и времени (“2021-04-23_T11-07-36” что означает 23 апреля 2021 в 11:07:36)
- Внутри каждой компилированной папки с датой/временем созраняется выходной отчет (например, 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