R — отличный ресурс для управления данными, статистики, анализа и визуализации, и он становится лучше с каждым днем. Во многом это связано с активным сообществом, которое постоянно создает и строит расширения для мира R. Если вы хотите внести свой вклад в это сообщество, написание пакета может быть одним из способов. Это именно то, что мы намеревались сделать с нашим пакетом overviewR. Несмотря на то, что существует множество отличных ресурсов для изучения того, как написать пакет на R, нам было трудно найти одно всеобъемлющее руководство, которое также было бы легко доступно для начинающих. Этот учебник призван восполнить этот пробел: мы предоставим вам пошаговое руководство, дополненное новыми и полезными пакетами, которые также вдохновлены презентациями на недавней виртуальной встрече пользователей R в Европе e-Rum 2020.

В следующих разделах мы будем использовать упрощенную версию одной функции ( overview_tab) из нашего пакета overviewR в качестве минимального рабочего примера.

Обзор

  1. Почему вы должны написать пакет
  2. С чего начать
    Идея
    Название
  3. Настройте свой пакет с помощью RStudio и GitHub
  4. Наполните свой пакет жизнью
    Добавьте функции
    Напишите файл справки
    Напишите ОПИСАНИЕ
    Добавьте внутренний набор данных
    Напишите NEWS.md
    Напишите виньетку
  5. Проверьте свой пакет
    Напишите тесты
    codecov
    Проверьте, работает ли он на различных операционных системах с помощью devtools и rhub
    Сгенерировать файл cran-comments.md
    Непрерывная интеграция с Travis CI
    Проверка на хорошую практику I: Goodpractice
    Проверка на хорошую практику II: интегрировать
  6. Отправить в CRAN
  7. Дополнения
    Создайте собственную шестиугольную наклейку
    Добавьте значки
    Создайте собственное руководство
    Создайте свой веб-сайт для ваш пакет
    Напишите свой CheatSheet
  8. Дополнительная литература

Полный исходный код пакета можно найти здесь.

Почему вы должны написать пакет

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

Когда дело доходит до нашего пакета, мы хотели добавить автоматизированный способ получить обзор — отсюда и название — данных, с которыми вы работаете, и представить их в аккуратном и доступном виде. В частности, наша главная мотивация возникла из-за необходимости получить обзор условий времени и масштаба (т. е. единиц наблюдения и временного интервала, которые встречаются в данных), поскольку это повторяющийся вопрос как в академических статьях, так и в реальной жизни. мировые ситуации. Хотя есть способы полуавтоматического извлечения этой информации, нам не хватало полностью интегрированной функции для этого. Вот почему мы начали работать над overviewR.

Чтобы сделать ваш пакет легко доступным для всех, есть две основные стратегии. Вы можете либо опубликовать свой пакет на GitHub (что с точки зрения прозрачности всегда является хорошей идеей), либо отправить его в Comprehensive R Archive Network (CRAN). Оба предлагают другим возможность использовать ваш пакет, но отличаются несколькими важными аспектами. Выпуск на CRAN предлагает дополнительные тесты, которые гарантируют, что ваш пакет стабилен в нескольких операционных системах, и его легко установить с помощью функции utils::install.packages() в R. Если у вас есть пакет только на GitHub, есть также функция, которая позволяет пользователям устанавливать его напрямую — devtools::install_github из пакета devtools — но большинство пользователей скорее предпочтут фреймворк и стабильность, которые можно ожидать от пакета, находящегося на CRAN.

Мы познакомим вас с обоими вариантами и начнем с того, как сделать ваш пакет доступным на GitHub, прежде чем обсуждать, что необходимо сделать и учесть при отправке его в CRAN. Чтобы настроить пакет в RStudio, вам необходимо загрузить следующие пакеты:

library(roxygen2) # In-Line Documentation for R 
library(devtools) # Tools to Make Developing R Packages Easier library(testthat) # Unit Testing for R 
library(usethis)  # Automate Package and Project Setup

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

Когда начать

Идея

Все хорошие вещи должны с чего-то начинаться, и чаще всего это происходит, когда вы понимаете, что в мире не хватает чего-то необходимого, и вы считаете, что это принесет пользу другим. Пакеты R бывают разных форм — от целых вселенных, таких как семейство пакетов tidyverse (если вы ищете какие-то статистические данные, такие как отзывы при использовании tidyverse и дополнений к этим вселенным, tidylog — ваш лучший друг!), пакеты для конкретных статистических моделей и их проверка (icr, MNLpred или oolong) для таких пакетов, как polite, который предлагает сетевой этикет при очистке веб-страниц, snakecase, который преобразует имена в формат змеиного регистра, rwhatsapp для очистки WhatsApp или meme, пакет что позволяет создавать индивидуальные мемы. Как вы понимаете, мир — и ваша фантазия — это ваша устрица.*

Имя

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

library(available) # Check if the Title of a Package is Available, 
                   # Appropriate and Interesting 
# Check for potential names 
available::suggest("Easily extract information about your sample")

## easilyr

suggest берет строку со словами, которые могут быть описанием вашего пакета, и предлагает имя на основе этой строки. Как видите, мы не согласились с этим предложением, а вместо этого выбрали overviewR. Затем мы проверили с помощью available, доступно ли это имя и действительно ли оно на разных платформах. Поскольку наш пакет уже опубликован, он недоступен на GitHub, CRAN или Bioconductor (отсюда и «x»).

