Pakete ---- Achtung, wird überarbeitet!

Ein wesentliches Merkmal von R ist die Erweiterbarkeit über Pakete. Neben den Paketen, die Sie über CRAN (offizielle Homepage des R-Projektes) auf Ihren Computer installieren können, ist es sicher hier und da hilfreich, eigene Pakete zu erstellen.
Die Installation der CRAN-Pakete wird in Einführung in R ausführlich beschrieben und wird hier nicht weiter behandelt.
Im Folgenden wird gezeigt, wie Sie ihr eigenes Paket unter der R-Version 2.11.0 “schnüren”  und wenn Sie es wünschen über CRAN der Allgemeinheit zur Verfügung stellen können. Wenn Sie diesen Weg in die Allgemeinheit gehen wollen, müssen die geschnürten Funktionen, Daten und Hilfedateien in englischer Sprache entwickelt und verfasst werden. Hier zählt besonders die “sprachliche Allgemeinverwendbarkeit”! Siehe auch hier zum Thema Allgemeinverwendbarkeit Einführung in R.
CRAN empfiehlt natürlich die Dokumentation zur Paketerstellung über die Konsole  (Hilfe -> HTML Hilfe) zu studieren. Nach dem Aufruf des Links Writing R Extensions... (Abb. 1)

Abb.1: Hilfe Writing R Extensions

... rufen Sie den Link Creating R packages auf und arbeiten sich durch das Themengebiet durch  (Abb. 2):

Abb. 2: Creating R packages

Im Folgenden wird die Paketerstellung an einem Demo-Beispiel beschrieben. Bevor Sie damit starten, sollten Sie die Systemvoraussetzung prüfen! Diese wird natürlich auch auf der Seite Writing R Extensions beschrieben.

Das Paketgrundgerüst mit den beiden Funktionen wird über die Funktion package.skeleton() erstellt:

package.skeleton(name = "demo", list = c("normalv", "anova_faes"))

Nach Return läuft R los und zeigt Ihnen folgende Meldung auf der Konsole (Abb. 4)...

Abb. 4: R-Rückmeldung

... und im Verzeichnis Eigene_Pakete wird das neue Paket-Verzeichnis demo (Abb. 5) angelegt:

Abb. 5: Das Verzeichnis demo

Unter dem Verzeichnis demo finden Sie neben den Verzeichnisse man und R die Datei DESCRIPTION, die das Grundgerüst für die Paketbeschreibung darstellt (Abb. 6):

Abb. 6: Verzeichnisstruktur demo

Bevor wir das Paketgrundgerüst mit weiteren Informationen füllen, schauen wir uns eine sinnvolle Variante der Erstellung an! In diesem Beispiel gehen wir davon aus, dass Sie dem Anwender Beispieldatensätze mit dem Paket zur Verfügung stellen möchten. Auch das ist denkbar einfach, Sie geben das Datenobjekt einfach im Funktionsaufruf mit an. In diesem Beispiel werden die Datenobjekte einfakt und zweifakt mitgegeben:

> einfakt <- read.csv2("Einf_ANOVA_Daten.csv")
> zweifakt <- read.csv2("Zweif_ANOVA_Daten.csv")

package.skeleton(name = "demo", list = c("normalv", "anova_faes", "einfakt", "zweifakt"))

Auch hier wird nach Return das Verzeichnis demo, aber zusätzlich mit dem Verzeichnis data, angelegt (Abb. 7):

Abb. 7: Verzeichnisstruktur demo mit Beispieldatsatz

Nun bauen wir das Paketgrundgerüst zum fertigen Paket aus! Dazu wird mit der DESCRIPTION-Datei gestartet. Diese Datei enthält eine Vorlage der notwendigen Information (Abb. 8) die Sie nicht ändern sollten, wie

• Paketbezeichnung (Package: demo)
• Objekttyp (Type: Package)

und Informationen, die Sie anpassen sollten:

• Title (eine kurze Beschreibung)
• Version
• Datum (Date)
• Autor (Author, wer hat das Paket entwickelt? Mehrere Autoren werden durch ein Komma getrennt)
• Pfleger des Paketes (Maintainer, e-mail-Adresse des hauptverantwortlichen Autors)
• Beschreibung (Description, Beschreibung des Paketes mit vielleicht mehr als einer Zeile)
• Lizenz (License, hoffentlich GPL version 2....!)
• LazyLoad: yes bedeutet, dass R-Objekte erst dann geladen werden, wenn sie benötigt werden.

Abb. 8: Grundgerüst der DESCRIPTION-Datei

In dieser Datei können noch weitere Informationen, wie z. B. Abhängigkeiten, abgelegt werden. Wenn z. B. ein bestimmtes Paket zur Funktion des Pakets demo notwendig ist, muss das Schlüsselwort Depends vorhanden sein:

