Contributing guide

Contributing to moscot

Clone moscot from source as:

git clone https://github.com/theislab/moscot
cd moscot
git checkout main

Install the test and development mode:

pip install -e'.[dev,test]'

Optionally install pre-commit. This will ensure that the pushed code passes the linting steps:

pre-commit install

Although the last step is not necessary, it is highly recommended, since it will help you to pass the linting step (see Code style guide). If you did install pre-commit but are unable to decipher some flags, you can still commit using the --no-verify.

Codebase structure

The moscot project:

• moscot: the root of the package.
  • moscot/backends: the OTT backend module, which deals with OTT solvers and output functions.
  • moscot/base: contains base moscot classes. - moscot/base/problems: the moscot problems module.
  • moscot/costs: contains different costs computation functions.
  • moscot/plotting: the plotting module.
  • moscot/problems: the functionality of general problems classes, subdivided into problem types.
  • moscot/utils: contains various utility functions.
  • moscot/datasets.py: contains loading and simulating functions for the datasets.

Tests structure:

• tests: the root of the package
  • tests/backends: tests for the ott backend.
  • tests/costs tests for the solving costs.
  • tests/data: tests for the simulated data module.
  • tests/datasets: tests for the datasets.
  • tests/plotting tests for the plotting module.
  • tests/problems tests for the problem classes, divided by problem type.
  • tests/solvers tests for the solvers.
  • tests/utils tests for the utility functions.
  • tests/conftest.py: pytest fixtures and utility functions.

Code style guide

We rely on black and isort to do the most of the formatting - both of them are integrated as pre-commit hooks. You can use tox to check the changes:

tox -e lint-code

Furthermore, we also require that:

• functions are fully type-annotated.
• exception messages are capitalized and end with ..
• warning messages are capitalized and do not end with ..
• when referring to variable inside an error/warning message, enclose its name in `.
• when referring to variable inside a docstrings, enclose its name in ``.

Testing

We use tox to automate our testing, as well as linting and documentation creation. To run the tests, run:

tox -e py{310,311}-{linux,macos}

depending on the Python version(s) in your PATH and your operating system. We use flake8 and mypy to further analyze the code. Use # noqa: <error1>,<error2> to ignore certain flake8 errors and # type: ignore[error1,error2] to ignore specific mypy errors.

To run only a subset of tests, run:

tox -e <environment> -- <name>

where <name> can be a path to a test file/directory or a name of a test function/class. For example, to run only the tests in the plotting module, use:

tox -e py310-linux -- tests/plotting/test_plotting.py

If needed, a specific tox environment can be recreated as:

tox -e <environment> --recreate

Writing documentation

We use numpy-style docstrings for the documentation with the following additions and modifications:

• no type hints in the docstring (applies also for the return statement) are allowed, since all functions are required to have the type hints in their signatures.
• when referring to some argument within the same docstring, enclose that reference in ``.
• prefer putting references in the references.bib instead under the References sections of the docstring.
• use docrep for repeating documentation.

In order to build the documentation, run:

tox -e build-docs

Since the tutorials are hosted on a separate repository (see Writing tutorials/examples), we download the newest tutorials/examples from there and build the documentation here.

To validate the links inside the documentation, run:

tox -e lint-docs

If you need to clean the artifacts from previous documentation builds, run:

tox -e clean-docs

Writing tutorials/examples

Tutorials and examples are hosted on a separate repository called moscot_notebooks. Please refer to this guide for more information.

Submitting a PR

Before submitting a new pull request, please make sure you followed these instructions:

• make sure that you've branched off main and are merging into main
• make sure that your code follows the above specified conventions (see Code style guide and Writing documentation).
• if applicable, make sure you've added/modified at least 1 test to account for the changes you've made
• make sure that all tests pass locally (see Testing).
• if there is no issue which this PR solves, create a new one briefly explaining what the problem is.
• make sure that the section under ## Description is properly formatted if automatically generating release notes.