A grandes rasgos, el Global Parkinson’s Genetics Program (GP2) se rige por una política de «evitar sorpresas», en virtud de la cual análisis, proyectos y manuscritos se coordinan y comunican de manera abierta y transparente. Es la voluntad del GP2 que los datos y el código se usen de la manera más generalizada y abierta posible, por lo que la estandarización del código entre los distintos equipos de análisis es fundamental. A todos los miembros del GP2 y a los usuarios externos que deseen llevar a cabo análisis con datos del GP2, GP2 les recuerda que es importante trabajar con un código limpio, organizado y replicable, y que esté a disposición plena de toda la comunidad científica. El código deberá seguir las directrices de estandarización, se reconocerá a GP2, y el código será puesto a disposición de toda la comunidad a través de GitHub.

Introducción

El Global Parkinson’s Genetics Program (GP2) es un programa internacional que tiene por objeto generar conocimientos reveladores sobre la base genética de la enfermedad de Parkinson (EP) y democratizar el acceso a resultados y datos. GP2 está financiado por la iniciativa Aligning Science Across Parkinson’s (ASAP, https://gp2.org/), y promover la colaboración, la generación de recursos y la democratización de los datos es parte de sus objetivos estratégicos. La difusión del código y los datos del GP2 es una de las metas principales del GP2, y ASAP fomenta la publicación de resultados rápida, accesible y a gran escala. 

Resumen 

El objetivo de esta política es garantizar que 

1. El código y los procesos del GP2 (derivados de análisis dirigidos por el consorcio GP2) se difundan de manera integral, precisa y sin demora.

2. El código y los procesos del GP2 (derivados de análisis dirigidos por el consorcio GP2) estén estandarizados, organizados y a disposición del público en GitHub

Las directrices de estandarización del código complementan la política de publicaciones del GP2. Consulte este documento para gestionar situaciones inusuales en relación con el consorcio GP2. 

La Política de estandarización del código describe las mejores prácticas en materia de estandarización de código adoptadas por el Comité Directivo del GP2 y los análisis dirigidos por el consorcio GP2 que complementan las publicaciones dirigidas por el consorcio GP2. Se alienta encarecidamente a los investigadores externos que empleen datos del GP2 a adherirse a estas prácticas en pro de los análisis de gran calibre y la ciencia accesible. Debido a la creciente inclinación del campo a utilizar Python/Jupyter Notebooks y no R, este documento se enfoca en Python. Reconocemos que muchos investigadores del GP2 pueden utilizar R u otras herramientas sin dejar de apoyar el código organizado, abierto y replicable en la comunidad GP2. 

Si bien sabemos que limpiar código es una tarea tediosa, GP2 tiene un firme compromiso con el código limpio y le alienta a seguir estas normas. Si el código no es limpio/claro ni se puede comunicar con eficacia por sí mismo, ¿tendrá el impacto que realmente desea? Contar con un código limpio también significa que, a largo plazo, pasará menos tiempo explicando y reexplicando análisis y conceptos. Por lo tanto, nos beneficia a todos. El código limpio permite la replicación y la transparencia. GP2 está comprometido con la ciencia accesible, la colaboración a través del código transparente y la inclusividad.

A continuación describimos información básica y flujos de trabajo con Python como lenguaje primario, Anaconda como la distribución de preferencia de Python, PEP8 como la estructura de Python a seguir, Google Cloud como solución de almacenamiento y el entorno de nube analítica Terra como la ubicación donde se ejecutan los análisis. También enfatizamos la importancia de producir un documento que describa claramente el flujo de trabajo y la lógica de cada análisis (conocido como README). Estos son los estándares que seguirá GP2, con la esperanza de que también lo haga la comunidad en su conjunto. 

Antes de empezar, algunas nociones básicas de programación general y de Python

1. En GP2, todo lo que tenga que ver con computación, seguramente sucederá en Terra, The AnVIL de NHGRI o alguna infraestructura similar basada en la nube.

a. Se proporcionará asistencia analítica y financiera a proyectos o grupos con limitaciones logísticas o financieras.

2. El lenguaje principal de los análisis del GP2 será Python3+; se proporcionará asistencia limitada para R y otros lenguajes. La idea es aprovechar las bases de código actuales del LNG Data Science Group del Instituto Nacional sobre el Envejecimiento (NIA).

3. Para aprender a utilizar Terra, cree una cuenta AMP PD, es un excelente punto de partida.

a. Ofrecen notebooks introductorios muy útiles (donde usted escribe y ejecuta su propio código), además de espacios de trabajo y muchos datos para que experimente. b. Los documentos para principiantes de Terra.bio también son muy buenos.

4. Para aprender Python a fondo en dos semanas…

a. Repita este ejercicio una vez al día.

b. Repita este ejercicio una vez a la semana (de nuestros buenos amigos de NSA a través de FOIA).

c. Google Colab es otro recurso gratuito que le permitirá aprender la estructura de notebooks y familiarizarse con Python sin demasiado estrés.

5. Un código es bueno si es simple, claro y está estandarizado con una gramática, igual que una receta.

a. Google Style Guides es un buen punto de partida.

b. PEP8 es la «gramática» de preferencia de Python.

c. Visual Studio Code es el editor favorito del GP2 porque incluye extensiones para estandarizar estilísticamente el código, pero puede usar el que más le guste.

6. El lenguaje por defecto de nuestros equipos es Python3, si elige las mismas herramientas que nosotros podremos compartir herramientas con usted y ofrecer asistencia a sus proyectos con mayor eficiencia.

a. Todas nuestras compilaciones internas de herramientas y códigos son en Python3.

b. Para la gran mayoría de los proyectos, los recursos compartidos del GP2 serán en Python3.

Instrucciones para descargar Anaconda/Python en el disco local 

1. Es importante recordar que cuando programemos con Python de manera local debemos seguir la distribución Anaconda para disponer de un entorno Python3 que incluya todas sus funcionalidades. a. LNG elaboró este documento sobre cómo configurar Anaconda.

Puntos clave y resumen

1. Debe disponer de algún método de control de versiones para evitar accidentes. Es como tener un cuaderno de laboratorio electrónico. El laboratorio de proyectos del GP2 tiene su propio GitHub para procesos orientados hacia el futuro. En consonancia con la filosofía del GP2, todo su contenido es público.

a. Si su código aún no está del todo listo para hacerlo público, ¡no pasa nada! Cree un repositorio privado, y cuando el código esté completo tendrá la opción de hacerlo público.

b. GitHub simplifica el control de versiones y la colaboración, especialmente en la nueva interfaz para desktop. Aquí encontrará más información para comenzar.

2. Producir un README es fundamental. Nuestros README no son únicamente la manera que tenemos de comunicarnos con los demás, sino que también son documentos vivos, en evolución constante, que incluyen información como:

a. Autores, colaboradores, nombre del proyecto, objetivo del proyecto, flujo de trabajo propuesto para los análisis, fecha de inicio, fecha de la última actualización, rutas de acceso a directorios de trabajo, rutas de acceso a archivos

b. Un editor Markdown gratuito y muy bueno para crear un README es stackedit.io

3. El equipo de análisis del GP2 desarrolla códigos experimentales (a modo de prueba de concepto) con Google Colab para aprovechar los procesadores gráficos gratuitos y porque los códigos se pueden compartir y modificar fácilmente en el entorno local de Jupyter.

4. Como regla general, si el grupo que trabaja en un proyecto es mayor de 2 o 3 personas que trabajan conjuntamente, el control de versiones será obligatorio.

5. Para poder compartir un proyecto/manuscrito con la red del GP2, se requiere control de versiones y algún tipo de recurso sobre el código transparente e inteligible.

a. El código se someterá a una auditoría antes de la aprobación de la publicación si se emplearon recursos del GP2, ya sea con apoyo analítico o financiero.

Organización del código

1. Aquí se describe una manera de organizar código.

a. Este recurso explora cómo crear funciones, módulos y otras maneras de compartimentar su trabajo.

b. Su código no tiene que seguir esta estructura si no le gusta, pero algún tipo de organización intuitiva sí es necesaria.

c. Piense en su código como parte del manuscrito, si un revisor no puede entender su manuscrito, ¿cree que va a cumplir con los estándares de ciencia accesible del GP2? La misma lógica se aplica al código.

d. Si bien GP2 no exige ningún requisito de formato de código, sí le pedimos que sea claro.

Estandarización del código en Python

1. Seguimos lo más fielmente que podemos los estándares PEP8 (Python Enhancement Proposal) de la programación Python. PEP8 es un documento que describe la mejor manera de escribir código en Python y tiene el objetivo de facilitar la lectura y garantizar la coherencia de los códigos en Python.

a. Aquí puede encontrarse un recurso muy completo y fácil de seguir.

b. La mayoría de los entornos de desarrollo integrados (IDE) tienen un complemento que permite seguir este estándar.

i. Un ejemplo es el complemento autopep8 de Visual Studio Code.

2. En notebooks, tenemos una plantilla reutilizable que nos recuerda tanto a nosotros como a los usuarios las motivaciones que hay detrás de cada proyecto. Si usa notebooks, Markdown será su mejor aliado, ya que no solo orienta al usuario, sino que también permite dar seguimiento al contenido ejecutado.

a. Aquí encontrará nuestra plantilla reutilizable actual.

i. La puede adaptar a sus necesidades.

ii. Para el código relativo a los proyectos que reciban apoyo directo del GP2, se deberá seguir el marco general. Así se facilita la supervisión y la resolución de problemas.

Mejores prácticas de la plataforma en la nube

1. Como parte de AMP PD y posiblemente también para GP2, utilizaremos la plataforma Terra para escribir, modificar y ejecutar flujos de análisis.

a. Terra es una plataforma diseñada por el Broad Institute y MIT que usa infraestructuras comerciales en la nube (varias opciones) y presenta un entorno en Python3 completamente interactivo en una estructura de notebooks (muy parecido a Jupyter).

i. Si no está familiarizado con la computación en la nube, Google ofrece una excelente introducción terminológica aquí, donde se abordan aspectos básicos como qué es un proyecto, un cubo, un contenedor y otros conceptos clave que tendrá que dominar.

ii. El equipo de AMP PD ha recopilado ejemplos específicos de Terra aquí.

iii. Puede encontrarse información básica sobre cómo mover archivos en la infraestructura en la nube en este práctico resumen.

iv. Las mejores prácticas de Google sobre nomenclatura, almacenamiento de datos y gestión de datos se explican aquí.

2. Existen dos diferencias clave entre ejecutar análisis a nivel local o en la nube:

a. Localmente, el usuario paga por el almacenamiento (ya sea en su propia computadora o en el clúster de una institución), mientras que el almacenamiento en la nube ya está pagado (por ejemplo, por AMP PD o por GP2).

b. Localmente, no pagará por la ejecución de análisis (nunca en su propia computadora, pero pagar por el clúster dependerá de la institución), mientras que en la nube el usuario paga por cada análisis ejecutado (por ejemplo, a través de su PI o institución).

3. Los equipos de análisis de AMP PD y GP2 han escrito varios procesos de análisis distintos (enlace) que se pueden adaptar.

a. Como paga por el entorno que configura y la cantidad de datos a los que accede, es fundamental diseñar y planear todos los análisis con el mayor detalle posible.

i. Aquí encontrará un ejemplo de cuánto puede costar el tiempo de ejecución a modo de guía.

b. Como el entorno en la nube se puede actualizar desde el backend, es importante llevar un registro de los cubos (en todas sus versiones) a los que tenga acceso para futura referencia.

c. Como paga por el entorno que configure y el tiempo consumido, póngalos en pausa o elimine aquellos entornos que no utilice para pagar únicamente por lo que consuma.

Mensaje para nuestros colegas encargados del trabajo de laboratorio

Los valores de transparencia, accesibilidad y reproducibilidad no se aplican únicamente a la computación. Recomendamos encarecidamente el uso de herramientas como protocols.io o Rocket Notebook para estandarizar también el trabajo de laboratorio y los experimentos. Los grupos de trabajo del GP2 de Análisis de datos complejos de la enfermedad de Parkinson y Difusión de código y datos se beneficiarían de que siga unas prácticas de laboratorio obligatorias y en consonancia con nuestros estándares actuales en materia de computación. También estamos ejerciendo presión para que se establezcan unas prácticas estandarizadas de adquisición y nomenclatura de muestras, que sean transparentes y se publiquen en línea; pero esta cuestión no forma parte de nuestro ámbito de trabajo directo.

Reconocimiento

Todos los manuscritos, prepublicaciones y abstracts/pósteres derivados del uso de los procesos de análisis de datos de GP2 deben citar a ASAP y GP2 con la formulación siguiente:

«El código utilizado en la preparación de este proceso de análisis pertenece al Global Parkinson’s Genetics Program (GP2). GP2 es un programa financiado por la iniciativa Aligning Science Across Parkinson’s (ASAP) y The Michael J. Fox Foundation for Parkinson’s Research (www.gp2.org). Para consultar la lista completa de miembros del GP2, visite www.gp2.org». The Michael J. Fox Foundation, ASAP y el Comité Directivo del GP2 se reservan el derecho de modificar las condiciones de este acuerdo, y podrán hacerlo mediante la publicación de un aviso de las modificaciones en esta página. Las modificaciones entrarán en vigor inmediatamente después de su publicación (a menos que se indique lo contrario). Es importante que regrese a esta página periódicamente para estar al día de las condiciones vigentes del acuerdo de uso.

«Código de conducta para programadores»: siga este marco conceptual cuando colabore en proyectos de programación del GP2.