• Depends: bestimmtes Paket, z. B. class
  oder eine bestimmtes R-Release
• Depends: R (>=2.11.0)

Für obiges Beispiel könnte die DESCRIPTION-Datei so aussehen (Abb. 9)...

Abb. 9: Ausgefüllte DESCRIPTION-Datei

... und steht Ihnen hier als Text-Datei zum Download zur Verfügung!

In dem Verzeichnis R werden die im Funktionsaufruf genannten Funktionen abgelegt (Abb. 10)...

Abb. 10: Verzeichnis R

... und im Verzeichnis data die Daten, die in dem Paket eingebunden werden sollen (Abb. 11):

Abb. 11: Verzeichnis data

Beide Verzeichnisse werden von uns nicht weiter betrachtet. Sie müssen nur unverändert vorhanden sein!
Im Verzeichnis man befindet sich das Dokumentationsgrundgerüst (Abb 12). Zu den einzelnen Funktionen und Datensätzen muss das jeweilige Gerüst gefüllt werden.

Abb. 12: Verzeichnis man

Die Dokumentationsanforderungen zwischen Funktionen und Datensätzen unterscheiden sich. Schauen wir uns beispielhaft zuerst die Beschreibung der Funktion anova_faes() an (Abb. 13):

Abb. 13: Ausschnitt Funktions-Dokumentation, Teil 1

Hinweis: Der blaue Text ist nur Kommentar und befindet sich nicht in der Datei!
Kopfinformationen der Hilfe-Dokumentation:

• \name{anova_faes}   Bezeichnung der Funktion
• \alias{anova_faes}    Identisch mit oben, oder die Bezeichnung weiterer Funktionen
                                  die hier beschrieben werden sollen (jeweils eigene alias-Zeile)
• \title{Überschrift}     Überschrift des Hilfetextes
• \description{Funktionsbeschreibung} Kurzbeschreibung der Funktion
• \usage{anova_faes(x, ...)} Funktionaufruf mit Übergabeobjekt und möglichen Argumenten
• \arguments{              Beschreibung der an die Funktion zu übergebende Argumente
        \item{x}             Beschreibung des Argumentest x
        \item{P}             Beschreibung des Argumentest x
        usw.
  }

Abb. 14: Ausschnitt Funktions-Dokumentation, Teil 2

• \details{
  Hier ist Platz für eine umfassende Funktionsbeschreibung als Ergänzung zum
  description-Teil. Also eine echte Unterstützung des Anwenders!
  }
• \value{
  Beschreibung der Funktionsrückgabe-Werte. Die Funktion anova_faes() gibt
  nur Informationen über cat() und print() zurück
  }
• references{
  Hier können Sie Hinweise auf Literaturstellen eingeben
  }
