Programmering

Hvordan man skriver en R-pakke

Når du ser "R-pakke", kan du tænke "Noget at dele med andre mennesker." Men en R-pakke kan også være en god måde at organisere dit eget arbejde på bare for dig selv. Og især dit fremtidige selv.

R-pakker giver dig en ensartet struktur, så du er mere tilbøjelig til at omlægge kode til funktioner. Og mindst lige så vigtigt: Pakker giver dig en konsekvent måde at dokumentere hver af dine funktioner på. Så næste år er der en bedre chance for at huske, hvilke dele af din kode der gør hvad.

System opsætning

Først vil du oprette dit system. For nem pakkeudvikling foreslår jeg at sikre dig, at du har disse biblioteker installeret på dit system: devtools, usethis, roxygen2, testthat, knitr og rmarkdown.

Du har sandsynligvis også brug for lidt mere systemopsætning. I Windows skal du installere software kaldet Rtools. Det er faktisk en softwareapplikation, ikke en R-pakke. På en Mac er det nyttigt at hente Xcode fra App Store.

Hvis du ikke er sikker på, om dit system er klar til at skrive pakker, har devtools en funktion kaldet has_devel () der kontrollerer, om dit pakkeudviklingsmiljø er OK. Jeg foreslår, at du kører det, når du har installeret devtools.

Sharon Machlis /

Dernæst kan du oprette en ny pakke i RStudio ved at gå til Filer> Nyt projekt> Ny mappe og vælge R-pakke.

Du bliver bedt om et pakkenavn, og om du vil oprette et Git-arkiv (som jeg normalt gør) og bruge packrat (som jeg normalt ikke gør).

I nederste højre panel efter oprettelse af pakken skal du bemærke, at der blev oprettet et par filer og to mapper.

R-underkatalogen er, hvor alle mine R-scripts har brug for at leve. Mandsmappen er til dokumentation - specifikt funktion hjælpefiler. RStudio opretter også en prøve hej. R. R-funktion.

Der er også et par vigtige filer i hovedmappen. Forklarer NAVNSTED kunne være en artikel i sig selv, men begyndere kan stole på, at devtools og bruger disse pakker tager sig af det.

BESKRIVELSE har nogle vigtige krævede metadata om pakken, så du skal udfylde det. Det er for det meste nemme ting som pakkenavn, forfatter, beskrivelse og licens. Det er også hvor pakkeafhængighederne går.

Usethis-pakken kan håndtere det korrekte pakkeafhængighedsformat for dig. For eksempel, hvis du har brug for lubridate-pakken til din pakke, kan du indlæse dette med bibliotek (bruger dette) og løb derefter use_package ("lubridate") for at tilføje en afhængighed. Du kan se, hvordan dette automatisk føjer den nødvendige tekst til BESKRIVELSE fil i videoen indlejret øverst i denne artikel (eller ved at køre lignende kode på dit eget system).

Skriv og dokumenter dine funktioner

Skriv derefter en hvilken som helst funktion som normalt, og gem den som et R-script i R-biblioteket. Du kan navngive filen, hvad du vil, og du kan medtage en eller flere funktioner i filen.

Roxygen tilbyder en nem måde at tilføje dokumentation til en funktion på. Placer din markør hvor som helst i funktionsdefinitionen, og vælg RStudio-menupunktet Kode> Indsæt Roxygen-skelet.

Det giver dig nogle stilladser til at dokumentere funktionen på en måde, som R forstår, såsom

# 'Titel

#'

# '@param dag

#'

#' @Vend tilbage

#' @eksport

#'

# '@eksempler

Titelfeltet er ret selvforklarende, og du kan også tilføje en linje til en kort beskrivelse. Der er en @param linje for hvert funktionsargument (i dette eksempel har funktionen et argument kaldet dag), @Vend tilbageog @eksempler. @param er hvor du dokumenterer hvilken datatype et argument skal være og kan give en lille beskrivelse. @Vend tilbage fortæller hvilken type genstand, der returneres. @eksempler er ikke påkrævet, men du skal enten give et eksempel eller slette denne standard @eksempler.

For at gøre dette stillads til en R-pakkehjælpefil skal du køre devtools :: dokument () fungere.

Nu hvis du kigger i mandkataloget, skal du have en Markdown-hjælpefil til din nye funktion (samt en anden til standard Hej fungere).

Sharon Machlis,

Du kan oprette pakken ved hjælp af fanen RStudio Build. Indstillingen Installer og genstart er god, når du er midt i arbejdet med din kode. Når du vil bygge den til deling, herunder at hente en kildefil eller binær fil, skal du tjekke rullemenuen Mere i fanen Build.

Løb hjælp (pakke = "dit pakkenavn") for at få hjælpefilen til den nye funktion.

Hvis du vil skrive en pakkevignet, skal du køre denne pakke brug_vignet () funktion til at indstille det. Inkluder navnet på den vignet, du vil have som argument, f.eks bruger dette :: use_vignette ("Intro"). Du skal se en standardvignet, hvor du kan udfylde vignettens titel og forklaringstekst.

Forhåbentlig er det nok til at overbevise dig om, at det er ret nemt at skrive en grundlæggende R-pakke! Der er meget mere, du kan gøre, som at tilføje i enhedstest med test det.

Hvis du gerne vil vide mere om test, skal du tjekke mit tidligere "Gør mere med R" -indlæg "Test din kode med testdet." Og Hadley Wickham har en hel bog om at skrive pakker, tilgængelig gratis online på r-pkgs.had.co.nz, selvom det er lidt forældet nu. Jenny Bryan hos RStudio arbejder sammen med Wickham om en opdatering. Du kan se lidt af det igangværende arbejde på r-pkgs.org.