Прямая история о том, что включить в полный пакет.

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

Использовать синтаксис roxygen2

Roxygen2 — популярный пакет в R для документирования функций с использованием простого синтаксиса, похожего на комментарии. Кто-то, как и вы, собрал бы его вместе и проверил, используя эти методы. roxygen2 позволяет вам документировать ваши функции в самом коде R, что упрощает поддержание документации в актуальном состоянии. Следуйте синтаксису и соглашениям roxygen2, чтобы документировать свои функции, аргументы, возвращаемые значения и примеры.

Документация по функциям: используйте #', чтобы начать блок комментариев roxygen2 для документирования функции. Вот пример:

#' Calculate the mean of a vector
#'
#' This function calculates the mean of a numeric vector.
#'
#' @param x A numeric vector
#' @return The mean of the input vector
#' @examples
#' my_vector <- c(1, 2, 3, 4, 5)
#' my_mean <- my_function(my_vector)
#' @export
my_function <- function(x) {
  mean(x)
}

В этом примере @docType используется для указания типа документации (в данном случае пакета), @name используется для указания имени пакета, @title используется для указания названия пакета, а @description используется для предоставления более длинного описание пакета. @seealso используется для указания любых связанных функций или пакетов. @importFrom используется для указания любых функций, импортированных из других пакетов, а @export используется для указания функций, которые следует экспортировать из пакета.

Документирование параметров: Используйте @param для документирования параметров функции, включая их имя, тип и описание. Вот пример:

#' Calculate the sum of two numbers
#'
#' This function calculates the sum of two numbers.
#'
#' @param a A numeric value
#' @param b A numeric value
#' @return The sum of \code{a} and \code{b}
#'
my_sum <- function(a, b) {
  a + b
}

В этом примере @param используется для документирования параметров a и b, включая их тип данных и описание.

Документирование возвращаемого значения: используйте @return для документирования возвращаемого значения функции. Вот пример:

#' Calculate the factorial of a number
#'
#' This function calculates the factorial of a non-negative integer.
#'
#' @param n A non-negative integer
#' @return The factorial of \code{n}
#' @examples
#' my_factorial <- factorial(5)
#' @export
factorial <- function(n) {
  if (n <= 1) {
    return(1)
  } else {
    return(n * factorial(n-1))
  }
}

В этом примере @return используется для документирования возвращаемого значения функции factorial.

Предоставить всеобъемлющую документацию

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

Вот пример:

#' Calculate the area of a rectangle
#'
#' This function calculates the area of a rectangle given its length and width.
#'
#' @param length Length of the rectangle. Default is 1.
#' @param width Width of the rectangle. Default is 1.
#' @return The area of the rectangle
#'
#' @examples
#' # Calculate the area of a rectangle with length 5 and width 3
#' my_area <- calculate_area(5, 3)
#'
#' # Calculate the area of a square with length 4 (length and width are the same)
#' my_square_area <- calculate_area(4)
#'
#' @export
calculate_area <- function(length = 1, width = 1) {
  length * width
}

В этом примере тег @param используется для документирования параметров функции length и width, а их значения по умолчанию указываются с использованием знака равенства (=), за которым следует значение по умолчанию. Затем значения по умолчанию используются в определении функции.

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

Используйте правильное форматирование

Используйте правильное форматирование в документации, чтобы ее было легко читать и понимать. Используйте заголовки, списки и блоки кода для эффективной организации документации. Следуйте рекомендуемым правилам форматирования, таким как использование Markdown или LaTeX, для согласованности и удобочитаемости.

Форматирование LaTeX можно использовать для создания форматированного текста, уравнений и других математических символов. Вот пример использования форматирования LaTeX в документации пакета R:

#' Title of the Function
#'
#' Description of the function.
#'
#' \eqn{y = mx + b}{}
#' 
#' \deqn{f(x) = \int_0^x g(t) \, dt}{}
#'
#' @param x Input parameter
#' @return Output value
#' @seealso \code{\link{other_function}}
#'
#' @examples
#' # Example usage of the function
#' my_function(3)
#'
#' @export
my_function <- function(x) {
  # Function code
}

Форматирование LaTeX используется в приведенной выше документации следующим образом:

  1. Встроенное уравнение: \eqn{y = mx + b}{} — создает встроенное уравнение с форматированием LaTeX. Уравнение y = mx + b будет отображаться вместе с остальным текстом.
  2. Уравнение отображения: \deqn{f(x) = \int_0^x g(t) \, dt}{} — создает уравнение отображения с форматированием LaTeX. Уравнение f(x) = \int_0^x g(t) \, dt будет отображаться как центрированное уравнение с собственной линией.

