2. Crear el paquete

⏱ Enseñanza: 10 minutos · Ejercicios: 15 minutos

Preguntas

  • ¿Cómo elijo un nombre para mi paquete?
  • ¿Cómo creo la estructura de un paquete?
  • ¿Cómo sé si mi paquete está bien?

Objetivos

  • Comprobar si un nombre es válido y está disponible con pak::pkg_name_check().
  • Crear un paquete con usethis::create_package().
  • Describir para qué sirve cada archivo de un paquete recién creado.
  • Correr devtools::check() e interpretar el resultado.
  • Agregar una licencia.

Elegir un nombre

Un nombre de paquete de R:

  • solo puede tener letras, números y puntos;
  • tiene que empezar con una letra;
  • no puede terminar con un punto.

No se permiten guiones (mis-dichos) ni guiones bajos (mis_dichos). Y aunque los puntos están permitidos, mejor evitarlos.

Antes de enamorarte de un nombre, comprobá si ya existe:

💻 En vivo

pak::pkg_name_check("dichosos")

La función revisa si el nombre es válido, si ya hay un paquete con ese nombre en CRAN o Bioconductor, y busca qué significa la palabra (en inglés) para avisarte si tiene connotaciones negativas.

AdvertenciaLas malas palabras, solo en inglés

pkg_name_check() solo conoce malas palabras en inglés. Un nombre que en castellano (o en el castellano de algún país) es una mala palabra puede pasar sin problemas. Si tenés dudas, preguntá a alguien de otro país. 😅

Crear el paquete

💻 En vivo

usethis::create_package("ruta_al_paquete/dichosos")

El argumento es la ruta donde se crea el paquete. El último pedazo de la ruta (dichosos) es el nombre del paquete.

RStudio abre una sesión nueva, con el proyecto del paquete. A partir de ahora trabajamos en esa sesión.

AdvertenciaNo crees un paquete adentro de otro proyecto

Si creás el paquete adentro de otro proyecto de RStudio (o adentro de otro paquete), usethis te avisa con un mensaje. Elegí otra carpeta.

Lo que creó usethis

dichosos/
├── .gitignore
├── .Rbuildignore
├── DESCRIPTION
├── NAMESPACE
├── R/
└── dichosos.Rproj
  • DESCRIPTION: los metadatos del paquete: nombre, título, descripción, quién lo escribió, la licencia y, más adelante, las dependencias.
  • R/: acá van los scripts con las funciones. Por ahora está vacía.
  • NAMESPACE: la lista de funciones que el paquete ofrece al mundo. No se edita a mano: lo va a escribir roxygen2 por nosotros.
  • .Rbuildignore: se listan los archivos que son parte de nuestro proyecto, pero no del paquete (como el .Rproj). De esta manera son ignorados cuando se construye el paquete.
  • .gitignore: archivos que Git no debería versionar (se suele usar para datos muy grandes).
  • dichosos.Rproj: el proyecto de RStudio.

El primer check()

devtools::check() corre R CMD check, la revisión oficial de R para paquetes: más de 50 comprobaciones sobre la estructura, la documentación, el código, los datos y los tests.

💻 En vivo

devtools::check()

Atajo de teclado: Ctrl + Shift + E (en Mac, Cmd + Shift + E).

Un paquete vacío ya tiene un problema:

❯ checking DESCRIPTION meta-information ... WARNING
  Non-standard license specification:
    `use_mit_license()`, `use_gpl3_license()` or friends to pick a
    license

0 errors ✔ | 1 warning ✖ | 0 notes ✔

check() nos dice tres tipos de cosas:

  • ERROR: algo grave. Hay que arreglarlo.
  • WARNING: algo que probablemente esté mal. Hay que arreglarlo.
  • NOTE: algo para mirar. A veces se puede ignorar.

El mensaje nos dice qué hacer: elegir una licencia.

La licencia

La licencia dice qué pueden hacer otras personas con tu código. La licencia MIT es permisiva: se puede usar, copiar y modificar tu código, citando la fuente.

💻 En vivo

usethis::use_mit_license("Yanina Bellini Saibene")
devtools::check()
0 errors ✔ | 0 warnings ✔ | 0 notes ✔

¡Nuestro primer paquete sin problemas! Está vacío, pero es un paquete. 🎉

