Come scrivere un pacchetto R.

Quando vedi "Pacchetto R", potresti pensare "Qualcosa da condividere con altre persone". Ma un pacchetto R può anche essere un buon modo per organizzare il tuo lavoro solo per te stesso . E soprattutto il tuo sé futuro.

I pacchetti R ti danno una struttura coerente, quindi è più probabile che tu esegua il refactoring del codice in funzioni. E, almeno altrettanto importante: i pacchetti ti offrono un modo coerente per documentare ciascuna delle tue funzioni. Quindi, l'anno prossimo, ci sono maggiori possibilità che ricorderai quali parti del tuo codice fanno cosa.

Configurazione del sistema

Innanzitutto, vuoi configurare il tuo sistema. Per un facile sviluppo dei pacchetti, suggerisco di assicurarti di avere queste librerie installate sul tuo sistema: devtools, usethis, roxygen2, testthat, knitr e rmarkdown.

Probabilmente avrai bisogno anche di un po 'più di configurazione del sistema. In Windows, installa il software chiamato Rtools. Questa è in realtà un'applicazione software, non un pacchetto R. Su un Mac, è utile ottenere Xcode dall'App Store.

Se non sei sicuro che il tuo sistema sia pronto per scrivere pacchetti, devtools ha una funzione chiamata has_devel()che controlla se il tuo ambiente di sviluppo dei pacchetti è OK. Suggerisco di eseguirlo dopo aver installato devtools.

Sharon Machlis /

Successivamente, puoi creare un nuovo pacchetto in RStudio andando su File> Nuovo progetto> Nuova directory e scegliendo Pacchetto R.

Ti viene chiesto un nome di pacchetto e se desideri creare un repository Git (cosa che di solito faccio) e utilizzare packrat (cosa che di solito non faccio).

Nel pannello in basso a destra dopo aver creato il pacchetto, nota che sono stati creati alcuni file e due directory. 

La sottodirectory R è dove devono risiedere tutti i miei script R. La cartella man è per la documentazione, in particolare, i file di aiuto delle funzioni . RStudio crea anche una hello.Rfunzione R di esempio .

Ci sono anche un paio di file importanti nella directory principale. Spiegare NAMESPACEpotrebbe essere un articolo in sé, ma i principianti possono contare sugli strumenti di sviluppo e utilizzare questi pacchetti che si prendono cura di questo.

DESCRIPTIONha alcuni metadati obbligatori importanti sul pacchetto, quindi è necessario compilarli. È per lo più cose facili come il nome del pacchetto, l'autore, la descrizione e la licenza. È anche dove vanno le dipendenze dei pacchetti.

L'utilizzo di questo pacchetto può gestire il formato di dipendenza del pacchetto appropriato per te. Ad esempio, se hai bisogno del pacchetto lubridate per il tuo pacchetto, puoi caricarlo con library(usethis)e quindi eseguire use_package("lubridate")per aggiungere una dipendenza. Puoi vedere come questo aggiunge automaticamente il testo necessario al DESCRIPTIONfile nel video incorporato all'inizio di questo articolo (o eseguendo un codice simile sul tuo sistema).

Scrivi e documenta le tue funzioni

Quindi, scrivi qualsiasi funzione come al solito e salvalo come uno script R nella directory R. Puoi denominare il file come preferisci e puoi includere una o più funzioni nel file.

Roxygen offre un modo semplice per aggiungere documentazione a una funzione. Posiziona il cursore in un punto qualsiasi della definizione della funzione e scegli l'opzione di menu RStudio Codice> Inserisci scheletro Roxygen.

Questo ti dà delle impalcature per documentare la funzione in un modo che R comprende, come 

# 'Titolo

# '

# '@param day

# '

#' @ritorno

#' @esportare

# '

# '@examples

Il campo del titolo è piuttosto autoesplicativo e puoi anche aggiungere una riga per una breve descrizione. C'è una @paramriga per ogni argomento della funzione (in questo esempio, la funzione ha un argomento chiamato day) @return, e @examples. @paramè dove si documenta quale tipo di dati dovrebbe essere un argomento e si può fornire una piccola descrizione. @returndice quale tipo di oggetto viene restituito. @examplesnon è richiesto, ma è necessario fornire un esempio o eliminare l'impostazione predefinita @examples.

Per trasformare questo scaffolding in un file della guida del pacchetto R, eseguire la devtools::document()funzione.

Ora se guardi nella directory man, dovresti avere un file di aiuto di Markdown per la tua nuova funzione (così come un altro per la hellofunzione predefinita ).

Sharon Machlis,

È possibile creare il pacchetto utilizzando la scheda Build di RStudio. L'opzione Installa e riavvia è utile quando stai lavorando al tuo codice. Quando desideri crearlo per la condivisione, incluso il recupero di un file sorgente o di un file binario, controlla il menu a discesa Altro nella scheda Crea.

Esegui help(package = "yourpackagename")per ottenere il file della guida per la nuova funzione.

Se vuoi scrivere una vignetta del pacchetto, esegui la funzione usa questo pacchetto use_vignette()per configurarlo. Includere il nome della vignetta che si desidera come argomento, ad esempio usethis::use_vignette("Intro"). Dovresti vedere una vignetta predefinita, in cui puoi inserire il titolo della vignetta e il testo esplicativo.

Si spera che sia abbastanza per convincerti che è abbastanza facile scrivere un pacchetto R di base! C'è molto di più che puoi fare, come l'aggiunta di unit test con testthat.

Se desideri saperne di più sui test, controlla il mio precedente post "Fai di più con R" "Prova il tuo codice con testthat." E Hadley Wickham ha un intero libro sui pacchetti di scrittura, disponibile gratuitamente online su r-pkgs.had.co.nz, anche se ora è un po 'obsoleto. Jenny Bryan di RStudio sta lavorando con Wickham su un aggiornamento. Puoi vedere un po 'del lavoro in corso su r-pkgs.org.