8  Otros componentes

Los dos primeros capítulos de esta parte del libro cubren las dos cosas más obvias que la gente distribuye a través de un paquete R: funciones (Capítulo 6) y datos (Capítulo 7). Pero eso no es todo lo que se necesita para crear un paquete R. Hay otros componentes del paquete que son necesarios, como un archivo DESCRIPTION, o altamente recomendados, como pruebas y documentación.

Las siguientes partes del libro están organizadas en torno a conceptos importantes: dependencias, pruebas y documentación. Pero antes de profundizar en esos temas, este capítulo desmitifica algunas partes del paquete que no son necesarias en todos los paquetes, pero que es bueno tener en cuenta.

8.1 Otros directorios

A continuación se muestran algunos directorios de nivel superior que puede encontrar en un paquete fuente de R, en orden aproximado de importancia y frecuencia de uso:

  • src/: Archivos fuente y de encabezado para código compilado, generalmente C y C++. Esta es una técnica importante que se utiliza para hacer que los paquetes de R tengan más rendimiento y desbloquear el poder de las bibliotecas externas para los usuarios de R. A partir de la segunda edición, el libro ya no cubre este tema, ya que un tratamiento verdaderamente útil del código compilado requiere más espacio del que podemos darle aquí. El tidyverse generalmente utiliza el paquete cpp11 para conectar C++ a R; la mayoría de los otros paquetes usan Rcpp, el paquete mejor establecido para integrar R y C++.

  • inst/: para archivos adicionales arbitrarios que desee incluir en su paquete. Esto incluye algunos archivos especiales, como CITATION, que se describe a continuación en Sección 8.2. Otros ejemplos de archivos que pueden aparecer debajo de inst/ incluyen plantillas de R Markdown (consulte usethis::use_rmarkdown_template()) o RStudio add-ins.

  • tools/: Archivos auxiliares necesarios durante la configuración, que generalmente se encuentran en compañía de un script configure. Discutimos esto más a continuación en Sección 8.3.

  • demo/: para demostraciones de paquetes. Consideramos las demostraciones como un fenómeno heredado, cuyos objetivos ahora se cumplen mejor con viñetas. (Capítulo 17). Para paquetes mantenidos activamente, probablemente tenga sentido reutilizar el contenido de cualquier demostración existente en algún lugar que sea más visible, por ejemplo. en README.Rmd (Sección 18.1) o en viñetas (Capítulo 17). Estas otras ubicaciones ofrecen otras ventajas, como garantizar que el código se ejerza con regularidad. Esto no es cierto para las demostraciones reales, lo que las deja vulnerables a la descomposición.

  • exec/: para scripts ejecutables. A diferencia de los archivos ubicados en otros directorios, los archivos en exec/ se marcan automáticamente como ejecutables. Empíricamente, en la medida en que los paquetes R incluyen scripts para intérpretes externos, el directorio inst/ parece ser la ubicación preferida en estos días.

  • po/: traducciones de mensajes. Esto es útil, pero está más allá del alcance de este libro. Consulte el capítulo Internacionalización de “Escribir extensiones de R” y el paquete potools para más detalles.

8.2 Archivos instalados

Cuando se instala un paquete, todo lo que está en inst/ se copia en el directorio de nivel superior del paquete instalado (consulte Figura 3.1). En cierto sentido, inst/ es lo opuesto a .Rbuildignore: donde .Rbuildignore le permite eliminar archivos y directorios arbitrarios del paquete compilado, inst/ le permite agregarlos.

Advertencia

Eres libre de poner lo que quieras en inst/ con una precaución: debido a que inst/ se copia en el directorio de nivel superior, no crees un subdirectorio que colisione con cualquiera de los directorios que componen la estructura oficial. de un paquete R. Recomendamos evitar directorios con significado especial ya sea en la forma fuente o instalada de un paquete, como por ejemplo: inst/data, inst/help, inst/html, inst/libs, inst/man, inst/Meta, inst/R, inst/src, inst/tests, inst/tools, and inst/vignettes. En la mayoría de los casos, esto evita que tenga un paquete con formato incorrecto. Y aunque algunos de los directorios anteriores están técnicamente permitidos, pueden ser una fuente innecesaria de confusión.

Estos son algunos de los archivos y carpetas más comunes que se encuentran en inst/:

  • inst/CITATION: cómo citar el paquete, consulte a continuación para obtener más detalles.

  • inst/extdata: datos externos adicionales para ejemplos y viñetas. Consulte la sección Sección 7.3 para obtener más detalles.

¿Qué sucede si necesita una ruta al archivo en inst/foo para usarla, por ejemplo, en el código debajo de R/ o en su documentación? La solución predeterminada es utilizar system.file("foo", package = "tupaquete"). Pero esto presenta un dilema en el flujo de trabajo: cuando estás desarrollando tu paquete, interactúas con él en su forma fuente (inst/foo), pero tus usuarios interactúan con su forma instalada (/foo). Afortunadamente, devtools proporciona una corrección para system.file() que se activa con load_all(). La sección Sección 7.3.1 cubre esto con más profundidad e incluye una alternativa interesante, fs::path_package() .

8.2.1 Cita del paquete

El archivo CITATION vive en el directorio inst y está íntimamente conectado a la función citation() que le indica cómo citar paquetes R y R. Llamar a citation() sin ningún argumento le indica cómo citar la base R:

