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 ) y es parte de los objetivos estratégicos de este programa apoyar la colaboración, generar recursos y democratizar los datos. 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
- 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.
- 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). Éstos son los estándares que GP2 seguirá, y esperamos que la comunidad en general también lo haga.
Antes de empezar, algunas nociones básicas de programación general y de Python
- Es probable que todos los cálculos para GP2 se realicen en Terra, The AnVIL de NHGRI o una infraestructura basada en la nube similar.
- Se proporcionará asistencia analítica y financiera a proyectos o grupos con limitaciones logísticas o financieras.
- 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).
- Para aprender Terra, regístrese para obtener una cuenta AMP PD, este es un excelente punto de partida.
- 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.
- Los documentos de introducción en Terra.bio son bastante buenos.
- Aprender Python realmente bien en dos semanas…
- Repite esto una vez al día.
- Repase esto una vez a la semana (de nuestros buenos amigos de la NSA a través de FOIA)
- Google Colabs también es un lugar de bajo costo y bajo estrés para aprender la estructura del cuaderno y familiarizarse con Python ( Mostrar cuadernos en Drive )
- Un código es bueno si es simple, claro y está estandarizado con una gramática, igual que una receta.
- Las guías de estilo de Google son un excelente lugar para comenzar
- PEP8 es la “gramática” preferida para Python
- Visual Studio Code es nuestro editor preferido en GP2, ya que incluye extensiones para estandarizar estilísticamente su código, pero use el que le resulte más cómodo.
- 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.
- Todas nuestras compilaciones internas de herramientas y códigos son en Python3.
- 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
- Es importante enfatizar que cuando programamos con Python localmente, estamos utilizando la distribución Anaconda para garantizar un entorno Python3 con todas las funciones. LNG elaboró un documento sobre cómo configurar Anaconda que se puede encontrar aquí
Puntos clave y resumen
- Debe tener algún método de control de versiones para evitar accidentes. Es como tener un cuaderno de laboratorio electrónico. El laboratorio del proyecto GP2 tiene su propio GitHub para pipelines orientados al futuro. En consonancia con la filosofía del GP2, todo su contenido es público.
- ¡Si aún no está listo para el público, no hay problema! Cree un repositorio privado, y cuando el código esté completo tendrá la opción de hacerlo público.
- 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.
- 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:
- 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
- Un editor de Markdown gratuito y atractivo para crear archivos README es stackedit.io
- El equipo de análisis de GP2 trabaja en conjunto en códigos de prueba de concepto experimentales utilizando Google Colabs para aprovechar las GPU gratuitas, compartirlas fácilmente y modificarlas fácilmente en el entorno local de Jupyter si es necesario.
- 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.
- 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.
- 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.
Organizando nuestro código
- Una forma de organizar el código, explicada aquí
- Este recurso explora cómo crear funciones, módulos y otras maneras de compartimentar su trabajo.
- Su código no tiene que seguir esta estructura si no le gusta, pero algún tipo de organización intuitiva sí es necesaria.
- 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.
- 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
- 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.
- 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.
- Aquí está nuestro texto estándar actual
- La puede adaptar a sus necesidades.
- 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.
- Aquí está nuestro texto estándar actual
Mejores prácticas para plataformas en la nube
- Como parte de AMP PD y probablemente para GP2, usaremos la plataforma Terra para escribir, ajustar y ejecutar procesos de análisis.
- 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).
- 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.
- El equipo AMP PD reunió ejemplos específicos de Terra aquí
- En esta práctica hoja de referencia se pueden encontrar algunos conceptos básicos sobre cómo mover archivos entre la infraestructura de la nube.
- Las prácticas recomendadas de Google sobre nombres, almacenamiento de datos y gestión de datos se pueden encontrar aquí
- 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).
- Existen dos diferencias clave entre ejecutar análisis a nivel local o en la nube:
- 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)
- 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).
- Los equipos de análisis de AMP PD y GP2 han escrito una serie de diferentes canales de análisis (enlace) que se pueden modificar.
- 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.
- Un ejemplo de costos de tiempo de ejecución que se puede utilizar como guía se puede encontrar aquí
- 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.
- 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.
- 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.
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 herramientas como protocols.io o el uso de Rocket Notebook para estandarizar tareas y experimentos de laboratorio. Tanto el Grupo de Trabajo de Análisis de Datos de Enfermedades Complejas como el Grupo de Trabajo de Difusión de Datos y Códigos del GP2 desean que se establezcan prácticas de laboratorio obligatorias que reflejen nuestro trabajo en el extremo computacional del espectro. 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.
Expresiones de gratitud
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 pipeline se obtuvo del Programa Global de Genética del Parkinson (GP2). GP2 está financiado por la iniciativa Aligning Science Against Parkinson’s (ASAP) e implementado por la Fundación Michael J. Fox para la Investigación del Parkinson ( MJFF ). Para ver una lista completa de los miembros de GP2, consulte aquí.
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 de los programadores”
Refleje este marco conceptual para colaborar en proyectos de codificación en GP2.