1  Редакционные и технические замечания

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

1.1 Подход и стиль

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

Еще несколько моментов:

• Это справочная книга по коду, сопровождаемая относительно короткими примерами, а не подробный учебник по R или науке о данных
  
• Это Руководство по R для использования в рамках прикладной эпидемиологии - а не учебник о методах или науке прикладной эпидемиологии
  
• Это меняющийся документ - оптимальные пакеты R для конкретной задачи часто меняются, и мы приветствуем обсуждение о том, что стоит осветить в данном руководстве

Пакеты R

Такой большой выбор

Одним из наиболее сложных аспектов изучения языка R является определение того, какой пакет R следует использовать для решения той или иной задачи. Часто случается так, что с трудом справляешься с задачей, а потом понимаешь - эй, есть пакет R, который делает все это в одной командной строке!

В данном руководстве мы стараемся предложить Вам как минимум два способа решения каждой задачи: один проверенный метод (возможно, в базовом R или tidyverse) и один специальный пакет R, созданный специально для этой цели. Мы хотим, чтобы у вас было несколько вариантов на случай, если вы не сможете загрузить данный пакет или он не подойдет вам по каким-либо другим причинам.

При выборе пакетов для использования мы отдавали предпочтение пакетам и подходам R, которые были протестированы и проверены сообществом, минимизируют количество пакетов, используемых в типичной рабочей сессии, являются стабильными (не меняются очень часто) и решают поставленную задачу просто и чисто.

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

При необходимости мы также предлагаем варианты кода с использованием базового R - пакетов и функций, поставляемых вместе с R при установке. Мы понимаем, что у некоторых читателей этой книги может не быть надежного Интернета для загрузки дополнительных пакетов.

Связывание функций с пакетами в явной форме

В учебниках по R часто бывает неприятно, когда функция показана в коде, но вы не знаете, из какого она пакета! Мы стараемся избежать такой ситуации.

В описательном тексте имена пакетов выделяются жирным шрифтом (например, dplyr), а функции записываются следующим образом: mutate(). Мы стараемся явно указывать, из какого пакета происходит та или иная функция, либо ссылаясь на пакет в соседнем тексте, либо явно указывая пакет в коде, например, так: dplyr::mutate(). Это может выглядеть излишним, но мы это делаем специально.

См. страницу Основы R для информации о пакетах и функциях.

Стиль кода

В руководстве мы часто используем “новые строки”, чтобы наш код выглядел “длинным”. Мы это делаем по нескольким причинам:

• Мы можем написать пояснительные комментарии с помощью #, которые будут находиться рядом с каждой частью кода
  
• Как правило, длинный (вертикальный) код легче читать
  
• Его легче читать на узком экране (не надо пролистывать вбок)
  
• С отступами легче понять, какой аргумент относится к какой функции

В результате код, который мог бы быть записан так:

linelist %>% 
  group_by(hospital) %>%  # группируем строки по больницам
  slice_max(date, n = 1, with_ties = F) # если равенство (даты), взять первую строку

…записывается так:

linelist %>% 
  group_by(hospital) %>% # группируем строки по больницам
  slice_max(
    date,                # сохранить строку на группу с максимальным значением даты 
    n = 1,               # сохранить только одну самую верхнюю строку 
    with_ties = F)       # если равенство (даты), взять первую строку

На R-код, как правило, не влияют новые строки и отступы. При написании кода, если инициировать новую строку после запятой, то будет применена автоматическая схема отступов.

Мы также используем пробелы (например, n = 1 вместо n=1), поскольку так легче читать. Будьте дружелюбны к людям, которые читают ваш код!

Номенклатура

В этом руководстве мы как правило используем понятия “столбцы” и “строки” вместо “переменных” и “наблюдений”. Как объясняется в этом материале по “аккуратным данным”, большинство эпидемиологических статистических наборов данных структурно состоят из строк, столбцов и значений.

Переменные содержат значения, которые измеряют одинаковый базовый атрибут (например, возрастная группа, исход или дата возникновения симпмтомов). Наблюдения содержат все значения, измеренные для одной единицы (например, человека, места или лабораторного образца). Так что эти аспекты может быть сложнее определить.

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

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

Примечания

Вот несколько типов примечаний, которые вы можете встретить в руководстве:

ПРИМЕЧАНИЕ: Это примечание.
СОВЕТ: Это совет.
ВНИМАНИЕ: Это предупредительное замечание.
ВНИМАНИЕ: Это предупреждение.

1.2 Редакционные решения

Ниже мы приводим основные редакционные решения, связанные с выбором пакетов и функций. Если вы не согласны или хотите предложить новый инструмент для рассмотрения, пожалуйста, присоединяйтесь к обсуждению на нашей странице Github.

Таблица пакетов, функций и других редакционных решений

