Учебник | R | Параметры R Markdown
Гибкая отчетность с R Markdown
Использование параметров для быстро воспроизводимого анализа
Все мы были на собрании, на котором кто-то спрашивает: «Можете ли вы провести этот анализ еще раз для другого периода времени», или: «Можете ли вы запустить его для группы B вместо группы A», или «можете ли вы прислать мне это? анализ, чтобы я мог поиграть с ним? "
Есть некоторые проблемы, с которыми мы часто сталкиваемся, пытаясь выполнить эти запросы. Сменить источник анализа может быть сложно, будь то с одного файла .csv на другой или с тестовой базы данных на производственную базу данных. Если соединение или файл для импорта определены в нескольких местах, можно легко пропустить одно и получить недопустимый вывод. Мы сталкиваемся с той же проблемой при переключении анализа из группы A в группу B или изменении временных рамок данных анализа. Это может быть несколько фильтров, которые нужно изменить.
Проведение анализа также может быть проблематичным. При работе над каким-либо специальным анализом обычно оставляют пароли базы данных в коде при проработке деталей анализа. Выдача этого файла R Markdown или оставление его на общем сетевом диске вызывает проблемы с безопасностью. Хотя dotenv является опцией, для правильной работы требуется немного больше настроек.
К счастью, в R Markdown есть функция, называемая параметрами, которая обеспечивает решения всех этих проблем.
Параметры жесткого кодирования
Параметры в документе R Markdown очень просты в использовании. В заголовке yaml (раздел в верхней части документа уценки) вам просто нужно добавить пару новых строк для ваших параметров, чтобы жестко их закодировать. После того, как они закодированы, они будут доступны в объекте params для использования в остальном анализ. Ссылаясь на параметры из заголовка yaml, любые обновления, которые необходимо внести, потребуют только одного изменения.
В этом примере мы рассмотрим набор данных gapminder. Это набор данных, доступный в пакете gapminder. В нем есть подмножество индикаторов, собранных фондом Gapminder. Посетите TED talk Ханса Рослинга (одного из основателей Gapminder) или сайт Gapminder для получения дополнительной информации.
# Setup
# install.packages("gapminder")
library(gapminder)
# The data frame
gapminder
Набор данных gapminder содержит 6 переменных: страна, континент, год, lifeExp (ожидаемая продолжительность жизни), pop (население) и gdpPercap (g ross d omestic p продукция на душу населения).
Параметры в фрагментах кода
Начнем с фильтрации фрейма данных за 2002 год. Используя tidyverse, этот код выглядит следующим образом:
library(tidyverse)
gapminder %>%
filter(year == 2002) %>%
head()
Мы могли бы захотеть запустить этот отчет за другой год, что делает его хорошим кандидатом для создания параметра. В заголовок yaml мы добавим еще один элемент с именем params, а под ним, с двумя пробелами впереди, мы создадим параметр year. При запуске R Markdown будет создан объект params, и названные параметры будут доступны для нашего использования.
--- title: "Hardcoded Parameters" author: "RealDrewData" date: "7/6/2021" output: html_document params: year: 2002 ---
Теперь мы можем вернуться к нашему коду фильтрации. Мы заменим 2002 на только что созданный параметр года.
library(tidyverse) gapminder %>% filter(year == params$year) %>% head()
Мы также можем использовать параметр года в других местах кода, например, в метке на графике. Давайте создадим диаграмму разброса с ВВП на душу населения по оси x, ожидаемой продолжительностью жизни по оси y, численностью населения для размера точек и континентом для цвета. В наших ярлыках мы можем использовать функцию paste() и нашу params$year, чтобы создать заголовок для графика, который обновляется с помощью параметра.
gapminder %>%
filter(year == params$year) %>%
ggplot(aes(x = gdpPercap, y = lifeExp, size = pop, color = continent)) +
geom_point() +
labs(title = paste("Life Expectancy and GDP for", params$year), x = "GPD Per Capita", y = "Life Expectancy")
Параметры в секциях Markdown
Разделы Markdown - это то место, где у нас есть простой текст. Мы можем запустить встроенный код, чтобы вернуть значения и отобразить их в выходном тексте. Например, у нас может быть заголовок раздела, в котором говорится:
## Gapminder Analysis for 2002
Это не будет обновляться, когда мы изменим наш параметр. Чтобы исправить это, мы можем использовать встроенный код, чтобы получить год из объекта params. r означает, что мы собираемся использовать код R. При связывании документа он будет точно таким же, как и предыдущий код, если для параметра year по-прежнему установлено значение 2002.
## Gapminder Analysis for 'r params$year'
Другое распространенное использование параметров
Параметры не обязательно должны быть числовыми, они также могут быть логическими. Одним из распространенных примеров этого является создание переключателей для изменения поведения при вязании Markdown. Один из примеров - выводить ли код в окончательный вывод. Когда вы показываете что-то менеджеру или руководителю, вы можете не захотеть видеть код, но при проверке с командой код может быть более важным.
Для этого создадим еще один параметр под годом: show_code.
--- title: "Hardcoded Parameters" author: "RealDrewData" date: "6/19/2021" output: html_document params: year: 2002 show_code: FALSE ---
Обычно в настройках задаются параметры вязания куска. В нашем случае мы хотим установить параметр echo равным show_code. Поскольку мы установили для него значение FALSE, это предотвратит отображение нашего кода в окончательном выводе.
knitr::opts_chunk$set(echo = params$show_code)
Динамические параметры
Параметры жесткого кодирования в Markdown явно добавляют некоторые важные преимущества. Что делать, если кто-то, кто не так хорошо знаком с Markdown, захочет изменить отчет или вы захотите быстро запустить его для другого периода? Здесь могут быть полезны динамические параметры.
Что касается фрейма данных gapminder, в имеющихся данных есть нюанс. Каждые 5 лет во фрейме данных, начиная с 1952 года и заканчивая 2007 годом. Тот, кто не знает данных, может легко изменить параметр на 1953 и очень запутаться, если данные не появятся. Чтобы изменить это, мы можем добавить настраиваемую подсказку, изменив параметр year в заголовке yaml.
Мы добавим еще один подуровень под годом с желаемыми настройками. В этом случае мы хотим, чтобы метка называлась годом, значением по умолчанию было 2002, а для ввода - ползунком. Мы также можем указать минимальное и максимальное значения, а также количество шагов между каждым значением.
---
title: "Dynamic Parameters"
author: "RealDrewData"
date: "6/19/2021"
output: html_document
params:
year:
label: "Year"
value: 2002
input: slider
min: 1952
max: 2007
step: 5
sep: ""
show_code: FALSE
Чтобы появилась подсказка, щелкните стрелку рядом с кнопкой вязания. Нажмите на вязать с параметрами.
Откроется окно с ползунком, обозначенным годом. Этот слайдер будет иметь ограничения, которые мы установили выше. Сдвинуть ползунок к 1977 и щелкнуть вязать - это то же самое, что изменить значение года в заголовке yaml. Дополнительным преимуществом является то, что мы знаем, что ввод будет правильного типа, и можем ограничить параметры, которые могут быть выбраны, чтобы гарантировать, что данные появятся в окончательном выводе.
Вы также заметите, что для параметра show_code был создан входной флажок. Это значение по умолчанию для логических параметров.
Другие типы ввода
Опять же, мы не ограничены только числовыми и логическими типами. Если у меня есть вызов базы данных, где для кода требуются имя пользователя и пароль, мы также можем создать для них параметры.
Имя пользователя может быть текстовым полем. Этот вход обозначается входом text. value - это значение по умолчанию, в данном случае пустое. placeholder - текст, отображаемый в пустом текстовом поле. Для ввода пароля мы можем использовать password вариант ввода текста. Это приведет к обфускации вводимого текста, как при входе на веб-сайт.
---
title: "Dynamic Parameters"
author: "RealDrewData"
date: "6/19/2021"
output: html_document
params:
year:
label: "Year"
value: 2002
input: slider
min: 1952
max: 2007
step: 5
sep: ""
show_code: FALSE
username:
label: "username"
value: ""
input: text
placeholder: "username"
password:
label: "PWD"
value: ""
input: password
placeholder: "password"
---
Когда мы нажимаем кнопку «Связать с параметрами», мы видим текстовое поле и ввод пароля. Это ни в коем случае не лучшая практика, но она дает вам пример того, что вы можете делать с динамическими параметрами.
Есть много других вариантов входов, которые вы можете использовать для установки своих параметров. Более полный список можно найти в Галерее блестящих виджетов.
Заключение
Параметры в R Markdown служат нескольким целям. Они позволяют вам внести одно изменение в документ, которое влияет на весь документ. Они позволяют легко создать один и тот же отчет для другого периода или для другой аудитории. Они также могут помочь в обмене анализом с другими, но могут быть лучшие варианты для этого конкретного случая использования.
- R Markdown: полное руководство, авторы Ихуи Се, Дж. Дж. Аллер, Гарретт Гролемунд. Написанный членами команды RStudio, он охватывает все, что вы когда-либо хотели знать о R Markdown. Он доступен в Интернете бесплатно здесь, но вы также можете приобрести бумажную копию
- Галерея блестящих виджетов: интерактивные примеры всех блестящих виджетов, которые можно использовать для динамической установки параметров в документе R Markdown.
- Hans Rosling TED Talk: Ханс Рослинг - один из основателей Gapminder Foundation. В этом выступлении на TED дается некоторая предыстория данных, используемых в примерах. Это всегда возбуждает меня и заставляет заняться анализом данных!
Я пишу о данных, аналитике и программировании. Вы можете связаться со мной в Medium, Twitter и LinkedIn.
