Creación de paquetes de R en Windows (y Linux)

Francesc Carmonafcarmona@ub.edu

Departamento de EstadísticaUniversidad de Barcelona

Marzo 2013

El proceso para escribir paquetes de R se describe con todo detalle en el manual Writing R extensions (WRE) del R Core Team y que se puede ver en el Comprehensive R Archive Network (CRAN). Un manual más sencillo es Creating R Packages: A Tutorial de Friedrich Leisch. Sin embargo, en este documento se pretende concretar y hacer comprensible el proceso de creación de un paquete de R en el entorno Windows y para usuarios no expertos.

Aunque es posible añadir código en un lenguaje de bajo nivel (como C/C++/Fortran), vamos a centrarnos únicamente en el empaquetado de código y datos en R.

R fue diseñado en un entorno Unix que incluye un conjunto de herramientas como compiladores, utilidades de programación y rutinas de consola (text-formating routines). De entrada Windows carece de estos componentes, de forma que deberemos descargar e instalar algunos programas de software libre equivalentes a los de Unix.

Aunque se puede crear un paquete únicamente desde la consola de R y la consola del sistema, es preferible utilizar un programa como RStudio que nos facilitará algunas tareas.

¿Porqué crear un paquete de R?

Algunas de las principales razones son:

1. En primer lugar, crear un paquete nos obligará a pulir nuestras funciones, datos y código y, sobre todo, a documentar todo el trabajo y dar ejemplos claros. Las funciones serán más fáciles de usar y podremos utilizar el comando ? para ver detalles de los parámetros, los resultados y ejemplos.

2. Es el modo más elegante de compartir su trabajo. Los posibles usuarios del paquete agradecerán el esfuerzo de mejora y documentación que requiere la creación de un paquete. El intercambio con los usuarios también favorece la mejora del código.

3. Es la forma establecida para contribuir al crecimiento de R.

Instalación de los programas que le faltan a Windows

Se necesitan las siguientes componentes:

1. Un conjunto mínimo de utilidades tipo Unix (las llamadas Rtools) de Brian Ripley y que ahora mantiene Duncan Murdoch.

2. Algunos compiladores GNU reunidos en MinGW-w64 (necesarios únicamente si su paquete contiene código C, Fortran o C++). El compilador de Perl ya no es necesario para nada.

1

3. El compilador de la ayuda HTML de Microsoft.4. Una versión del procesador de textos TeX (como MiKTeX para Windows).

La obtención de las dos primeras componentes se hace directamente del CRAN. En nuestro mirror preferido hacemos Download R for Windows y Rtools, para seleccionar el ejecutable RtoolsXX.exe más actual.

Figura 1: Instalación de las Rtools.

Al instalar este archivo optaremos por la Package authoring installation.Se aconseja mantener los nombres de las carpetas de instalación o recordar las que modifiquemos por si debemos introducirlas en la variable PATH. El programa de instalación nos ofrece la posibilidad de modificar automáticamente la variable PATH. Es razonable aceptar el ofrecimiento.

También es recomendable, aunque no imprescindible, descargar e instalar el compilador HTML de Windows. Para ser exactos se puede descargar del Download Center, se trata del “Microsoft HTML Help Workshop” y el archivo es h tmlhelp.exe .

