Contributing#
We welcome contributions to grassp! This guide will help you get started with contributing to the project.
Getting Started#
Fork the repository on GitHub.
Clone your fork locally:
git clone https://github.com/yourusername/grassp.git cd grassp
Create a development environment:
This installs the package with the -e option and development and documentation dependencies as well as pre-commit hooks.
make setup-develop
If you are touching the pRoloc bridge or building the docs, also create the R environment:
The R half of the bridge (
r/grasspio) needs a Bioconductor stack that is not pip-installable, so it lives in a conda environment declared by r-environment.yml:make setup-rThat creates the
grassp-renvironment, installsgrasspiointo it, and registers theirJupyter kernel. The kernel is the part worth knowing about: the docs build executesdocs/source/tutorials/proloc_r_tutorial.Rmdwith it. Without it, build withGRASSP_DOCS_SKIP_R=1, which renders that page without outputs instead of failing. Runmake test-rfor the grasspio test suite.
Testing#
Tests can be added to grassp/tests
Run the tests:
pytest grassp/tests
Code Style#
Follow PEP 8 style guidelines.
Use type hints where appropriate.
Add docstrings to all public functions.
Documentation#
Update docstrings for any changed functions.
Update tutorials if adding new features.
Build docs locally to check formatting:
make docs # from the repo root; writes docs/build/html GRASSP_DOCS_SKIP_R=1 make docs # without the R environment
Every tutorial is executed as part of the build, except ccompass_tutorial, which ships
pre-rendered because it needs TensorFlow. So building the docs needs the .[docs] extra, network
access (the tutorials download datasets from the grassp portal), and — for the R tutorial — the
conda environment from make setup-r.
A notebook that fails to execute fails the build, with the failing cell’s traceback in the log.
The docs are built on every pull request and published to
https://czbiohub-sf.github.io/grassp/ on every push to main, by
docs.yml. There is
nothing to upload by hand.
Adding New public functions#
When adding support for new functionality:
Add the code for the function in the most appropriate submodule
preprocessingis for data filtering, enrichment, qctoolsis for dimensionality reduction, classification, differential testingplottingis for visualizationiois for reading from diffferent sources and writing outputs
Make sure you follow the recommended Code Style section below and describe the function and parameters accurately with a docstring
Expose the function as public by importing it in the
__init__.pyfile of the submoduleAdd the function to the documentation by adding it to the api documentation.
Build the documentation (Documentation below) to check proper formatting.
Add tests and run them (Testing above)
Create a PR against
main