Tu primera contribución a PyMC#

Este tutorial te guiará en el envío de tu primer PR al repositorio pymc. Hemos tratado de cubrir todos los pasos y ser claros con el resultado esperado en cada uno de ellos.

Empezarás clonando el repositorio pymc, instalando los requisitos que necesitarás para contribuir, haciendo algunos cambios en una cadena de documentación de tu elección y enviando un pull request.

Descargo de responsabilidad

Se trata de un tutorial tal y como se define en diataxis. Aquí hay algunas cosas a tener en cuenta:

¿Tengo que seguir cada paso exactamente como se explica? No, pero te recomendamos encarecidamente que los sigas. Una vez que hayas enviado tu primer PR y te sientas cómodo con el proceso, puedes empezar a experimentar y personalizarlo.
¿Debo enviar una edición de la cadena de documentación como primer PR? No, pero te recomendamos encarecidamente que lo hagas. Esto te permitirá separar el flujo de trabajo de la contribución del contenido de la contribución. Podremos ayudarte mucho mejor a lo largo del proceso si sigues estos pasos, ya que tendremos una idea clara de tu situación en todo momento. Creemos que esto te ayudará a sentirte cómodo con las herramientas y la infraestructura (git, entornos virtuales, GitHub PRs y CI) lo antes posible para que luego puedas centrarte en el contenido de tus próximos PRs.
¿Comprenderé las razones de cada paso? No, el objetivo de este tutorial es enseñarte a hacer a través del hacer.

Si prefieres vídeo en lugar de contenido escrito, puedes ver a Reshama repasar esta guía y enviar un PR a PyMC en el siguiente vídeo:

Prepara tu entorno virtual#

Si aún no tienes configurado tu sistema, puedes seguir las instrucciones del tutorial Configuración del entorno local.

Escoge una cadena de documentación#

Ve a la documentación de la API de PyMC API, haz clic en el módulo (y submódulo si es necesario) que más te interese y elige una cadena de documentación (docstring) sobre el que trabajar.

Nota

Este tutorial sigue el proceso de actualización de pymc.Uniform y combina comentarios generales sobre la actualización de cadenas de documentación con comentarios específicos sobre la aplicación de esos cambios a pymc.Uniform.

La cadena de documentación está disponible en la página Sample docstring, he actualizado la cadena de documentación en PyMC mientras escribía esta guía.

Una vez que hayas elegido, ve a nuestro issue tracker, comprueba que nadie esté trabajando ya en ello y comenta que vas a actualizarlo.

Importante

Recuerda esa función y mantén la pestaña abierta (o guarda el enlace para más tarde)

Abre el archivo con tu editor de texto#

Abre el archivo que contiene la cadena de documentación que elegiste para editar con tu editor de texto. El archivo estará dentro de la carpeta pymc, pero probablemente no será fácil de adivinar solo por el nombre de la función o clase.

Vuelve a la página de la API y haz clic en el botón «[source]» a la derecha de la firma de la función.

source_button

Ahora échale un vistazo al enlace. Esto es lo que muestra para pymc.Uniform:

https://www.pymc.io/projects/docs/en/latest/_modules/pymc/distributions/continuous.html#Uniform

El archivo con la definición de la clase Uniform y su cadena de docuemntación es pymc/distributions/continuous.py, la ruta que viene después de _modules con extensión .py.

Edita la cadena de documentación#

Los cambios que tienes que hacer son asegurarte de que la cadena de documentación sigue la convención de numpydoc. Tenemos algunas convenciones adicionales, que he explicado aquí, pero solo son relevantes para algunas secciones, la mayor parte del tiempo seguirás numpydoc directamente.

Abre la guía de estilo numpydoc una al lado de la otra o en una ventana diferente. Estoy actualizando la cadena de documentación de pymc.Uniform como ejemplo.

Tienes que revisar sección por sección para asegurarte de que todo está bien documentado. Si has elegido una clase que no es una distribución (a diferencia de este ejemplo en el que estamos trabajando en la distribución pymc.Uniform), debes revisar las cadenas de documentación de todos los métodos (aunque solo si ya existen, no es necesario escribir las cadenas de documentación que faltan). De lo contrario, deberías trabajar solo en la cadena de documentación de la función o de la clase. Por lo tanto, ignoraremos las cadenas de documentación de los métodos logcdf, get_moment y dist.

Comentarios que no están relacionados con ninguna sección#

Solo es necesario un breve resumen. El resto debe utilizarse cuando sea pertinente. Por regla general, si falta una sección, ignórala por ahora. Si crees que debería añadirse, toma nota y comunícalo cuando abras el PR.
Si encuentras instancias de la directiva para graficar ..plot::, asegúrate de que estén ya sea en el resumen extendido o en la sección de ejemplos y de que usen el contexto close-figs. Debería lucir así:
```
.. plot::
    :context: close-figs

    python code starts here
```

Breve resumen#

Comentarios generales: Asegúrate de que haya una descripción corta (de preferencia una sola línea) del objeto. En la mayoría de casos tendrás que ignorar la regla de “no usar los nombres de las variables o de la función”.
Cadena de documentación de la clase pymc.Uniform:

Advertencia de depreciación#

Comentarios generales: No debería haber advertencias de caducidad, usamos un decorador para eso. Si encuentras una cadena de documentación con una, toma nota, no lo modifiques y avísanos cuando abras el PR.
Cadena de documentación de la clase pymc.Uniform:

Resumen extendido#

Comentarios generales: Esta sección ya lleva bastante avance y probablemente no necesite muchas modificaciones además de, tal vez, actualizar directivas o mover algo de código a la sección de notas.
Cadena de documentación de la clase pymc.Uniform class docstring: Faltó cerrar figs en la directiva de gráficos.

Parámetros#

Comentarios generales: Esta es la sección que, probablemente, tomará la mayor cantidad de trabajo. Algunos aspectos clave a tener en cuenta además de los mencionados en los consejos sobre numpydoc:
- Los dos puntos entre un nombre de argumento y su tipo deben llevar espacios antes y después.
- Las pistas de tipado deberían ir en la firma de la función, no en la cadena de documentación. Optional[Union[str, int]] no es un contenido adecuado para una cadena de documentación, debería ser str or int, optional. Las pistas de tipado son para las computadoras, las cadenas de documentación son para las personas.
- Los parámetros opcionales deben indicarse con , optional o , default <value>. Si el valor por defecto es del tipo documentado y se utiliza directamente, es preferible utilizar default en lugar de optional. Sin embargo, si el valor por defecto depende de otros parámetros o es un marcador de posición (por ejemplo, es muy común usar None para argumentos de tipo kwarg) entonces debe usarse optional, explicando el valor por defecto en la descripción.
- En las descripciones de tipos. Tenemos varios alias disponibles para mantener las cadenas de documentación sin procesar cortos y claros mientras se genera una página html agradable con todos los enlaces correctos:
  - tensor_like: Uno de los alias más comunes (si no el más común). Debe usarse en todos los parámetros que tomen un tensor aesara o cualquier objeto que pueda convertirse en él. En general, tendrás que cambiar tensor, aesara tensor (incluyendo combinaciones con diferentes mayúsculas, punto o guion en medio) por tensor_like.
  - TensorVariable: Similar a tensor_like pero solo debe usarse para parámetros que no serán convertidos internamente y necesitan ser tensores de Aesara antes de pasarlos a los argumentos. Utiliza TensorVariable, sin comillas extra o backticks. Pregunta si no estás seguro sobre el uso de tensor_like o TensorVariable.
  - RandomVariable: Cambia var, random var, aesara var y conceptos similares, deberían ser RandomVariable.
  - array_like: Cambia array like o array-like por array_like con guion bajo. Si encuentras esto en un parámetro devuelto, anótalo en la descripción del PR.
  - ndarray: Cambia np.ndarray o numpy.ndarray por ndarray. Sin embargo, si encuentras esto en un argumento de entrada, anótalo en la descripción del PR.
  - Covariance and Mean: solo dentro del módulo gp covariance, covariance objects, Covariance instances y similares deben modificarse a Covariance. Lo mismo para Mean.
  - InferenceData: cambia cosas como arviz.InferenceData o inference data por esto.
  - MultiTrace y BaseTrace: cambia cualquier cosa que contenga esto en el tipo a ellos. Lo más probable es encontrar pymc.backends.base.MultiTrace.
  - Point: cambia pymc.Point, point y parecidos por esto
  - SMC_kernel: dentro del módulo smc cambia las referencias a kernel, smc kernel y similares por esto. Fíjate en el guion bajo y las mayúsculas.
  - Aesara_Op: cambia Aesara Op, Op y variaciones por Aesara_Op, ¡ten cuidado con el guión bajo y las mayúsculas!
  - También podríamos darnos cuenta de que nos falta un alias importante gracias a tus contribuciones. Revisa el archivo conf.py de vez en cuando para ver si hay nuevos alias no explicados aquí. Los alias se definen en el diccionario numpydoc_xref_aliases.
Cadena de documentación de la clase pymc.Uniform:
- No debe haber espacios entre el nombre de un argumento y los dos puntos.
- Ambos argumentos son, de hecho, opcionales. En Distributions, esto no se puede ver en la clase como tal sino en el método dist. En el caso de Uniform, tendremos dist(cls, lower=0, upper=1, **kwargs). Por tanto, los dos son opcionales y tienen valores por defecto de 0 y 1, respectivamente.
- Los parámetros de entrada a las distribuciones pueden ser tensores Aesara, escalares o arreglos NumPy. Por lo tanto, se debe utilizar tensor_like. En este caso, los parámetros de la distribución son números reales (en lugar de discretos, por ejemplo) por lo que utilizaremos tensor_like of float. Para parámetros discretos usaríamos tensor_like of int.

Retorna y produce#

Comentarios generales: Nada que añadir a numpydoc. Siguen el estilo de la sección de parámetros pero con el nombre del argumento siendo opcional para valores retornados o producidos únicos. Deberías buscar las mismas cosas detalladas en la sección de parámetros además de asegurarte de que el tipo (más el nombre si lo hay) y la descripción están en líneas diferentes.
Cadena de documentación de la clase pymc.Uniform:

Confirma tus cambios en git y prepara tu PR.#

¡Fantástico! Ya estás listo para hacer tu PR.

Puedes seguir el PR Tutorial que explica cómo puedes hacer un PR a PyMC.

Tu PR será revisado y, con suerte, fusionado por el equipo de PyMC. Después de eso, podrás celebrar tu primera contribución a PyMC. ¡Gracias por contribuir!