Как да напиша R пакет

Когато видите „R пакет“, може да си помислите „Нещо за споделяне с други хора“. Но пакетът R може да бъде и добър начин да организирате собствената си работа само за себе си . И особено бъдещото ви Аз.

R пакетите ви дават последователна структура, така че е по-вероятно да рефакторирате кода във функции. И, поне толкова важно: Пакетите ви дават последователен начин за документиране на всяка една от вашите функции. Така че, следващата година има по-голям шанс да запомните кои части от кода ви правят какво.

Системни настройки

Първо искате да настроите вашата система. За лесно разработване на пакети, предлагам да се уверите, че имате инсталирани на вашата система тези библиотеки: devtools, usethis, roxygen2, testthat, knitr и rmarkdown.

Вероятно се нуждаете и от малко повече настройка на системата. В Windows инсталирайте софтуер, наречен Rtools. Това всъщност е софтуерно приложение, а не R пакет. На Mac е полезно да получите Xcode от App Store.

Ако не сте сигурни дали вашата система е готова за писане на пакети, devtools има функция, наречена, has_devel()която проверява дали вашата среда за разработка на пакети е наред. Предлагам да го стартирате, след като сте инсталирали devtools.

Шарън Маклис /

След това можете да създадете нов пакет в RStudio, като отидете на File> New Project> New Directory и изберете R Package.

Поискано е името на пакета и дали искате да създадете Git хранилище (което обикновено правя) и да използвате packrat (което обикновено не правя).

В долния десен панел след създаването на пакета имайте предвид, че са създадени няколко файла и две директории. 

Поддиректорията R е мястото, където трябва да живеят всичките ми R скриптове. Папката man е за документация - по-конкретно, файлове с помощна функция . RStudio също създава примерна hello.RR функция.

В главната директория има и няколко важни файла. Обяснението NAMESPACEможе да бъде само по себе си статия, но начинаещите могат да разчитат на devtools и да използват тези пакети, като се грижат за това.

DESCRIPTIONима някои важни необходими метаданни за пакета, така че трябва да попълните това. Това са предимно лесни неща като име на пакета, автор, описание и лиценз. Това е и мястото, където отиват зависимостите на пакета.

Този пакет може да се справи с правилния формат на зависимост от пакета вместо вас. Например, ако имате нужда от пакета lubridate за вашия пакет, можете да заредите usethis с library(usethis)и след това да изпълните, за use_package("lubridate")да добавите зависимост. Можете да видите как това автоматично добавя необходимия текст към DESCRIPTIONфайла във видеото, вградено в горната част на тази статия (или като стартирате подобен код на вашата собствена система).

Напишете и документирайте вашите функции

След това напишете всяка функция както обикновено и я запазете като R скрипт в R директорията. Можете да дадете име на файла, каквото искате, и можете да включите една или повече функции във файла.

Roxygen предлага лесен начин за добавяне на документация към функция. Поставете курсора навсякъде в дефиницията на функцията и изберете опцията от менюто RStudio Код> Вмъкване на скелет Roxygen.

Това ви дава малко скеле, за да документирате функцията по начин, който R разбира, като например 

#' Заглавие

# '

# '@param ден

# '

# '@ ​​завръщане

# '@export

# '

#' @примери

Полето за заглавие е доста обяснително и можете също да добавите ред за кратко описание. Има @paramред за всеки аргумент на функцията (в този пример функцията има един извикан аргумент day) @return, и @examples. @paramе мястото, където документирате какъв тип данни трябва да бъде аргумент и можете да дадете малко описание. @returnказва какъв тип обект се връща. @examplesне се изисква, но трябва или да дадете пример, или да изтриете това по подразбиране @examples.

За да превърнете това скеле в помощен файл на R пакет, стартирайте devtools::document()функцията.

Сега, ако погледнете в директорията man, трябва да имате файл за помощ Markdown за новата си функция (както и друг за функцията по подразбиране hello).

Шарън Маклис,

Можете да изградите пакета, като използвате раздела RStudio Build. Опцията Инсталиране и рестартиране е добра, когато сте в средата на работа по вашия код. Когато искате да го изградите за споделяне, включително получаване на изходен файл или двоичен файл, проверете падащото меню Още в раздела Изграждане.

Изпълнете, за help(package = "yourpackagename")да получите помощния файл за новата функция.

Ако искате да напишете винетка на пакет, стартирайте функцията на този пакет, за use_vignette()да го настроите. Включете името на винетката, която искате като аргумент, например usethis::use_vignette("Intro"). Трябва да видите винетка по подразбиране, където можете да попълните заглавието и текста на обяснението на винетката.

Надяваме се, че това е достатъчно, за да ви убеди, че е доста лесно да напишете основен R пакет! Има много повече неща, които можете да направите, като добавяне в модулни тестове с testthat.

Ако искате да научите повече за тестването, вижте по-ранната публикация „Правете повече с R“ „Тествайте кода си с testthat“. А Хадли Уикъм има цяла книга за писане на пакети, достъпна безплатно онлайн на r-pkgs.had.co.nz, макар че вече е малко остаряла. Джени Брайън от RStudio работи с Уикъм по актуализация. Можете да видите малко от текущата работа на r-pkgs.org.