Убедитесь, что все специальные символы правильно экранированы с помощью обратной косой черты (\). Кроме того, если вы часто используете такое форматирование, обязательно ознакомьтесь с политиками CRAN в отношении использования LaTeX, поскольку могут применяться некоторые общие рекомендации.

Включить виньетку

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

Вот пример резюме виньетки, которую вы можете включить в документацию по пакету R:

Название: «Введение в PackageName: полное руководство по PackageNameдля анализа данных»

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

Ключевые разделы виньетки:

  1. Введение в PackageName: обзор пакета и его функций.
  2. Установка и загрузка: пошаговые инструкции по установке и загрузке PackageName.
  3. Основные функции и их функциональность: Подробное описание основных функций в PackageName и способы их использования.
  4. Примеры анализа данных с PackageName: Практические примеры выполнения задач анализа данных с помощью PackageName.
  5. Советы и рекомендации: Практические советы и рекомендации по эффективному использованию PackageName.
  6. Дополнительные ресурсы: ссылки на дополнительные ресурсы для дальнейшего обучения.
  7. Заключение: Резюме и заключительные замечания.

Зависимости документа

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

Общие типы зависимостей для пакетов R включают в себя:

  1. Пакеты CRAN (Comprehensive R Archive Network): это пакеты, доступные в официальном репозитории CRAN, и их можно установить с помощью функции install.packages(). Например, такие пакеты, как dplyr, ggplot2 и tidyr, обычно используются в качестве зависимостей во многих пакетах R.
  2. Пакеты Bioconductor: это специализированные пакеты для биоинформатики и вычислительной биологии, которые доступны в репозитории Bioconductor. Их можно установить с помощью пакета BiocManager. Например, такие пакеты, как DESeq2, limma и BioconductorAnnotationHub, обычно используются в качестве зависимостей в пакетах R, связанных с биоинформатикой.
  3. Пакеты GitHub: это пакеты, размещенные на GitHub, популярной платформе для совместного использования кода и контроля версий. Их можно установить с помощью пакетов remotes или devtools. Например, такие пакеты, как tidyverse/ggplot2, rstudio/shiny и ropensci/rgbif, обычно используются в качестве зависимостей в пакетах R.
  4. Системные зависимости: это внешнее программное обеспечение или библиотеки, которые необходимо установить в системе пользователя для правильной работы пакета R. Например, пакеты, которые взаимодействуют с внешними базами данных или требуют определенных библиотек системного уровня, таких как RMySQL, который требует установки программного обеспечения MySQL в системе, могут иметь системные зависимости.
  5. Внутренние пакеты: это другие пакеты, которые разрабатываются и поддерживаются в той же экосистеме пакетов или организации. Их можно установить с помощью стандартных методов установки пакетов в R. Например, пакеты, разработанные в организации, которые используются в нескольких проектах, могут быть перечислены как зависимости в пакетах R, разработанных этой организацией.

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

Обновляйте документацию

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

  1. Регулярно просматривайте и обновляйте документацию: периодически выделяйте время для просмотра и обновления документации по пакету R. Это включает в себя файл README, виньетки, документацию по функциям и любые другие файлы документации, включенные в ваш пакет. Обновите документацию, чтобы отразить изменения в функциональности вашего пакета, новые функции, исправления ошибок и другие важные обновления.
  2. Синхронизируйте документацию с обновлениями пакетов: всякий раз, когда вы вносите изменения в свой пакет R, обязательно обновляйте документацию соответствующим образом. Например, если вы добавляете новую функцию или изменяете поведение существующей функции, обновите документацию функции, чтобы отразить изменения. Точно так же, если вы обновляете зависимости пакета, обязательно обновите документацию, чтобы отразить новые требования.
  3. Следуйте единообразному стилю документации. Поддерживайте единый стиль и формат документации по пакету R. Если вы начали с определенного стиля, продолжайте использовать его. Это включает в себя использование правильного и общепринятого синтаксиса, соблюдение согласованного соглашения об именах для функций и аргументов, а также предоставление четких и кратких объяснений того, как использовать пакет. Единый стиль документации помогает пользователям понять, как эффективно использовать ваш пакет, и упрощает навигацию и поиск нужной информации.
  4. Отвечайте на отзывы пользователей: обратите внимание на отзывы пользователей и вопросы, связанные с документацией вашего пакета. Если пользователи сообщают о проблемах, ошибках или неясностях в вашей документации, обязательно устраняйте их быстро и обновляйте документацию соответствующим образом. Это включает в себя уточнение инструкций, исправление неточностей и предоставление дополнительных примеров или вариантов использования на основе отзывов пользователей.
  5. Документируйте новые функции и изменения. Когда вы вводите новые функции или вносите существенные изменения в свой пакет R, подробно документируйте их. Объясните, как работают новые функции, приведите примеры и обновите соответствующие разделы документации, чтобы отразить изменения. Это поможет пользователям понять изменения и узнать, как воспользоваться преимуществами новых функций в вашем пакете.
  6. Используйте контроль версий для документации: храните документацию по пакету R в системе контроля версий (например, Git) вместе с исходным кодом вашего пакета. Это позволяет вам отслеживать изменения в вашей документации с течением времени и легко возвращаться к предыдущим версиям, если это необходимо. Когда вы вносите изменения в свою документацию, фиксируйте их в системе управления версиями и предоставляйте осмысленные сообщения фиксации для документирования внесенных изменений.

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