# Check whether it's available 
available::available("overviewR", browse = FALSE)
## -- overviewR ----------------------------------------------------## Name valid: ✓
## Available on CRAN: x
## Available on Bioconductor: x
## Available on GitHub: x
## Abbreviations: http://www.abbreviations.com/overview 
## Wikipedia: https://en.wikipedia.org/wiki/overview 
## Wiktionary: https://en.wiktionary.org/wiki/overview 
## Urban Dictionary: 
##    a general [summary] of a subject "the [treasurer] gave [a    
      brief] overview of the financial consequences" 
## http://overview.urbanup.com/3904264 
## Sentiment:???

Дайте волю своему творчеству и учитесь на фантастических названиях пакетов, таких как GeneTonic или charlatan.

Настройте свой пакет с помощью RStudio и GitHub

При настройке пакета возможны различные способы. Мы должны были использовать RStudio и GitHub. В RStudio уже есть шаблон, который поставляется с основными документами, необходимыми для сборки вашего пакета. Чтобы получить доступ к шаблону, просто нажмите File › New Project... › New Directory › R Package. Обратите внимание, вам нужно установить флажок Create a git, чтобы настроить локальный git.

Ура, вы запустили свой собственный пакет! Давайте посмотрим на различные файлы, которые были созданы.

  • .gitignore и .Rbuildignore содержат документы, которые следует игнорировать при сборке в git или R.
  • DESCRIPTION дает пользователю всю основную информацию о вашем пакете — об этом мы поговорим ниже.
  • man содержит все руководства по вашим функциям. Вам не нужно трогать файлы .Rd там, так как они будут сгенерированы автоматически, как только мы заполним наш пакет функциями и запустим devtools::document().
  • NAMESPACE позже будет содержать информацию об экспортированных и импортированных функциях. Этот файл не будет изменен вручную, но мы покажем вам, как это сделать автоматически. Это может показаться нелогичным в рабочем процессе, но здесь нам нужно удалить файл NAMESPACE. Мы делаем это, потому что хотим, чтобы NAMESPACE сгенерировался и был доступен с вселенной devtools. Мы сгенерируем его автоматически позже с помощью команды devtools::document().
  • R содержит все созданные вами функции. Мы обратимся к этой папке и ее файлам на следующем шаге.
  • Файл overviewR.Rproj — это обычный файл проекта R, о котором вы можете прочитать подробнее здесь.

Однако ваш пакет еще не связан с вашим GitHub. Мы сделаем это на следующем шаге:

  1. Войдите в свою учетную запись GitHub.
  2. Создайте новый репозиторий с помощью «+Новый репозиторий». Мы назвали его «overviewR» (как наш пакет). Вы можете установить его как частный или общедоступный — как вам больше нравится.
  3. Не устанавливайте флажок «Инициализировать этот репозиторий с помощью файла README».
  4. После того, как вы создали репозиторий, выполните следующие три команды в своем терминале RStudio:
git remote add origin https://github.com/YOUR_USERNAME/REPOSITORY_NAME.git 
git commit -m "initial commit" 
git push -u origin master

Если вы сейчас обновите свой репозиторий GitHub, вы увидите, что ваш пакет R идеально синхронизирован с GitHub.

GitHub теперь также спросит вас, хотите ли вы создать README — просто нажмите на него, и вы готовы к работе. Чтобы получить README в своем проекте, извлеките его из GitHub либо с помощью кнопки Pull на вкладке Git в RStudio, либо выполните следующую командную строку в терминале RStudio:

git pull

Наполните свою посылку жизнью

Мы продемонстрируем типичный рабочий процесс для создания пакета, используя один пример функции (overview_tab) из нашего пакета overviewR. На практике вы можете добавить в свой пакет столько функций, сколько захотите.

Добавить функции

Папка R содержит все ваши функции, и каждая функция сохраняется в новом файле R, где имя функции и имя файла совпадают. Как видите, шаблон поставляется с предустановленной функцией hello, которая при выполнении возвращает "Hello, world!". (Файл hello.R демонстрирует функцию и может быть позже удален.) Чтобы теперь включить и нашу функцию, мы открываем новый файл R и вставляем базовую версию нашей функции.

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

В преамбуле этого файла мы можем добавить информацию о функции. Пример показан ниже:

#' @title overview_tab 
#' 
#' @description Provides an overview table for the time and scope 
#'     conditions of a data set 
#' 
#' @param dat A data set object 
#' @param id Scope (e.g., country codes or individual IDs) 
#' @param time Time (e.g., time periods are given by years, ...) 
#' 
#' @return A data frame object that contains a summary of a sample 
#'     that can later be converted to a TeX output using 
#'     \code{overview_print} 
#' @examples 
#' data(toydata) 
#' output_table <- overview_tab(dat = toydata, id = ccode, time = year) 
#' @export 
#' @importFrom dplyr "%>%"
  • @title берет имя вашей функции
  • @description содержит краткое описание
  • @param принимает все ваши аргументы, которые есть на входе функции с кратким описанием. Наша функция имеет три аргумента (dat (набор данных), id (область действия) и time (период времени)).
  • @return предоставляет пользователю информацию о выводе вашей функции
  • @examples в конечном итоге предоставить минимальный рабочий пример для пользователя, чтобы увидеть, что ему/ей нужно включить. Вы также можете обернуть \dontrun{} свои примеры, если они не должны выполняться (например, если отсутствует дополнительное программное обеспечение или ключ API). Если это не так, не рекомендуется оборачивать это, так как это вызовет предупреждение для пользователя. Если ваш пример длится более 5 секунд, вы можете обернуть его \donttest{}.
  • @export — если это новый пакет, всегда рекомендуется экспортировать свои функции. Он автоматически добавляет эти функции в файл NAMESPACE.
  • @importFrom dplyr "%>%" предварительно определяет необходимые функции для вашей функции. Он автоматически добавляет эти функции в файл NAMESPACE.

