GNU R: Eigene Zusatzpakete erstellen

R wird von einer großen Anzahl von Freiwilligen weiter auf- und ausgebaut.

Es besteht die Möglichkeit, sich mit selbsterstellten Funktionen und/oder Datensätzen am Aufbau zu beteiligen. Die gängigste Methode ist, seine Daten in einem eigenen Zusatzpaket zu bündeln, und dieses dann über das CRAN der Allgemeinheit zugängig zu machen.

Paket erstellen

Bearbeiten

Um die Daten und Funktionen zu einem Paket zu bündeln steht die Funktion package.skeleton() zur Verfügung. Sie erstellt die erforderlichen Unterverzeichnisse des Pakets, legt die Daten und Funktionen in eben diesen ab und generiert Dummy-Dateien zur Dokumentation.


Die Paketverzeichnisse

Bearbeiten

Ein Paket besteht aus einem Hauptverzeichnis (welches den Namen des Pakets haben sollte) und mehreren Unterverzeichnissen. Die benötigten Paket-Unterverzeichnisse werden von package.skeleton() automatisch angelegt.

Die Inhalte der Verzeichnisse werden im Folgenden dargestellt:

Hauptverzeichnis:

  • DESCRIPTION: Diese Datei gibt eine Beschreibung des Pakets. Das Format ihres Inhalts ist vorgegeben. Da mit package.skeleton() eine Dummy-DESCRIPTION-Datei angelegt wird, müssen die Inhalte nur noch entsprechend ausgefüllt bzw. ergänzt werden.
Package: (Name des Pakets)
Type: Package
Version: (Paketversion, z.B. 1.3)
Date: (Datum des Erstellens, z.B. 2007-06-02)
Author: (Liste der Autoren, mit Kommata getrennt)
Maintainer: (Name des Hauptautors und dessen E-Mail-Adresse)
Depends: R (>= 2.4.0), PKGNAME (R-Version und andere benötigte Zusatzpakete)
Description: (Eine kurze Beschreibung des Pakets, Sinn und Zweck)
License: GPL version 2 or newer
URL: (einen oder mehrere Links)

Unterverzeichnisse:

  • data: In diesem Verzeichnis befinden sich die Datensätze, die in dem Paket enthalten seien sollen.
  • man: Hier befinden sich alle Dokumentationen im "R Dokumentationformat (Rd)". Dokumentationen sollten für alle Datensätze und Funktionen des Pakets erstellt werden.
  • R: In diesem Verzeichnis befinden sich die Funktionen des Pakets.

Dokumentation schreiben

Bearbeiten

Dokumentationen werden im "R Documentation"-Format geschrieben. Dies ist eine ASCII-Datei, welche die Dateiendung ".Rd" besitzt und ins man-Verzeichnis gelegt wird. Wie bereits oben beschrieben, legt die Funktion package.skeleton() Dummy-Dokumentations-Dateien zu allen Objekten, Daten und Funktionen an, welche mit dem Paket gebündelt werden sollen. Sie müssen "lediglich" noch mit den passenden Infos erweitert werden.

Dokumentation zu datasets

Bearbeiten

Jeder Datensatz muss eine Dokumentationsdatei besitzen. Diese ist wie folgt aufzubauen:

\name{DATENSATZNAME}       # hier wird der Name des Datensatzes eingetragen
\docType{data}             # hier muss bei datasets immer data eingetragen werden.
\title{KURZBESCHREIBUNG}   # hier kommt eine kurze Überschrift der Daten hin
\description{BESCHREIBUNG} # hier kommt eine kurze Beschreibung über die Daten hin.
\usage{DATENAUFRUF}        # hier wird beschrieben, wie die Daten aufzurufen sind 
                             (dies ist meist der Name des Datensatzes).
\format{FORMAT}            # hier wird das Datenformat eingetragen, also z.B. vector, matrix, data frame
                             bei Matrizen und Data frames sollte eine Beschreibung der Zeilen und 
                             Spalten gegeben werden.
\references{QUELLEN}       # hiermit können Literaturangaben angegeben werden.
\source{QUELLE}            # hier wird eingetragen, woher die Daten stammen (Originalquelle)
\keyword{datasets}         # hier muss bei datasets immer datasets eingetragen werden.