• \author{Autor}  Autoreninformationen: URLs werden als \url{http://www.faes.de}
                           und die Mail-Adresse als \email{kontakt@r-statistik.de} angegeben
• \note{
  Hier können Sie Notizen eingeben
  }
• \seealso{}   Hinweise/Verknüpfungen zu relevanter Hilfe

Abb. 15: Ausschnitt Funktions-Dokumentation, Teil 3

• \examples{
  Hier sollten Sie einen Beispielaufruf formulieren.....
  }

Abb. 16: Ausschnitt Funktions-Dokumentation, Teil 4

• \keyword{Schlüsselword 1}  Hier muss mindests ein R-Keyword eingegeben werden,
                                              damit die Funktion im R-Hilfesystem eingeordnet
                                              werden kann.
                                              Die möglichen Keywörter erhalten Sie über den Aufruf
                                              file.show(file.path(R.home("doc"), "KEYWORDS"))
                                              auf der Konsole.
• \keyword{Schlüsselword 2}  Es können mehrere Schlüsselwörter hinterlegt werden,
                                              allerdings immer mit einer eigenen Zeile!

Von Zeile 63 an bis zur Zeile 416 wird der Funktionscode aufgeführt. Dieser Code wurde gelöscht. Die Funktionsdokumentation anova_faes können Sie als Text-Datei zum Download laden.

Die Dokumentationsdatei-Bearbeitung für Datensätze gestaltet sich ein bisschen übersichtlicher. Dazu schauen wir uns das Gerüst zur Dokumentation des Datensatzes einfakt näher an (Abb. 17):

Abb. 17: Ausschnitt der Datensatzdokumentation einfakt, Teil 1

• \name{einfakt}    Hier wird von package.skeleton() der Name des Datensatzes
                             eingetragen
• \alias{einfakt}     Siehe name
• \doctype{data}   Der Datentyp wird durch package.skeleton() vorgegeben und darf
                             nicht geändert werden!
• \title{}                Die Datensatzbezeichnung
• \description{}     Beschreibung des Datensatzes (1 bis 5 Zeilen)
• \usage{data(einfakt)} Beschreibung, wie der Datensatz aufzurufen ist. Wird ebenfalls
                                   über die Funktion package.skeleton() eingetragen.
• \format{}            Innerhalb der Klammern wird das Format, ebenfalls durch die
                            Funktion package.skeleton() eingetragen. Schauen Sie sich den
                            Datensatz einfakt zur Kontrolle an!

Abb. 18: Ausschnitt der Datensatzdokumentation einfakt, Teil 2

• \details{}           Wenn nötig, können hier weitere Angaben zum Datensatz gemacht
                            werden.
• \source{}          Angabe der Datenquelle, z. B. als URL
• \refernences{}   Angaben weiterer Quellen oder Referenzen
• \examples{}      Angabe möglicher Beispiele
• \keyword{datasets}  Wird durch die Funktion package.skeleton() vorgegeben und
                                   darf nicht geändert werden.

Die Datensatzdokumentation einfakt können Sie als Text-Datei downloaden.

Als letzten Datei-Typ wird die demo-package-Datei bearbeitet. In diesem Beispiel wird sie nur grundlegend ausgefüllt...

Abb. 19: Die demo-package-Datei

... und die Read-and-delete-me-Datei aus dem demo-Verzeichnis gelöscht.

Nun wird es ernst! Vor der Paketerstellung wird die Fehlerfreiheit des Paketes geprüft. Dazu dient das R-Kommando check. Über die R-Konsole führen wir dazu mit der Funktion system() das Rcmd check demo aus (Abb. 20):

Abb. 20: Ausführung des Kommandos Rcmd check, Teil 1

Es sieht schon sehr positiv aus, wenn Sie bei Ihren versuchen ähnlich wie in Abb.21 gezeigt, ein OK-Meldung nach der anderen erhalten. Wenn Sie genau hinschauen, werden Sie in Abb. 21 auch eine Error- bzw. Warnmeldung finden. In diesem Fall stört sich die check-Anweisung an die Umlaute in den Funktionen! Wenn Sie also daran denken sollten, Ihr Paket der globalen R-Gemeinde zur Verfügung stellen zu wollen, sollte die Sprache englisch sein. Pakete, die an CRAN gesendet werden, müssen natürlich frei von Warnungen oder gar Fehlern sein. Prüfen Sie die Logbuchdateien im demo.Rcheck-Verzeichnis (Abb. 22)! Die letzte Zeile sagt aus, dass wir etwas wie ein Paket erstellt haben - aber natürlich sind wir ja noch beim Prüfen (check) (Abb. 21)....:

Abb. 21: Ausführung des Kommandos Rcmd check, Teil 2, Logbuch

Wir sind zufrieden und “bauen” nun endlich unser Paket! Dazu führen wir das Kommando build im Eingabeaufforderungs-Fenster (Abb. 23):

Abb. 23: Paketerstellung über build

Die Paketerstellung verlief positiv, das Paket demo_1.0.tar.gz wurde erstellt (Abb. 24)...

Abb. 24: Paketerstellung über build verlief erfolgreich!

... und im Verzeichnis Eigene_Pakete abgelegt (Abb. 25):

Abb. 25: Paketdatei demo_1.0.tar.gz

Bevor Sie nun das Paket in Ihre R-Umgebung einbinden können, muss es noch ins Windowsformat gewandelt werden. Hier sind wir auf fremde Hilfe angewiesen! Diese Hilfe wird von der Uni Dortmund (Uwe Ligges) über den Link http://win-builder.r-project.org/ zur Verfügung gestellt und besteht aus einem Server der die Dateiwandlung vornimmt (Abb. 26). Laden Sie die Datei in das Verzeichnis R-release des Servers ...

Abb. 26: Server der Uni Dortmund, hochgeladene Datei demo_1.0.tar.gz

... und nach kurzer Zeit erhalten Sie ein automatisches Mail mit Informationen zur gewandelten Datei  (Abb. 27):

Abb. 27: Automatische Mail vom Wandlungsserver

Klicken Sie auf den Link im obigen Mail (Abb. 27) und speichern Sie die Datei in dem gewünschten Verzeichnis (Abb. 28):

Abb. 28 Paket und Logbücher auf dem Server

Dann können Sie wie bekannt, das Paket installieren (siehe Einführung in R). Hier wird wegen der Vollständigkeit das in die Hilfe eingebundene Paket gezeigt (Abb. 29):

Abb. 29: Paket in der R-Hilfe eingebunden

Hat der Inhalt Ihnen weitergeholfen und Sie möchten diese Seiten unterstützen?