R Language
Pakketten maken met devtools

Invoering

Opmerkingen

Pakketten maken en distribueren

Dit is een compacte handleiding voor het snel maken van een R-pakket op basis van uw code. Uitputtende documentatie wordt gekoppeld wanneer deze beschikbaar is en moet worden gelezen als u een diepere kennis van de situatie wilt. Zie Opmerkingen voor meer bronnen.

De map waar uw code staat zal worden aangeduid als ./ , en alle opdrachten zijn bedoeld om te worden uitgevoerd vanaf een R-prompt in deze map.

Aanmaken van de documentatie

De documentatie voor uw code moet een indeling hebben die erg lijkt op LaTeX.

We zullen echter een tool genaamd roxygen gebruiken om het proces te vereenvoudigen:

install.packages("devtools")
library("devtools")
install.packages("roxygen2")
library("roxygen2")

De volledige manpagina voor roxygen is hier beschikbaar. Het lijkt erg op doxygen .

Hier is een praktisch voorbeeld over het documenteren van een functie met roxygen :

#' Increment a variable.
#'
#' Note that the behavior of this function
#' is undefined if `x` is not of class `numeric`.
#'
#' @export
#' @author  another guy
#' @name    Increment Function
#' @title   increment
#'
#' @param x   Variable to increment
#' @return    `x` incremented of 1
#'
#' @seealso   `other_function`
#'
#' @examples
#' increment(3)
#' > 4
increment <- function(x) {
  return (x+1)
}

En hier zal het resultaat zijn .

Het wordt ook aanbevolen om een vignet te maken (zie het onderwerp Vignetten maken ), een volledige handleiding voor uw pakket.

Constructie van het pakket skelet

Ervan uitgaande dat uw code bijvoorbeeld in bestanden ./script1.R en ./script2.R is geschreven, start u de volgende opdracht om de bestandsstructuur van uw pakket te maken:

package.skeleton(name="MyPackage", code_files=c("script1.R","script2.R"))

Verwijder vervolgens alle bestanden in ./MyPackage/man/ . U moet nu de documentatie samenstellen:

roxygenize("MyPackage")

U moet ook een referentiehandleiding uit uw documentatie genereren met behulp van R CMD Rd2pdf MyPackage vanaf een opdrachtprompt die is gestart in ./ .

Editie van de pakketeigenschappen

1. Pakketbeschrijving

Wijzig ./MyPackage/DESCRIPTION volgens uw behoeften. De velden Package , Version , License , Description , Title , Author en Maintainer zijn verplicht, de andere zijn optioneel.

Als uw pakket afhankelijk is van andere pakketten, geeft u deze op in een veld met de naam Depends (R-versie <3.2.0) of Imports (R-versie> 3.2.0).

2. Optionele mappen

Nadat je de skeletbouw had gelanceerd, had ./MyPackage/ alleen R/ en man/ submappen. Het kan echter enkele andere hebben:

• data/ : hier kunt u de gegevens plaatsen die uw bibliotheek nodig heeft en dat is geen code. Het moet worden opgeslagen als gegevensset met de extensie .RData en u kunt het tijdens runtime laden met data() en load()
• tests/ : alle codebestanden in deze map worden tijdens de installatie uitgevoerd. Als er een fout optreedt, mislukt de installatie.
• src/ : voor C / C ++ / Fortran-bronbestanden die u nodig hebt (met Rcpp ...).
• exec/ : voor andere uitvoerbare bestanden.
• misc/ : voor nauwelijks al het andere.

Voltooien en bouwen

U kunt ./MyPackage/Read-and-delete-me verwijderen.

Zoals het nu is, is uw pakket klaar om te worden geïnstalleerd.

U kunt het installeren met devtools::install("MyPackage") .

Om uw pakket als een bron tarball te bouwen, moet u de volgende opdracht uitvoeren, vanaf een opdrachtprompt in ./ : R CMD build MyPackage

Distributie van uw pakket

Via Github

Maak eenvoudig een nieuwe repository genaamd MyPackage en upload alles in MyPackage/ naar de master branch. Hier is een voorbeeld .

Dan kan iedereen uw pakket van github installeren met devtools:

install_package("MyPackage", "your_github_usename")

Door CRAN

Uw pakket moet voldoen aan het CRAN Repository-beleid . Inclusief maar niet beperkt tot: uw pakket moet platformoverschrijdend zijn (behalve enkele zeer speciale gevallen), het moet de R CMD check doorstaan.

Hier is het inzendformulier . U moet de bron tarball uploaden.

Vignetten maken

Een vignet is een lange handleiding voor uw pakket. Functiedocumentatie is geweldig als u de naam kent van de functie die u nodig hebt, maar anders is het nutteloos. Een vignet is als een hoofdstuk uit een boek of een academische paper: het kan het probleem beschrijven dat uw pakket is ontworpen om op te lossen en vervolgens de lezer tonen hoe het op te lossen.

Vignetten worden volledig in markdown gemaakt.

Voorwaarden

• Rmarkdown: install.packages("rmarkdown")
• Pandoc

Vignet creatie

devtools::use_vignette("MyVignette", "MyPackage")

U kunt nu uw vignet bewerken op ./vignettes/MyVignette.Rmd .

De tekst in uw vignet is opgemaakt als Markdown .

De enige toevoeging aan de originele Markdown is een tag die R-code gebruikt, uitvoert, de uitvoer vastlegt en vertaalt in opgemaakte Markdown:

```{r}
# Add two numbers together
add <- function(a, b) a + b
add(10, 20)
```

Wordt weergegeven als:

# Add two numbers together
add <- function(a, b) a + b
add(10, 20)
## [1] 30

Alle pakketten die u in uw vignetten gaat gebruiken, moeten dus worden vermeld als afhankelijkheden in ./DESCRIPTION .