Подробное руководство по созданию и публикации пакета данных R с использованием Devtools.

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

Шаг за шагом описание разработки моего пакета данных “Richmondway” на R с подсчетом нецензурной лексики Роя Кента

Когда меня пригласили выступить на конференции Posit 2023 и рассказать о рассказах с анимацией и интерактивностью, я несколько месяцев размышляла над идеальным набором данных. Казалось, что каждый интересный набор данных уже использован, и мне не хотелось основывать свою презентацию на скучных данных. И вот однажды, просматривая сериал Тед Лассо и наслаждаясь все более утонченными нецензурными выражениями Роя Кента, у меня возникла идея. Я пересмотрела сериал и подсчитала каждый раз, когда Рой использовал или жестикулировал словом “F**k”. Это стало моим набором данных! В этой статье я расскажу вам о подробных шагах, которые я предприняла, чтобы превратить этот набор данных в пакет R Data, позволяющий вам легко создавать такие пакеты самостоятельно.

Добро пожаловать в мир Richmondway, моего первого пакета данных на R, который позволяет загрузить данные и изучить подробности лексикона Роя Кента, эпизод за эпизодом, сезон за сезоном. Наконец, мы сможем ответить на вопрос, который никто не задавал: в каком сезоне Рой Кент использовал больше всего нецензурных выражений?

Зачем я создала пакет?

• Я давно хотела научиться создавать пакеты на R. И начать с простого пакета данных казалось отличной идеей.
• Вставка данных для тестирования функций необходима. Она знакомит пользователей с возможностями пакета – шаг, который понадобится мне для создания более сложных пакетов в будущем.
• Этот набор данных был слишком интересным, чтобы держать его при себе. Упаковка в пакет обеспечивает легкий доступ для всех после конференции.

Итак, будь вы любознательны в отношении создания пакета данных на R или являетесь поклонником “Теда Лассо”, заварите чай и давайте приступим!

Подробные шаги, которые я использовала для создания пакета данных на R

Шаг 0: Набор данных и название пакета

Вот как выглядит снимок моего набора данных под названием “richmondway”. Он содержит 34 строки, соответствующих каждому эпизоду, и 16 столбцов с различными значениями, описанными в пакете, который мы создадим.

• Являются ли предварительно обученные модели основы будущего молекулярного машинного обучения? Представляем беспрецедентные наборы данных и библиотеку машинного обучения Graphium.
• Декораторы Python Полное руководство
• Использование клинической научы данных для улучшения клинических результатов

Название вашего пакета – это как имя питомца – оно очень особенное. Хотя вы захотите выбрать запоминающееся название, также убедитесь, что оно простое, особенно если вы собираетесь сделать его общедоступным. Я назвала свой пакет Richmondway – это отсылка к АФК Ричмонду, футбольному клубу, за который играл Рой Кент в сериале Тед Лассо. И, кстати, оно начинается на “R”, что является счастливым совпадением. Я также хотела, чтобы название было достаточно ясным указателем на содержимое пакета.

Шаг 1: Установите инструментарий

Установите эти пакеты для R: devtools, usethis и roxygen2. Они позволяют очень легко структурировать и документировать ваш новый пакет.

install.packages(c("devtools", "usethis", "roxygen2"))

Шаг 2: Создание нового пакета в качестве проекта

Есть два способа создать пакет с использованием devtools. Devtools заботится о множестве предварительных настроек структуры пакета.

Метод 1: Прямо из консоли RStudio

Метод 2: С помощью пакета usethis

С использованием команды usethis::create_package() вы можете непосредственно создать новый пакет, указав путь, где вы хотите создать каталог пакета. В остальной части этой статьи я буду демонстрировать другие команды usethis, которые упрощают и ускоряют процесс создания пакета и документации.

usethis::create_package("путь/richmondway")

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

Шаг 3: Добавление набора данных

