R Language
Creare pacchetti con devtools

introduzione

Osservazioni

Creazione e distribuzione di pacchetti

Questa è una guida compatta su come creare rapidamente un pacchetto R dal tuo codice. Documentazioni esaustive saranno collegate quando disponibili e dovrebbero essere lette se si desidera una conoscenza più approfondita della situazione. Vedi Note per maggiori risorse.

La directory in cui si trova il codice verrà indicata come ./ , e tutti i comandi devono essere eseguiti da un prompt R in questa cartella.

Creazione della documentazione

La documentazione per il tuo codice deve essere in un formato molto simile a LaTeX.

Tuttavia, useremo uno strumento chiamato roxygen per semplificare il processo:

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

La pagina man completa per roxygen è disponibile qui . È molto simile a doxygen .

Ecco un esempio pratico su come documentare una funzione con 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)
}

E qui sarà il risultato .

Si consiglia inoltre di creare una vignetta (vedere l'argomento Creazione di vignette ), che è una guida completa sul pacchetto.

Costruzione dello scheletro del pacchetto

Supponendo che il tuo codice sia scritto ad esempio nei file ./script1.R e ./script2.R , lancia il seguente comando per creare l'albero dei file del tuo pacchetto:

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

Quindi elimina tutti i file in ./MyPackage/man/ . Devi ora compilare la documentazione:

roxygenize("MyPackage")

Dovresti anche generare un manuale di riferimento dalla tua documentazione usando R CMD Rd2pdf MyPackage da un prompt dei comandi avviato in ./ .

Edizione delle proprietà del pacchetto

1. Descrizione del pacchetto

Modifica ./MyPackage/DESCRIPTION base alle tue esigenze. I campi Package , Version , License , Description , Title , Author e Maintainer sono obbligatori, mentre gli altri sono facoltativi.

Se il pacchetto dipende da altri pacchetti, specificarli in un campo denominato Depends (versione R <3.2.0) o Imports (versione R> 3.2.0).

2. Cartelle opzionali

Una volta che hai lanciato la build scheletro, ./MyPackage/ solo R/ e man/ sottocartelle. Tuttavia, può avere altri:

• data/ : qui puoi inserire i dati di cui la tua biblioteca ha bisogno e che non è un codice. Deve essere salvato come set di dati con l'estensione .RData , ed è possibile caricarlo in runtime con data() e load()
• tests/ : tutti i file di codice in questa cartella verranno tests/ al momento dell'installazione. Se c'è qualche errore, l'installazione fallirà.
• src/ : per i file sorgente C / C ++ / Fortran necessari (usando Rcpp ...).
• exec/ : per altri eseguibili.
• misc/ : per quasi tutto il resto.

Finalizzazione e costruzione

Puoi eliminare ./MyPackage/Read-and-delete-me .

Come ora, il tuo pacchetto è pronto per essere installato.

Puoi installarlo con devtools::install("MyPackage") .

Per creare il tuo pacchetto come tarball sorgente, devi eseguire il seguente comando, da un prompt dei comandi in ./ : R CMD build MyPackage

Distribuzione del tuo pacchetto

Attraverso Github

Basta creare un nuovo repository chiamato MyPackage e caricare tutto in MyPackage/ sul ramo master. Ecco un esempio .

Quindi chiunque può installare il pacchetto da github con devtools:

install_package("MyPackage", "your_github_usename")

Attraverso CRAN

Il pacchetto deve essere conforme alle Norme sui repository CRAN . Incluso ma non limitato a: il tuo pacchetto deve essere multipiattaforma (tranne alcuni casi molto speciali), dovrebbe superare il test di R CMD check .

Ecco il modulo di invio . Devi caricare il tarball sorgente.

Creare vignette

Una vignetta è una guida di lungo formato al tuo pacchetto. La documentazione delle funzioni è ottima se conosci il nome della funzione che ti serve, ma è inutile altrimenti. Una vignetta è come un capitolo di un libro o un documento accademico: può descrivere il problema che il pacchetto è progettato per risolvere e quindi mostrare al lettore come risolverlo.

Le vignette verranno create interamente in markdown.

Requisiti

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

Creazione di vignette

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

Ora puoi modificare la tua vignetta in ./vignettes/MyVignette.Rmd .

Il testo nella tua vignetta è formattato come Markdown .

L'unica aggiunta al Markdown originale è un tag che prende il codice R, lo esegue, cattura l'output e lo traduce in Markdown formattato:

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

Visualizzerà come:

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

Pertanto, tutti i pacchetti che utilizzerai nelle tue vignette devono essere elencati come dipendenze in ./DESCRIPTION .