Finalmente, deberemos instalar una versión del procesador TeX si queremos someter el paquete creado al CRAN. El TeX se utiliza para obtener las versiones LaTeX de la documentación. La distribución MikTeX (http://www.miktex.org/) de LaTeX en su versión básica debería ser suficiente para lo que necesitamos. También es posible usar la distribución TeXLive de http://www.tug.org/texlive/.

En el apéndice The Windows toolset de la documentación de R "R Installation and Administration" podemos hallar más detalles de los elementos necesarios, tanto para crear un paquete, como para compilar el propio R.

Además necesitaremos un editor ASCII como el propio RStudio u otro.

2

La variable de entorno PATH

Cuando instalamos las Rtools, opcionalmente, el programa de instalación nos ofrece editar la variable PATH variable así:

PATH=c:\Rtools\bin;c:\Rtools\gcc-4.6.3\bin;<otros>

Es muy importante que comprobemos que las carpetas son correctas respecto a nuestras indicaciones anteriores y, sobre todo, que dejemos el PATH en el mismo orden. LaTeX y el HTML Help Workshop deberían instalarse con los "otros".

Ahora Windows está preparado para localizar estos programas y utilidades. El siguiente punto fundamental es probarlos. Para ello abriremos una ventana “Indicador de comandos” (las variables de entorno se inicializan y fijan cada vez que abrimos esta ventana). Escribimos path y ejecutamos esta instrucción. El resultado es la lista de carpetas de la variable de entorno PATH. Leámosla con cuidado para observar si falta alguna carpeta o si hay algún error. Un ejemplo:

C:\Usuarios\fcarmona>pathPATH=c:\Rtools\bin;c:\Rtools\gcc-4.6.3\bin;C:\WINDOWS\system32;C:\WINDOWS;C:\WINDOWS\System32\Wbem<otras>

A continuación, sin cerrar la ventana “Indicador de comandos”, procederemos a comprobar la ejecución de algunos programas desde la línea de comandos.Escribimos R y ejecutamos. Con ello abrimos una sesión de “Rterm” que es la versión de línea de comandos de R. Si vamos a trabajar desde RStudio no es necesario que incluyamos en el PATH el camino a los ejecutables de R. En caso contrario es imprescindible. Si queremos que R funcione en el “Indicador de comandos” y R funciona en Windows pero ahora la respuesta es un mensaje de error y no entramos en el programa, está claro que no tenemos escrita correctamente la localización del programa en la variable de entorno PATH. Si todo va bien, veremos el mensaje de bienvenida al programa R y ejecutaremos q() para salir.Para ver si los otros programas están bien instalados, ejecutaremos algunas instrucciones en la línea de comandos (cada una por separado):

gcc --help (compilador GNU de C)tex --help (programa TeX)tar --help (una de las Rtools)

Para cada una, deberíamos obtener una larga lista de opciones. Eso nos indica que los programas están listos para ser utilizados.

Si alguna instrucción falla, habrá que localizar las carpetas que contienen los ejecutables (.exe) de estas instrucciones y corregir adecuadamente la variable de entorno PATH. Para ello haremos clic con el botón derecho del ratón en el icono de “Inicio” del escritorio con la siguiente secuencia:

Panel de control → Sistema y seguridad → Sistema → Configuración avanzada del sistema

3

Con esto llegaremos a las Propiedades del sistema y en la pestaña Avanzados pulsaremos el botón Variables de entorno y nos encontraremos con una ventana como la Figura 1.

Para modificar la variable de sistema PATH seleccionaremos y pulsaremos el botón de edición. Se trata de escribir, separadas por un punto y coma, las carpetas donde se localizan los programas de las Rtools, compilador GCC, compilador HTML, R y TeX.

Hay que tener mucho cuidado en la escritura correcta de los nombres de las carpetas. Deberemos recordar con exactitud donde hemos instalado cada uno de los programas.Algunos detalles:

a) En Windows, los nombres de las carpetas son equivalentes en mayúsculas o en minúsculas.

b) Es posible que algunas carpetas ya hayan sido escritas en la instalación del programa correspondiente.

c) La subcarpeta “bin” acostumbra a contener los archivos ejecutables como ocurre en los sistemas operativos Unix y Linux.

Una vez modificada la variable PATH, debemos comprobar el entorno Windows como ya se ha explicado para ver si todo funciona correctamente. Si todo está bien, estamos preparados para construir nuestro paquete.

4

Figura 2: Ventana de las variables de entorno

Construcción del paquete

La referencia fundamental para la construcción de un paquete está en los capítulos 1 y 2 del documento Writing R extensions (PDF), que también podemos consultar en la web Writing R extensions (HTML). En ellos se describen los detalles y los documentos necesarios, aunque el proceso resulta un poco confuso. En este documento no están todas las opciones pero se describirá el proceso de creación de un paquete sencillo.

Paso 1: Creación de la estructura de carpetas y archivos

Este paso se puede hacer de forma manual con la función package.skeleton() o como un proyecto “Paquete” en RStudio. Primero vamos a ver la forma manual y a continuación explicaremos su equivalente en RStudio.

De forma manual, lo más sencillo es utilizar la función con sus mínimos parámetros de la siguiente forma:

Limpiar el espacio de trabajo> rm(list = ls())

Cargar en R los objetos (funciones y datos) del futuro paquete.

Crear la estructura en la carpeta nombre_paquete> package.skeleton(”nombre_paquete”, path=”C:/Carpeta_obj”)

Esto creará la estructura de carpetas y archivos en el lugar indicado por el parámetro path y en el interior de la carpeta nombre_paquete que también será obviamente el nombre del paquete. La dirección indicada en el parámetro path debe existir previamente. Si estamos situados en la carpeta de trabajo que ya nos conviene, podemos omitir el parámetro path.Observemos un detalle importante en la indicación del camino a la carpeta. La barra “/” es la barra oblicua o “slash” de Unix y no la barra inversa “\” típica en Windows. Si queremos poner una barra inversa, hay que ponerla doble “\\”.

Otra posibilidad es detallar las funciones y objetos que deben formar nuestro paquete

> package.skeleton(”nombre_paquete”, path=”C:/Carpeta_obj”, list=c(funcion1, datos1, más))

Todos los detalles de esta función se pueden consultar en su ayuda.

El contenido de la carpeta creada es el siguiente:

1. En su nivel superior se encuentran los archivos de definición y de información como

Read-and-delete-me Indicaciones para la creación del paqueteDESCRIPTION Describe las características principales del paqueteNAMESPACE Carga los paquetes necesarios y exporta las funciones

5

2. Algunas carpetas como

carpeta contenido R funciones del paqueteman documentación o ayudasrc código en un lenguaje de bajo nivel (opcional)data bases de datos (opcional)

Ejemplo

Vamos a crear un paquete muy sencillo con dos funciones elementales. Se trata de calcular el intervalo de confianza y el test para la media con datos normales y varianza conocida. Las funciones son:

IC.z.test <- function(x, sigma, conf.level=0.95){ alpha <- 1 - conf.level z.alpha <- qnorm(1-alpha/2) n <- length(x) SE <- sigma/sqrt(n) return(mean(x) + c(-1,1)*z.alpha*SE)}z.test <- function(x, mu=0, sigma=1){ n <- length(x) SE <- sigma/sqrt(n) z <- (mean(x)-mu)/SE p.value <- (1-pnorm(abs(z)))*2 return(list(media=mean(x), z=z, p.valor=p.value))}

La instrucción que crea el paquete, suponiendo que la carpeta C:/Rpaquetes exista, es:

> package.skeleton("miPaquete", path="C:/Rpaquetes")

Ahora podemos examinar el contenido de la carpeta miPaquete y rellenar todos los archivos necesarios.

Paso 1 con RStudio

Para crear un nuevo paquete con RStudio utilizaremos la instrucción Create Project desde el menú Project o desde la barra de herramientas. Atención: si estamos trabajando, eso cierra la sesión y abre una nueva. Es mejor iniciar una sesión y crear el proyecto desde cero.Debemos seleccionar el Type: Package, dar un nombre al paquete que será también el nombre del proyecto y el nombre de la carpeta y decirle donde crearlos (carpeta y proyecto). De entrada nos ofrece crearlos en la carpeta por defecto o “home”. No en la carpeta de trabajo. Mejor si especificamos la carpeta exacta donde se creará la carpeta del paquete o proyecto. También hay que añadir el archivo fuente con las funciones y datos que queremos incorporar al paquete. Así, cuando pulsemos el botón Create Project, se creará toda la estructura de archivos necesaria dentro de la carpeta especificada y estaremos en disposición de rellenar los archivos de configuración y documentación del paquete.

6

Figura 3: New Project en RStudio.

Figura 4: Create New Project en RStudio.

7

Paso 2: Edición de los archivos de descripción

El primero y fundamental es el archivo DESCRIPTION. Este archivo le indica a R las características básicas de nuestro paquete y un breve resumen de su funcionalidad.

Si editamos el archivo DESCRIPTION que hemos creado para nuestro paquete de ejemplo miPaquete, observaremos que se deben rellenar los campos con los datos concretos:

Package: miPaqueteType: PackageTitle: What the package does (short line)Version: 1.0Date: 2007-07-17Author: Who wrote itMaintainer: Who to complain to <yourfault@somewhere.net>Description: More about what it does (maybe more than one line)License: What license is it under?