Я сохранил набор данных в локальной среде под именем “richmondway”. Запуск команды ниже добавляет каталог '/data' в корень вашего пакета и помещает файл ".rda" в него.

usethis::use_data(richmondway)

Шаг 4: Создание словаря данных `data.R`:

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

usethis::use_r("data")

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

#' Данные для демонстрации количества использований слова "f**k"#'#' Набор данных, содержащий количество раз, когда слово "f**k" использовалось в "Тед Лассо" Роем Кентом.#'#' @format Data frame с 34 строками и 16 столбцами.#' \describe{#' \item{Character}{Одиночное значение - Рой Кент}#' \item{Episode_order}{Порядок эпизодов от первого до последнего}#' \item{Season}{Сезон 1, 2 или 3, связанный с количеством}#' }#' @source Создано Дипшей Менгхани при просмотре шоу и подсчете количества ф**ков, использованных в предложениях и жестах#'#' @examples#' data(richmondway)"richmondway"

Разберем этот файл на его компоненты:

Описание комментариев:

#' Данные для отображения количества употребления слова f**k#'#' Набор данных, содержащий количество раз, которое слово f**k использовалось в сериале «Тед Лассо» рой Кентом.

Это короткое название и описание набора данных. Комментарии, начинающиеся с #', используются для аннотации объектов R таким образом, чтобы их мог бы распознать пакет roxygen2, который используется в R для создания документации.

Комментарий о формате:

#' @format Датафрейм с 34 строками и 16 столбцами.

Это указывает на формат данных. В данном случае набор данных – это датафрейм с 34 строками и 16 столбцами.

Описание переменных:

#' \describe{#' \item{Character}{Один элемент - Рой Кент}#' \item{Episode_order}{Порядок эпизодов с первого до последнего}#' \item{Season}{Сезон 1, 2 или 3, связанный с количеством}#' }

Эта часть предоставляет подробное описание некоторых основных переменных/столбцов в датафрейме. Блок \describe используется для перечисления и описания каждой переменной, которая представлена тегом \item с указанием имени переменной и ее описания.

Комментарий об источнике:

#' @source Создано Deepsha Menghani, смотрящим и подсчитывающим число слово f**k, используемых в предложениях и в жестах.

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

Комментарий с примерами:

#' @examples #' data(richmondway)

Это дает пример того, как пользователи могут получить доступ к набору данных и использовать его. В этом случае он просто демонстрирует, как загрузить данные в R после установки вашего пакета.

Имя данных:

"richmondway"

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

Когда пользователи устанавливают и загружают ваш пакет в R и затем вводят ?richmondway, им будет представлена эта документация в структурированном формате, чтобы им было понятно, о чем идет речь в наборе данных, его структуре и как его использовать.

Шаг 5: Обновление файла “DESCRIPTION“

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

Package: richmondwayTitle: Набор данных, содержащий количество раз, которое слово f**k использовалось в сериале «Тед Лассо» рой КентомAuthors@R: person("Deepsha", "Menghani", email = "abc@gmail.com", role = c("aut", "cre"))Description: Загружает набор данных, содержащий количество раз, которое слово f**k использовалось в сериале «Тед Лассо» рой Кентом.License: file LICENSE

Шаг 6: Создание файла «LICENSE»

Этот файл похож на резюме вашего пакета. Обратите внимание, что в моем файле DESCRIPTION я ссылался на файл с названием LICENSE. Этого файла еще нет, поэтому мы сейчас его создадим. В нем нужно указать файл, где хранится информация о лицензии. Информация о лицензии уведомляет пользователя пакета, как использовать предоставленные данные через этот пакет, то есть права. В моем случае я использовала лицензию CC0 и добавила стандартное описание в файл LICENSE с помощью следующих команд.

