Ein eigenes R-Paket in zwei Minuten erstellen mit RStudio

Dank der Unterstützung durch RStudio (die kostenlose Desktop-Version reicht vollkommen aus) kann man in wenigen Minuten ein eigenes R-Paket erstellen.

Dieser Beitrag ist die Fortsetzung zu: Eigene R-Pakete erstellen: Warum und wann?

R-Paket als RStudio-Projekt

RStudio bietet die Möglichkeit, Projekte anzulegen. Das ist auch sinnvoll, wenn man kein Paket erstellen will: Man erhält dann für jedes Thema, an dem man arbeitet, eine separate Arbeitsumgebung (Environment, R-Objekte wie Daten, Vektoren, eigene Funktionen, …) und eine separat verwaltete History (Befehls-Geschichte); zudem kann man mit Strg + Shift + F („Find in Files“) alle Dateien nach Stichworten durchsuchen, die zu einem Projekt gehören.

Hier geht es uns jedoch ausdrücklich um ein R-Paket: Auch dazu empfiehlt sich ein RStudio-Projekt. Rechts oben, knapp unterhalb des „X“ zum Schließen, befindet sich ein kleiner Pfeil, daneben steht (wenn man gerade kein Projekt geöffnet hat): Project: (None). Diesen Pfeil können wir aufklappen …

Neues Projekt erstellen in RStudio: Pfeil neben Project: (None) aufklappen

… und den ersten Eintrag New Project auswählen. Je nachdem, ob wir schon einen Ordner vorbereitet haben, wählen wir New Directory (legt ein neues Verzeichnis an) oder Existing Directory (wählt ein vorhandenes Verzeichnis aus).

Neues Projekt in RStudio: New Directory (in neuem Verzeichnis anlegen)

Ich entscheide mich hier für New Directory, um einen ganz frischen Anfang zu machen. Als Projekttyp wählen wir R Package.

Projekttyp in RStudio auswählen: R Package

Man könnte hier alternativ ein Grundgerüst für eine Shiny Web Applikation erstellen oder eine der Varianten für ein Paket mit C++ – Elementen über Rcpp auswählen. Wir bleiben bei der einfachen Variante R Package.

Im folgenden Fenster können wir einen Namen vergeben, ggf. bereits bestehende R-Skripte einbinden, ein Hauptverzeichnis angeben, Versionsverwaltung (Git repository) und packrat aktivieren.

Versionsverwaltung (git) und packrat in R-Projekten

Mit der Versionsverwaltung kann man ältere Projektstände wiederherstellen, detailliert Unterschiede zwischen definierten Projektständen vergleichen etc. RStudio unterstützt git, das jedoch separat installiert werden muss (kostenlos möglich).

packrat stellt einem Projekt einen eigenen Ordner für andere R-Pakete zur Verfügung, die man im Projekt mit verwenden will. Das ist vor allem dann hilfreich, wenn man projektspezifisch bestimmte Paket-Versionen halten will (und speziell Schwierigkeiten durch Paket-Updates vermeiden will), während die eigentliche R-Installation unabhängig davon Paket-Updates mitmachen darf.

Inzwischen gibt es ein Nachfolgepaket, das praxistauglicher sein soll: renv. Es soll demnächst in RStudio integriert werden.

Wir wollen es hier simpel halten und verzichten auf Versionsverwaltung und auf packrat.

Erstes R-Paket: Minimale Ordnerstruktur

Wenn wir das Paket erstellen, erhalten wir folgende Dateien – die minimal notwendige Ordnerstruktur:

Minimale Ordner- und Dateistruktur eines R-Pakets in RStudio
  • .Rbuildignore beschreibt Dateien, die nicht ins komprimierte Paket übernommen werden.
    Empfehlung: Nicht per Hand füllen (Vorsicht: reguläre Ausdrücke / regular expressions), sondern usethis::use_build_ignore() verwenden. Das Paket usethis wird gemeinsam mit devtools geladen: library(devtools).
  • DESCRIPTION enthält Metadaten wie Autor, Kontaktadresse des Autors, Paket-Version, Lizenz, Abhängigkeiten zu anderen Paketen, etc. Reine Textdatei, die zum Teil mit usethis-Funktionen gefüllt werden kann (z. B. use_mit_license() für eine MIT-Lizenz), zum Teil manuell bearbeitet werden kann (z. B. Autor, eventuelle Co-Autoren; Kurzbeschreibung).
  • xxx.Rproj (hier: MeinErstesPaketr.Rproj): RStudio-Systemdatei zur Projektverwaltung.
  • NAMESPACE: regelt Zusammenarbeit mit anderen Paketen, etwa bei gleich benannten Funktionen (z. B. „filter“ in dplyr und stats).
    Empfehlung: Nicht per Hand füllen, sondern das Paket roxygen2 verwenden, das die Dokumentation von R-Paketen sehr erleichtert.
  • Ordner: man für die Hilfe-Dateien (manual), R für die R-Skripte.

Mit diesen wenigen Klicks haben wir bereits ein R-Paket erstellt – zumindest die Quelldateien. In einem R-Projekt, das als Paket definiert ist, steht uns in RStudio neben Environment / History / Connections ein weiterer Reiter zur Verfügung: Build. Darunter finden wir die Schaltfläche Install and Restart. Klicken – kurz warten – fertig ist das R-Paket!

Der Reiter Build enthält die Schaltfläche Install and Restart, mit der das Paket installiert und in einer neuen R-Session geladen werden kann.

Was steckt in dem RStudio-R-Paket?

Wir haben es uns sehr leicht gemacht – RStudio hat ein Beispielpaket erstellt, wir mussten keine eigene R-Funktion schreiben. Die Funktion, die das Paket bereitstellt, enthält die berühmten Worte:

> hello()
[1] "Hello, world!"

Wir haben allerdings ein Grundgerüst, das wir bearbeiten können – mit ein paar nützlichen Infos:

R-Code für die Beispielfunktion hello()

Der Link ist allerdings stand heute (März 2020) nicht mehr aktuell – empfehlenswert ist die zweite Auflage des Buches zu R-Paketen, die Hadley Wickham gemeinsam mit Jenny Bryan verfasst und die dauerhaft online kostenlos lesbar ist: https://r-pkgs.org/ . (In Buchform gibt es bisher nur die erste Auflage. Da sich seitdem viel an den Paketen geändert hat, die die Paket-Entwicklung unterstützen, kann ich die erste Auflage nicht mehr empfehlen.)

Was hier fehlt, sind die roxygen2-Kommentare, die die Hilfe zu der Funktion erstellen – Thema für einen weiteren Beitrag. Eine rudimentäre Hilfe selbst ist jedoch vorhanden, wie die Eingabe von ?hello in die Konsole beweist. Empfehlenswert ist jedenfalls, .Rd-Dateien wie diese (im Ordner man) nicht per Hand zu füllen:

Die Hilfe zur hello()-Funktion: Eine .Rd-Datei. Empfehlung: roxygen2-Kommentare nutzen und die .Rd-Datei automatisiert erstellen lassen.

Viel Erfolg mit ihren eigenen R-Paketen! Wer dabei Unterstützung benötigt, kann gern einen Workshop anfragen. Mit Workshops per Video habe ich schon gute Erfahrungen gemacht.