Introducción

En R, la unidad fundamental de código compartible es el paquete. Un paquete agrupa código, datos, documentación y pruebas, y es fácil de compartir con otros. En marzo de 2023, había más de 19 000 paquetes disponibles en la red Comprehensive R Aarchive Network, o CRAN, la cámara de compensación pública para paquetes R. Esta enorme variedad de paquetes es una de las razones por las que R tiene tanto éxito: lo más probable es que alguien ya haya resuelto un problema en el que estás trabajando y puedas beneficiarte de su trabajo descargando su paquete.

Si estás leyendo este libro, ya sabes cómo trabajar con paquetes de las siguientes maneras:

El objetivo de este libro es enseñarle cómo desarrollar paquetes para que pueda escribir los suyos propios, no sólo utilizar los de otras personas. ¿Por qué escribir un paquete? Una razón de peso es que tienes un código que quieres compartir con otros. Agrupar su código en un paquete facilita su uso para otras personas porque, al igual que usted, ellos ya saben cómo utilizar los paquetes. Si su código está en un paquete, cualquier usuario de R puede descargarlo, instalarlo y aprender a usarlo fácilmente.

Pero los paquetes son útiles incluso si nunca compartes tu código. Como dice Hilary Parker en su introducción a los paquetes: “En serio, no tiene por qué tratarse de compartir tu código (¡aunque eso es un beneficio adicional!). Se trata de ahorrar tiempo”. Organizar el código en un paquete le facilita la vida porque los paquetes vienen con convenciones. Por ejemplo, pones código R en R/, pones pruebas en tests/ y pones datos en data/. Estas convenciones son útiles porque:

Incluso es posible utilizar paquetes para estructurar sus análisis de datos (por ejemplo, Marwick, Boettiger, y Mullen (2018a) o Marwick, Boettiger, y Mullen (2018b)), aunque no profundizaremos en ese caso de uso aquí.

Filosofía

Este libro defiende nuestra filosofía de desarrollo de paquetes: todo lo que pueda automatizarse, debe automatizarse. Haga lo menos posible a mano. Haga todo lo posible con las funciones. El objetivo es dedicar su tiempo a pensar en lo que quiere que haga su paquete en lugar de pensar en los detalles de la estructura del paquete.

Esta filosofía se logra principalmente a través del paquete devtools, que es la cara pública de un conjunto de funciones de R que automatizan tareas de desarrollo comunes. El lanzamiento de la versión 2.0.0 en octubre de 2018 marcó su reestructuración interna en un conjunto de paquetes más enfocados, con devtools convirtiéndose más en un metapaquete. El paquete usethis es el subpaquete con el que es más probable que interactúe directamente; Explicamos la relación devtools-usethis en 2.2 devtools, usethis, y usted.

Como siempre, el objetivo de devtools es hacer que el desarrollo de paquetes sea lo más sencillo posible. Resume las mejores prácticas desarrolladas por Hadley Wickham, inicialmente de sus años como prolífico desarrollador en solitario. Más recientemente, ha reunido un equipo de desarrolladores en Posit (anteriormente conocido como RStudio), que en conjunto se ocupan de cientos de paquetes R de código abierto, incluidos los conocidos como the tidyverse. El alcance de este equipo nos permite explorar el espacio de todos los posibles errores a una escala extraordinaria. Afortunadamente, también nos brinda la oportunidad de reflexionar sobre los éxitos y los fracasos, en compañía de colegas expertos y comprensivos. Intentamos desarrollar prácticas que hagan la vida más agradable tanto para el mantenedor como para los usuarios de un paquete. El metapaquete devtools es donde estas lecciones se concretan.

devtools trabaja mano a mano con RStudio, que creemos que es el mejor entorno de desarrollo para la mayoría de los usuarios de R. La alternativa más popular a RStudio es actualmente Visual Studio Code (VS Code) con la extensión R habilitado. Este puede ser un entorno gratificante y poderoso, sin embargo, requiere un poco más de trabajo para configurarlo y personalizarlo 1.

RStudio

A lo largo del libro, destacamos formas específicas en las que RStudio puede acelerar el flujo de trabajo de desarrollo de paquetes, en secciones con formato especial como esta.

Juntos, devtools y RStudio lo aíslan de los detalles de bajo nivel sobre cómo se crean los paquetes. A medida que comience a desarrollar más paquetes, le recomendamos encarecidamente que obtenga más información sobre esos detalles. El mejor recurso para conocer los detalles oficiales del desarrollo de paquetes es siempre el manual oficial de escritura de extensiones R 2. Sin embargo, este manual puede resultar difícil de entender si aún no está familiarizado con los conceptos básicos de los paquetes. También es exhaustivo y cubre todos los componentes posibles del paquete, en lugar de centrarse en los componentes más comunes y útiles, como lo hace este libro. Escribir extensiones de R es un recurso útil una vez que dominas los conceptos básicos y deseas aprender qué sucede bajo el capó.

En este libro