license_text <- 'CC0 1.0 Universal (CC0 1.0) Public Domain DedicationThe person who associated a work with this deed has dedicated the work to the public domain by waiving all of his or her rights to the work worldwide under copyright law, including all related and neighboring rights, to the extent allowed by law.You can copy, modify, distribute and perform the work, even for commercial purposes, all without asking permission.For more information, please see<http://creativecommons.org/publicdomain/zero/1.0/>'writeLines(license_text, con = "packagepath/LICENSE")

Шаг 7: Загрузите документацию

Теперь, когда все файлы были созданы и обновлены, мы загружаем документацию с помощью следующей удобной команды. Эта команда создаст документацию с использованием файла data.R, в котором мы добавили описание данных. Эта документация будет помещена во вновь созданную папку man, что означает “manual” (ручное управление).

devtools::document()

После выполнения команды документации вы можете воспользоваться командой помощи ?richmondway, и должна открыться документация пакета. Убедитесь, что документация ясна и необходимые данные из файла data.R отображаются ожидаемым образом.

Шаг 8: Проверка

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

devtools::check()

Результаты devtools::check() представляют собой ЗАМЕЧАНИЯ, ПРЕДУПРЕЖДЕНИЯ и ОШИБКИ, каждое из которых требует разной степени внимания:

ОШИБКИ: Вы должны немедленно их исправить, так как они указывают на серьезные проблемы.ПРЕДУПРЕЖДЕНИЯ: Их следует исправить для обеспечения функциональности и соответствия стандартам CRAN.ЗАМЕЧАНИЯ: Предлагают полезные советы и рекомендации, иногда требуют исправления для представления в CRAN.

Шаг 9: Установка пакета локально и тестирование

Следующая команда из devtools может использоваться для установки пакета локально. Затем используйте тот же метод, который вы использовали в примере в файле data.R, чтобы проверить доступ к данным.

devtools::install() # Установка пакета локальнодata(richmondway) # Доступ к данным через пакет

Шаг 10. Опубликуйте ваш новый пакет на GitHub

Теперь нам нужно инициализировать наш репозиторий Git и загрузить пакет на GitHub с помощью дополнительных команд usethis. Прежде чем выполнять эти команды, убедитесь, что у вас есть учетная запись GitHub и что вы настроили SSH-ключи или токены доступа (PAT) для использования с GitHub.

usethis::use_git() # Интеграция Gitusethis::use_github() # Интеграция GitHub

Что делает usethis::use_git()

• Инициализация Git: Эта функция инициализирует новый репозиторий Git в вашем проекте.
• Первый коммит: Он делает первый коммит с текущим состоянием проекта.

Что делает usethis::use_github()

• Создание репозитория на GitHub: Эта функция помогает создать новый репозиторий на GitHub и подключить ваш локальный Git репозиторий к удаленному репозиторию на GitHub.
• Аутентификация: Помогает настроить аутентификацию с GitHub. Он проверяет, авторизованы ли вы в GitHub. Если нет, то может потребоваться выполнить авторизацию.
• Отправка: Отправляет ваши локальные коммиты в удаленный репозиторий на GitHub.

Шаг 11: И, наконец, поделитесь своим пакетом с миром

Теперь вы можете поделиться ссылкой на свой пакетный репозиторий. Любой может установить ваш пакет напрямую из GitHub, используя devtools::install_github(“your_username/packagename”) и получить доступ к данным.

Например, данные из richmondway внутри моего пакета на GitHub можно получить с помощью следующей команды:

devtools::install_github("deepshamenghani/richmondway")

Вы справились!

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

Не стесняйтесь изучать этот интересный набор данных и отмечайте меня в своем анализе и визуализации. Или вы можете форкнуть репозиторий richmondway на GitHub и внести свой вклад в словарь Роя Кента. Продолжайте упаковывать!

Ресурсы

1. Репозиторий пакета Richmondway
2. Пакеты R от Хэдли Уикхэма и Дженнифер Брайан
3. Документация по Roxygen2
4. Пакет Usethis
5. Пакет Devtools

Счастливого программирования! Если хотите, найдите меня на LinkedIn.