После того, как вы включили преамбулу, теперь вы можете добавить свою функцию ниже.

Написать файл справки

Когда вы выполняете devtools::document(), R автоматически генерирует соответствующий файл справки в man, а также новый файл NAMESPACE. Если вы нажмете на него, вы увидите, что он доступен только для чтения, и все изменения должны выполняться в основном файле функции R в R/.

Теперь вы можете вызвать функцию с помощью ? overview_tab и получить прекрасную справку по пакету, которую вы знаете и по другим функциям.

Напишите ОПИСАНИЕ

DESCRIPTION предварительно создается roxygen2 и содержит всю необходимую информацию о вашем пакете. Мы проведем вас через самые важные части:

Type: Package 
Package: overviewR 
Title: Easily Extracting Information About Your Data 
Version: 0.0.2 
Authors@R: c( 
    person("Cosima", "Meyer", email = "[email protected]", 
           role = c("cre","aut")), 
    person("Dennis", "Hammerschmidt", email = "[email protected]", 
           role = "aut")) 
Description: Makes it easy to display descriptive information on a 
    data set. Getting an easy overview of a data set by displaying 
    and visualizing sample information in different tables (e.g., 
    time and scope conditions). The package also provides 
    publishable TeX code to present the sample information. 
License: GPL-3 
URL: https://github.com/cosimameyer/overviewR 
BugReports: https://github.com/cosimameyer/overviewR/issues 
Depends: 
   R (>= 3.5.0) 
Imports: 
   dplyr (>= 1.0.0) 
Suggests: 
   covr, 
   knitr, 
   rmarkdown, 
   spelling, 
   testthat 
VignetteBuilder: 
    knitr 
Encoding: UTF-8 
Language: en-US 
LazyData: true 
RoxygenNote: 7.1.0
  • Type: Package следует оставить без изменений
  • Package содержит имя вашего пакета
  • Title — это действительно краткое описание вашего пакета.
  • Version имеет номер версии (вы, скорее всего, начнете с 0.0.1, если хотите узнать больше, вот отличная справочка).
  • Authors@R содержит имена авторов и их роли. [cre] обозначает создателя, и этот человек также является сопровождающим, а [aut] является автором. Также есть возможность указать автора ([ctb]) или переводчика ([trl]). Если вам нужно больше, вот отличный обзор или вы можете просто проверить наличие дополнительных ролей, используя ? person. На этом этапе вам также необходимо указать свой адрес электронной почты. Если вы хотите отправить свой пакет в CRAN (а также в любом другом случае), убедитесь, что ваш адрес электронной почты верен и доступен!
  • Description предоставляет более подробное описание того, что делает ваш пакет. Если вы хотите сделать отступ, используйте четыре пробела.
  • License показывает другим, что они могут делать с вашим пакетом. Это важная часть и, вероятно, трудное решение. Здесь и здесь или здесь — это отличные обзоры различных лицензий и начальное руководство о том, как выбрать лучшую для вас.
  • URL указывает, где в настоящее время размещен пакет
  • BugReports показать, куда пользователи должны направлять свои отчеты (если они связаны с GitHub, это автоматически направит пользователя в раздел проблем)
  • Depends показывает версию R, с которой работает ваш пакет (всегда нужно указывать номер версии!)
  • Imports показывает пакеты, которые необходимы для запуска вашего пакета (здесь всегда нужно указывать номер версии, чтобы можно было избежать возможных конфликтов с предыдущими версиями!)
  • Suggests перечисляет все пакеты, которые вы предлагаете, но которые не обязательно необходимы для функциональности вашего пакета.
  • …
  • LazyData: true обеспечивает автоматическую загрузку внутренних наборов данных при загрузке пакета.

Добавить внутренний набор данных

Вдохновленные этим превосходным обзором, мы решили включить внутренний набор данных, чтобы легко протестировать функциональность нашего пакета. Как это сделать, очень просто: у вас есть предварительно сгенерированный набор данных (или вы можете создать его самостоятельно) и сохранить его в data/.

Как вы знаете, каждый хороший набор данных, даже если это всего лишь игрушечный набор данных, имеет описание. Для вашего пакета просто настройте файл .R с именем вашего набора данных (в нашем случае toydata.R) и сохраните его в папке R. Файл должен содержать следующую информацию:

  • Начинается с заголовка набора данных
  • Затем у вас есть несколько строк для краткого краткого описания
  • @docType определяет тип документа (data)
  • @usage описывает здесь, как следует загружать набор данных.
  • @format дает информацию о формате объекта
  • Затем \describe{} позволяет вам дать пользователю конкретное описание ваших переменных, включенных в набор данных.
  • @references необходим, если вы не используете искусственно сгенерированные данные для указания источника
  • @keywords позволяет указать ключевые слова (здесь мы использовали dataset)
  • @examples наконец дает вам возможность продемонстрировать свои данные

Следующий вывод описывает, что мы включили в наш файл toydata.R (вы можете просто скопировать и вставить код и настроить его под свои нужды).

