Pakete

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)

CRAN_Paket_Hilfe

Abb.1: Hilfe Writing R Extensions

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

CRAN_Paket_Hilfe_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.

Pakete bestehen aus einem Paket-Verzeichnis, welches den Paket-Namen trägt, und Unterverzeichnisse. Deswegen ist es sinnvoll, die Paketerstellung von einem “Eigene_Pakete”-Verzeichnis aus durchzuführen (Abb. 3). Achten Sie darauf, dass sich in dem Verzeichnisnamen keine Leerstellen und Umlaute befinden!

Wenn Sie nun das R-Arbeitsverzeichnis auf dieses Verzeichnis einstellen (Menü: Datei -> Verzeichnis wechseln...), werden Sie Ihre Paketverzeichnisse direkt wieder finden!

In diesem Beispiel erstellen wir das Paket “demo” mit den Funktionen anova_faes und normalv erstellen (Siehe hier!).

Dazu laden wir die Funktionen anova_faes und Normalverteilung in die R-Arbeitsumgebung.

Pakete_Abb3

Abb. 3: Paket-Verzeichnis

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)...

Pakete_Abb4

Abb. 4: R-Rückmeldung

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

Pakete_Abb5

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):

Pakete_Abb6

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):

Pakete_Abb7

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.
Pakete_Abb8

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)...

Pakete_Abb9

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)...

Pakete_Abb10

Abb. 10: Verzeichnis R

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

Pakete_Abb11

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.

Pakete_Abb12

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):

Pakete_Abb13

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.
    }
Pakete_Abb13

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
Pakete_Abb13b

Abb. 15: Ausschnitt Funktions-Dokumentation, Teil 3

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

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):

Pakete_Abb16

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!
Pakete_Abb17

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...

Pakete_Abb18

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):

Pakete_Abb19

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)....:

Pakete_Abb20

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

Wie schon erwähnt, schauen Sie sich die Dateien des Rcheck-Verzeichnisses, insbesondere wenn Sie Warn- oder Fehlermeldungen erhalten haben. Die Datei 00check.log  beinhaltet die Konsolen-Ausgabe und die Datei 00install.out enthält weitere Informationen. Beide Dateien verdienen Ihre Aufmerksamkeit (Abb. 22)!

Pakete_abb20b

Abb. 22: Das demo.Rcheck-Verzeichnis

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

Pakete_Abb22

Abb. 23: Paketerstellung über build

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

Pakete_Abb23

Abb. 24: Paketerstellung über build verlief erfolgreich!

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

Pakete_Abb24

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 ...

Pakete_Abb25

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):

Pakete_Abb26

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):

Pakete_Abb27

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):

Pakete_Abb28

Abb. 29: Paket in der R-Hilfe eingebunden

Das erstellte Paket kann unter Berücksichtigung der oben erwähnten Punkte per FTP zum CRAN-Server geschickt werden (ftp://cran.r-project.org/incoming/ , anonym, Abb. 30):

Seitenanfang
Pakete_Abb29

Abb. 30: Cran-Paketeingangsserver

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

Impressum      Datenschutz
 

Version vom 17.11.2018