Programovanie

Ako napísať balík R.

Keď uvidíte balíček „R“, môže vás napadnúť „Niečo na zdieľanie s ostatnými ľuďmi“. Balík R však môže byť tiež dobrým spôsobom, ako si zariadiť vlastnú prácu len pre seba. A hlavne svoje budúce ja.

Balíky R vám poskytujú konzistentnú štruktúru, takže je pravdepodobnejšie, že kód prepracujete na funkcie. A prinajmenšom rovnako dôležité: Balíky vám poskytujú konzistentný spôsob dokumentovania každej z vašich funkcií. Budúci rok bude teda väčšia šanca, že si spomeniete, ktoré časti vášho kódu čo robia.

Nastavenie systému

Najskôr chcete nastaviť systém. Pre ľahký vývoj balíkov navrhujem ubezpečiť sa, že máte vo svojom systéme nainštalované tieto knižnice: devtools, usethis, roxygen2, testthat, knitr a rmarkdown.

Pravdepodobne budete tiež potrebovať trochu viac nastavenia systému. V systéme Windows nainštalujte softvér s názvom Rtools. To je vlastne softvérová aplikácia, nie balík R. V systéme Mac je užitočné získať Xcode z App Store.

Ak si nie ste istí, či je váš systém pripravený na písanie balíkov, má devtools funkciu s názvom has_devel () ktorá kontroluje, či je vývojové prostredie vášho balíka v poriadku. Navrhujem spustiť po nainštalovaní nástrojov devtools.

Sharon Machlis /

Ďalej môžete vytvoriť nový balík v RStudio tak, že prejdete do ponuky Súbor> Nový projekt> Nový adresár a vyberiete R Package.

Zobrazí sa výzva na zadanie názvu balíka a toho, či chcete vytvoriť úložisko Git (čo zvyčajne robím ja) a používať packrat (čo zvyčajne nie).

Vpravo dole na paneli po vytvorení balíka nezabudnite, že bolo vytvorených niekoľko súborov a dva adresáre.

Podadresár R je miesto, kde musia žiť všetky moje R skripty. Zložka man slúži na dokumentáciu - konkrétne súbory pomocníka s funkciami. RStudio tiež vytvorí vzorku ahoj.R Funkcia R.

V hlavnom adresári je tiež niekoľko dôležitých súborov. Vysvetlenie NÁZAM by mohol byť článok sám o sebe, ale začiatočníci môžu počítať s tým, že sa o to postarajú devtools a tieto balíčky.

POPIS obsahuje niektoré dôležité požadované metadáta o balíku, takže ich musíte vyplniť. Sú to väčšinou ľahké veci, ako napríklad názov balíka, autor, popis a licencia. Týka sa to aj závislostí balíkov.

Tento balík useth zvládne správny formát závislosti od balíka. Napríklad, ak potrebujete pre svoj obal obal s mazivom, môžete ho týmto naplniť knižnica (používa sa) a potom bežať use_package ("lubridate") pridať závislosť. Môžete vidieť, ako to automaticky pridá potrebný text do priečinka POPIS súbor vo videu vloženom v hornej časti tohto článku (alebo spustením podobného kódu vo vašom vlastnom systéme).

Píšte a dokumentujte svoje funkcie

Ďalej napíšte ľubovoľnú funkciu ako obvykle a uložte ju ako skript R do adresára R. Môžete pomenovať súbor, ako chcete, a môžete doň zahrnúť jednu alebo viac funkcií.

Roxygen ponúka jednoduchý spôsob pridania dokumentácie k funkcii. Umiestnite kurzor kamkoľvek do definície funkcie a vyberte možnosť ponuky RStudio Kód> Vložiť Roxygen Skeleton.

To vám dáva nejaké lešenie na zdokumentovanie funkcie spôsobom, ktorému R rozumie, ako napr

# 'Názov

#'

# '@param deň

#'

# '@ ​​návrat

#' @export

#'

# '@ ​​príklady

Pole Názov je dosť zrozumiteľné a môžete tiež pridať riadok pre krátky popis. Existuje @param riadok pre každý argument funkcie (v tomto príklade má funkcia jeden argument s názvom deň), @ návrata @ príklady. @param je miesto, kde dokumentujete, aký dátový typ by mal mať argument, a môžete uviesť malý popis. @ návrat povie, aký typ objektu sa vráti. @ príklady nie je povinné, ale musíte buď uviesť príklad, alebo toto predvolené nastavenie odstrániť @ príklady.

Ak chcete z tohto lešenia urobiť súbor pomoci s balíkom R. Spustite príkaz devtools :: document () funkcia.

Ak sa teraz pozriete do adresára man, mali by ste mať k dispozícii súbor pomocníka Markdown pre svoju novú funkciu (a tiež ďalší pre predvolenú funkciu). Ahoj funkcia).

Sharon Machlis,

Balík môžete vytvoriť pomocou karty RStudio Build. Možnosť Inštalovať a reštartovať je dobrá, keď práve pracujete na svojom kóde. Ak ho chcete vytvoriť na zdieľanie vrátane získania zdrojového alebo binárneho súboru, pozrite si rozbaľovaciu ponuku Viac na karte Vytvoriť.

Bež help (package = "yourpackagename") získať súbor pomocníka pre novú funkciu.

Ak chcete napísať vignetovú zásielku, spustite jej use_vignette () funkciu nastaviť. Ako argument uveďte názov vinety, ktorú chcete usethis :: use_vignette ("Intro"). Mali by ste vidieť predvolenú vinetáciu, kde môžete vyplniť názov a vysvetľujúci text vinety.

Dúfajme, že to stačí na to, aby sme vás presvedčili, že je ľahké napísať základný balík R! Môžete toho urobiť ešte veľa, napríklad pridať do jednotkových testov s testthat.

Ak sa chcete dozvedieť viac informácií o testovaní, prečítajte si môj predchádzajúci príspevok „Do More With R“ „Testujte svoj kód pomocou testthat“. A Hadley Wickham má celú knihu o písacích balíčkoch, ktorá je k dispozícii zadarmo online na adrese r-pkgs.had.co.nz, aj keď je už trochu zastaraná. Jenny Bryan z RStudio pracuje s Wickhamom na aktualizácii. Trochu rozpracovaných prác si môžete pozrieť na stránke r-pkgs.org.