Тема	Рассматривали	Решение	Краткое обоснование
Общий подход к кодированию	tidyverse, data.table, base	tidyverse, со страницей о data.table, а также упоминаниями базовых альтернатив для читателей без интернета	tidyverseчитаемость, универсальность, чаще всего изучается
Загрузка пакетов	library(),install.packages(), require(), pacman	pacman	Сокращает и упрощает код для большинства установок/применения нескольких пакетов
Импорт и экспорт	rio, многие другие пакеты	rio	Простота для многих типов файлов
Группирование для сводной статистики	dplyr group_by(), stats aggregate()	dplyr group_by()	Соответствует фокусу на tidyverse
Поворот	tidyr (функции поворота), reshape2 (расплав/изготовление), tidyr (растягивание/сбор)	tidyr (функции поворота)	reshape2 вышел из употребления, tidyr использует функции поворота с версии v1.0.0
Чистые имена столбцов	linelist, janitor	janitor	Подчеркивается консолидация пакетов
Эпиднедели	lubridate, aweek, tsibble, zoo	lubridate в целом, другие для конкретных случаев	гибкость lubridate, последовательность, перспективы поддержки пакета
Подписи ggplot	labs(), ggtitle()/ylab()/xlab()	labs()	все подписи в одном месте, простота
Конвертация в фактор	factor(), forcats	forcats	разные функции также конвертируют в фактор в той же команде
Эпидемические кривые	incidence, ggplot2, EpiCurve	incidence2 как быстрый, ggplot2 как детальный	надежность
Конкатенация	paste(), paste0(), str_glue(), glue()	str_glue()	Более простой синтаксис, чем функции paste; внутри stringr

1.3 Основные пересмотры

Дата	Основные изменения
10 мая 2021	Выпуск версии 1.0.0
20 ноя 2022	Выпуск версии 1.0.1

НОВОСТИ В версии 1.0.1 были внесены следующие изменения:

• Обновление до версии R 4.2
  
• Вычистка данных: переход от {linelist} к {matchmaker}, удалили лишнюю строку из примера case_when()
  
• Даты: поменяли {linelist} guess_date() на {parsedate} parse_date()
• Поворот: небольшое обновление в pivot_wider() id_cols=
  
• Анализ опросов: поменяли plot_age_pyramid() на age_pyramid(), небольшое изменение кода аллювиального графика
  
• Тепловые графики: добавили ungroup() во фрагмент agg_weeks
  
• Интерактивные графики: добавили ungroup() во фрагмент, который создает agg_weeks, чтобы expand() работала как надо
  
• Временные ряды: добавили data.frame() вокруг объектов внутри всех команд trending::fit() и predict()
  
• Анализ комбинаций: поменяли case_when() на ifelse() и добавили опциональный код для подготовки данных across()
  
• Цепочки распространения: Обновление до более свежей версии {epicontacts}

1.4 Информация о сессии (R, RStudio, пакеты)

Ниже приведена информация о версиях R, RStudio и пакетов R, использованных при составлении данного Руководства.

sessioninfo::session_info()

─ Session info ───────────────────────────────────────────────────────────────
 setting  value
 version  R version 4.3.2 (2023-10-31 ucrt)
 os       Windows 11 x64 (build 22621)
 system   x86_64, mingw32
 ui       RTerm
 language (EN)
 collate  English_United States.utf8
 ctype    English_United States.utf8
 tz       Europe/Stockholm
 date     2024-06-19
 pandoc   3.1.11 @ C:/Program Files/RStudio/resources/app/bin/quarto/bin/tools/ (via rmarkdown)

─ Packages ───────────────────────────────────────────────────────────────────
 package     * version date (UTC) lib source
 cli           3.6.2   2023-12-11 [2] CRAN (R 4.3.2)
 digest        0.6.35  2024-03-11 [1] CRAN (R 4.3.3)
 evaluate      0.23    2023-11-01 [2] CRAN (R 4.3.2)
 fastmap       1.1.1   2023-02-24 [2] CRAN (R 4.3.2)
 htmltools     0.5.8   2024-03-25 [1] CRAN (R 4.3.3)
 htmlwidgets   1.6.4   2023-12-06 [2] CRAN (R 4.3.2)
 jsonlite      1.8.8   2023-12-04 [2] CRAN (R 4.3.2)
 knitr         1.45    2023-10-30 [2] CRAN (R 4.3.2)
 rlang         1.1.3   2024-01-10 [2] CRAN (R 4.3.2)
 rmarkdown     2.26    2024-03-05 [1] CRAN (R 4.3.3)
 rstudioapi    0.15.0  2023-07-07 [2] CRAN (R 4.3.2)
 sessioninfo   1.2.2   2021-12-06 [2] CRAN (R 4.3.2)
 xfun          0.43    2024-03-25 [1] CRAN (R 4.3.3)

 [1] C:/Users/ngulu864/AppData/Local/R/win-library/4.3
 [2] C:/Program Files/R/R-4.3.2/library

──────────────────────────────────────────────────────────────────────────────