Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
119 lines (94 loc) · 5.52 KB

CONTRIBUTING.md

File metadata and controls

119 lines (94 loc) · 5.52 KB
Raw

Contributing to Varcode

Varcode supports Python 3.11 and later. Read AGENTS.md for the repository workflow and RELEASING.md before preparing a release. The 2026-09-24 audit records known quality gaps and their issue links.

Report a problem

Search the open issues first. Include a minimal reproduction, the Varcode, PyEnsembl and Python versions, the annotation release, and the variant's coordinates, REF/ALT and assembly. For file parsing problems, include a small synthetic input with the relevant header and sample fields. Report substantial new work as an issue before implementation, and link related issues from the PR.

Set up a development environment

From the repository root:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[rna,test-data,lint]' pytest pytest-cov pytest-xdist
python -m pip install mkdocs mkdocs-material 'mkdocstrings[python]'
python -m pip install build twine 'setuptools>=64'

rna installs the optional BAM reader; test-data installs the pinned Osteosarc adapter. lint installs Ruff and the same pinned mypy version used in CI. pytest-xdist is optional: test.sh also runs serially. Activate this environment before invoking the scripts so Python and its tools come from the same installation. ./develop.sh installs just the editable library into the active environment.

Install the reference datasets used by the full suite (these are downloads):

pyensembl install --release 75 --species human
pyensembl install --release 81 --species human
pyensembl install --release 93 --species human
pyensembl install --release 95 --species human
pyensembl install --release 95 --species mouse
pyensembl install --release 99 --species dog
pyensembl install --release 2020_10 --species dog

These canonical sources match the EnsemblRelease objects used by the tests. PyEnsembl 2.27.5 keys downloads and indexes by their source URL; rerun the installer after upgrading from the older cache format. The optional ATM regressions also run when pyensembl install --release 115 --species human has completed.

During pytest, bare GRCh38 references use Ensembl 81, matching the shared fixtures. Reference selection does not scan or populate the user cache; install the data above before running annotation tests. Explicit release choices are preserved. The bundled Osteosarc snapshot checks open their data offline. The complete public somatic benchmarks use human 75/93 and dog 99. Selected native ROS_Cfam_1.0 canine variants additionally use dog annotation 2020_10. Their provenance and comparison limits explain the assemblies, source versions and explicitly unresolved canine records. See tests/README.md for fixture provenance and regeneration.

Make and verify a change

Create a feature branch before editing; land changes through a reviewed PR. Use PEP 8 and NumPy-style docstrings. Include a focused regression for a bug fix and keep the fixture construction or reproducible source acquisition alongside the tests. Scientific expected values should have an independent basis, rather than comparing a function with itself. Preserve public APIs where practical: Isovar, Topiary and Vaxrank consume Varcode results.

./lint.sh
./test.sh
mkdocs build --strict

For a focused test run, use python -m pytest tests/test_vcf_limits.py. test.sh accepts pytest arguments and chooses a memory-aware worker count; set TEST_SH_MAX=2 to cap it when running other suites concurrently. The CI parity check is ./test.sh --annotator=protein_diff -m parity.

Typing is incremental. The package includes py.typed; ./lint.sh checks the five input/comparison modules listed in [tool.mypy] and a small consumer example in tests/typing/api_inputs.py. Function bodies are checked even where signatures are still unannotated. Imported legacy modules and third-party libraries without stubs remain permissive; the marker does not mean every Varcode API has complete annotations. Expand the configured scope as modules gain annotations, keeping the consumer checks in sync.

Every PR includes a version bump in varcode/version.py, relevant changelog notes, and issue links. Wait for green GitHub checks before merging; follow the release procedure to publish and verify the package.

Licensing

Varcode and contributions are licensed under the Apache License 2.0.

Writing transforms

Every transform owes three things, documented in its docstring:

Field Meaning
Cardinality preserves, reduces, or increases.
Provenance Every output variant carries source_variants: tuple[Variant, ...]. Empty tuple for pass-through; one element for derived-from-one; two or more for combined. Not part of hash/equality.
Metadata behavior Explicit rule for how source_to_metadata_dict entries flow through (which fields are inherited from which source, which require agreement, what happens on disagreement).

Transforms are idempotent on inputs they don't recognize. Running pair_breakends twice produces the same VC; the second pass finds no unpaired BNDs to combine because every combined row's source_variants is already populated.

The proposed combine_cis_snvs transform is tracked in #368; it is not a shipped API. User-facing examples belong in the transforms guide.