La primera parte del libro trata de brindarle todas las herramientas que necesita para comenzar su viaje de desarrollo de paquetes y le recomendamos encarecidamente que lo lea en orden. Comenzamos en 1  Todo el juego con un recorrido por el desarrollo completo de un paquete pequeño. Su objetivo es pintar el panorama general y sugerir un flujo de trabajo, antes de pasar al tratamiento detallado de los componentes clave de un paquete R. Luego, en 2  Configuración del sistema aprenderá cómo preparar su sistema para el desarrollo de paquetes, y en 3  Estructura y estado del paquete aprenderá la estructura básica de un paquete y cómo varía entre los diferentes estados. A continuación, en 4  Flujos de trabajo de desarrollo fundamentales, cubriremos los flujos de trabajo principales que surgen repetidamente para los desarrolladores de paquetes. La primera parte del libro termina con otro estudio de caso (5  El paquete en el interior de su código), esta vez centrándose en cómo se puede convertir un script en un paquete y analizando los desafíos que enfrentará en el camino.

El resto del libro está diseñado para leerse según sea necesario. Elija entre los capítulos a medida que surjan los distintos temas en su proceso de desarrollo.

Primero cubrimos los componentes clave del paquete: 6  Código R analiza dónde reside su código y cómo organizarlo, 7  Datos le muestra cómo incluir datos en su paquete y 8  Otros componentes cubre algunos archivos y directorios menos importantes que hay que discutirlo en alguna parte.

A continuación, profundizaremos en los metadatos del paquete, comenzando con DESCRIPTION en 9  DESCRIPTION. Luego profundizaremos en las dependencias. En 10  Dependencias: mentalidad y antecedentes, cubriremos los costos y beneficios de asumir dependencias y brindaremos algunos antecedentes técnicos sobre los espacios de nombres de los paquetes y la ruta de búsqueda. En 11  Dependencias: en la práctica, nos centramos en cuestiones prácticas, como cómo utilizar diferentes tipos de dependencias en diferentes partes de su paquete. Aquí también hablamos de las funciones de exportación, que es lo que hace posible que otros paquetes y proyectos dependan de su paquete. Terminaremos esta parte echando un vistazo a las licencias en 12  Licencias.

Para garantizar que su paquete funcione según lo diseñado (y continúe funcionando a medida que realiza cambios), es esencial probar su código, por lo que los siguientes tres capítulos cubren el arte y la ciencia de las pruebas. 13  Conceptos básicos de pruebas le ayuda a comenzar con los conceptos básicos de las pruebas con el paquete testthat. 14  Diseñar su conjunto de pruebas te enseña cómo diseñar y organizar pruebas de la forma más eficaz. Luego terminamos nuestra cobertura de pruebas en 15  Técnicas de prueba avanzadas, que le enseña habilidades avanzadas para afrontar situaciones desafiantes.

Si desea que otras personas (¡incluido usted en el futuro!) comprendan cómo utilizar las funciones de su paquete, deberá documentarlas. 16  Documentación de la función le ayuda a empezar a utilizar roxygen2 para documentar las funciones de su paquete. La documentación de funciones solo es útil si sabe qué función buscar, por lo que a continuación en 17  Viñetas analizaremos las viñetas, que le ayudarán a documentar el paquete en su conjunto. Terminaremos la documentación con una discusión sobre otros archivos de maquetación importantes como README.md y NEWS.md en 18  Otros archivos markdown, y creando un sitio web de paquete con pkgdown en 19  Sitio web.

El libro concluye volviendo a considerar las prácticas de desarrollo, como el beneficio de utilizar el control de versiones y la integración continua (20  Prácticas de desarrollo de software). Concluiremos analizando el ciclo de vida (21  Ciclo de vida) de un paquete, incluido su lanzamiento en CRAN (22  Liberando a CRAN).

Hay mucho que aprender, pero no se sienta abrumado. Comience con un subconjunto mínimo de funciones útiles (por ejemplo, ¡solo un directorio R/!) y acumule con el tiempo. Parafraseando al monje zen Shunryu Suzuki: “Cada paquete es perfecto tal como está — y necesitaría una pequeña mejora”.

¿Qué no hay aquí?

También hay prácticas específicas que tienen poco o ningún tratamiento aquí simplemente porque no las usamos lo suficiente como para tener una visión especial. ¿Significa esto que desalentamos activamente esas prácticas? Probablemente no, ya que intentamos ser explícitos sobre las prácticas que creemos que deberías evitar. Entonces, si algo no se cubre aquí, simplemente significa que se construyen un par de cientos de paquetes R muy utilizados sin una dependencia significativa de esa técnica. Esa observación debería motivarlo a evaluar qué tan probable es que sus requisitos de desarrollo realmente no se superpongan con los nuestros. Pero a veces la respuesta es un claro “sí”, en cuyo caso simplemente necesitarás consultar otro recurso.

  1. Los usuarios de Emacs Speaks Statistics (ESS) encontrarán que muchos de los flujos de trabajo descritos en este libro también están disponibles allí. Para aquellos leales a vim, recomendamos el Nvim-R plugin.↩︎

  2. También puede disfrutar de la versión “en Quarto” en https://rstudio.github.io/r-manuals/r-exts/.↩︎