“Buenas prácticas” con �Jupyter Notebook

Pablo Huijse

​

Mayo, 2020

Reproducibilidad

Se refiere a la habilidad de replicar los resultados de un trabajo científico previo

¿Es ciencia si no es reproducible? NO

En el caso de la ciencia de la computación y ciencia de los datos necesitamos como mínimo que “los datos y el código fuente usado para analizar dichos datos esté disponible”

¿Es esto suficiente? NO

Se necesita también: Documentación, instrucciones, dependencias, configuraciones, etc

Jupyter notebook

Nuevo formato que combina

• código (Python, Julia, R, C, etc)
• resultados y visualizaciones
• ecuaciones
• texto enriquecido
• interfaces de usuario (GUI)

esto lo hace ideal para crear “narrativas científicas” interactivas

​

Hipótesis

Datos

Modelos

Interpretación

Experimento

​

Nuestros experimentos serán ser leídos y re-ejecutados por nosotros mismos y por otras personas

Nuestros experimentos deben ser entendibles y fácilmente reproducibles

​

Hipótesis

Datos

Modelos

Interpretación

Experimento

Dificultades asociadas a Jupyter Notebook

1. El código puede correr en orden arbitrario
2. Estados ocultos difíciles de inspeccionar
• corre una celda y luego bórrala ¿De dónde salió esa variable?
• se puede redefinir una variable en distintos bloques ¿Cuál es la versión más nueva?
• referencias a variables de bloques que aun no se han ejecutado
3. No son modulares
• no es fácil reutilizar código de un notebook
4. El control de versiones es engorroso y son difíciles de testear

Podemos terminar con notebooks desordenados y difíciles de mantener

Esto dificulta la reproducibilidad y puede crear malos hábitos

​

​

(1) Código en orden arbitrario y (2) estados ocultos

Puede sonar obvio, pero no está demás repetirlo:

Se ordenado y diseña tus notebooks en orden secuencial

​

Podemos minimizar los errores por estados ocultos

utilizando Restart and Run All con cierta frecuencia

Esto limpia las variables y corre el cuadernillo completo y en orden

​

(3) Modularidad

No hagas copy paste entre celdas o entre notebooks

Refactoriza tus funciones y clases “estables” en módulos

Si usas aimport (extensión autoreload) no es necesario reiniciar el notebook cada vez que hagas un cambio en tus módulos. Puedes desarrollar tus módulos con vscode, pycharm, vim, emacs, etc

Maneja tus dependencias usando pip o conda. Usa un ambiente dedicado para tu proyecto. Disponibiliza la lista de requisitos con las versiones que utilizaste

Haz todos tus import statements al principio de tu notebook

​

​

​

​

Apéndice Clean Code Código Limpio

• Usa nombres largos y descriptivos que tengan significado y sean fáciles de buscar para funciones y clases
• Usa funciones cortas con pocos argumentos (idealmente keyword)
• Considera usar typed annotations
• Seguir una convención, PEP8
• Escribe módulos cohesionados sin imports circulares

(4) Control de versiones y Tests

Por debajo los notebook son archivos JSON con código y bastante metadata

Esto complejiza el control de versiones pero no lo hace imposible

• Haz “clear output” antes de versionar, si hay imágenes o resultados que son importantes versiónalos por separado (png + html)
• Usa herramientas como nbdime o reviewnb
• Agrega .ipynb_checkpoints a tu .gitignore

Puedes hacer test unitarios en notebooks usando ipytest

Combate el desorden con “Organización”

Dale narrativa a tus experimentos: Explota las celdas markdown

• Agrega una introducción al principio de tu notebook �¿Cuál es el objetivo del experimento?
• Presenta tu metodología�¿Qué método usarás para resolver el problema? ¿Por qué?
• Secciona tu notebook con headings (#, ##, ###), �aprovecha las extensiones TOC2 y collapsible heading
• Escribe preámbulos y documenta tus bloques
• No hagas celdas de código demasiado breves (1 línea) o �demasiado largas (que no quepa en tu pantalla)

​

​

Combate el desorden con “Organización”

Dale estructura a tu proyecto, por ejemplo

• src/lib: Módulos propios reutilizables por varios notebooks
• data: Datos de entrada y otros input
• results: Imágenes, tablas y resultados intermedios
• notebooks: Separa tus experimentos largos en varios notebooks. Puedes serializar resultados intermedios.

NOMBRA tus notebooks al momento de crearlos

2020_05_28_PH_experimento_eeg

​

Consejos para compartir notebooks

Un notebook bien documentado es el primer paso

Comparte también la lista de requisitos. Si usas conda se puede conectar con binder (zero-install environment) o contenedores tipo docker

Comparte también los datos de entrada (o una pequeña porción de ellos). Puedes usar servicios como zenodo o figshare

Puedes compartir versiones estáticas de tus experimentos con nbviewer

​

Notebooks en producción

(Organización) Considera separar o distinguir los

notebooks de desarrollo (develop) y producción (production-ready)

Se pueden parametrizar y correr notebooks de producción usando papermill

Esto permite integrar notebooks en una pipeline

Es posible convertir un notebook en una aplicación web interactiva usando voila

Se puede usar con heroku u otros servicios cloud para apps

Referencias

1. Adam Rule et al, “Ten simple rules for writing and sharing computational analyses in Jupyter Notebooks“, PLOS Computational Biology, 2019
2. Joel Grus, “I don’t like notebooks”, jupytercon 2018