citation()
#> To cite R in publications use:
#> 
#>   R Core Team (2024). _R: A Language and Environment for
#>   Statistical Computing_. R Foundation for Statistical
#>   Computing, Vienna, Austria. <https://www.R-project.org/>.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Manual{,
#>     title = {R: A Language and Environment for Statistical Computing},
#>     author = {{R Core Team}},
#>     organization = {R Foundation for Statistical Computing},
#>     address = {Vienna, Austria},
#>     year = {2024},
#>     url = {https://www.R-project.org/},
#>   }
#> 
#> We have invested a lot of time and effort in creating R,
#> please cite it when using it for data analysis. See also
#> 'citation("pkgname")' for citing R packages.

Llamarlo con un nombre de paquete le indica cómo citar ese paquete:

citation("tidyverse")
#> To cite package 'tidyverse' in publications use:
#> 
#>   Wickham H, Averick M, Bryan J, Chang W, McGowan LD,
#>   François R, Grolemund G, Hayes A, Henry L, Hester J, Kuhn
#>   M, Pedersen TL, Miller E, Bache SM, Müller K, Ooms J,
#>   Robinson D, Seidel DP, Spinu V, Takahashi K, Vaughan D,
#>   Wilke C, Woo K, Yutani H (2019). "Welcome to the
#>   tidyverse." _Journal of Open Source Software_, *4*(43),
#>   1686. doi:10.21105/joss.01686
#>   <https://doi.org/10.21105/joss.01686>.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Article{,
#>     title = {Welcome to the {tidyverse}},
#>     author = {Hadley Wickham and Mara Averick and Jennifer Bryan and Winston Chang and Lucy D'Agostino McGowan and Romain François and Garrett Grolemund and Alex Hayes and Lionel Henry and Jim Hester and Max Kuhn and Thomas Lin Pedersen and Evan Miller and Stephan Milton Bache and Kirill Müller and Jeroen Ooms and David Robinson and Dana Paige Seidel and Vitalie Spinu and Kohske Takahashi and Davis Vaughan and Claus Wilke and Kara Woo and Hiroaki Yutani},
#>     year = {2019},
#>     journal = {Journal of Open Source Software},
#>     volume = {4},
#>     number = {43},
#>     pages = {1686},
#>     doi = {10.21105/joss.01686},
#>   }

El archivo inst/CITATION asociado tiene este aspecto:

bibentry(
  "Article",
  title = "Welcome to the {tidyverse}",
  author = "Hadley Wickham, Mara Averick, Jennifer Bryan, Winston Chang, Lucy D'Agostino McGowan, Romain François, Garrett Grolemund, Alex Hayes, Lionel Henry, Jim Hester, Max Kuhn, Thomas Lin Pedersen, Evan Miller, Stephan Milton Bache, Kirill Müller, Jeroen Ooms, David Robinson, Dana Paige Seidel, Vitalie Spinu, Kohske Takahashi, Davis Vaughan, Claus Wilke, Kara Woo, Hiroaki Yutani",
  year = 2019,
  journal = "Journal of Open Source Software",
  volume = 4,
  number = 43,
  pages = 1686,
  doi = "10.21105/joss.01686",
)

Puede llamar a usethis::use_citation() para iniciar este archivo y completar sus datos. Lea el tema de ayuda ?bibentry para obtener más detalles.

8.3 Herramientas de configuración

Si un paquete tiene un script de configuración (configure en sistemas Unix, configure.win en Windows), se ejecuta como primer paso mediante R CMD INSTALL. Esto generalmente se asocia con un paquete que tiene un subdirectorio src/ que contiene código C/C++ y el script configure es necesario en el momento de la compilación. Si ese script necesita archivos auxiliares, estos deben ubicarse en el directorio tools/. Los scripts debajo de tools/ pueden tener un efecto en el paquete instalado, pero el contenido de tools/ finalmente no estará presente en el paquete instalado. En cualquier caso, esto es principalmente (pero no exclusivamente) relevante para paquetes con código compilado, lo cual está más allá del alcance de este libro.

Mencionamos esto porque, en la práctica, algunos paquetes usan el directorio tools/ para un propósito diferente pero relacionado. Algunos paquetes tienen tareas de mantenimiento periódicas para las cuales resulta útil registrar instrucciones detalladas. Por ejemplo, muchos paquetes incorporan algún tipo de recurso externo, p. código o datos:

  • Código fuente y encabezados para una biblioteca C/C++ integrada de terceros.

  • Kits de herramientas web.

  • Código R integrado (en lugar de importado).

  • Especificación para una API web.

  • Paletas de colores, estilos y temas.

Estos activos externos también suelen evolucionar con el tiempo, por lo que es necesario reingerirlos periódicamente. Esto hace que sea particularmente gratificante implementar dicha limpieza de manera programática.

Este es el segundo uso no oficial del directorio tools/, caracterizado por dos grandes diferencias con respecto a su propósito oficial: los paquetes que hacen esto generalmente no tienen un script configure y enumeran tools/ en .Rbuildignore, lo que significa que estos scripts no están incluidos en el paquete. Estos scripts se mantienen en el paquete fuente para comodidad del desarrollador, pero nunca se envían con el paquete.

Esta práctica está estrechamente relacionada con nuestra recomendación de almacenar las instrucciones para la creación de datos del paquete en data-raw/ (sección Sección 7.1.1) y registrar el método de construcción de cualquier dispositivo de prueba (sección Sección 15.1.3).