Contributing Code

Setting up a development environment

1. Fork the repository on GitHub.

2. Clone your fork:

   git clone https://github.com/{your-username}/spatialvi-tools.git
   cd spatialvi-tools
   

3. Install the development dependencies in editable mode:

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

4. Install pre-commit hooks:

   pre-commit install
   

Running tests

python -m pytest tests/ -v

Run a subset:

python -m pytest tests/model/test_scviva.py -v

Code style

We use ruff for linting and formatting. Run it with:

ruff check src/
ruff format src/

Pre-commit hooks run these automatically on every commit.

Adding a new model

1. Add the neural-network module under src/spatialvi/module/.

2. Add the model class under src/spatialvi/model/, inheriting from SpatialBaseModel.

3. Register it in src/spatialvi/model/__init__.py and src/spatialvi/__init__.py.

4. Write tests under tests/model/.

Package layout

src/spatialvi/
├── model/           # High-level model classes
│   ├── base/        # Shared mixins and base class
│   └── utils/       # Model-level utilities and DE sub-packages
│       └── _scviva_de/  # scVIVA niche differential expression
├── module/          # PyTorch neural-network modules
│   └── utils/       # Module-level component libraries
│       └── _nichevae_components.py
├── data/            # Custom AnnData fields
├── external/        # External/ported model adaptations
├── train/           # Training plan overrides
└── utils/           # Shared spatial utilities