Wie schreibe ich ein R-Paket

Wenn Sie "R-Paket" sehen, denken Sie möglicherweise "Etwas, das Sie mit anderen Personen teilen können". Ein R-Paket kann aber auch eine gute Möglichkeit sein, Ihre eigene Arbeit nur für sich selbst zu organisieren . Und vor allem dein zukünftiges Selbst.

R-Pakete bieten Ihnen eine konsistente Struktur, sodass Sie Code mit größerer Wahrscheinlichkeit in Funktionen umgestalten. Und mindestens genauso wichtig: Pakete bieten Ihnen eine konsistente Möglichkeit, jede Ihrer Funktionen zu dokumentieren. Nächstes Jahr besteht also eine bessere Chance, dass Sie sich daran erinnern, welche Teile Ihres Codes was tun.

Systemkonfiguration

Zunächst möchten Sie Ihr System einrichten. Für eine einfache Paketentwicklung empfehle ich, sicherzustellen, dass diese Bibliotheken auf Ihrem System installiert sind: devtools, usethis, roxygen2, testthat, knitr und rmarkdown.

Sie benötigen wahrscheinlich auch etwas mehr System-Setup. Installieren Sie unter Windows die Software Rtools. Das ist eigentlich eine Softwareanwendung, kein R-Paket. Auf einem Mac ist es hilfreich, Xcode aus dem App Store zu beziehen.

Wenn Sie nicht sicher sind, ob Ihr System zum Schreiben von Paketen bereit ist, verfügt devtools über eine Funktion has_devel(), die überprüft, ob Ihre Paketentwicklungsumgebung in Ordnung ist. Ich schlage vor, das auszuführen, nachdem Sie devtools installiert haben.

Sharon Machlis /

Als Nächstes können Sie ein neues Paket in RStudio erstellen, indem Sie zu Datei> Neues Projekt> Neues Verzeichnis gehen und R-Paket auswählen.

Sie werden nach einem Paketnamen gefragt und ob Sie ein Git-Repository erstellen möchten (was ich normalerweise mache) und packrat verwenden möchten (was ich normalerweise nicht mache).

Beachten Sie, dass nach dem Erstellen des Pakets unten rechts einige Dateien und zwei Verzeichnisse erstellt wurden. 

Im R-Unterverzeichnis müssen alle meine R-Skripte leben. Der man-Ordner dient zur Dokumentation, insbesondere für Funktionshilfedateien . RStudio erstellt auch eine Beispiel- hello.RR-Funktion.

Es gibt auch einige wichtige Dateien im Hauptverzeichnis. Das Erklären NAMESPACEkönnte ein Artikel für sich sein, aber Anfänger können sich darauf verlassen, dass die devtools und diese Pakete sich darum kümmern.

DESCRIPTIONhat einige wichtige erforderliche Metadaten zum Paket, daher müssen Sie diese ausfüllen. Es sind meistens einfache Dinge wie Paketname, Autor, Beschreibung und Lizenz. Hier gehen auch Paketabhängigkeiten hin.

Das usethis-Paket kann das richtige Paketabhängigkeitsformat für Sie verarbeiten. Wenn Sie beispielsweise das Lubridate-Paket für Ihr Paket benötigen, können Sie usethis mit laden library(usethis)und dann ausführen use_package("lubridate"), um eine Abhängigkeit hinzuzufügen. Sie können sehen, wie dies automatisch den erforderlichen Text zur DESCRIPTIONDatei in dem oben in diesem Artikel eingebetteten Video hinzufügt (oder indem Sie ähnlichen Code auf Ihrem eigenen System ausführen).

Schreiben und dokumentieren Sie Ihre Funktionen

Schreiben Sie als Nächstes eine beliebige Funktion wie gewohnt und speichern Sie sie als R-Skript im R-Verzeichnis. Sie können die Datei beliebig benennen und eine oder mehrere Funktionen in die Datei aufnehmen.

Roxygen bietet eine einfache Möglichkeit, einer Funktion Dokumentation hinzuzufügen. Setzen Sie den Cursor an eine beliebige Stelle in der Funktionsdefinition und wählen Sie die RStudio-Menüoption Code> Roxygen Skeleton einfügen.

Das gibt Ihnen ein Gerüst, um die Funktion auf eine Weise zu dokumentieren, die R versteht, wie z 

#' Titel

# '

# '@param Tag

# '

#' @Rückkehr

#' @Export

# '

# '@Beispiele

Das Feld Titel ist ziemlich selbsterklärend, und Sie können auch eine Zeile für eine kurze Beschreibung hinzufügen. @paramFür jedes Funktionsargument gibt es eine Zeile (in diesem Beispiel hat die Funktion ein Argument day) @returnund @examples. @paramHier dokumentieren Sie, welcher Datentyp ein Argument sein sollte, und können eine kleine Beschreibung geben. @returnGibt an, welcher Objekttyp zurückgegeben wird. @examplesist nicht erforderlich, aber Sie müssen entweder ein Beispiel angeben oder diese Standardeinstellung löschen @examples.

Führen Sie die devtools::document()Funktion aus, um dieses Gerüst in eine Hilfedatei für ein R-Paket umzuwandeln .

Wenn Sie jetzt im man-Verzeichnis suchen, sollten Sie eine Markdown-Hilfedatei für Ihre neue Funktion haben (sowie eine andere für die Standardfunktion hello).

Sharon Machlis,

Sie können das Paket über die Registerkarte RStudio Build erstellen. Die Option "Installieren und neu starten" eignet sich, wenn Sie gerade an Ihrem Code arbeiten. Wenn Sie es für die Freigabe erstellen möchten, einschließlich des Abrufs einer Quelldatei oder einer Binärdatei, lesen Sie die Dropdown-Liste Mehr auf der Registerkarte Erstellen.

Führen Sie diese aus help(package = "yourpackagename"), um die Hilfedatei für die neue Funktion abzurufen.

Wenn Sie eine Paketvignette schreiben möchten, führen Sie die use_vignette()Funktion dieses Pakets aus , um diese einzurichten. Geben Sie den Namen der gewünschten Vignette als Argument an, z usethis::use_vignette("Intro"). Sie sollten eine Standardvignette sehen, in die Sie den Titel und den Erklärungstext der Vignette eingeben können.

Hoffentlich reicht das aus, um Sie davon zu überzeugen, dass es ziemlich einfach ist, ein einfaches R-Paket zu schreiben! Sie können noch viel mehr tun, z. B. Unit-Tests mit testthat hinzufügen.

Wenn Sie mehr über das Testen erfahren möchten, lesen Sie meinen früheren Beitrag "Testen Sie Ihren Code mit testthat". Und Hadley Wickham hat ein ganzes Buch über das Schreiben von Paketen, das kostenlos online unter r-pkgs.had.co.nz erhältlich ist, obwohl es jetzt etwas veraltet ist. Jenny Bryan von RStudio arbeitet mit Wickham an einem Update. Unter r-pkgs.org können Sie einen Teil der laufenden Arbeiten sehen.