Contributing

Table of contents

1. TOC

---

Setup for development

git clone https://github.com/samuelecancellieri/genecircuitry.git
cd GeneCircuitry
python -m venv venv && source venv/bin/activate
pip install -e ".[dev,grn,hotspot]"

---

Running tests

pytest tests/                      # all tests
pytest tests/test_config.py       # config-specific
pytest -v --tb=short              # verbose with short tracebacks

When adding new config parameters, add a corresponding test to tests/test_config.py.

---

Code conventions

Parameters must use config

# ✅ correct
from genecircuitry import config

def my_function(adata, threshold=None):
    if threshold is None:
        threshold = config.MY_THRESHOLD

New pipeline steps go in PipelineController

# In genecircuitry/pipeline/controller.py
def run_step_my_analysis(self, adata, log_dir=None):
    log_step("Controller.MyAnalysis", "STARTED")
    try:
        result = my_analysis_function(adata)
        log_step("Controller.MyAnalysis", "COMPLETED")
        return result
    except Exception as e:
        log_error("Controller.MyAnalysis", e)
        raise

Then add "my_analysis" to the steps list in run_complete_pipeline().

New plots go in genecircuitry/plotting/

Do not add plotting code to preprocessing.py, grn_deep_analysis.py, or hotspot_processing.py. Create or extend the relevant file in genecircuitry/plotting/.

Optional dependencies

Wrap new optional-dep modules in genecircuitry/__init__.py:

try:
    from . import my_new_module
except ImportError:
    my_new_module = None

---

Adding a new config parameter

1. Add the constant to genecircuitry/config.py with a docstring.
2. Add it to the get_config() return dict in the same file.
3. Add assert "MY_PARAM" in config to tests/test_config.py.

---

AnnData conventions

Location	Usage
.obs	Per-cell metrics (QC values, cluster labels)
.var	Per-gene flags (mt, ribo, hb, highly_variable)
.obsm['X_pca']	PCA embedding
.obsm['X_umap']	UMAP embedding
.layers['raw_count']	Raw counts (stored before normalization)

---

Releases & Bioconda Autobump

When a new version tag/release is published on GitHub:

1. publish.yml builds and pushes the distribution to PyPI.
2. conda-recipe-autobump.yml detects the release, waits for PyPI availability, fetches the SHA256 checksum of the sdist, updates the local conda-recipe/meta.yaml, and commits it.
3. The workflow automatically opens a Pull Request against bioconda/bioconda-recipes updating recipes/genecircuitry/meta.yaml.

Configuring Bioconda PR Submission

To allow GitHub Actions to open PRs against bioconda/bioconda-recipes:

• Generate a GitHub Personal Access Token (PAT) with public_repo (or fine-grained repo) scope.
• Add it as a repository secret named BIOCONDA_TOKEN in GitHub Settings > Secrets and variables > Actions.

Manual Autobump Trigger

You can also trigger the autobump workflow manually via the GitHub Actions tab (workflow_dispatch), or locally via the helper script:

# Dry run
python scripts/autobump_bioconda.py --version 0.2.3 --dry-run

# Run with token
python scripts/autobump_bioconda.py --version 0.2.3 --token "$BIOCONDA_TOKEN"

---

Pull request checklist

• No hardcoded numeric values — all thresholds reference config.*
• New config parameters have tests in tests/test_config.py
• New plots added to genecircuitry/plotting/, not inline in processing modules
• New pipeline steps integrated into PipelineController, not standalone scripts
• Optional dependencies wrapped in try/except ImportError
• Docstrings include example imports from the correct module