Este es el conjunto mínimo de campos. Otros campos son opcionales, pero en todo caso hay que tener mucho cuidado al rellenarlos ya que este archivo se consulta durante el proceso de creación del paquete.Observemos que el nombre del paquete es el mismo que el de la carpeta y el mismo que utilizaremos en la construcción del paquete.La fecha al estilo yyyy-mm-dd.Si algún campo ocupa más de una línea, como el campo Description, la segunda y siguientes deben empezar por un tabulador o espacio en blanco.

Figura 4: El archivo DESCRIPTION en RStudio.

Ejemplo

Para el paquete que pretendemos crear un archivo DESCRIPTION es

Package: miPaqueteType: PackageTitle: Test para la media en poblaciones normales con varianza conocidaVersion: 1.0Date: 2013-02-27Author: Francesc Carmona <fcarmona@ub.edu>Maintainer: Francesc Carmona <fcarmona@ub.edu>

8

Depends: R (>= 2.15.2)Description: Este paquete proporciona algunas funciones para calcular el

intervalo de confianza y el test para la media de una variable normal con varianza conocida.

License: GPL (version 2 or later)Encoding: latin1

Aunque no es recomendable, hemos añadido el item Encoding para utilizar el idioma propio (castellano, catalán,...) en los archivos de ayuda. En linux sería Encoding: UTF-8.Otras posibilidades se pueden ver en el documento de referencia Writing R extensions.

Otro archivo importante es el NAMESPACE. Sirve para cargar los paquetes o librerías que necesita nuestro paquete y para indicar qué funciones haremos públicas (con ayuda). Nuestro paquete de ejemplo es tan sencillo que no lo necesita.

Paso 3: Documentación de las funciones

Curiosamente, este es uno de los pasos más difíciles, pero irrenunciable. Si nuestra documentación es confusa, pobre o inexistente, el paquete no se podrá utilizar. ¡Incluso por su creador o creadora!La subcarpeta man contiene los archivos de documentación (Rd) de cada uno de los objetos utilizables del paquete. Para cada función de la carpeta R, debemos crear un archivo de documentación (con la extensión Rd) en la carpeta man. Es decir, si miFuncion.R es un archivo de la carpeta R, debemos crear el archivo miFuncion.Rd en la carpeta man.R utiliza un lenguaje especial para crear estos archivos de documentación “Rd”. La instalación de R se encargará de trasladar este lenguaje genérico Rd a archivos HTML, de texto o LaTeX, según se necesite. Este lenguaje de documentación tiene una semejanza evidente con el LaTeX. En todo caso no es necesario saber LaTeX para escribir la documentación de nuestro paquete.

Si hemos utilizado la función package.skeleton(), ya tenemos una plantilla “Rd” para cada función de nuestro paquete. Ahora debemos editar y rellenar la información requerida.

El lenguaje “Rd” consiste en una serie de instrucciones con sus correspondientes argumentos. Cada instrucción es de la forma:

\command{arg}

Por ejemplo

\title{ este es mi título }

El archivo “Rd” para una función contiene los puntos obligatorios ‘name’, ‘alias’, ‘title’, ‘description’, ‘usage’ en la cabecera y ‘keyword’ en el pié, además de los puntos opcionales como ‘arguments’, ‘value’, ‘details’, ‘references’, ‘seealso’, ‘examples’ en el cuerpo del archivo. Además de los puntos obligatorios, se recomienda añadir las secciones ‘arguments’, ‘value’, ‘author’ y ‘examples’. Luego un archivo “Rd” típico tiene un mínimo de 10 secciones, cada una de las cuales empieza por su correspondiente instrucción:

9

\name{ ... }\alias{ ... }\title{ ... }\description{ ... }\usage{ ... }\arguments{ ... }\value{ ... }\author{ ... }\examples{ ... }\keyword{ ... }

En todo caso la recomendación es empezar con un mínimo de puntos y añadir los que deseemos después de depurar de errores el archivo.

Por ejemplo, a continuación se muestra la plantilla creada para la función z.test() de nuestro paquete:

\name{z.test}\alias{z.test}%- 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{z.test(x, mu = 0, sigma = 1)}%- maybe also 'usage' for other objects documented here.\arguments{ \item{x}{ ~~Describe \code{x} here~~ } \item{mu}{ ~~Describe \code{mu} here~~ } \item{sigma}{ ~~Describe \code{sigma} 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 asfunction(x,mu=0,sigma=1) {

10

n <- length(x)SE <- sigma/sqrt(n)z <- (mean(x)-mu)/SEp.value <- (1-pnorm(abs(z)))*2return(list(media=mean(x), z=z, p.valor=p.value)) }}% Add one or more standard keywords, see file 'KEYWORDS' in the% R documentation directory.\keyword{ ~kwd1 }\keyword{ ~kwd2 }% __ONLY ONE__ keyword per line

Algunos consejos para rellenar esta plantilla:

\name{} da nombre al archivo de ayuda

Con el \alias{} se puede utilizar el mismo documento de ayuda para varios objetos. Es el caso de las funciones “dnorm”, “rnorm”, “pnorm” y “qnorm”.Los ejemplos deben ser ejecutables. R comprobará durante la instalación que los ejemplos funcionan.

El último item \keyword{} debe contener como mínimo una de las palabras clave estándar que se pueden hallar en el archivo R_HOME/doc/KEYWORDS.db1.

Las páginas de ayuda para conjuntos de datos siguen una estructura similar y contienen los items ‘name’, ‘alias’, ‘doctype’, ‘title’, ‘description’, ‘usage’, ‘format’, ‘source’, ‘examples’ y ‘keyword’, donde ‘doctype’ viene definido como {data} y ‘keyword’ como {datasets}.

Instrucciones de formato “Rd”

Hay un extenso conjunto de instrucciones para dar formato. Todas ellas están descritas en el capítulo 2 de WRE. Mi recomendación es no abusar de ellas y, a medida que se tome confianza, leer el capítulo mencionado y probarlas.

Algunas de las más utilizadas son:

Para utilizar la fuente “typewriter” (especialmente para código R): \code{ miFuncion }Insertar URL: \url{ http://www.r-project.org/ }Insertar una dirección de correo: \email{ fcarmona@ub.edu }

La instrucción \arguments usa la subinstrucción \item para organizar una lista. Si el retorno de la función es una lista, también se necesitará usar la instrucción \item. Por ejemplo, la función z.test de nuestro paquete devuelve una lista con tres items. Esto significa que en la sección \value deberemos insertar:

\item{media}{ valor medio de los datos muestrales }\item{z}{ valor del estadístico para el contraste }\item{p.valor}{ p-valor para el contraste sobre la media }

1 R_HOME puede ser algo como C:/Archivos de programa/R/R-2.15.3

11

NOTA: no debe haber espacios entre la llave } que cierra el nombre del item y la llave que abre { el texto del argumento.

Depuración de un documento “Rd”

Los mensajes de error de R para los archivos de documentación pueden ser muy crípticos. Por ello es conveniente tener mucho cuidado en los detalles de su redacción.

Peter Rossi (2006) da las siguientes recomendaciones:

Hay dos ideas fundamentales:1. Crear el archivo “Rd” de forma incremental. Es decir, no escribir un archivo completo

a la primera. Se puede empezar con un archivo simple y probar los cambios uno a uno.2. Trabajar con una única función cada vez. Resistir la tentación de escribir el paquete

completo y todos sus archivos “Rd” y esperar que el depurado conjunto funcione.

No es una buena idea ejecutar la instrucción R CMD check para chequear los archivos “Rd” al principio. Es mejor usar R CMD Rd2txt primero. Si tenemos un archivo de documentación, mifun.Rd, se puede utilizar la siguiente instrucción en la consola:

R CMD Rd2txt mifun.Rd

Si funciona sin errores, use la instrucción:

R CMD Rdconv –t=html –o=mifun.html mifun.Rd

que producirá la versión html. Entonces se puede abrir el archivo creado con su navegador preferido. Inspeccione el resultado para ver si todas las secciones definidas se muestran correctamente.

Claves para redactar archivos “Rd”: 1. Como en TeX/LaTeX, el formateador “Rd” tiene sus propias ideas sobre cómo debe

quedar un documento. No intente modificar el resultado demasiado, por ejemplo con \cr (nueva línea). Inserte una línea en blanco para separar grupos de texto.

2. No olvide que % es el símbolo de comentario en los archivos “Rd” (como # lo es en las funciones R).Esto significa que debe tener cuidado con la multiplicación de matrices en un ejemplo. Utilice el carácter de escape “\” para insertar %, como en C = A\%*\%B.

3. Evite los carácteres $, #, _, <, > y |.4. No olvide cerrar las llaves “{ }”. Lo mejor es utilizar un editor que facilite este tema.5. La inclusión de ecuaciones en LaTeX es más un problema que una solución,

especialmente si tenemos en cuenta que los documentos presentados con la ayuda (instrucción help o ?) son versiones en texto llano. Las ecuaciones LaTeX no se traducen muy bien a texto. Esto se puede evitar con alguna alternativa, como un enlace a un archivo PDF.

6. El procesador Rd es muy sensible a los espacios entre la instrucción y el principio del argumento. Por ejemplo:

12

\author{Francesc Carmona} funcionará, pero \author {Francesc Carmona} no.

7. Si tiene un conjunto de funciones relacionadas, utilice \code{\link{nombre_funcion}} para insertar enlaces entre los diversos archivos de documentación.

Para añadir objetos a un paquete que se va a crear

Si queremos añadir objetos, como un conjunto de datos o una nueva función, a una estructura de paquete ya creada, deberemos gravar los objetos mismos y sus archivos de documentación en las carpetas apropiadas.Gravar un conjunto de datos se puede hacer con la instrucción save(). Los nombres de los objetos a gravar se ponen como primer argumento. En el argumento “file” se debe especificar la carpeta donde dejaremos los objetos. Por ejemplo, si queremos añadir un data.frame “datos”, se gravará como “Rda” con la instrucción

> save(datos, file=”C:/Rpaquetes/miPaquete/data/datos.Rda”)

El código R se debe gravar con la función dump(). Por ejemplo, para gravar una función de nombre “nuevo.test” hacemos

> dump("nuevo.test", file="C:/Rpaquetes/miPaquete/R/nuevo.test.R")

Para redactar el archivo de documentación asociado a un objeto se puede utilizar la función prompt(). Esta creará el archivo “Rd” apropiado para el objeto especificado. En el argumento ‘filename’ tenemos que detallar la carpeta y el nombre en el que el archivo “Rd” se guardará. Por ejemplo:

> prompt(nuevo.test, filename="C:/Rpaquetes/miPaquete/man/nuevo.test.rd")

Paso 4: Chequear el paquete

En teoría, este paso es sencillo. Abra una ventana de instrucciones o consola y vaya hasta la carpeta en la que empieza el árbol de carpetas de su paquete.Use R CMD check para “chequear” su paquete.R CMD check prueba directamente en la consola una serie de instrucciones que crearan los archivos de documentación en los formatos texto, LaTeX y HTML, compilará el código fuente y creará los DLL, chequeará las inconsistencias y varios errores, ejecutará los ejemplos y finalmente construirá un manual en formato DVI.

La mejor forma de evitar los errores en este punto es revisar antes todo su código con mucho ojo:

1. Revise todas las funciones y ejecute los ejemplos de cada una.2. Compile previamente y cree los DLL antes3. Ejecute R CMD Rd2txt y R CMD Rdconv en todos los archivos “Rd”.

Si se tienen en cuenta estos detalles previos, los errores detectados por R CMD check se verán gratamente limitados.

13

R CMD check construirá el paquete en una carpeta de nombre miPaquete.Rdcheck que se creará en la misma carpeta donde la instrucción se invoca.Finalmente, confirme que el tiempo de ejecución de los ejemplos es inferior a 2 minutos. Esto se puede ver en el archivo miPaquete-Ex.Rout en la carpeta “Rdcheck”.

Paso 4 con RStudio

RStudio dispone de una pestaña específica para chequear el paquete.

Figura 5: La pestaña Build de RStudio.

Si pulsamos el icono Check se chequea el paquete y veremos los errores o advertencias2.Corregidos los errores y todas las advertencias que podamos, el siguiente paso lo podemos hacer con el icono Build & Reload que construye el paquete y lo carga para que lo probemos.

En RStudio también es posible chequear cada archivo Rd de forma individual ya que dispone de un botón para ver el resultado en HTML. Por otra parte también se puede ejecutar directamente en la consola de R la instrucción

> system("Rcmd.exe Rd2txt ~/R/miPaquete/man/z.test.Rd")

Paso 5: Crear el paquete

Use la instrucción R CMD build miPaquete para construir definitivamente el paquete. Esta creará un archivo “tar” que se puede someter al CRAN o distribuir entre los colegas. En su propio ordenador, que ya dispone de las herramientas necesarias, se puede usar la instrucción R CMD INSTALL miPaquete para instalar su paquete en la localización habitual de todos los paquetes del programa R. A continuación se podrá cargar en una sesión con la instrucción:

> library(miPaquete)

2 En una instalación inicial con MikTeX se produjo un error inesperado con la fuente “inconsolata”. Ver la solución al final de este documento.

14

Paso 5 con RStudio

Con el icono More de la Figura 5 se despliega un menú que permite crear el paquete en la versión “tar” con la opción Build Source Package.

Paso 6: Distribuir el paquete

El archivo “tar” que contiene el paquete se puede instalar gracias a las herramientas de que dispone nuestro ordenador (Rtools, ...). En un ordenador Linux seguramente estas herramientas se incluyen de forma natural y la instalación del paquete no tendrá ninguna dificultad. Sin embargo, para instalar nuestro paquete en otro ordenador Windows será mejor convertirlo al formato “zip” y entonces se podrá instalar desde el menú:

Packages -> Install package(s) from local zip files ...

Para obtener el arhivo “zip” del paquete bastará con comprimir en este formato el paquete “Windows” que ya está instalado en nuestro ordenador en la carpeta R_HOME/library. Al nombre del archivo le podemos añadir el número de versión: miPaquete-1.0.zip.

Si hemos creado un paquete en Linux y queremos distribuirlo a usuarios Windows podemos utilizar el servicio del CRAN (http://win-builder.r-project.org/) y en concreto la página:

http://win-builder.r-project.org/upload.aspx

Paso 6 con RStudio

Con el icono More de la Figura 5 se despliega un menú que permite crear el paquete en la versión “zip” en Windows con la opción Build Binary Package.

Cómo escribir vignettes para un paquete

Además de los archivos de documentación en el formato “Rd”, R también permite incluir archivos en otros formatos. Estos archivos se deben situar en la subcarpeta inst/doc del paquete a crear. Su contenido se copiará en la subcarpeta doc cuando se instale el nuevo paquete. En realidad los archivos se pueden escribir en cualquier formato, pero se recomienda encarecidamente que sea en PDF.Un caso realmente especial son los documentos en formato Sweave, los que llamaremos package vignettes. Los documentos Sweave permiten integrar código R en archivos LaTeX, de forma que cuando se procesan se consigue un documento definitivo con los resultados del código R incrustados, tanto numéricos, como gráficos. Los documentos Sweave para un paquete a crear se situarán también la carpeta inst/doc y se prueban con la instrucción R CMD check (excepto las partes con eval=FALSE). La carpeta de trabajo para las pruebas es la carpeta doc del paquete “instalado”, de forma que debemos asegurarnos que la carpeta inst/doc contiene todo lo necesario.La instrucción R CMD build se encarga de ejecutar los archivos Sweave y obtener sus correspondientes PDF. Sin embargo, se pueden dejar las versiones PDF en la subcarpeta inst/doc para que no se necesite su compilación durante la instalación. En todo caso, como

15

se ha explicado, R se encarga de chequear el código R (no la literatura) de los archivos Sweave.

Un problema con MikTeX

Con una instalación inicial de MikTeX, al chequear por primera vez un paquete se produce un error ya que no está instalado el paquete “inconsolata”. Con el MikTeX Package Manager se puede instalar fácilmente. Sin embargo, el problema persiste hasta que se ejecuta la siguiente instrucción en el “Indicador de comandos”:

initexmf --mkmaps

Bibliografía

R Core Team (2012). Writing R extensions

Rossi, P.(2006). Making R Packages Under Windows: A Tutorial.

Leisch, F. (2009). Creating R Packages: A Tutorial.

Falcon, S. and Gentleman, R (2006). Lab: Writing packages in R.

16