Overview 🌀

An example of a custom matching algorithm for vrs-matcher, built against vrs-matcher/PR #14 + following the steps in plugins.md!

This example plugin restricts matching to a fixed panel of VRS IDs (e.g. a disease gene panel) before scoring with plain Jaccard/

The panel in example_plugin.py uses real VRS IDs from VRS Matcher's examples/example-cohort.vcf.gz

Quick Start ⚡

git clone https://github.com/EllrottLab/vrs-matcher-example-plugin

cd vrs-matcher-example-plugin

uv sync

uv run vrs-matcher plugins list
# example
# identity

wget https://github.com/EllrottLab/vrs-matcher/raw/refs/heads/development/examples/example-cohort.vcf.gz

uv run vrs-matcher load-samples example-cohort.vcf.gz --db variants.db
# Loaded 6 allele records into variants.db

uv run vrs-matcher match-samples SAMPLE_A SAMPLE_B --db variants.db --algorithm example
# Jaccard:              1.0000
# Weighted concordance: 1.0000
# Shared variants:      2
# Total alleles (A/B):  2 / 2

Developing ⚙️

Running as a script plugin

uv run vrs-matcher match-samples SAMPLE_A SAMPLE_B \
  --db variants.db \
  --plugin-file src/vrs_matcher_example_plugin/example_plugin.py

# Jaccard:              1.0000
# Weighted concordance: 1.0000
# Shared variants:      2
# Total alleles (A/B):  2 / 2

Testing

Validate against a small cohort with known expected rankings, and compare against the built-in identity plugin:

# Match one sample against all others, ranked
uv run vrs-matcher match-sample SAMPLE_A --db variants.db --algorithm example

# Compare to the built-in identity plugin
uv run vrs-matcher match-sample SAMPLE_A --db variants.db --algorithm identity

Project Layout

vrs-matcher-example-plugin/
├── pyproject.toml
├── README.md
├── src/
│   └── vrs_matcher_example_plugin/
│       ├── __init__.py
│       └── example_plugin.py   # Example Plugin
└── tests/
    └── test_example_plugin.py  # Plugin tests