¡Por favor… Dibújame un proyecto!

Maëlle Salmon 🏠 https://masalmon.eu 🐦 ma_salmon

Licencia CC-BY-SA

👋 ¡Hola desde Nancy!

Edificios en la plaza Stanislas de Nancy. Cielo con nuves grises.

Fotografía de Dimitry Anikin en Pexels.

Hoy:
Gestionar tu proyecto R

¡Compartiré consejos y trucos!

Niñ@ disfrazado de El Pequeño Principe, mostrando las estrellas, y acostado cerca de una rosa.

Fotografía de cottonbro en Pexels.

¿Pero primero, quién soy?

Trabajo reciente

Ingeniera de software para investigación en rOpenSci a tiempo parcial, en particular manteniando nuestra guía de desarrollo y revisión de paquetes R (“dev guide”). 🔧

Trabajo sobre la proxima versión de pkgdown. ✨

E-libro “HTTP testing in R” con Scott Chamberlain. 📖

Curso “Bloguear con R Markdown” en LatinR 2020. 📝

Otras actividades

Cuenta Twitter de R-Ladies Global. 🐦 ¡Utiliza la etiqueta #RLadies !

Editora para el sistema de revisión de paquetes de rOpenSci. 📦

Varias charlas. 😉

Mis diapositivas estan en línea 😁

🔗 https://rladiesmvd-maelle.netlify.app/

Objetivos de mi charla

Que cad@ un@ aprenda al menos una cosa nueva. 😁

⚒️ Principios fundamentales para proyectos R ;

⚒ Cómo proteger tu proyecto R de cambios externos;

⚒️ Cuál estructura para tu proyecto ;

⚒️ Cómo hacer girar tu proyecto.

¿Por qué dar consejos sobre proyectos?

😿 No es lo que preguntó El Pequeño Príncipe (oveja).

😺 Mejora la vida de toda persona tocando o leyendo tus resultados y su origen. Reproducibilidad.

😹 Siempre hay algo que mejorar o sobre lo cuál procrastinar.

Porqué escucharme a mi
sobre este tema?

😦 No estoy a cargo de realizar análisis muy a menudo.

😄 Me informo mucho sobres las novedades de R.

Recursos en español

✨ https://www.learnr4free.com/es/index.html ✨

Sitio de Mine Dogucu, lista de recursos en español mantenida por Yanina Bellini Saibene.

¡Es una lista colaborativa! 😉 👋

Principios fundamentales

Rosa asperjada de agua

Fotografía de cottonbro en Pexels.

Principal fuente de consejos: Jenny Bryan!

Nota al margen: charla de Sharla Gelfand

Don’t repeat yourself, talk to yourself! Repeated reporting in the R universe

¡Sharla también es una fuente de buenas ideas! 💐

Principal fuente de consejos: Jenny Bryan!

logo de 'Everything I know is from Jenny Bryan' con un ordenador en flamas

Logo de Martin Monkman.

¿Tu proyecto, un jardín?

Jardín lleno de rosas rojas

Fotografía de Irina Iriser en Pexels.

¡Si, pero independiente!

¡Un proyecto, una carpeta!

🔥

Si la primera línea de tu programa es …

