pyhgvs is no longer maintained... migration guide to biocommons HGVS

[davmlaw]

First, thank you to the original authors and contributors of pyhgvs. This library was genuinely useful and we relied on it heavily in production for several years.

However, pyhgvs appears to be unmaintained (no commits in 6 years) while Biocommons HGVS is actively developed and has a broader feature set including alignment gap projections, and better SV support

If you are starting a new project today, I would recommend using Biocommons HGVS.

Legacy migration guide

We had a large codebase that heavily used pyhgvs, and undertook a migration to Biocommons HGVS for the new features and support.

Migrating was risky: pyhgvs classes were spread throughout our codebase, and we needed to validate that Biocommons would produce identical results before switching. The transition steps were:

• Abstract away pyhgvs classes and methods behind our own interfaces
• Write implementations for both pyhgvs and Biocommons
• Run both in parallel during testing, raising errors if they disagreed
• Switch to Biocommons-only once confident

hgvs_shim is a cleaned-up library from this work.

HGVS Shim gives you:

• A single HGVSConverter interface backed by either pyhgvs or biocommons HGVS
• PyHGVSConverter and BioCommonsHGVSConverter with identical method signatures
• ComboCheckerHGVSConverter to run both in parallel during migration and flag discrepancies
• Library-independent HGVSVariant, HGVSException etc. so calling code needs no changes when you switch

Migration path

1. Install: pip install hgvs_shim
2. Replace direct pyhgvs calls with PyHGVSConverter — no other code changes needed
3. Switch the converter to BioCommonsHGVSConverter
4. Optionally run ComboCheckerHGVSConverter in test for a period to validate both give the same results before dropping pyhgvs entirely

  from hgvs_shim import PyHGVSConverter, BioCommonsHGVSConverter, ComboCheckerHGVSConverter

  # Step 2: wrap existing pyhgvs usage
  converter = PyHGVSConverter(fasta_file="hg38.fa", get_transcript=my_transcript_loader)

  # Step 3: switch to biocommons (needs a data provider, e.g. cdot)
  from cdot.hgvs.dataproviders import JSONDataProvider
  hdp = JSONDataProvider(["GRCh38.json.gz"])
  converter = BioCommonsHGVSConverter("GRCh38", hdp)

  # Optional: run both and compare
  converter = ComboCheckerHGVSConverter(pyhgvs_converter, biocommons_converter)

Thanks again for pyhgvs!