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.

1 comentario:

  1. Hola, estoy haciendo un paquete y estoy cubriendo los archivos Rd en inglĆ©s pero tengo que poner varios nombres que tienen acentos y Ʊ. He puesto \encoding{UTF-8} en todos los archivos y Encoding: UTF-8 en DESCRIPTION pero aĆŗn asĆ­ al hacer el check me dice que esos caracteres no son admitidos y no me crea bien el manual. Me puedes ayudar? Gracias.

    ResponderEliminar