Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Crear paquetes en R

Oscar Perpiñán Lamigueirohttp://oscarperpinan.github.io

1 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Definiciones previas (Creating R Packages: atutorial)

I Package: An extension of the R base system withcode, data and documentation in standardizedformat.

I Library: A directory containing installed packages.I Repository: A website providing packages for

installation.

2 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Definiciones previas (Creating R Packages: atutorial)

I Source: The original version of a package withhuman-readable text and code.

I Binary: A compiled version of a package withcomputer-readable text and code, may work only ona specific platform.

3 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Definiciones previas (Creating R Packages: atutorial)

I Base packages: Part of the R source tree, maintainedby R Core.

I Recommended packages: Part of every Rinstallation, but not necessarily maintained by RCore.

I Contributed packages: All the rest.

4 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

¿Por qué crear y publicar un paquete para R?I Es una herramienta cómoda para mantener

colecciones coherentes de funciones y datos.I Permite publicar código de forma que pueda ser

empleado por otros siguiendo unas estructurascomunes.

I La estructura de un paquete obliga a organizar,limpiar y documentar el código.

I Al distribuir las herramientas para que otros puedanusarlas, se obtiene realimentación sobre lo publicado,de forma que se aumenta su robustez, se amplian susfuncionalidades y se conecta con otras herramientasy proyectos.

I «As we enjoy great advantages from the inventionsof others, we should be glad of an opportunity toserve others by any invention of ours, and this weshould do freely and generously.»

5 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Algunos consejos genéricos

Extraído de Best Practices for Scientific Computing

I Write programs for people, not computers.I Automate repetitive tasksI Use the computer to record historyI Make incremental changesI Use version controlI Don’t repeat yourself (or others)I Plan for mistakesI Optimize software only after it works correctlyI Document design and purpose, not mechanicsI Collaborate

6 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Referencias

I Writing R ExtensionsI Creating R Packages: a tutorialI R package primerI Making an R package

7 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Estructura

I Las fuentes de un paquete de R están contenidas enun directorio que contiene al menos:I Los ficheros DESCRIPTION y NAMESPACEI Los subdirectorios:

I R: código en ficheros .RI man: páginas de ayuda de las funciones, métodos y

clases contenidos en el paquete.

I Esta estructura puede ser generada conpackage.skeleton.

8 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

DESCRIPTION

I El fichero DESCRIPTION contiene la informaciónbásica:

Package: pkgnameVersion: 0.5-1Date: 2004-01-01Title: My First Collection of FunctionsAuthors@R: c(person("Joe", "Developer", role = c("aut", "cre"),

email = "Joe.Developer@some.domain.net"),person("Pat", "Developer", role = "aut"),person("A.", "User", role = "ctb",

email = "A.User@whereever.net"))Author: Joe Developer and Pat Developer, with contributions from A. UserMaintainer: Joe Developer <Joe.Developer@some.domain.net>Depends: R (>= 1.8.0), nlmeSuggests: MASSDescription: A short (one paragraph) description of what

the package does and why it may be useful.License: GPL (>= 2)URL: http://www.r-project.org, http://www.another.url

I Los campos Package, Version, License, Title,Author y Maintainer son obligatorios.

I Si usa métodos S4 debe incluir Depends: methods

9 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

NAMESPACE

I R usa un sistema de gestión de espacio de nombres quepermite al autor del paquete especificar:I las variables del paquete que se exportan (y son, por

tanto, accesibles a los usuarios)I las variables que se importan de otros paquetes.I las clases y métodos S3 y S4 que deben registrarse.

I Este mecanismo queda definido en el contenido delfichero NAMESPACE.

10 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

NAMESPACE

El NAMESPACE controla la estrategia de búsqueda devariables que utilizan las funciones del paquete:I En primer lugar busca entre las creadas localmente

(por el código de la carpeta R/).I En segundo lugar busca entre las variables

importadas explícitamente de otros paquetes.I En tercer lugar busca en el NAMESPACE del paquete

base.I Por último busca siguiendo el camino habitual (ver

el resultado de search())

11 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

NAMESPACE

I Para exportar las variables f y g:

export(f, g)

I Para importar todas las variables del paquetepkgExt:

import(pkgExt)

I Para importar las variables var1 y var2 del paquetepkgExt:

importFrom(pkgExt, var1, var2)

12 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

NAMESPACEI Para registrar el método S3 print para la clase

myClass:

S3method(print, myClass)

I Para usar clases y métodos S4

import("methods")

I Para registrar las clases S4 class1 y class2:

exportClasses(class1, class2)

I Para registrar los métodos S4 method1 y method2:

exportMethods(method1, method2)

I Para importar métodos y clases S4 de otro paquete:

importClassesFrom(package, ...)

importMethodsFrom(package, ...)

13 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Documentación

I Las páginas de ayuda de los objetos R se escribenusando el formato “R documentation” (Rd), unlenguaje similar a LATEX.

I Es aconsejable seguir estas orientaciones: Guidelinesfor Rd files

I Para generar el esqueleto de un fichero Rd esaconsejable usar:I prompt: genéricaI promptClass y promptMethods: clases y métodos.I promptPackage: paqueteI promptData: datos

I Todos los comandos disponibles están en eldocumento Parsing Rd files.

14 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

\name{load}\alias{load}\title{Reload Saved Datasets}\description{Reload the datasets written to a file with the function\code{save}.

}\usage{load(file, envir = parent.frame())

}\arguments{\item{file}{a connection or a character string giving the

name of the file to load.}\item{envir}{the environment where the data should be

loaded.}}\seealso{\code{\link{save}}.

}\examples{## save all datasave(list = ls(), file= "all.RData")

## restore the saved values to the current environmentload("all.RData")

## restore the saved values to the workspaceload("all.RData", .GlobalEnv)

}\keyword{file}

15 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Ejemplos

I Paquete simple:https://github.com/oscarperpinan/pkgEx

I Paquete con métodos S4:https://github.com/oscarperpinan/pkgMethods

16 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Itinerario

I ComprobarR CMD check myPackage/

I ConstruirR CMD build myPackage/

I Publicar (o actualizar) en un repositorio

17 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Comprobar

I Comprobar un directorio (desde línea de comandos):R CMD check myPackage/

I Comprobar un paquete ya construido (desde líneade comandos):

R CMD check myPackage.tar.gz

I Esta comprobación incluye más de 20 puntos deprueba detallados en el manual Writing R extensions.

18 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Construir

Fuente o binarioSe puede construir un fichero fuente en formato tarball(independiente de la plataforma, habitual en sistemasUnix) o en forma binaria (dependiente de la plataforma,habitual para Windows y Mac).

I Fuente en formato tarball: el resultado es un ficherotarball myPackage.tar.gz que se puede distribuir acualquier sistema.

R CMD build myPackage/

I Comprimido binario: el resultado es una copiacomprimida de la versión instalada del paquete:depende del sistema operativo.

R CMD INSTALL --build myPackage/

19 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Comprobar y construir en sistemas Windows

I Para paquetes sin código compilado (C, Fortran),también se puede usar R CMD check y R CMD build

en un sistema Windows.I Para generar un binario hay que usar R CMD INSTALL

--build.I Es posible que haya que modificar la variables de

entorno TEMP y TMP de forma que sólo contengancaracteres ASCII.

I Para paquetes con código compilado, o en caso deproblemas con los comandos anteriores, hay queusar Rtools.

I Se pueden instalar fuentes tarball con (ver Rinstallation and administration):

install.packages(myPackage.tar.gz, type='source')

20 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Repositorios: CRAN

El principal repositorio de paquetes estables es CRAN.I Publicar en este repositorio conlleva la aceptación de

unas condiciones.I Para publicar en CRAN hay que subir el fichero

fuente tarball resultado de R CMD build mediante elformulario webhttps://cran.r-project.org/submit.html

siguiendo los pasos que allí se indican.I Es imprescindible haber comprobado el fichero con R

CMD check --as-cran antes de subirlo al formulario.El resultado de esta comprobación no debe contenererrores, advertencias o notas.

I Más detalle en el apartado Submission de lascondiciones de CRAN.

21 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Repositorios

Otros repositorios destacables son:

I GitHub (versiones de desarrollo)I R-Forge (versiones de desarrollo)I RForge (versiones de desarrollo)I Bioconductor (paquetes de bioinformática)

22 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Repositorios: GitHub

I GitHub es actualmente el repositorio de código másimportante por número de usuarios y proyectosalojados.I Documentación: Guías sobre GitHub.I Existe una aplicación de escritorio (guía

introductoria)I Emplea git para realizar control de versiones.

I Recursos para aprender a usar git.

I Proyectos de R en GitHub.I Instalar paquete desde GitHub:

install.packages('remotes') ## solo primera vez

library(remotes)

## https://github.com/oscarperpinan/tdr

install_github("oscarperpinan/tdr")

23 / 24

Crear paquetes enR

Oscar PerpiñánLamigueirohttp://

oscarperpinan.github.io

Introducción

Crear un paqueteen R

Publicar unpaquete

Ejemplos

I Paquete simple:https://github.com/oscarperpinan/pkgEx

I Paquete con métodos S4:https://github.com/oscarperpinan/pkgMethods

24 / 24