Developer Documentation
Note: this document is a work in progress. Contrbitions to all sections are welcome.
GitHub Workflow
- Reviews from all of
PyRenew-devsare encouraged, but an approving review from a codeowner (@dylanhmorris or @damonbayer is required before a pull request can be merged tomain. - For CDC contributors: if your pull request has not received a review at the time of the next standup, use standup to find a reviewer.
- External contributors should expect to receive a review within a few days of creating a pull request.
- If you create a draft pull request, indicate what, if anything, about the current pull request should be reviewed.
- Only mark a pull request as “ready for review” if you think it is ready to be merged. This indicates that a thorough, all-encompassing review should be given.
Installation for Developers
uv sync --extra devpre-commit install
Coding Conventions
A variety of coding conventions are enforced by automated tools in continuous integration (black, isort, ruff, numpydoc-validation) via pre-commit hooks.
PyRenew Principles
-
Variable naming conventions
- Use the
data_prefix for (potentially) observed data. - Use the
_rvsuffix for random variables. - Use the
observed_for the output of sample statements whereobsis adata_prefixed object. - Thus, code which may reasonably written like
infections = infections.sample(x, obs=infections)should instead be writtenobserved_infections = infections_rv.sample(x, obs=data_infections).
- Use the
-
Class conventions
- Composing models is discouraged.
- Returning anything from
Model.sampleis discouraged. Instead, sample from models usingPredictiveor ourprior_predictiveorposterior_predictivefunctions. - Using
numpyro.deterministicwithin aRandomVariableis discouraged. Only use at thenumpyro.deterministicModellevel. If something might need to be recorded from aRandomVariable, it should be returned from theRandomVariableso it can be recorded at theModellevel. - Using default site names in a
RandomVariableis discouraged. Only use default site names at theModellevel. - Use
DeterministicVariables instead of constants within a model.
-
scanconventions- Use
jax.lax.scanfor any scan whose iterations are deterministic, i.e. iterations contain no internal calls toRandomVariable.sample()ornumpyro.sample(). - Use
numpyro.scanfor any scan whose the iterations are stochastic, i.e. the iterations potentially include calls toRandomVariable.sample()ornumpyro.sample().
- Use
-
Multidimensional array conventions
- In a multidimensional array of timeseries, time is always the first dimension. By default,
jax.lax.scan()andnumpyro.contrib.control_flow.scan()build output arrays by augmenting the first dimension, and variables are often scanned over time, making default output of scan over time sensible.
- In a multidimensional array of timeseries, time is always the first dimension. By default,
Documenting code for MkDocs
The project uses MkDocs and mkdocstrings to generate documentation.
MkDocs builds the documentation pages from the source files contained in the docs directory
and these, in turn, contain mkdocstrings directives to include the docstrings in the source code file.
The top-level Makefile task docs will build the site locally in a new directory site
make docs
open site/index.html
New module or classes
For each submodule or class, there is a corresponding pages in directory docs/reference.
For example, under the ./docs/reference, the index.md file lists the distributions module by adding the following entry:
# Distributions
::: pyrenew.distributions
New tutorials
PyRenew tutorials are quarto documents located under ./docs/source/tutorials.
The make docs Makefile task first renders the .qmd files to .md, then runs mkdocs build to generate the site.
To make the new tutorial available in the website, developers should follow these steps:
- Create a new
quartofile in the./docs/tutorialsdirectory. For instance, theexample_with_datasets.qmdfile was added to the repository. - Add an entry in the
./docs//tutorials/.pagesfile to specify the order in which this tutorial will appear in the navigation sidebar. The entry specifies the plain markdown filename.
For example, if you are adding a tutorial named seasonal_effects.qmd, then you would update the
file docs/tutorials/.pages as follows
arrange:
- getting_started.md
- basic_renewal_model.md
- extending_pyrenew.md
- hospital_admissions_model.md
- day_of_the_week.md
- periodic_effects.md
- seasonal_effects.md
Adding new pages
To add a new page which is neither source code documentation nor a tutorial:
- Create a
mdfile in the appropriate directory. For example, this file about development was added under./docs/source/developer_documentation.md. - Make sure the new
mdfile is included in the.pagesfile for that directory.
nav:
- reference
- tutorials
- developer_documentation.md
The last entry is the developer_documentation page.