#' Cross-sectional data for countries 
#' 
#' Small, artificially generated toy data set that comes in a 
#' cross-sectional format where the unit of analysis is either 
#' country-year or country-year-month. It provides artificial 
#' information for five countries (Angola, Benin, France, Rwanda, 
#' and the UK) for a time span from 1990 to 1999 to illustrate the #' use of the package. 
#' 
#' @docType data 
#' 
#' @usage data(toydata) 
#' 
#' @format An object of class \code{"data.frame"} 
#' \describe{ 
#'  \item{ccode}{ISO3 country code (as character) for the countries #'     in the sample (Angola, Benin, France, Rwanda, and UK)} 
#'  \item{year}{A value between 1990 and 1999} 
#'  \item{month}{An abbreviation (MMM) for month (character)} 
#'  \item{gpd}{A fake value for GDP (randomly generated)} 
#'  \item{population}{A fake value for population (randomly 
#'      generated)} 
#' } 
#' @references This data set was artificially created for the 
#'     overviewR package. 
#' @keywords datasets 
#' @examples 
#' 
#' data(toydata) 
#' head(toydata) 
#' "toydata"

Пишите в NEWS.md

Вы можете автоматически создать файл NEWS.md, используя R с usethis::use_news_md. Наш новостной файл выглядит так:

# overviewR 0.0.2 
- Bug fixes in overview_tab that affected overview_crosstab 
--- 
# overviewR 0.0.1

Самая новая версия всегда идет первой, а версии разделяются --- разделителями. Чтобы проинформировать пользователей, используйте маркеры для описания изменений, внесенных в новую версию. В качестве плюса, если вы планируете создать веб-сайт с pkgdown (позже мы объясним, как вы можете это сделать), раздел новостей автоматически интегрирует этот файл.

Напишите виньетку

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

Здесь usethis предлагает отличный сервис и позволяет автоматически создать свою первую виньетку с помощью команды usethis::use_vignette("NAME-OF-VIGNETTE"). Эта команда делает три разные вещи:

  1. Он генерирует вашу папку vignettes/,
  2. Добавляет основные характеристики в ОПИСАНИЕ и
  3. Он также хранит черновик виньетки «NAME-OF-VIGNETTE.Rmd» в папке vignettes, к которой теперь можно получить доступ и редактировать. Этот черновик виньетки уже содержит хороший шаблон, который предлагает вам всю информацию и предварительные требования, необходимые для создания красивой виньетки. Вы можете изменить это по мере необходимости, чтобы показать, что делает ваш пакет и как его можно использовать лучше всего.

Проверьте свой пакет

Следующие шаги либо рекомендуются, либо требуются при отправке пакета в CRAN. Однако мы рекомендуем соблюдать их все. Мы суммировали то, что, по нашему мнению, будет полезно при тестировании вашего пакета.

Пишите тесты

Написание тестов казалось самой сложной частью сборки пакета. По сути, вы должны придумать тесты для каждой части вашей функции, чтобы убедиться, что все — не только конечный результат вашей функции — работает гладко. Хороший совет, который мы читали несколько раз, заключается в том, что всякий раз, когда вы сталкиваетесь с ошибкой, напишите для нее тест, чтобы проверить ее появление в будущем. Для настройки тестовой среды мы использовали комбинацию отличного пакета testthat и covr, что позволяет визуально увидеть, насколько хорошо ваше тестовое покрытие и какие части пакета еще нужно протестировать.

  1. Создайте тестовую среду usethis::use_testthat. Это создает папку tests/ с другой папкой с именем testthat/, которая позже содержит ваши тесты, а также файл R testthat.R. Мы добавим тесты только в папку tests/testthat/ и не будем трогать файл R.
  2. Добавьте тест(ы) в виде .R файлов. Имя файла не имеет значения, просто выберите то, что считаете разумным.
  3. Запустите тесты с помощью devtools::test(). Чтобы получить оценку покрытия тестами, вы можете использовать devtools::test_coverage().

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

context("check-output")  # Our file is called "test-check_output.R" library(testthat)        # load testthat package 
library(overviewR)       # load our package  
# Test whether the output is a data frame 
test_that("overview_tab() returns a data frame", {   
    output_table <- overview_tab(dat = toydata, 
        id = ccode, time = year)   
    expect_is(output_table, "data.frame") 
})  
# In reality, our function is more complex and aggregates your input 
# if you have duplicates in your id-time units -- this is why the 
# following two tests were essential for us 
## Test whether the output contains the right number of rows test_that("overview_tab() returns a df with correct no of rows", { 
     output_table <- overview_tab(dat = toydata, id = ccode, 
          time = year)   
     expect_equal(nrow(output_table), length(unique(toydata$ccode))) }) 
## Test whether the function works on a df without duplicates in id-## time 
test_that("overview_tab() works on a df in correct format", {
     df_com <- data.frame(               
     # Countries               
       ccode  = c(rep("RWA", 4),
                  rep("AGO", 8),
                  rep("BEN", 2),
                  rep("GBR", 5),                 
                  rep("FRA", 3)
               ),
               # Time frame
               year =
                 c(
                   seq(1990, 1995),
                   seq(1990, 1992),
                   seq(1995, 1999),
                   seq(1991, 1999, by = 2),
                   seq(1993, 1999, by = 3)
                 )
             )
             output_table <-
               overview_tab(dat = df_com, id = ccode, time = year)
             expect_equal(nrow(output_table), 5)
           })

кодек

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

Чтобы связать codecov и GitHub, просто выполните следующие действия:

  1. Войдите на codecov.io под своей учетной записью GitHub.
  2. Предоставьте codecov доступ к вашему репозиторию с вашим пакетом
  3. Откроется страница, откуда вы можете скопировать свой токен.
  4. Теперь вернитесь в консоль RStudio и выполните:
library(covr) # Test Coverage for Packages 
covr::codecov(token = "INCLUDE_YOUR_CODECOV_TOKEN_HERE")

5. Это свяжет ваш репозиторий GitHub с codecov и сгенерирует значок.

Проверьте, работает ли он на разных операционных системах с помощью devtools и rhub.

Чтобы проверить, работает ли наш пакет в различных операционных системах, мы использовали комбинацию пакетов rhub и devtools. Эти пакеты также помогут вам интегрировать непрерывную интеграцию с Travis CI, которая автоматически проверяет ваш пакет в Ubuntu (подробнее об этом ниже).

Мы последовательно использовали следующие строки кода для проверки нашего пакета:

# The following function runs a local R CMD check 
devtools::check()

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

# Check for CRAN specific requirements 
rhub::check_for_cran()

Эта команда проверяет стандартные требования, указанные CRAN, и, если они сохранены в объекте, вы можете создать свой файл cran-comments.md на основе этой команды. Подробнее об этом мы поговорим в следующем разделе. Если вы используете rhub в первый раз, вам необходимо подтвердить свой адрес электронной почты с помощью rhub::validate_email(). Затем вы можете выполнить команду. После запуска команды вы получите три разных сообщения электронной почты с подробными отзывами о том, насколько хорошо тесты выполнялись в трех разных операционных системах. На момент написания статьи эта функция проверяла наш пакет на Windows Server 2008 R2 SP1, R-devel, 32/64 бит; Ubuntu Linux 16.04 LTS, R-выпуск, GCC; и Fedora Linux, R-devel, clang, gfortran. По нашему опыту, проверки в Windows были очень быстрыми, но нам пришлось немного подождать, пока мы не получили результаты для Ubuntu и Fedora.

Затем мы также проверили пакет в разрабатываемой версии R, как было предложено, с помощью следующей функции:

# Check for win-builder 
devtools::check_win_devel()

Сгенерировать файл cran-comments.md

Если вы планируете отправить свой пакет в CRAN, вам следует сохранить результаты теста в файле cran-comments.md. rhub и usethis позволяют создать этот файл почти автоматически, используя следующие строки кода:

# Check for CRAN specific requirements using rhub and 
# save it in the results objects 
results <- rhub::check_for_cran()  
# Get the summary of your results 
results$cran_summary()

Мы получили следующий вывод при выполнении команды results$cran_summary().

For a CRAN submission we recommend that you fix all NOTEs, 
WARNINGs and ERRORs. 
## Test environments 
- R-hub windows-x86_64-devel (r-devel) 
- R-hub ubuntu-gcc-release (r-release) 
- R-hub fedora-clang-devel (r-devel)  
## R CMD check results 
> On windows-x86_64-devel (r-devel), ubuntu-gcc-release (r-release), fedora-clang-devel (r-devel)   
checking CRAN incoming feasibility ... NOTE      
New submission   
Maintainer: 'Cosima Meyer <[email protected]>'  
0 errors ✓ | 0 warnings ✓ | 1 note x

Ваш пакет не должен вызывать ошибок или предупреждений при отправке в CRAN. Даже заметки должны быть хорошо объяснены. В нашем случае мы получаем одну заметку о том, что это новая подача. Это примечание появляется каждый раз, когда вы отправляете новый пакет, и может быть кратко объяснено при отправке вашего пакета в CRAN в файле cran-comments.md.

Затем мы сгенерировали наш файл cran-comments.md с помощью следующей команды и скопировали этот вывод с небольшими изменениями.

# Generate your cran-comments.md, then you copy-paste the output 
# from the function above 
usethis::use_cran_comments()

Непрерывная интеграция с Travis CI

Непрерывная интеграция (CI) невероятно полезна для обеспечения бесперебойной работы вашего пакета каждый раз, когда вы обновляете даже небольшие части. С помощью команды usethis::use_travis() вы можете легко связать Travis CI с вашим репозиторием GitHub. Затем Travis CI проверяет ваш пакет после каждой отправки в ваш репозиторий в Ubuntu. Для более подробного объяснения CI потребуется отдельный пост в блоге или отдельная книга. К счастью, Юлия Силге написала отличный обзор, который можно найти здесь. По сути, CI проверяет после каждой фиксации и отправки в ваш репозиторий на GitHub, что весь код/пакет работает, и отправляет вам электронное письмо, если возникают какие-либо ошибки.

Проверка хорошей практики I: хорошая практика

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

library(goodpractice) 
goodpractice::gp()

В качестве общего совета по улучшению стиля вашего кода пакет styler предоставляет простое решение, форматируя весь исходный код в соответствии со стилем tidyverse (аналогично встроенной комбинации горячих клавиш RStudio с Cmd + Shift + A (Mac) или Ctrl + Shift + A (Windows)).

Хотя все эти пакеты ссылаются на руководство по стилю tidyverse, вы, как правило, вольны выбирать, какой стиль (программирования) вам больше нравится.

Проверка хорошей практики II: интегрировать