Проверьте свою документацию

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

Вот несколько шагов, которые вы можете выполнить, чтобы протестировать пакет R:

  1. Модульное тестирование: Напишите модульные тесты для отдельных функций или компонентов вашего пакета, используя среду тестирования, такую ​​как testthat или tinytest. Модульные тесты помогают убедиться, что отдельные функции или компоненты вашего пакета работают должным образом, и могут обнаружить ошибки или неожиданное поведение на ранней стадии.
  2. Интеграционное тестирование: проверьте интеграцию различных компонентов или функций в вашем пакете, чтобы убедиться, что они правильно работают вместе. Это включает в себя тестирование взаимодействия между различными частями вашего пакета и проверку того, что они дают ожидаемые результаты.
  3. Протестируйте различные варианты использования. Протестируйте свой пакет с различными входными данными, параметрами и настройками, чтобы убедиться, что он работает правильно в различных сценариях. Рассмотрите пограничные случаи, граничные случаи и распространенные сценарии использования, чтобы тщательно протестировать поведение и производительность вашего пакета.
  4. Тестируйте на разных платформах: протестируйте свой пакет на разных платформах (например, Windows, macOS, Linux) и разных версиях R, чтобы убедиться, что он совместим и работает в разных средах. Это включает в себя тестирование с различными версиями R, различными операционными системами и различными конфигурациями программного обеспечения для выявления и устранения любых проблем, связанных с платформой.
  5. Проверьте зависимости пакетов: убедитесь, что зависимости ваших пакетов правильно указаны в файле DESCRIPTION и что они правильно установлены и загружены во время тестирования. Убедитесь, что ваш пакет правильно работает с указанными вами версиями зависимостей.
  6. Автоматизируйте тестирование: используйте инструменты непрерывной интеграции (CI), такие как Travis CI, GitHub Actions или Jenkins, или другие альтернативы для автоматизации процесса тестирования. Настройте автоматические тесты для запуска всякий раз, когда в исходный код или документацию вашего пакета вносятся изменения. Это помогает выявлять потенциальные проблемы на ранней стадии и гарантирует, что ваш пакет всегда тестируется перед публикацией.
  7. Запрашивайте отзывы: запрашивайте отзывы у коллег, коллег или других экспертов в этой области. Попросите их просмотреть и протестировать ваш пакет, чтобы выявить любые проблемы или внести предложения по улучшению.
  8. Документируйте результаты тестирования: отслеживайте свои усилия по тестированию, включая выполненные тесты, их результаты и любые обнаруженные проблемы или исправления. Задокументируйте процесс и результаты тестирования в документации вашего пакета, чтобы пользователи знали об усилиях по тестированию и могли быть уверены в надежности вашего пакета.

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

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

В прошлой жизни я был военнослужащим США, работавшим в сфере иностранных дел, а сейчас я инструктор по статистике и специалист по данным. Я хочу понять мир, в котором мы живем, и я считаю, что статистические знания доступны каждому. Я люблю кодирование, человеческие языки и математику. Найдите меня в LinkedIn или Twitter. Также обратите внимание на мою совместную работу с DataCamp по созданию курса Концепции сторителлинга на основе данных.