Contributing guide#
Table of Contents#
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{38,39,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 py39-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 theReferences
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 intomain
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, see also Creating release notes.
Making a new release#
TODO
Creating release notes#
TODO