martes, 5 de marzo de 2013

Creación de paquetes con RStudio

Introducción

Los paquetes de R son la forma ideal de distribuir código R y datos para que otras personas los puedan reutilizar. RStudio incluye un conjunto de herramientas que facilitan la creación y desarrollo de paquetes en R de forma más productiva:

  • Un panel específico con las instrucciones adecuadas para el desarrollo de paquetes y una vista de los resultados de la compilación y los errores.
  • Un comando “Build and Reload” que reconstruye el paquete y vuelve a cargarlo en una nueva sesión.
  • Herramientas para la documentación en R que incluyen la vista previa, la corrección ortográfica y la edición Roxygen.
  • Integración del paquete devtools para el desarrollo de funciones.
  • Soporte para Rcpp que incluye el resaltado de la sintaxis para C/C++ y los errores de navegación con gcc.

Documentación básica

Para entender las bases del desarrollo de paquetes con R, los siguientes enlaces proporcionan la información esencial:

Prerequisitos

Además del propio R, hay dos elementos imprescindibles para construir paquetes:

  • Un conjunto de herramientas de desarrollo de programación GNU que incluyen un compilador C/C++.
  • El programa LaTeX para los manuales y las viñetas.

Veamos como instalar estos elementos según el sistema operativo.

Ubuntu

En Debian/Ubuntu y derivados con una sencilla instrucción se pueden instalar todas las herramientas necesarias para el desarrollo de paquetes R así como el propio LaTeX completo:

sudo apt-get install r-base-dev texlive-full

Hay que señalar que la versión actual de Texlive (una distribución de TeX/LaTeX) en los repositorios es del 2009. Seria mejor instalar la última versión con la guía rápida.

Algunos paquetes requieren la instalación de otros paquetes de Ubuntu. Para tener todos los componentes necesarios para compilar el propio R desde la fuente hay que ejecutar:

sudo apt-get build-dep r-base-core

Para otras versiones de Linux se debe consultar su propia documentación sobre como instalar las herramientas de desarrollo GNU y el LaTeX.

Windows

El conjunto de utilidades necesarias para el desarrollo de paquetes en R se debe obtener directamente del CRAN: Rtools Downloads.

Se trata de elegir la versión de Rtools apropiada para nuestra versión de R, ejecutarla y, sobre todo, asegurarnos que el PATH del sistema queda configurado apropiadamente (esto se puede hacer automáticamente durante la instalación de Rtools).

Para los manuales y las viñetas necesitaremos también una instalación de LaTeX que para Windows puede ser MikTeX.

Mac OS X

El núcleo principal de las utilidades de software necesarias para el desarrollo de paquetes en R se pueden obtener instalando la aplicación de linea de comandos para XCode. Esto se puede hacer de dos formas distintas:

  • Descargar e instalar Xcode de la Mac AppStore: Xcode
  • Dentro de Xcode ir a Preferences: Descargar e instalar las 'Command Line Tools'

O alternativamente (para que el tamaño de descarga sea menor):

Para hacer manuales y vignettes también se necesita una distribución de LaTeX como MacTeX (u otra versión de LaTeX para Mac). MacTeX se puede descargar de aquí: http://www.tug.org/mactex/downloading.html.

Creación de un nuevo paquete

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). Por defecto nos ofrece crearlos en la carpeta por defecto o home. No en la carpeta de trabajo. Mejor especificar 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.

Escribir la documentación del paquete

Uno de los requisitos fundamentales de los paquetes en R es que todas las funciones, objetos y datos visibles por el usuario deben estar documentados. RStudio tiene la habilidad de editar y ver los archivos de documentación Rd. También soporta, gracias a Sweave y knitr, la autoría y visionado de las viñetas.

Archivos Rd

Con RStudio se pueden editar los archivos Rd directamente. Estos archivos usan un formato muy similar al LaTeX. Para ver información detallada de este formato se puede consultar el artículo Writing R Documentation del CRAN.

Estos archivos se procesan y constituyen la ayuda de las funciones o datos del paquete que luego vemos con la instrucción help.

Hay que tener especial cuidado en la redacción de los ejemplos con código R. Los comentarios en ese apartado empiezan con #, pero si necesitamos un símbolo como %, hay que utilizar la notación LaTeX y escribir \%.

También hay que editar el archivo DESCRIPTION rellenando adecuadamente todos los campos, en especial, el de la licencia.

Aunque no es recomendable por problemas de compatibilidad, podemos escribir la ayuda en nuestro idioma (castellano, catalán,…), en cuyo caso habrá que añadir un campo Encoding: UTF-8 al archivo DESCRIPTION. El código también puede ser latin1 si estamos en Windows. Si únicamente queremos escribir un archivo .Rd en nuestro idioma hay que añadir una sección \encoding{UTF-8} en dicho archivo. La instrucción \enc{}{} permite escribir palabras en dos códigos, el primero no-ASCII y el segundo como alternativa ASCII. Por ejemplo: \enc{Ocaña}{Ocana}.

Comprobación y construcción del paquete

Cuando todos los archivos esten rellenados, debemos proceder a la comprobación con todo detalle que hace R con la instrucción R CMD check (Ctrl + Shift + E). Debemos leer con atención y corregir cualquier error o alerta.

Cuando todo sea correcto continuaremos con la instrucción R CMD INSTALL (Ctrl + Shift + B) que forma e instala el paquete en una sesión limpia y permite comprobar su funcionamiento.

Finalmente, si el paquete funciona y las ayudas son satisfactorias podemos acabar por empaquetar los archivos con la instrucción R CMD build que forma el paquete fuente. Esto produce el archivo tar.gz que podemos instalar en cualquier otro ordenador con SO linux o mac.

Si estamos en Windows podemos crear también un archivo binario exclusivo de este sistema operativo. Si, como en mi caso, se ha creado el archivo tar.gz en linux y no tenemos Windows, podemos utilizar la página Win-builder para obtener cómodamente el binario.