Hilfe erstellen für Funktionen in eigenen R-Paketen (roxygen2)

Nachdem wir in früheren Beiträgen gesehen haben, warum und wann es überhaupt sinnvoll ist, eigene R-Pakete zu erstellen und wie man ein erstes Paket in zwei Minuten erstellen kann, wollen wir uns heute mit einem wesentlichen Aspekt von R-Paketen näher beschäftigen: Der Dokumentation. Erst mit einer guten Dokumentation wird unser Paket für andere und, nicht zu vernachlässigen, für uns selbst in der Zukunft leicht(er) anwendbar.

Eine Beispielfunktion: Zufallsalbum ausgeben

Als Beispiel betrachten wir eine relativ simple Funktion, die aus einem Datensatz mit Musikalben ein Album zufällig auswählt und in der Konsole ausgibt. Die Daten stammen von der empfehlenswerten Webseite tsort.info – The World’s Music Charts.

zufallsalbum <- function(band = "The Beatles", data = albums) {
   banddaten <- data[data$artist == band, ]
   if(nrow(banddaten) == 0) stop(paste("Keine Daten zu", band))
   album <- base::sample(banddaten$name, 1)
   cat(paste0("Zufällig ausgewähltes Album von ", band, ": ", album))
 }

The Funktion filtert nach der angegebenen Band (voreingestellter Wert: „The Beatles“), gibt eine Meldung aus, falls keine Daten zur entsprechenden Band vorliegen, zieht zufällig ein Album und gibt dieses aus.

> zufallsalbum()
Zufällig ausgewähltes Album von The Beatles: Anthology 3 

Eine Hilfe steht für diese Funktion zunächst jedoch nicht zur Verfügung:

?zufallsalbum
No documentation for ‘zufallsalbum’ in specified packages and libraries:
you could try ‘??zufallsalbum’ 

Eigene Funktionen dokumentieren wie in der Hilfe von R

Die Dokumentation zu unserem Paket erstellen wir mit Hilfe von sogenannten roxygen-Kommentaren. Das Paket roxygen2, entwickelt von einem Team um Hadley Wickham (siehe help(package = „roxygen2“)), unterstützt uns dabei. Dazu sollten wir in RStudio unter Tools – Project Options – Build Tools die entsprechenden Einstellungen vornehmen:

Hier sollten wir Roxygen aktivieren, mindestens für Rd files, sehr empfehlenswert auch für den NAMESPACE. Wer diese Dateien per Hand bearbeitet, kann sich sehr leicht Fehler einbauen.

Vorteile von roxygen2 gegenüber dem Bearbeiten von .Rd-Dateien

.Rd-Dateien enthalten Latex-ähnliche Zeichen, um die Dokumentation zu kennzeichnen. Aus ihnen erstellt R bei der Paket-Installation die gewohnte Hilfe für R-Funktionen. Roxygen2 bietet folgende Vorteile gegenüber der direkten Bearbeitung der .Rd-Dateien:

• Code und Dokumentation werden verknüpft. Bei Änderungen am Code werden wir erinnert, auch die Dokumentation zu aktualisieren.
• Roxygen2 „denkt mit“ und erkennt Objekte – so müssen wir nicht alle Standardtexte per Hand schreiben
• Roxygen2 abstrahiert von Detail-Unterschieden in der Dokumentation unterschiedlicher Objekttypen. Wir als Anwender müssen so weniger Einzelheiten lernen.
• Roxygen2 kann auch den NAMESPACE verwalten: die Datei, in der z. B. eingetragen wird, welche Funktionen unseres Pakets für Anwender von außen sichtbar werden („exportiert“).

Wie sehen roxygen-Kommentare aus?

Roxygen-Kommentare beginnen, wie die üblichen Kommentare in R-Skripten, mit dem Doppelkreuz #, allerdings zusätzlich gefolgt von einem einfachen Anführungszeichen. Hier einige der wichtigsten roxygen tags – weitere siehe hier oder im Buch R Packages von Hadley Wickham und Jenny Bryan.

Die roxygen2 Tags werden direkt in das Skript mit der entsprechenden R-Funktion eingefügt, und zwar oberhalb des R-Codes. Das Skript kann dann im Falle unserer Beispielfunktion von oben so aussehen:

Man kann die Hilfe Schritt für Schritt manuell eintragen – oder es sich leichter machen und in RStudio unter Code den Punkt Insert Roxygen Skeleton (Strg + Alt + Shift + R) ausführen. Dann erhält man ein Grundgerüst mit roxygen-Tags, das man nur noch inhaltlich auffüllen muss.

Dokumentation erstellen: Workflow

Wie wird nun aus diesem Skript eine dokumentierte Funktion, deren Hilfe wir wie gewohnt in der Konsole mit ?funktion, hier ?zufallsalbum, aufrufen können?

Die Dokumentation wird erstellt, wenn wir das Paket installieren: Unter Build – Install and Restart. Bei größeren Paketen kann das eine ganze Weile dauern. Es gibt eine Abkürzung: Mit Build – More – Document bzw. mit Strg + Shift + D wird die Hilfe ebenfalls erstellt, ohne dass gleich das ganze Paket installiert wird. In Kombination mit Strg + Shift + L oder Build – More – Load All können wir so schnell in kleinen Schritten die Funktion erweitern, die Hilfe ergänzen und gleich testen, wie sie aussieht. (Hinweis: Die Funktion sollte nur im Paket liegen, nicht im Environment / der Arbeitsumgebung!)

Ein kleiner Haken besteht darin, dass zumindest bei mir in der development version, der schnellen Variante über Strg + Shift + D, die Umlaute nicht korrekt dargestellt werden. Nach vollständiger Installation des Pakets werden sie jedoch richtig angezeigt.

Dokumentation ergänzen: Weitere Möglichkeiten

Die Dokumentation muss nicht bei der Erläuterung einzelner Funktionen stehen bleiben. Weitere Möglichkeiten:

• Datensätze ins Paket integrieren und dokumentieren
  Beispiel: siehe ?mtcars
• Vignetten erstellen: ausführliche, allgemeiner gehaltene Hilfe-Seite, die ins Paket einführt (d. h. man muss nicht schon den Namen einer bestimmten Funktion kennen, um zu ihrer Hilfe zu gelangen).
  Beispiel: siehe help(package = „ggplot2“) – es erscheint im Hilfefenster eine Übersicht, die unterhalb von DESCRIPTION zu den Vignetten verlinkt.

Viel Erfolg mit ihren R-Paketen! Wenn Sie für Ihre Projekte / Ihre Firma / Abteilung ein Paket erstellen möchten und dazu Unterstützung benötigen, stehe ich für einen Workshop gern zur Verfügung.