🔥 setwd("C:/usuarios/tu/una/ruta/especifica/a/tu/ordenador);

🔥 or rm(list = ls());

Jenny Bryan vendrá en tu oficina y prenderá fuego tu ordenador. 😱

Tweet

Rutas de archivo relativas
a la raíz del proyecto

NO:

readr::read_csv("/home/maelle/Documents/conferences/r-ladies-montevideo/datos/cosas-buenas.csv")

Rutas de archivo relativas
a la raíz del proyecto

Ilustración de Allison Horst explicando el paquete here. A la izquierda una cueva con setwd() y a la derecha un jardín bonito con el paquete here.

Ilustración de Allison Horst.

Paquete here
de Kirill Müller

  • .Rproj o un archivo vacío llamado .here a la raíz del proyecto.

  • Rutas relativas a este.

here::here()

[1] "/home/maelle/Documents/conferences/r-ladies-montevideo"

here::here("datos")

[1] "/home/maelle/Documents/conferences/r-ladies-montevideo/datos"

Paquete here
de Kirill Müller

readr::read_csv(here::here("datos", "cosas-buenas.csv"))

Funciona desde cuálquier parte de mi carpeta r-ladies-montevideo! (r-ladies-montevideo/README.Rmd, r-ladies-montevideo/informes/codigo.R, etc.)

Nuevo comienzo a menudo

  • ¡Reinicie R a menudo y sin miedo!

  • ¡NUNCA guardar y cargar de nuevo .RData!

“Project-oriented workflow”
(“Flujo de trabajo orientado proyecto”)

🌹 Entrada de blog de Jenny Bryan

🌹 ¡Una manera de vivir, hum, trabajar!

✨ usethis::create_project() ✨

El nombre de tus rosas

¿Qué hay en un nombre? Lo que llamamos rosa olería igual de dulce si tuviese cuálquier otro nombre.

Shakespeare en Romeo y Julieta. 🌹

¡Mentira cuando escribimos código! 😅

Nombrar tus archivos

Consejos de Jenny Bryan

  • Legibles por una máquina (sin acentos);

  • Legibles por humanos (informativos sobre el contenido);

  • Combinan bien con el orden por defecto (AAAA-MM-DD en vez DD-MM-AAAA).

Nombrar cosas

Nombrar cosas

Tu proyecto con el tiempo

🌻 ¡RESPALDO! 🌻

Cartel indicando el peligro de suelo mojado.

Fotografía de Skitterphoto en Pexels.

Control de versiones

Tu proyecto cambiará: ¿cómo registrar los cambios para poder viajar en el tiempo?

Brote.

Fotografía de PhotoMIX Company en Pexels.

Control de versiones

  • Fechas en nombres de archivos

  • o ✨ control de versiones ✨.

Aprender git: ¡difícil pero merece la pena! No R pero útil para R.

Poder intentar cosas, viajar en el pasado, entender cambios pasados.

¿Qué es git?

[Persona 1 señala un ordenador sobre un escritorio mientras otras dos personas están de pie más allá, detrás de una silla de oficina]. Persona en el ordenador: Esto es git. Hace un seguimiento del trabajo colaborativo en los proyectos a través de un hermoso modelo de árbol de la teoría de grafos distribuidos. Otra persona: Genial. ¿Cómo lo usamos? Persona en el ordenador: Ni idea. Sólo tienes que memorizar estos comandos del shell y escribirlos para sincronizar. Si obtienes errores, guarda tu trabajo en otro lugar, borra el proyecto y descarga una copia nueva.

XKCD de Randall Munroe.

¿Qué es git?

Dibujo que muestra varias versiones de una oveja, desde la oveja bebé hasta la oveja adulta, con flechas de izquierda a derecha. La oveja del medio también puede evolucionar a una caja con agujeros.

Dibujo de Damien Cornu. ❤️

Algunos comandos de git
explicados rapidamente

  • git add para empezar a “seguir” un archivo (.gitignore es la lista de los archivos que se ignoran siempre) ;
  • git commit para registrar un cambio en la historia ;
  • git pull / git push para descargar / cargar la versión local / remota (e.g. GitHub);
  • git checkout -b para crear una rama (“branch”).

Donde usar
comandos git?

Mis preferencias 😁

  • Paquetes usethis (usethis::use_git(), usethis::use_github(), etc.) y gert (gert::git_push()) desde R mismo ;
  • Ventana git en RStudio para cliquear sin ir lejos de R ;
  • Línea de comandos para los comandos pegados desde Stack Overflow ;
  • ¿Una interfaz grafica para visualizar mejor? E.g. GitKraken, VSCODE.

Recursos sobre git

Hasta ahora, lo que aprendímos de Jenny Bryan…

  • Isolar proyectos R, reiniciar R a menudo.

  • Nombrar bien a los archivos.

  • Utilizar control de versiones.

Más sabiduría
de Jenny Bryan et al

🌹 Good enough practices in scientific computing Wilson G, Bryan J, Cranston K, Kitzes J, Nederbragt L, et al. (2017) Good enough practices in scientific computing. PLOS Computational Biology 13(6): e1005510. https://doi.org/10.1371/journal.pcbi.1005510

🌹 What They Forgot to Teach You About R, Jenny Bryan, Jim Hester.

Protege tu proyecto de cambios externos

Rosa debajo de una cubierta de vidrio

Fotografía de cottonbro en Pexels.

Una historia de horror …

  • Escribes código magnífico para domar tus datos con paquete::funcion_fantastica()…

  • ¡Actualiza tu versión de paquete y no hay más funcion_fantastica()!

Había buenas razones pero ahora tu código no funciona más. 😱

Registra las dependencias del código

¡Encapsula tu proyecto! 🎉

Herramienta importante : ¡renv de Kevin Ushey!

Sucesor de packrat.

renv en 3 pasos

  • renv::init().

  • Instala y desinstala paquetes cómo usualmente. Regularmente renv::snapshot(). Metadatos de las dependencias registrados en renv.lock. 🔒

  • Tus compañer@s heredando tu proyecto utiliza renv::restore().

Aún más encapsulación

🐳 Docker? 🔒 Versión de R, sistema operativo, resumiendo: todo.

Protege tu proyecto de cambios externos

Lista de dependencias del proyecto.

La manera más facil de empezar es utilizar el paquete renv.

¿Cuál estructura de archivos
para tu proyecto?

Niño disfrazado del Pequeño Principe, manteniando una rosa gigante.

Fotografía de cottonbro en Pexels.

¿Qué hay en la carpeta de tu proyecto?

  • Datos o código para consegirlos desde una base de datos o un recurso remoto;

  • Codigo limpiando y analizando los datos;

  • Resultados en forma de gráfico, informe, etc.

¿Cuál estructura de archivos
para tu proyecto?

  • Uniforme.

  • Creación automática.

  • … ¿En forma de paquete o no?

projectTemplate

De Kenton White.

Love for ProjectTemplate, Hilary Parker (traducción mía 😅):

✅ “La rutina es tu amiga.”

✅ “Es más fácil empezar desde algo y después customizar que empezar desde 0.”

✅ “La reproducibilidad tiene que ser la más facil que se pueda.”

✅ “Encontrar cosas también debería ser lo más fácil posible.”

¿Crear un paquete R?

  • Para guardar funciones y datos utilizados en varios proyectos: ¡¡¡SI!!!

    E.g. tutorial de Shel Kariuki en R-Ladies Nairobi.

  • Para guardar un “RStudio project template” o una función que recrea una estructura de carpeta: ¡¡¡SI!!!
  • Para guardar tu proyecto, eso es decir tu proyecto en forma de paquete : tal vez.

Proyecto de análisis = 📦

  • Dependencias en DESCRIPTION,

  • Funciones en R/ con documentación en man/,

  • Datos en data/ (o data-raw/),

  • Analsis cómo vignettes/vignetas (R Markdown),

  • README informativo.

¿Proyecto de análisis = 📦?

🏄‍♂️ Re-utiliza o actualiza tus conocimientos sobre desarrollo de paquetes,

🏄‍♂️ Re-utiliza herramientas hechas para desarrollar paquetes (como devtools y usethis).

“Research compendium.” Packaging Data Analytical Work Reproducibly Using R (and Friends), Ben Marwick, Carl Boettiger & Lincoln Mullen (2018), The American Statistician, 72:1, 80-88, DOI: <10.1080/00031305.2017.1375986>

Proyecto en forma de paquetes,
herramientas específicas

📦 rrtools de Ben Marwick. Crea un compendium!

📦 holepunch de Karthik Ram. Un clic y la persona leyendo tu repositorio puede experimentar con tu código! (🤫 holepunch también funciona sin la estructura de compendium.)

🚀 R-universe de Jeroen Ooms en rOpenSci para publicar tus análisis. ¡Entrada de blog en español por Yanina Bellini Saibene!

Proyecto en forma de paquetes:
¿no?

Project as an R package: An okay idea by Miles McBain.

“Mi repuesta a les defensores de proyectos en forma de paquetes es: ==Están perdiendo tiempo creando los paquetes equivocados.==”

“En vez de forzar su trabajo en el dominio de desarrollo de paquete, con la pérdida de fidelidad consiguiente, ¿por qué no estan creando paquetes que crean la experiencia fluida como con {devtools}/{usethis}, para su dominio?”

¿Cuál estructura de archivos
para tu proyecto?

Como quieras 😉 (como tu equipo de trabajo quiera) pero

  • Estructura básica uniforme en el tiempo ;

  • Creación automática.

Haz que la reproducibilida sea ✨ más facil ✨.

¿Cómo hacer girar
tu proyecto?

Niño disfrazado del Pequeño Príncipe mostrando algo a una rosa.

Fotografía de cottonbro en Pexels.

¿Hacer girar el proyecto?

¿Cómo transformas recursos y código en resultados de análisis (informes, graficos)?

🤸

¿Cómo hacer girar
tu proyecto?

¿Tal vez sólo necesitas el botón knit/tricotar si tu proyecto es un informe R Markdown?

¿Tal vez necesitas algo más complejo?

Dos casos

  • Optimizar una pipeline/tubería.

  • Registrar versiones de un análisis (lo que entra y lo que sale).

Dos casos

  • Optimizar una pipeline/tubería. 📦 targets mantenido por Will Landau.

  • Registrar versiones de un análisis (lo que entra y lo que sale). 📦 orderly mantenido por Rich FitzJohn.

targets de Will Landau

  • targets adivina relaciones entre las piezas de un proyecto (e.g. si cambian los datos brutos, hay que rehacer todo) ;

  • targets sólo computa lo que hace falta.

Parte de la colección de paquetes de rOpenSci. Sucesor de drake del mismo autor.

targets

A la raíz de cada proyecto targets, el archivo _targets.R.

  • Cargar paquetes;

  • Cargar funciones (source() archivos de R/ por ejemplo);

  • Definir targets/objetivos!

_targets.R 1/2:
Cargar

library("dplyr")
source("R/mis-funciones.R")

_targets.R 2/2:
Targets

list(
  tar_target(
    archivo_datos_brutos,
    "datos/datos_brutos.csv",
    format = "file"
  ),
  tar_target(
    datos_brutos,
    read_csv(archivo_datos_brutos, col_types = cols())
  ),
  tar_target(
    datos,
    datos_brutos %>%
      filter(!is.na(Ozono))
  ),
  tar_target(hist, crea_grafico(datos)),
  tar_target(modelo, calcula_modelo(Ozono ~ Viento + Temperatura, datos))
)

¿Cómo gira?

  • Para construir, targets::tar_make() (y targets::tar_destroy());

  • Para entender tu “pipeline,” targets::tar_glimpse() y otras funciones similares.

Visualizar una pipeline

targets::tar_glimpse()

Diagrama mostrando los pasos de un proyecto ejemplo, desde los datos brutos a un modelo y un grafico

Ilustración del manual de targets.

¿Cómo aprender a utilizar targets?

The R Targetopia

An R package ecosystem for democratized reproducible pipelines at scale

Ecosistema de paquetes entorno de targets.

¿Cómo informarse sobre los cambios de targets?

orderly de Rich FitzJohn

(Gracias a Rich por contestar mis preguntas 🙏)

Problema diferente: registrar todo lo que entra y sale en y de un análisis, en diferentes versiones.

Por ejemplo permite hacer controles en el futuro, o combinar versiones para un analisis meta.

El analisis puede ser enorme, se necesita más que git para el respaldo.

orderly

En orderly hay repos y en repos hay “reports” (informes/tareas).

Ejemplo con un repo de una tarea. orderly::orderly_init("blop") después orderly::orderly_new("example", "blop"), un poco de copiar pegar y después tengo:

blop
├── orderly_config.yml
└── src
    └── example
        ├── orderly.yml
        └── script.R

Configuración src/example/orderly.yml

script: script.R

artefacts:
  - staticgraph:
      description: Un grafico de cosas
      filenames: mi-grafico.png
  - data:
      description: Datos que utilize
      filenames: mi-datos.csv

Programa ejemplo (script.R)

dat <- data.frame(x = 1:10, y = runif(10))
write.csv(dat, "mi-datos.csv", row.names = FALSE)

png("mi-grafico.png")
plot(dat)
dev.off()

¿Cómo gira?

  1. Experimenta con el “modo desarrollo”.
  1. Crea una versión borrador.
id <- orderly::orderly_run("example", root = "blop")

Este borrador (recursos, programa, resultados, TODO) aparece en la carpeta draft/example/id-illegible.

  1. Si te conviene, “commit.”
orderly::orderly_commit(id, root = "blop")

Este versión (recursos, programa, resultados, TODO) aparece en la carpeta archive/example/id-illegible.

¿Cómo gira?

⚠️ Las carpetas archive y draft pueden ser enormes, hace falta un sistema de respaldo que no es git. ⚠️

(¡puedes utilizar git para las otras carpetas!)

¿Cómo aprender a utilizar orderly?

¿Cómo informarse sobre los cambios de orderly?

¿Cómo hacer girar
tu proyecto?

  • Solo un o un par de informes R Markdown: botón knit?

  • Optimizar una pipeline/tuberiá: targets.

  • Registrar todas las versiones : orderly, con un sistema de respaldo.

Hay otras herramientas y puedes crear la tuya! workflowr, cabinets, etc..

Conclusión

Niño disfrazado del Pequeño Principe sentado en el suelo y mirando lejos.

Fotografía de cottonbro en Pexels.

¡Gracias!

Antes del resumen, ¡gracias a las organizadoras! 🙏 Daniela Vázquez, Natalia da Silva, Paula Pereda-Suárez, Maine Fariello. 🙏

¡Gracias a tod@s! 🙏

Gracias a Yanina Bellini Saibene y María Rosa Morales por sus comentarios sobre las diapositivas!

Gracias a Christophe Dervieux por sus comentarios sobre el contenido de esta charla!

¿Cómo dibujar un proyecto?

🌻 Principios fundamentales cómo isolar tu proyecto, respaldos.

🌻 Encapsular tu proyecto. (¿renv? ¿Docker?)

🌻 Estructura práctica, uniforme y automática. (¿en forma de paquete o no?)

🌻 Utilizar herramientas adaptadas para obtener resultados (¿optimizar una pipeline/tubería? ¿registrar todas las versiones?).

¿Cómo aprender a dibujar un proyecto?

Otros recursos en inglés:

¿Cómo dibujar un proyecto?

🌹 Lee todo lo que escribe Jenny Bryan.

🌹 Elige o crea, con tu equipo, la caja donde pones y haces girar tu proyecto.

🌹 No tengas miedo de actualizar tus herramientas con el tiempo.

Diapositivas 🔗 https://rladiesmvd-maelle.netlify.app/