Com fer un package amb Windows, un exemple complet

Avuí farem un paquet amb una funció senzilla per a fer un exemple. El paquet es dirà ‘GridPlot’.  Suposo que si esteu llegint aquesta tutoria ja teniu unes funcions fetes, però sinó aquí també farem un exmple mínim d’una funció amb R.

1)      Obrim una sessió nova d’R amb el teu IDE preferit.
2)      Fem una funció que fa alguna cosa mig-útil:

grplot <- function(gr.col="white",
gr.lty=1,
gr.lwd=1,
grv.at=axTicks(side=1),
grh.at=axTicks(side=2),
xaxsi=TRUE,
yaxsi=TRUE){
if (xaxsi==TRUE) par("xaxs"="i")
if (yaxsi==TRUE) par("yaxs"="i")
plot(...) # una manera barata de fixar par("usr")
rect(par("usr")[1],par("usr")[3],par("usr")[2],par("usr")[4],col=bg.col)
abline(v=grv.at,col=gr.col)
abline(h=grh.at,col=gr.col)
par(new=TRUE)
plot(...)
}

grplot() fa exactament el mateix que plot(), però li dona un fons gris i una malla de referència blanca per defecte, i posa els límits dels eixos x i y exactes  (par(“xaxs”=”i”))  per defecte, en lloc del que l’R posa per defecte que és un buffer del 4%.  Es a dir, només canviem els defectes, segurament es pot fer millor!

Un exemple:

set.seed(53)
grplot(1:10,
sort(rnorm(10)),
col="green",
type='l',
ylim=c(-2,2),
main="plot() amb fons de malla semblat al ggplot2")
lines(1:10,sort(rnorm(10)),col="blue")

 

Segurament tingeu coses més series! Ara volem fer el package… Es a dir, ara comença el treball.

3)      Utilitzem la funció package.skeleton(), per a començar. (Has de primer enviar grplot a R per a què sàpiga que és). Name es el nom del package, i list es un vector de noms d’objectes (funcions  i/o dades).

package.skeleton(name="GridPlot",list=c("grplot"))

package.skeleton() ens farà una carpeta al directori de treball. Fes getwd() si no saps quin és el teu directori de treball. Aquesta carpeta tindrà el nom del package, ‘GridPlot’, i tindrà uns quants elements. Mirem:

Tenim 2 carpetes, ‘man’ i ‘R’, i despres 3 fitxers., DESCRIPTION, NAMESPACE i Read-and-delete-me.

4) Obrim DESCRIPTION amb qualsevol editor de text. Normalment es pot fer al mateix programa que utilitzis per a R. El fitxer tindrà el seguent:

Package: MyPackage
Type: Package
Title: What the package does (short line)
Version: 1.0
Date: 2011-11-07
Author: Who wrote it
Maintainer: Who to complain to
Description: More about what it does (maybe more than one line)
License: What license is it under?

Serà evident que s’ha de canviar! Posem tot:

Package: GridPlot
Type: Package
Title: grplot- draw a grid and plot on top of it.
Version: 1.0
Date: 2011-11-07
Author: Tim Riffe, RUGBCN
Maintainer: Tim Riffe
Description: grplot put a grid behind the plot rather than on top of it. It has a few friendly defaults.
License: GPL-2

Pots ser més o menys específic segons el teu gust. Val la pena investigar els tipus de llicencies. Guarda’l.

5) Deixa NAMESPACE. Pots llegir i borrar Read-and-Delete-me. Ara, mirem dins de la carpeta ‘R’. Conté un fitxer .R per a cada funció que vam incloure amb l’argument list al package skeleton. Ara només tenim un fitxer: grplot.R. Conté només la definció de la funció. No cal canviar res amb aquest fitxer, i de fet, pots ignorar la carpeta ‘R’ totalment.

6) Es la carpeta ‘man‘ la que dona més feina! Dins de ‘man‘ trobes un fitxer .Rd per a cada funció (i si a cas, dades) que vas incloure amb l’argument list més un fitxer -package.Rd. Un fitxer .Rd es un fitxer de help amb R. Així, quan tens el package carregat y fas ?grplot et soritrà els detalls de help. Nosaltres tenim llavors grplot.Rd i GridPlot-package.Rd.També els obrim amb el editor de text. Amb grplot.Rd veuràs:

