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
BearbeitenUm 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
BearbeitenEin 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:
|
|
Unterverzeichnisse:
|
Dokumentation schreiben
BearbeitenDokumentationen 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
BearbeitenJeder 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
BearbeitenJede 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
BearbeitenIm 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
BearbeitenWenn 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
BearbeitenDas fertige Paket kann nun per FTP zum CRAN hochgeladen werden. Die URL lautet:
- ftp://cran.R-project.org/incoming/
- Username: anonymous
- Passwort: (Ihre E-Mail-Adresse)
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.
Weblinks
Bearbeiten
InhaltsverzeichnisBearbeiten
|