TipOtras licencias

Hay una función para cada licencia: use_gpl3_license(), use_apache_license(), use_cc0_license(), use_ccby_license()… Las licencias Creative Commons son para datos y documentos, no para código.

Presentar el paquete: DESCRIPTION

Abrí DESCRIPTION. Hay que completar tres campos:

  • Title: una línea, con mayúscula en las palabras importantes, sin punto final.
  • Description: un párrafo sobre qué hace el paquete. Las líneas que siguen a la primera empiezan con cuatro espacios.
  • Authors@R: quiénes hicieron el paquete, con la función person(). El rol "cre" es la persona que lo mantiene y "aut" quien lo escribió.
TipPara no escribir tu nombre en cada paquete

Podés guardar tus datos en el archivo .Rprofile, que R lee cada vez que arranca. Así usethis completa Authors@R y la licencia por vos. Abrilo con usethis::edit_r_profile() y agregá:

options(
  usethis.description = list(
    "Authors@R" = utils::person(
      "Tu nombre", "Tu apellido",
      email = "tu.correo@ejemplo.com",
      role = c("aut", "cre")
    ),
    License = "MIT + file LICENSE",
    Language = "es"
  )
)

Se configura una sola vez por computadora. Es como ajustar la altura del asiento de la bicicleta: no lo tenés que hacer cada vez que salís a andar.

Desafío 2.1: Crear tu paquete 10 minutos

  1. Comprobá el nombre con pak::pkg_name_check("dichosos").
  2. Creá el paquete con usethis::create_package(). Guardalo en una carpeta que encuentres fácil, por ejemplo en Documentos o en tu carpeta de proyectos, pero no adentro de otro proyecto de RStudio.
  3. En la nueva sesión de RStudio, corré devtools::check().
  4. Agregá la licencia MIT y volvé a correr devtools::check() hasta ver 0 errores y 0 warnings.
pak::pkg_name_check("dichosos")
usethis::create_package("~/Documents/dichosos")   # o la ruta que elijas

# En la sesión nueva, la del paquete:
devtools::check()
usethis::use_mit_license("Tu Nombre")
devtools::check()

Si te aparece una NOTE que dice unable to verify current time, no te preocupes: pasa cuando no hay conexión a internet o la red es lenta.

Desafío 2.2: ¿Quién es quién? 5 minutos, en parejas

Uní cada archivo o carpeta con lo que hace.

Archivo o carpeta Qué hace
1. DESCRIPTION a. Lista las funciones que el paquete exporta. No se edita a mano.
2. R/ b. Lista archivos que R ignora cuando construye el paquete.
3. NAMESPACE c. Tiene los metadatos: nombre, título, autoría, licencia, dependencias.
4. .Rbuildignore d. Guarda los scripts con las funciones.
5. dichosos.Rproj e. Es el archivo del proyecto de RStudio.

1-c, 2-d, 3-a, 4-b, 5-e.

Desafío 2.3: Presentá tu paquete 5 minutos

Abrí el archivo DESCRIPTION y completá:

  • Title: una línea, con mayúscula en cada palabra importante y sin punto final.
  • Description: un párrafo que explique qué hace el paquete.
  • Authors@R: tu nombre y tu correo.

Corré devtools::check() otra vez. ¿Cambió algo?

Package: dichosos
Title: Dichos y Expresiones Populares de America Latina
Version: 0.0.0.9000
Authors@R:
    person("Yanina", "Bellini Saibene", , "tu.correo@ejemplo.com",
           role = c("aut", "cre"))
Description: Un paquete de ejemplo para aprender a desarrollar paquetes
    de R. Incluye dichos y expresiones populares de America Latina y
    funciones para elegirlos al azar y buscarlos por palabra.
License: MIT + file LICENSE

check() debería seguir dando 0 errores y 0 warnings. Estos campos no se comprueban por su contenido, pero son lo primero que ve cualquier persona que mira tu paquete.

Puntos clave

  • pak::pkg_name_check() comprueba si el nombre es válido y está disponible.
  • usethis::create_package() crea toda la estructura del paquete.
  • devtools::check() revisa el paquete: el objetivo es 0 errores y 0 warnings.
  • DESCRIPTION tiene los metadatos; NAMESPACE no se toca a mano.