\name{grplot}
\alias{grplot}
%- Also NEED an '\alias' for EACH other topic documented here.
\title{
%% ~~function to do ... ~~
}
\description{
%% ~~ A concise (1-5 lines) description of what the function does. ~~
}
\usage{
grplot(..., bg.col = "#EBEBEB", gr.col = "white", gr.lty = 1, gr.lwd = 1, grv.at = axTicks(side = 1), grh.at = axTicks(side = 2), xaxsi = TRUE, yaxsi = TRUE)
}
%- maybe also 'usage' for other objects documented here.
\arguments{
\item{\dots}{
%% ~~Describe \code{\dots} here~~
}
\item{bg.col}{
%% ~~Describe \code{bg.col} here~~
}
\item{gr.col}{
%% ~~Describe \code{gr.col} here~~
}
\item{gr.lty}{
%% ~~Describe \code{gr.lty} here~~
}
\item{gr.lwd}{
%% ~~Describe \code{gr.lwd} here~~
}
\item{grv.at}{
%% ~~Describe \code{grv.at} here~~
}
\item{grh.at}{
%% ~~Describe \code{grh.at} here~~
}
\item{xaxsi}{
%% ~~Describe \code{xaxsi} here~~
}
\item{yaxsi}{
%% ~~Describe \code{yaxsi} here~~
}
}
\details{
%% ~~ If necessary, more details than the description above ~~
}
\value{
%% ~Describe the value returned
%% If it is a LIST, use
%% \item{comp1 }{Description of 'comp1'}
%% \item{comp2 }{Description of 'comp2'}
%% ...
}
\references{
%% ~put references to the literature/web site here ~
}
\author{
%% ~~who you are~~
}
\note{
%% ~~further notes~~
}
%% ~Make other sections like Warning with \section{Warning }{....} ~
\seealso{
%% ~~objects to See Also as \code{\link{help}}, ~~~
}
\examples{
##---- Should be DIRECTLY executable !! ----
##-- ==> Define data, use random,
##-- or do help(data=index) for the standard data sets.
## The function is currently defined as
function (..., bg.col = "#EBEBEB", gr.col = "white", gr.lty = 1,
gr.lwd = 1, grv.at = axTicks(side = 1), grh.at = axTicks(side = 2),
xaxsi = TRUE, yaxsi = TRUE)
{
if (xaxsi == TRUE)
par(xaxs = "i")
if (yaxsi == TRUE)
par(yaxs = "i")
plot(...)
rect(par("usr")[1], par("usr")[3], par("usr")[2], par("usr")[4],
col = bg.col)
abline(v = grv.at, col = gr.col)
abline(h = grh.at, col = gr.col)
par(new = TRUE)
plot(...)
}
}
% Add one or more standard keywords, see file 'KEYWORDS' in the
% R documentation directory.
\keyword{ ~kwd1 }
\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line

Està escrit amb una llengua semblant al LaTeX. No es difícil. Ens ha fet uns quants camps que cal omplir. Jo vaig posar això:

\name{grplot}
\alias{grplot}
\title{
A function to plot over a gridded background. Defaults to exact plot region limits rather than the default 4% expansion.
}
\description{
All arguments are the same as for \code{plot()}, except a few optional parameters to conrol the appearance of grid lines, the background color, and the plot region dimensions.
}
\usage{
grplot(..., bg.col = "#EBEBEB", gr.col = "white", gr.lty = 1, gr.lwd = 1, grv.at = axTicks(side = 1), grh.at = axTicks(side = 2), xaxsi = TRUE, yaxsi = TRUE)
}
\arguments{
\item{\dots}{
arguments to pass to \code{plot()}. Minimally, you must include \code{x}.
}
\item{bg.col}{
the background color for the plot region. Defaults to \code{"#EBEBEB"}, a light grey color.
}
\item{gr.col}{
the grid lines color. Defaults to \code{"white"}
}
\item{gr.lty}{
the grid line type. Defaults to \code{1}
}
\item{gr.lwd}{
the grid line width. Defaults to \code{1}
}
\item{grv.at}{
optional. a vector of x coordinates of the vertical grid lines, in case. Default uses \code{axTicks()}
}
\item{grh.at}{
optional. a vector of x coordinates of the horizontal grid lines, in case. Default uses \code{axTicks()}
}
\item{
xaxsi, {yaxsi}}{logical. Should \code{par("xaxs"="i")} so that no padding is added to the x and y axes? Default = \code{TRUE}. If \code{FALSE} the plot will be like a normal plot.
}
}
\details{
arguments to pass to \code{plot()} recognize order as they normally would, so you don't need to specify them by name unless you normally would.
}
\value{
a plot is drawn, nothing is returned.
}
\author{RUGBCN}
\seealso{
\code{\link{plot}}
}
\examples{
set.seed(53)
grplot(1:10,
sort(rnorm(10)),
col="green",
type='l',
ylim=c(-2,2),
main="plot() amb fons de malla semblat al ggplot2")
lines(1:10,sort(rnorm(10)),col="blue")
}
\keyword{hplot}