Пакет, который был представлен на e-Rum 2020 и все еще находится в экспериментальном цикле, но невероятно полезен, — это пакет inteRgrate. Основная идея этого пакета заключается в том, что он тестируется более строго, чем другие пакеты с четкими стандартами. Таким образом, он направлен на то, чтобы вы были в безопасности при отправке вашего пакета в CRAN. Хорошей отправной точкой является этот список команд, который указан в разделе «Функции», где мы особо выделяем следующие функции:

  • check_pkg() устанавливает зависимости пакета, собирает и устанавливает пакет перед запуском проверки пакета (по умолчанию эта проверка довольно строгая, и любое примечание или предупреждение по умолчанию вызывает ошибку)
  • check_lintr() запускает lintr пакет, файл README и виньетку. lintrпроверяет, соответствует ли ваш код определенным стандартам и избегаете ли вы синтаксических ошибок и семантических проблем.
  • check_tidy_description() следит за чистотой вашего файла DESCRIPTION. Если нет, вы можете использовать usethis::use_tidy_description(), чтобы следовать соглашениям о форматировании tidyverse.
  • check_r_filenames() проверяет, чтобы все расширения файлов были .R и все имена были в нижнем регистре.
  • check_gitignore() проверяет, содержит ли .gitignore стандартные файлы.
  • check_version() гарантирует, что вы обновите версию пакета (может быть, лучше запустить в качестве последнего шага)

Отправить в CRAN

Отправка пакета в CRAN требует значительно больше усилий, чем его размещение на GitHub. Однако это заставляет вас тестировать ваш пакет в различных операционных системах и гарантирует его стабильность во всех этих системах. В итоге ваш пакет станет более удобным и доступным для большей части пользователей. Пройдя весь процесс, мы считаем, что это стоит затраченных усилий — только по этим простым причинам. При тестировании нашего пакета для CRAN мы в основном следовали этому сообщению в блоге и собрали для вас основные шаги ниже, а также добавили то, что, по нашему мнению, также полезно для публикации в CRAN. Столбец Необходимо основан на том, что запрашивается при запуске devtools::release(). Рекомендуется включает дополнительные аккуратные проверки, которые мы сочли полезными.

CRAN также предлагает подробную политику отправки пакетов, а также контрольный список при отправке вашего пакета. Мы определенно рекомендуем проверить их в дополнение к нашему списку выше.

Как уже упоминалось выше, крайне важно, чтобы ваш пакет не вызывал ошибок или предупреждений при отправке в CRAN. Даже заметки должны быть хорошо объяснены. Если вы отправляете новый пакет, вы мало что можете с этим поделать, и он всегда будет создавать заметку.

Функция devtools::release() позволяет легко отправить ваш пакет в CRAN — она работает как шарм. Когда вы почувствуете, что готовы, обязательно отправьте свои изменения на GitHub, а затем просто введите команду в консоли. Он запускает пару вопросов да-нет перед отправкой. Следующие вопросы заданы в функции devtools::release() на момент написания этого поста.

Проверяли ли вы орфографические ошибки (с spell_check())?

Вы запускали R CMD check локально?

Были ли проверки devtool успешными?

Вы проверили на R-hub (с check_rhub())?

Вы проверили на win-builder (с check_win_devel())?

Вы обновили файл NEWS.md?

Вы обновили DESCRIPTION?

Вы обновили cran-comments.md?

Источник: https://github.com/r-lib/devtools/blob/master/R/release.R

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

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

Как только CRAN свяжется с вами, они сообщат вам о потенциальных проблемах, которые вы должны решить, прежде чем повторно отправлять свой пакет — или вам повезет, и ваш пакет будет принят немедленно.

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

Общие вещи, которые мы узнали (и которые другие могут найти полезными) при прохождении процесса подачи CRAN:

  1. Не изменяйте (сохраняйте или удаляйте) выходные данные в домашнем файловом пространстве пользователя. Используйте tempdir() и/или tempfile()вместо этого при запуске примеров/виньеток/тестов.
  2. Убедитесь, что пользователь может указать каталог и имя файла при сохранении выходных данных. Просто добавьте аргумент файла/пути к своим функциям.
  3. Пишите имена пакетов, программ и API в одинарных кавычках в файле DESCRIPTION. Если вы используете, например, LaTeX в своем DESCRIPTION, заключите его в одинарные кавычки. Эта проблема, по-видимому, не обнаружена goodpractice::gp() или одной из функций inteRgrate.

После того, как ваш пакет был принят CRAN, рекомендуется подождать еще 48 часов, прежде чем праздновать, потому что CRAN все равно проведет некоторые проверки биографических данных. После этого перейдите в свой репозиторий GitHub, нажмите Создать новый выпуск, введите номер версии вашего пакета (vX.X.X) и скопируйте и вставьте примечания к выпуску из файла NEWS в описание выпуска.

При отправке вашего пакета в CRAN с помощью функции devtools::release() был создан файл CRAN-RELEASE, чтобы напомнить вам пометить свой выпуск на GitHub. Теперь этот файл можно безопасно удалить.

Дополнения

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

Создайте свою собственную шестиугольную наклейку

Наклейки Hex (agon) — это маленькие значки в форме шестиугольника, которые есть на большом количестве упаковок и которые, похоже, нравятся людям. Так почему бы не придумать собственную наклейку для своей собственной упаковки? Пакет hexSticker позволяет невероятно легко настроить и создать красивую наклейку. Чтобы получить наклейку для своей посылки, достаточно добавить в функцию hexSticker::sticker() следующие аргументы: package (название вашей посылки), subplot (изображение — мы сами нарисовали нашу лампу, сохранили в формате .png и включили в нашей наклейке без проблем) и h_fill (если хотите изменить цвет фона). Затем вы можете настроить наклейку, определив положение текста, подсюжет, размер шрифта или даже добавив прожектор, как это сделали мы. Это работает практически с любой комбинацией текста и изображения, в том числе с логотипом Methods Bites.

Вот код для нашей наклейки с обзором R:

library(hexSticker) # Create Hexagon Sticker in R 
library(showtext)   # Using Fonts More Easily in R Graphs  
## Loading Google fonts (http://www.google.com/fonts) font_add_google("Inconsolata", "incon")  
sticker(
   # Subplot (image)
   subplot = "logo-image.png",       # Image name
   s_y = 1,                          # Position of the sub plot (y)
   s_x = 1.05,                       # Position of the sub plot (x)     
   s_width = 1.15,                   # Width of the sub plot   
   s_height=0.01,                    # Height of the sub plot   
   # Font
   package = "overviewR",            # Package name (will be printed
                                     # on the sticker)
   p_size = 6,                       # Font size of the text
   p_y = 0.8,                        # Position of the font (y)
   p_x=0.75,                         # Position of the font (x)
   p_family = "incon",               # Defines font
   # Spotlight
   spotlight = TRUE,                 # Enables spotlight
   l_y=0.8,                          # Position of spotlight (y)
   l_x=0.7,                          # Position of spotlight (x)
   # Sticker colors
   h_fill = "#5d8aa6",               # Color for background
   h_color = "#2A5773",              # Color for border
   # Resolution
   dpi=1200,                         # Sets DPI
   # Save
   filename="logo.png"               # Sets file name and location
                                     # where to store the sticker )

Такие рисунки, как ваш логотип, обычно хранятся в man/figures/.

Добавить значки

Значки в вашем репозитории GitHub немного похожи на наклейки, но они также служат информативным целям. Мы включили пять разных значков в наш README в нашем репозитории GitHub: статус Travis CI, статус codecov, а также статус репо. Затем мы также добавили значок, сигнализирующий о том, что пакет готов к использованию, и еще один, сообщающий пользователю, что пакет был создан с помощью R (… и любовь!).

Если вы хотите узнать больше о доступных значках для вашего пакета, здесь и здесь — хорошие обзоры. Вы также можете использовать пакет badgecreatr для проверки значков и включения их.

Создайте собственное руководство

Если вы хотите создать собственное руководство в формате PDF для своего пакета, devtools::build_manual сделает это за вас.

Вот предварительный просмотр нашего руководства

Создайте свой веб-сайт для вашего пакета

И наконец, чтобы рекламировать свой пакет и предоставить более подробное представление о том, как работает ваш пакет, вы можете создать для него отдельный веб-сайт! С пакетом pkgdown это так же просто, как написать одну строку кода — буквально! Все, что вам нужно сделать, это установить и загрузить pkgdown, а затем — при условии, что вы выполнили все описанные выше шаги и у вас есть R-пакетная структура в вашем репозитории GitHub — запустить pkgdown::build_site(). Это автоматически преобразует ваш пакет в веб-сайт, который следует структуре вашего пакета с целевой страницей на основе файла README, частью начала работы вашей виньетки, а также разделами для ссылок на функции на основе содержимого вашей папки man/, и специальная страница для вашего NEWS.md. Он даже включает боковую панель со ссылками на репозиторий GitHub, имя(а) автора(ов) и, конечно же, все ваши значки. Удивительно, правда?

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

По умолчанию ваш веб-сайт размещен на страницах GitHub со следующим URL-адресом: https://GITHUB_USERNAME.github.io/PACKAGENAME. Чтобы гарантировать, что каждый раз, когда вы обновляете свой пакет, веб-сайт также обновляется, вы можете изменить файл .travis.yml в корне вашего пакета и добавить в него следующие части:

after_success:
 - Rscript -e 'pkgdown::build_site()'
deploy:
 provider:
 pages skip-cleanup: true
 github-token: $GITHUB_PAT
 keep-history: true
 local-dir: docs
 on:
   branch: master

Вот предварительный просмотр нашего веб-сайта pkgdown

Напишите свой CheatSheet

По мере роста вашего пакета CheatSheet может помочь пользователям отслеживать, насколько мощным является ваш пакет. RStudio предлагает шаблоны (в Keynote и PowerPoint), которые удобны для пользователя и легко настраиваются. Вот пример нашей CheatSheet для вдохновения.

Дальнейшие чтения

Ссылки на пакеты

  • Аллер, Джей Джей, Ихуи Се, Джонатан Макферсон, Хавьер Лураски, Кевин Уши, Арон Аткинс, Хэдли Уикхэм, Джо Ченг, Уинстон Чанг и Ричард Ианнон (2020). rmarkdown: динамические документы для пакета R. R версии 2.3. URL-адрес https://rmarkdown.rstudio.com.
  • Чан, Чунг-хон (2020). oolong: Создание проверочных тестов для автоматизированного анализа контента. Пакет R версии 0.3.4. https://CRAN.R-project.org/package=oolong
  • Чемберлен, Скотт и Кайл Войтович (2020). шарлатан: создавайте поддельные данные. Пакет R версии 0.4.0. https://CRAN.R-project.org/package=charlatan
  • Чарди, Габор и Ханна Фрик (2018). рекомендуемая практика: рекомендации по сборке пакетов R. Пакет R версии 1.0.2. https://CRAN.R-project.org/package=goodpractice
  • Чарди, Габор и Маэль Салмон (2019). rhub: подключиться к R-hub. Пакет R версии 1.1.1. https://CRAN.R-project.org/package=rhub
  • Элберс, Бенджамин (2020). tidylog: Ведение журнала для функций dplyr и tidyr. Пакет R версии 1.0.1. https://CRAN.R-project.org/package=tidylog
  • Ганц, Карл, Габор Чарди, Джим Хестер, Молли Льюис и Рэйчел Татман (2019). доступный: проверьте, является ли название пакета доступным, подходящим и интересным. Пакет R версии 1.0.4. https://CRAN.R-project.org/package=available
  • Гроссер, Мальте (2019). змея: конвертировать строки в любой регистр. Пакет R версии 0.11.0. https://CRAN.R-project.org/package=snakecase
  • Грубер, Йоханнес (2020). WhatsApp. Пакет R для работы с данными WhatsApp. Пакет R версии 0.2.2, ‹URL: https://github.com/JBGruber/rwhatsapp›.
  • Хестер, Джим (2020). covr: тестовое покрытие для пакетов. Пакет R версии 3.5.0. https://CRAN.R-project.org/package=covr
  • Хогерворст, Роэл М. (2019). badgecreatr: создайте значки для Travis, Repostatus, Codecov.io и т. д. в Github Readme. Пакет R версии 0.2.0. https://CRAN.R-project.org/package=badgecreatr
  • Прыгающие реки (2020). интегрировать: независимые стили кодирования пакетов. Версия пакета R 1.0.1.9006.
  • Марини, Федерико (2020). GeneTonic: наслаждайтесь анализом и интеграцией результатов анализа дифференциальной экспрессии и анализа функционального обогащения. Пакет R версии 1.0.1, https://github.com/federicomarini/GeneTonic.
  • Мейер, Козима и Деннис Хаммершмидт (2020). обзорR: Простое извлечение информации о ваших данных. Пакет R версии 0.0.4. https://CRAN.R-project.org/package=overviewR
  • Мюллер, Кирилл и Лоренц Вальтерт (2020). styler: неинвазивная красивая печать кода R. Пакет R версии 1.3.2. https://CRAN.R-project.org/package=styler
  • Нойманн, Мануэль (2020). MNLpred — смоделированные прогнозируемые вероятности для полиномиальных логит-моделей (версия 0.0.2) URL https://CRAN.R-project.org/package=MNLpred.
  • Переполкин, Дмитрий (2019). вежливо: будьте вежливы в Интернете. Пакет R версии 0.1.1. https://CRAN.R-project.org/package=вежливый
  • Qiu, Yixuan и авторы/соавторы прилагаемого программного обеспечения. Подробности смотрите в файле AUTHORS. (2020). showtext: Более простое использование шрифтов в R Graphs. Пакет R версии 0.8–1. https://CRAN.R-project.org/package=showtext
  • Основная команда R (2020). R: Язык и среда для статистических вычислений. R Foundation for Statistical Computing, Вена, Австрия. URL https://www.R-project.org/.
  • Штаудт, Александр и Пьер Л'Экюйе (2020). icr: Вычислите альфу Криппендорфа. Пакет R версии 0.6.2. https://CRAN.R-project.org/package=icr
  • Уикхэм, Хэдли (2011). testthat: начните с тестирования. Журнал R, том. 3, нет. 1, стр. 5–10
  • Уикхэм, Хэдли и Дженнифер Брайан (2020). usethis: автоматизация установки пакетов и проектов. Пакет R версии 1.6.1. https://CRAN.R-project.org/package=usethis
  • Уикхэм, Хэдли, Питер Даненберг, Габор Чарди и Мануэль Югстер (2020). roxygen2: встроенная документация для пакета R. R версии 7.1.0. https://CRAN.R-project.org/package=roxygen2
  • Уикхэм, Хэдли и Джей Хессельберт (2020). pkgdown: Создание статической HTML-документации для пакета. Пакет R версии 1.5.1. https://CRAN.R-project.org/package=pkgdown
  • Уикхэм, Хэдли, Джим Хестер и Уинстон Чанг (2020). devtools: инструменты для упрощения разработки пакетов R. Пакет R версии 2.3.0. https://CRAN.R-project.org/package=devtools
  • Ю, Гуанчуан (2019). мем: Создать мем. Пакет R версии 0.2.2. https://CRAN.R-project.org/package=meme
  • Ю, Гуанчуан (2020). hexSticker: Создайте шестиугольную наклейку в пакете R. R версии 0.4.7. https://CRAN.R-project.org/package=hexSticker

Об авторах

Козима Мейер — докторант и преподаватель Университета Мангейма и один из организаторов Лаборатории социальных наук МЗЭС. Мотивированная продолжающимся повторением конфликтов в мире, ее исследовательский интерес к изучению конфликтов все больше сосредоточивался на стабильности после гражданской войны. В своей диссертации она анализирует выживание лидерства, в частности, в постконфликтных ситуациях. Используя широкий спектр количественных методов, она дополнительно исследует вопросы конфликтных выборов, представительства женщин, а также авторитарного сотрудничества.

Деннис Хаммершмидт — докторант и преподаватель Университета Мангейма. Он работает на пересечении количественных методов и международных отношений, чтобы исследовать основную структуру государственных отношений в международной системе. Используя информацию из политических речей и сетей сотрудничества, в его диссертации анализируется взаимодействие государств в Организации Объединенных Наций и оцениваются структуры выравнивания государств на международной арене.

* На момент написания этого поста более 16 000 пакетов на CRAN и около 85 000 пакетов на GitHub. Это может быть ошеломляющим, особенно при попытке найти пакет для решения конкретной проблемы или при попытке узнать, что делают другие. Есть несколько действительно полезных и проницательных аккаунтов в Твиттере или сообщений в блогах, которые предоставляют отличный обзор горячих тем и восходящих звезд в мире пакетов R.

Первоначально опубликовано на https://www.mzes.uni-mannheim.de 16 июля 2020 г.