A medida que los análisis de datos científicos aumentan en complejidad, también aumentan los desafíos para asegurarse que estos análisis sean reproducible. Varias propuestas han surgido para intentar solucionar los problemas de reproducibilidad en el análisis computacional de datos.
Lastimosamente esto se complica aún mas con la falta de instrucción formal en el manejo y estructuración de datos para análisis que sufren (sufrimos) los científicos. Esto hace casi inevitable la poca consistencia y hasta el caos en nuestra organización de datos para proyectos de investigación. Este es un ejemplo de un proyecto “poco estructurado” (por usar un eufemismo):
Esta (falta de) “estructura” no es práctica. Lastimosamente, es probable que no sea un caso aislado.
En este tutorial hablaremos sobre algunas de las herramientas que se han desarrollado para solventar estos problemas que se han desarrollado en R.
Aquí encontrarán una lista corta y para nada exhaustiva de ejemplos de estructura de carpetas para proyectos de análisis de datos.
Noble (2009) propone una estructura de datos especifica para datos bioinformáticos (aunque podría ser adaptada a otras necesidades):
Esta estructura, sin embargo, utiliza carpetas con fechas para llevar el orden cronológico del análisis, algo que debería ser documentado con un sistema de control de versiones (i.e. Git). Por lo que resulta poco funcional.
En este blog se propone el siguiente formato:
analysis_r-dir/
|
├── code/
│ ├── processed
│ └── raw
├── data/
│ ├── raw/
│ └── clean/
├── figures/
│ ├── exploratory
│ └── final
└── text/
├── final
└── notes
Las principales carpetas incluyen:
code: contiene todos los scripts de R (u otros lenguajes); los crudos (?) van en “./code/raw” y los procesados en “./processed/clean”
data: cualquier tipo de datos, los crudos van en “./data/raw” y los procesados en “./data/clean”
figures: las figuras exploratorias van en “./figures/exploratory” y las definitivas en “./figures/final”
Este formato puede ser copiado (o clonado) de su repositorio de github.
Las estructura propuesta es similar a otras que encontramos en la web. Las variaciones dependen un poco del tipo de datos y el formato de los resultado obtenidos (i.e. imágenes vs arboles filogéneticos).
Este formato es muy similar al anterior, y se incluye principalmente para resaltar los factores comunes entre los diferentes formatos propuestos:
nombre_del_proyecto
|--data
|--raw
|--file_001.xlsx
|--file_002.gen
|--file_002.sample
|--tidy
|--file_001-cleaned.csv
|--refs
|--Oldach_2018.pdf
|--analysis
|--01-analysis.Rmd
|--figures
|--01-scatterplot.jpg
|--01-correlation.png
|--R
|--exploratory_analysis.R
|--pdf_scraper.R
|--name_of_project.Rproj
|--run_all.R
Las principales diferencias con el formato “r-dir” son el uso de una carpeta de referencias y el código para compilar el compendio en el directorio raíz.
El formato se describe en detalle en este blog y puede ser clonado de su repositorio de github.
Algunas de estas herramientas disponibles en paquetes de R utilizan
la estructura de carpetas e integración continua propia de estos
paquetes (Marwick et al. 2018; Vourre & Crump 2020). Uno de estos es
el paquete vertical
(Vourre & Crump 2020). Sus autores
proponen varias ventajas de utilizar este formato para compartir una
productos de investigación (desde guiones de experimentos hasta
artículos, presentaciones y carteles):
Los paquetes de R tienen una estructura de archivos estandarizada y bien organizada que es útil para fines organizativos
Los investigadores a menudo desarrollan funciones personalizadas para el análisis, y ponerlas en un paquete de R facilita compartir las funciones
Los paquetes R pueden incluir datos de un proyecto de investigación y proveen una forma natural de documentar los datos utilizando los mismos esquemas para documentar funciones de R
Los paquetes de R incluyen varios documentos a través de la carpeta de viñetas, que en principio podrían incluir varios formatos para comunicar la investigación, como un manuscrito o un conjunto de diapositivas escrito en R Markdown
Los paquetes R se pueden convertir automáticamente en sitios web
a través de pkgdown
, lo que proporciona un formato
atractivo para compartir materiales relacionados a la
investigación
Sin embargo el uso de este formato puede generar mas problemas de los que ayuda a resolver. Aquí enumero algunas de las incongruencias:
Las funciones deberían usarse una vez o en un solo punto en el flujo de análisis, entonces, ¿para que compilarlas y documentarlas con tanto detalle?
Documentar paquetes y las funciones dentro de estos es complejo
DESCRIPTION duplica esfuerzo e información de README y demanda un mayor conocimiento de formato y convenciones específicas de paquetes de R
Hacer datos disponibles al cargar el ambiente no provee ventajas
y hace los datos menos accesibles fuera de R (i.e. no se gana nada
usando data("base_de_datos")
en vez de
read.csv("base_de_datos.csv")
)
Los paquetes son para compartir herramientas que se usen repetidas veces. La reproducción de un análisis de datos se da una o pocas veces
Los paquetes de R tienen carpetas que no tienen funcionalidad en análisis de datos (“man”, “vignettes”, “inst”)
El integrar los componentes de un paquete (necesario para poder usar integración continua) requiere de otros archivos con estructuras y convenciones complejas que implican una curva de aprendizaje innecesariamente empinada
Para una discusión mas detallada de los problemas asociados con el uso de paquetes como plantillas les recomendamos leer este post (McBrain 2020).
El paquete vertical
provee un flujo de trabajo
estructurado basado en la estructura de carpetas e integración continua
de los paquetes de R para crear y compartir materiales y recursos de
investigación como un paquete de R (Matthew et al. 2020). El paquete se
puede instalar y/o cargar desde github así (aún no está en CRAN(?)):
También necesitarán otros paquetes si desean hacer uso de funcionalidades como escribir artículos y generar presentaciones:
# instalar papaja
devtools::install_github("crsh/papaja")
install.packages("tinytex")
tinytex::tlmgr_update()
# si no puede generar los articulos trate esto como ultima
# opcion update.packages(ask = FALSE, checkBuilt = TRUE)
La instalación del paquete vertical
agrega una nueva
plantilla de proyecto a RStudio (RStudio debe reiniciarse después de
instalarvertical
para que reconozca la plantilla). Los
usuarios pueden iniciar un nuevo proyecto “vertical” desde RStudio
eligiendo la opción al crear un nuevo proyecto. Por defecto, un proyecto
“vertical” se estructura de la siguiente manera:
El nuevo proyecto contiene un esqueleto más complejo que el de un paquete de R:
_pkgdown.yml
para controlar los parámetros
del sitio web cuando se procesa con pkgdown
De forma predeterminada, vertical
incluye plantillas de
R Markdown de otros paquetes dentro de cada carpeta para crear cada tipo
de contenido. Como resultado, vertical
sugiere usar R como
una fuente de soluciones de plataforma única para la creación de
productos de investigación.
Luego de instalar vertical
reinicie RStudio, luego siga
estos pasos para iniciar un nuevo proyecto vertical
. Cuando
elija un nombre, debe ser un nombre de un
paquete de R válido. Por ejemplo, el nombre debe contener letras,
números o puntos (por ejemplo, mi.nombre), pero sin puntos al final.
Esto significa que no hay espacios, guiones ni guiones bajos.
También puede crear un proyecto ‘vertical’ desde la consola, consulte
la documentación de vertical_project()
para más opciones.
Esto carga la ventana de plantillas de proyectos de R desde la
consola:
Esta es la estructura de carpetas que genera:
compendio_vertical/
|
├── data_raw/
├── manuscripts/
│ ├── manuscript.Rmd
│ └── r-references.bib
├── posters/
├── R/
├── slides/
└── vignettes/
Ejercicio 1
1.1 Cree compendio usando vertical
1.2 Modifique el archivo R markdown en ‘./manuscripts/’ y genere nuevamente el HTML
El objetivo de rrtools
es “proporcionar instrucciones,
plantillas y funciones para crear un compendio básico adecuado para
escribir un artículos o informes reproducibles en R” (Marwick 2019).
Este paquete documenta los pasos clave y proporciona funciones útiles
para crear rápidamente un nuevo compendio de investigación.
rrtools
brinda una plantilla para la escritura académica
utilizando R Markdown y bookdown
. También permite el
aislamiento de su entorno computacional mediante Docker
, el
control de versiones de paquetes mediante MRAN
y la
integración continua mediante Travis
:
Podemos iniciar un compendio con rrtools
así (no lo
corran si están dentro de un proyecto de Rstudio):
Deben actualizar el archivo DESCRIPTION (ubicado en el directorio del compendio) para incluir metadatos precisos. Por ejemplo, la sección ‘imports’debe tener los nombres de los paquetes utilizados en los códigos en nuestro compendio (i.e. ’Imports: warbleR, baRulho, NatureSounds’).
Podemos agregar una licencia al compendio de esta forma:
Esto añade la licencia a DESCRIPTION y genera un archivo LICENCE con los detalles de la licencia. Por defecto utiliza la licencia de MIT aunque otras licencias pueden ser definidas.
A diferencia de vertical
, rrtools
no genera
todas las carpetas básicas necesarias para un compendio. Podemos crear
estas carpetas de esta forma:
Esto genera la carpeta “./analysis” con la siguiente estructura:
analysis/
|
├── paper/
│ ├── paper.Rmd # documento para generar el articulo
│ └── references.bib # referencias en formato bibtex
├── figures/ # figuras producidas por el rmarkdown
|
├── data/
│ ├── raw_data/ # datos crudos (originales)
│ └── derived_data/ # datos procesados
|
└── templates
├── journal-of-archaeological-science.csl # estilo de citas
|
├── template.docx # plantilla de articulo generado
└── template.Rmd # plantilla para rmd de articulo
EL archivo README.Rmd se puede crear asi:
EL README generado incluye una plantilla que muestra cómo citar su proyecto (debe ser editado para incluir el título y el DOI correctos). También contiene información de la licencia, las figuras, el código y los datos de su compendio.
Esta función también agrega otros dos archivos Rmd: un código de conducta para los usuarios (CONDUCT.md) y otro con instrucciones básicas para las personas que desean contribuir a su proyecto (CONTRIBUTING.md).
Además ofrece funciones como rrtools::use_dockerfile()
y
rrtools::use_travis()
para facilitar la integración
continua. Visite el
repositorio de github del paquete para mas detalle.
El paquete workflowr
intenta ayudar a los investigadores
a “organizar sus análisis de una manera que promueve la gestión eficaz
del proyecto, la reproducibilidad, la colaboración y el intercambio de
resultados” (Blischak et al. 2019). workflowr
combina
programación literaria (knitr
y rmarkdown
) y
control de versiones (Git, a través de git2r
) para generar
un sitio web que contiene resultados documentados, y ‘versionados’.
A diferencia de rrtools
y vertical
,
workflowr
no emula la estructura de carpetas de los
paquetes de R, lo cual simplifica su uso y hace mas intuitiva su
estructura desde el punto de vista del investigador.
Estas son algunas de las características del paquete que se detallan en su sitio de github:
El paquete lo podemos instalar así:
Para crear un proyecto con workflowr
primero debemos
configurar git con la función wflow_git_config()
y luego lo
iniciamos con wflow_start()
:
# Configurar Git
wflow_git_config(user.name = "nombre completo", user.email = "correo@dominio")
# Empezar un proyecto
wflow_start("mi_compendio")
Esta es la estructura de las carpetas en el compendio de ‘workflowr’:
mi_compendio/
├── .gitignore
├── .Rprofile
├── _workflowr.yml
├── analysis/
│ ├── about.Rmd
│ ├── index.Rmd
│ ├── license.Rmd
│ └── _site.yml
├── code/
│ ├── README.md
├── data/
│ └── README.md
├── docs/
├── myproject.Rproj
├── output/
│ └── README.md
└── README.md
Y con este código podemos compilar el sitio del compendio:
Este comando ‘teje’ todos los archivos de R Markdown en la carpeta ‘./analysis’ y guarda los archivos HTML correspondientes en ‘./docs’. Cada archivo se crea en su propia sesión R externa para evitar posibles conflictos entre análisis (este es el comportamiento por defecto de archivos Rmd). Ademas abre la copia local del sitio del compendio en el navegador de internet. También podemos darle un vistazo a la copia local del sitio así:
workflowr
distingue entre los archivos R Markdown que se
publican y los que no se publican. Un archivo publicado se incluye en el
sitio web en línea; mientras que el archivo HTML de un archivo R
Markdown no publicado solo se puede ver en la computadora local. Dado
que el proyecto recién se inició, no hay archivos publicados. Para ver
el estado del proyecto de workflowr
, debemos usar
wflow_status()
:
Si queremos hacer los HTMLs públicos, debemos usar la función
wflow_publish()
y proveer los nombres de los R markdowns
que los generan con el argumento files. Además debemos agregar un
mensaje para el ‘commit’ que acompaña los cambios generados cuando se
sincroniza con la copia remota:
# publicar rmds
wflow_publish(files = c("analysis/index.Rmd", "analysis/about.Rmd",
"analysis/license.Rmd"), message = "mi primer commit del compendio")
En este punto hemos creado un sitio web con control de versiones que
existe localmente. El siguiente paso es ponerlo en un repositorio en
linea (i.e. GitHub o GitLab). Para subir y/o sincronizar el compendio
(incluyendo el sitio web) a github usamos la función
wflow_use_github()
. El único argumento que requiere es el
nombre de usuario:
El tutorial “getting
started” de workflowr
provee mas detalles de cada uno
de los pasos para generar compendios con este paquete. La documentación
es bastante completa, incluyendo varios otros tutoriales para
personalizar los compendios y sus sitios web. [Aquí podemos encontrar la
lista de tutoriales](https://jdblischak.github.io/workflowr/articles/index.html.
Ejercicio 2
2.1 Cree un compendio usando workflowr
2.2 Cree el sitio del compendio
Este es un paquete que estamos desarollando recientemente. Por el momento solo permite crear la estructura de carpetas y generar un Rmarkdown para escribir el artículo. Tambien permite visualizar la estructura del compendio en la consola. La principal diferencia con los otros paquetes es que no se casa con una sola estructura; provee varias estructuras alternativas y también permite al usuario generar sus propios formatos.
Para usarlo debemos primero instalarlo desde github así:
El paquete viene con 13 estructuras de carpetas.Se pueden usar con la
función compendium_skeleton()
. La función crea las
carpetas/subcarpetas e imprime un diagrama del compendio en la
consola:
path = tempdir()
make_compendium(name = "proyect_x", path = path, format = compendiums$basic$skeleton)
(en el ejemplo se usa un directorio temporal pero este debe ser cambiado al directorio donde se quiere crear el compendio)
Podemos usar formatos de otras fuentes. En este caso usamos el de Wilson et al. (2017):
También podemos añadir comentarios para explicar los contenidos de cada carpeta:
make_compendium(name = "proyect_z", path = path, format = compendiums$large_compendium$skeleton,
comments = compendiums$large_compendium$comments)
Cuando se crea un compendio que incluye una carpeta llamada “manuscript” el paquete añade automáticamente el archivo “manuscript_template.Rmd” que puede ser usado para escribir el artículo del proyecto.
La idea es incluir funciones para identificar archivos grandes que no pueden ser subidos a github y poder subirlos a otros repositorios (i.e. figshare o zenodo).
Ejercicio 3
3.1 Cree un compendio con una estructura personalizada usando
sketchy
3.2 Añada comentarios a cada carpeta
Session information
## R version 4.1.1 (2021-08-10)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 20.04.2 LTS
##
## Matrix products: default
## BLAS: /usr/lib/x86_64-linux-gnu/blas/libblas.so.3.9.0
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.9.0
##
## locale:
## [1] LC_CTYPE=es_ES.UTF-8
## [2] LC_NUMERIC=C
## [3] LC_TIME=es_CR.UTF-8
## [4] LC_COLLATE=es_ES.UTF-8
## [5] LC_MONETARY=es_CR.UTF-8
## [6] LC_MESSAGES=es_ES.UTF-8
## [7] LC_PAPER=es_CR.UTF-8
## [8] LC_NAME=C
## [9] LC_ADDRESS=C
## [10] LC_TELEPHONE=C
## [11] LC_MEASUREMENT=es_CR.UTF-8
## [12] LC_IDENTIFICATION=C
##
## attached base packages:
## [1] stats graphics grDevices utils datasets
## [6] methods base
##
## other attached packages:
## [1] papaja_0.1.1 tinylabels_0.2.3
## [3] rrtools_0.1.5 vertical_0.1.0.0000
## [5] workflowr_1.7.0 tufte_0.12
## [7] rticles_0.24 revealjs_0.9
## [9] rmdformats_1.0.4 kableExtra_1.3.4
## [11] rmarkdown_2.14 sketchy_1.0.2
## [13] remotes_2.4.2 leaflet_2.1.1
## [15] knitr_1.39 xaringanExtra_0.7.0
## [17] emo_0.0.0.9000 cowsay_0.8.0
##
## loaded via a namespace (and not attached):
## [1] uuid_1.1-0 systemfonts_1.0.4
## [3] plyr_1.8.7 lazyeval_0.2.2
## [5] crosstalk_1.2.0 usethis_2.1.6
## [7] ggplot2_3.3.6 urltools_1.7.3
## [9] digest_0.6.29 foreach_1.5.2
## [11] htmltools_0.5.3 rsconnect_0.8.26
## [13] fansi_1.0.3 magrittr_2.0.3
## [15] memoise_2.0.1 svglite_2.1.0
## [17] prettyunits_1.1.1 colorspace_2.0-3
## [19] rvest_1.0.2 xfun_0.31
## [21] dplyr_1.0.9 callr_3.7.0
## [23] crayon_1.5.1 jsonlite_1.8.0
## [25] zoo_1.8-10 iterators_1.0.14
## [27] ape_5.6-2 glue_1.6.2
## [29] gtable_0.3.0 emmeans_1.7.4-1
## [31] webshot_0.5.3 pkgbuild_1.3.1
## [33] scales_1.2.0 oai_0.3.2
## [35] mvtnorm_1.1-3 solrium_1.2.0
## [37] DBI_1.1.3 Rcpp_1.0.9
## [39] viridisLite_0.4.0 xtable_1.8-4
## [41] bold_1.2.0 rgbif_3.7.3
## [43] clisymbols_1.2.0 datawizard_0.4.1
## [45] htmlwidgets_1.5.4 httr_1.4.3
## [47] RColorBrewer_1.1-3 ellipsis_0.3.2
## [49] pkgconfig_2.0.3 reshape_0.8.9
## [51] sass_0.4.1 utf8_1.2.2
## [53] here_1.0.1 conditionz_0.1.0
## [55] crul_1.2.0 tidyselect_1.1.2
## [57] rlang_1.0.4 later_1.3.0
## [59] effectsize_0.7.0 munsell_0.5.0
## [61] tools_4.1.1 cachem_1.0.6
## [63] fortunes_1.5-4 cli_3.3.0
## [65] generics_0.1.2 devtools_2.4.3
## [67] evaluate_0.15 stringr_1.4.0
## [69] fastmap_1.1.0 yaml_2.3.5
## [71] processx_3.6.1 fs_1.5.2
## [73] purrr_0.3.4 ritis_1.0.0
## [75] packrat_0.8.0 nlme_3.1-152
## [77] whisker_0.4 formatR_1.12
## [79] taxize_0.9.100 xml2_1.3.3
## [81] brio_1.1.3 compiler_4.1.1
## [83] rstudioapi_0.13 curl_4.3.2
## [85] testthat_3.1.4 tibble_3.1.8
## [87] bslib_0.3.1 stringi_1.7.8
## [89] highr_0.9 ps_1.7.1
## [91] parameters_0.18.1 desc_1.4.1
## [93] lattice_0.20-44 vctrs_0.4.1
## [95] pillar_1.8.0 lifecycle_1.0.1
## [97] rmsfact_0.0.3 triebeard_0.3.0
## [99] jquerylib_0.1.4 estimability_1.3
## [101] data.table_1.14.2 insight_0.17.1
## [103] httpuv_1.6.5 R6_2.5.1
## [105] bookdown_0.27 promises_1.2.0.1
## [107] sessioninfo_1.2.2 codetools_0.2-18
## [109] assertthat_0.2.1 pkgload_1.2.4
## [111] rprojroot_2.0.3 withr_2.5.0
## [113] httpcode_0.3.0 bayestestR_0.12.1
## [115] parallel_4.1.1 grid_4.1.1
## [117] coda_0.19-4 git2r_0.30.1
## [119] getPass_0.2-2 lubridate_1.8.0