Escrius el titol de la pàgina d’adjuda per aquesta funció, i li dones una descripció més llarga. Descrius cada argument amb tota la informació que fa falta per a saber de que consisteix l’argument. Fixa’t amb les convencions d’R! \code{} és al marcador per a posar text amb el font de codi al help. Com més exemples donis, és més probable que la gent faci servir el teu package :-), I menys correus rebràs amb preguntes. Ara, fem el mateix amb el fitxer GridPlot-package.Rd. Jo vaig posar això:

\name{GridPlot-package}
\alias{GridPlot-package}
\alias{GridPlot}
\docType{package}
\title{
\code{grplot}, it’s \code{plot} but with a gray background and gridlines.
}
\description{
This package contains just the function \code{grplot}. It is identical to \code{plot}, save for a few defaults. It gives a background color, some grid lines at the axis ticks, and defaults to exact x and y limits.
}
\details{
\tabular{ll}{
Package: \tab GridPlot\cr
Type: \tab Package\cr
Version: \tab 1.0\cr
Date: \tab 2011-11-07\cr
License: \tab GPL-2\cr
}
}
\author{
RUGBCN
Maintainer: RUGBCN
}
\keyword{ package }
\keyword{ hplot}
\seealso{
\link[graphics]{plot}
}
\examples{
set.seed(53)
grplot(1:10,
sort(rnorm(10)),
col="green",
type='l',
ylim=c(-2,2),
main="plot() amb fons de malla semblat al ggplot2")
lines(1:10,sort(rnorm(10)),col="blue")
}

Per a més informació sobre la redacció de manuals amb els fitxers .Rd, mira aquest document

7) Ara tenim tot preparat, però falta una eina: Rtools. Cal baixar i instal•lar la versió més recent d’aquí: Durant la instal•lació, Veuràs uns quants pasos genèrics, fem ‘Next’ uns 3 cops. Arribes a ‘Select Components’, amb 4 caixetes preseleccionats (R toolset, Cygwin DLLs, MinGW compilers and tools, x64 MinGW compilers)- això deixem i fem ‘Next’. Ara veurem aquesta plana:

Selecciona les 2 caixetes! (pot ser no tens el MikTex- no fa falta, ignora la part de MikTex).

Ara, cal posar manualment una altra línia per a salvar-nos problemes després. Posem la ruta d’arxiu a la nostre instal·lació d’R: ‘C:\Program Files\R\R-2.14.0\bin\’, per a mi. No oblidis de posar el ‘;’ al final de la penúltima entrada. Per estar segur és així:

‘Next’, ‘Install’ – dura un moment… ‘Finish’ .
8) Ara utilitzarem el ‘dos prompt’ per a compilar el package. La part final! Fes click sobre ‘Inici’, i al buscador posa ‘cmd’. Sortirà cmd.exe com a opció i l’obrim. Cal navegar al directori que contingui GridPlot. Para mi es E:\CODE\

Després posem R CMD build GridPlot
R CMD build es fa sempre. Però aixó ens fa només el ‘treball’, el fitxer que acabi amb ‘tar.gz’ al mateix directori que GridPlot. (Mira’l està!) . Normalment amb Windows es posa la opció -binary, i ens faría el .zip necesari per a Windows, però avui em sorten errors! Fem un hack petit (de fet es un hack conegut per si vols fer un package per a Windows des de Mac o Linux…):

mkdir tempdir
R CMD INSTALL -l tempdir GridPlot_1.0.tar.gz
cd tempdir
zip -r GridPlot GridPlot

Ara trobaràs el package amb format .zip a un directori que es diu tempdir al teu directori de treball (tu sabràs on l’has posat). Per a mi, es aqui: E:\CODE\tempdir\
Ja estem!

9) De fet, ja tens el package instal·lat, però per a fer una installació local a Windows a un altre sistema fas: utils:::menuInstallLocal() i et soritrà una finestra de navegació. Si vols compartir el package amb usuaris de Mac o Linux, voldran l’arxiu GridPlot_1.0.tar.gz.

10) Ara, cal reconèixer que el pas 8 normalment es molt frustrant, precisament per la documentació. R CMD fa moltes proves, i tot ha d’estar escrit perfectament. Quan et sorti un error, normalment et dirà amb quin fitxer i on has fet l’error. Si tens molts fitxers .Rd això pot durar molt. Aquí, clar, tenim un exemple que funciona, però normalment és un procés bastant iteratiu! Bona sort!

Tim, RUGBCN
*He fet aquesta tutoria utilitzant una màquina amb Windows 7 Enterprise, 64bit i el R-2.14.0.