Dokumentation zu Funktionen

Bearbeiten

Jede Funktion sollte im man-Verzeichnis eine eigene Dokumentationsdatei erhalten. Diese ist wie folgt aufzubauen:

\name{FUNKTIONSNAME}       # hier wird der Name der Funktion eingetragen
\alias{ALIASNAME}          # Falls mehrere Funktionen auf dieselbe Help-Seite verweisen
                             werden diese hier mit je einer alias-Zeile aufgelistet
\title{KURZBESCHREIBUNG}   # hier kommt eine kurze Überschrift der Funktion hin
\description{BESCHREIBUNG} # hier kommt eine kurze Beschreibung über die Funktionsweise
                             der Funktion hin.
\usage{FUNKTIONSAUFRUF}    # hier wird beschrieben, wie die Funktion aufzurufen ist.
                             z.B.: function(argument1, argument2, ...)
\arguments{                # hier werden die Argumente, die übergeben werden können,
    \item{ARGUMENT1}         durch die Aufzählung "item" beschrieben.
    \item{ARGUMENT2}
}
\details{DETAILS}          # hier kommt eine exakte Beschreibung hin, welche den "description"
                             -Part ergänzt und erweitert.
\references{QUELLEN}       # hiermit können Quellenangaben angegeben werden.
\note{NOTIZ}               # hier können Notizen eingetragen werden.
\author{AUTOR}             # Informationen über die Autoren. URLs und E-Mail können innerhalb
                             per \url{http://www.foo.bar} und \email{e@mail.de} angegeben werden
\examples{BEISPIELE}       # innerhalb der Klammern können Beispielaufrufe formuliert werden.
\keyword{keyword1}         # Hier muss mindestens ein R-Keyword gesetzt werden. Für eine Übersicht
\keyword{keyword2}         # an Keywords tippen Sie ein: file.show(file.path(R.home("doc"), "KEYWORDS"))

Dokumentation zum Paket

Bearbeiten

Im Gegensatz zu Datensätzen und Funktionen muss die Dummy-Dokumentations-Datei zur Paketdokumentation mit dem Befehl promptPackage() angelegt werden. Die einzig geforderte Angabe innerhalb dieser Datei ist:

\docType{package}          # das "package" muss so stehen bleiben!

Paket überprüfen und fertig stellen

Bearbeiten

Wenn man alle oben aufgeführten Schritte durchgeführt hat, ist es an der Zeit, das Paket fertigzustellen. Bevor dies geschieht, muss das Paket allerdings noch auf Fehler überprüft werden. Dies geschieht in der Shell. Man geht hierzu in das Verzeichnis, in welchem das Hauptverzeichnis des Pakets (als Unterverzeichnis) liegt, und tippt in die Shell den folgenden Befehl ein:

R CMD check PAKETNAME

Da das Paketverzeichnis den Namen des Pakets tragen sollte (s.o.), weiss das Script, wo es nach Daten suchen muss. Nun wird das Paket auf mögliche Fehler hin überprüft. Es ist wichtig, dass man erst weiter arbeitet, wenn diese Routine fehlerfrei durchläuft!!!

Ist die Überprüfung fehlerfrei verlaufen, kann das Paket zu einer tar.gz-Datei geschnürt werden. Hierzu gibt man in die Shell ein:

R CMD build PAKETNAME

Das Script holt sich die passenden Versions-Informationen aus der DESCRIPTION-Datei, so dass die tar-Datei (entsprechend der Version) automatisch als z.B. PKGNAME_1.12.tar.gz erstellt wird.

Paket zum CRAN hochladen

Bearbeiten

Das fertige Paket kann nun per FTP zum CRAN hochgeladen werden. Die URL lautet:

Mit der als Passwort angegebenen Adresse muss dann eine Info-Mail an cran@r-project.org gesendet werden. Das Paket wird zunächst auf mögliche Fehler überprüft und anschließend dem CRAN hinzugefügt.

Bearbeiten


Inhaltsverzeichnis

Bearbeiten