CI Nightly reference-aware tests Codecov Crates.io PyPI Python versions Documentation API docs License install with bioconda DOI

ferro-hgvs

A high-performance HGVS variant nomenclature parser and normalizer written in Rust.

WARNING: ALPHA SOFTWARE - USE AT YOUR OWN RISK

This software is currently in ALPHA. While we have extensively tested it across a wide variety of HGVS patterns, no guarantees are made regarding correctness or stability.

Fulcrum Genomics

Features

  • Full HGVS Parsing: All coordinate systems (g/c/n/r/p/m/o) and edit types
  • Variant Normalization: 3' shifting per HGVS specification
  • High Performance: ~5M variants/sec single-threaded parsing (>12M/s parallel), zero-copy with nom
  • Type-Safe: Leverages Rust's type system for correctness

Installation

Python

pip install ferro-hgvs

Pre-built wheels are available for Linux (x86_64, aarch64), macOS (x86_64, Apple Silicon), and Windows (x86_64) on Python 3.10+.

Rust

Add to your Cargo.toml:

[dependencies]
ferro-hgvs = "0.1"

Or install the CLI:

cargo install ferro-hgvs

Quick Start

CLI

# Parse a variant
ferro parse "NM_000088.3:c.459A>G"

# Parse from file
ferro parse -i variants.txt -f json

# Prepare reference data (downloads RefSeq, genome, cdot — RefSeq-only by default)
ferro prepare --output-dir ferro-reference

# Verify reference data is ready
ferro check --reference ferro-reference

# (Optional) pre-build the on-disk cdot cache as a setup step, so the one-time
# cache build doesn't slow the start of a real (or timed/benchmarked) run.
ferro check --reference ferro-reference --build-cache

# Normalize with reference
ferro normalize "NM_000088.3:c.459del" --reference ferro-reference/

Read the warnings. Normalization sometimes repairs a description in a way the normalized string does not record — separately reported cis members merged into one delins (MEMBERS_COALESCED_FROM_REPORTED_FORM), a ins[100_110] reference-range payload replaced by the bases it denotes (INSERTED_SEQUENCE_EXPANDED), a stated reference base that contradicted the reference and was accepted anyway (REFSEQ_MISMATCH). Those are reported as warning[CODE]: message on stderr (and in the warnings array under --format json, the detail column under --format tsv), so a pipeline reading only stdout will not see them. --error-mode strict is not a substitute: it rejects a specific ladder of conditions and reports the rest exactly as lenient does.

Throughput tip: when normalizing many variants, feed them sorted by transcript accession (or by genomic position). ferro caches each resolved transcript, so consecutive variants on the same transcript skip the (dominant) cost of re-reading and re-building it from the reference. Sorted input keeps the relevant transcripts resident in the cache and is markedly faster on large batches — see Performance Comparison.

Optional reference data

A bare ferro prepare builds a RefSeq-only reference (accessions NM_/NR_/NP_/NG_). Two opt-in flags provision additional data — pass them at prepare time; they are what a fully-provisioned ("blessed") reference is built with:

# Add Ensembl support (accessions ENST/ENSG/ENSP). Downloads the Ensembl cdot
# metadata and cDNA FASTAs (~1 GB+); off by default. Without it, an ENST/ENSG/ENSP
# input reports "Reference not found" and the message points back at this flag.
ferro prepare --output-dir ferro-reference --ensembl

# Derive version-independent NG_ placements and the NG_→transcript-version map
# (ng_hosted_transcripts) for a curated list of RefSeqGene accessions. Required to
# resolve legacy gene-symbol selectors (NG_(GENE):c.…) and bare-NG_ hosted lookups.
ferro prepare --output-dir ferro-reference \
  --derive-ng-placements path/to/ng_accessions.txt

# A fully-provisioned reference combines both in one run:
ferro prepare --output-dir ferro-reference --ensembl \
  --derive-ng-placements path/to/ng_accessions.txt

Both flags are incremental: re-running ferro prepare over an existing reference adds the requested data and preserves already-provisioned artifacts.

Library

use ferro_hgvs::{parse_hgvs, HgvsVariant};

fn main() -> Result<(), ferro_hgvs::FerroError> {
    let variant = parse_hgvs("NM_000088.3:c.459A>G")?;

    match &variant {
        HgvsVariant::Cds(v) => println!("CDS variant: {}", v),
        HgvsVariant::Genome(v) => println!("Genomic variant: {}", v),
        _ => println!("Other: {}", variant),
    }

    Ok(())
}

Python

import ferro_hgvs

# Parse a variant
variant = ferro_hgvs.parse("NM_000088.3:c.459A>G")
print(variant.variant_type)  # "coding"
print(variant.reference)     # "NM_000088.3"
print(str(variant))          # "NM_000088.3:c.459A>G"

# Normalize with reference data
normalizer = ferro_hgvs.Normalizer(reference_json="ferro-reference/cdot.json")
normalized = normalizer.normalize("NM_000088.3:c.459del")

# `normalize` returns only the string, so it cannot tell you that normalization
# repaired something. `normalize_with_warnings` returns the same string plus the
# diagnostics — as a free function, or as a Normalizer method.
result = normalizer.normalize_with_warnings("NM_000088.3:c.459del")
print(str(result.result))                      # the same normalized string
print([(w.code, w.message) for w in result.warnings])

Documentation

Full guides live in the documentation site (source under docs/src/):

Why ferro-hgvs?

ferro-hgvs provides the most comprehensive HGVS variant normalization across all pattern types, with performance orders of magnitude faster than alternatives. For the full capability matrix against mutalyzer / biocommons / hgvs-rs, the cross-tool parse/normalize benchmarks, and what ferro prepare builds, see Why ferro-hgvs? — tool comparison.

Benchmark: Reference Data & Tool Comparison

The main ferro binary includes commands to prepare reference data (ferro prepare) and check its status (ferro check). The ferro-benchmark tool (build with --features benchmark) extends this for tool comparison benchmarks.

Command Description
prepare <tool> Prepare reference data for a tool
check <tool> Verify tool configuration and dependencies
parse <tool> Parse HGVS patterns with specified tool
normalize <tool> Normalize HGVS patterns with specified tool
compare results Compare parse/normalize results between tools
extract Extract patterns from ClinVar, VCFs, or create samples
setup Set up UTA database, SeqRepo, and other services
generate Generate summary reports and configs
collate Aggregate sharded results

Quick Start

# Prepare ferro reference (main binary - no special features needed)
ferro prepare --output-dir data/ferro

# Check reference data
ferro check --reference data/ferro

# Normalize with ferro
ferro normalize -i patterns.txt --reference data/ferro

# For tool comparison, build with benchmark support
cargo build --release --features benchmark

# Prepare other tools (uses ferro reference for transcript data)
ferro-benchmark prepare mutalyzer --ferro-reference data/ferro --output-dir data/mutalyzer
ferro-benchmark prepare biocommons --seqrepo-dir data/seqrepo --uta-dump uta_20210129b.pgd.gz --ferro-reference data/ferro

# Compare results between tools
ferro-benchmark normalize mutalyzer -i patterns.txt -o mutalyzer.json --mutalyzer-settings data/mutalyzer/mutalyzer_settings.conf
ferro-benchmark compare results normalize ferro.json mutalyzer.json -o comparison.json

Supported tools: ferro-hgvs, mutalyzer, biocommons/hgvs, hgvs-rs

Note: The pixi.toml and pixi.lock files in this repository define a pixi environment for the Python-based external tools (mutalyzer, biocommons/hgvs, seqrepo) used in benchmarking. Run pixi shell to activate it.

See docs/BENCHMARK_GUIDE.md for detailed usage.

Development

cargo build
cargo test                        # default features
cargo clippy -- -D warnings

The commands above use the default feature set, and CI keeps them compiling (see the build job). They do not cover the whole suite — the feature-gated tests and the integration tree need dev, which is what CI runs and what you want before opening a PR:

cargo nextest run --features dev
cargo clippy --features dev --all-targets -- -D warnings

License

Licensed under the MIT License. See LICENSE for details.

Disclaimer

This software is under active development. While we make a best effort to test this software and to fix issues as they are reported, this software is provided as-is without any warranty (see the license for details). Please submit an issue, and better yet a pull request as well, if you discover a bug or identify a missing feature. Please contact Fulcrum Genomics if you are considering using this software or are interested in sponsoring its development.

Contributing

See CONTRIBUTING.md for guidelines.

Project links

Data verified by PyPI on Aug 25, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.0.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for nilshomer from gravatar.com nilshomer

GitHub Statistics

Data verified by PyPI on Aug 25, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.10

Tags

hgvs variant normalization bioinformatics genomics

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ferro_hgvs-0.17.2.tar.gz (7.4 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

ferro_hgvs-0.17.2-cp310-abi3-win_amd64.whl (4.0 MB view details)

Uploaded CPython 3.10+Windows x86-64

ferro_hgvs-0.17.2-cp310-abi3-musllinux_1_2_x86_64.whl (4.4 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ x86-64

ferro_hgvs-0.17.2-cp310-abi3-musllinux_1_2_aarch64.whl (4.1 MB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ ARM64

ferro_hgvs-0.17.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.1 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ x86-64

ferro_hgvs-0.17.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (4.0 MB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

ferro_hgvs-0.17.2-cp310-abi3-macosx_11_0_arm64.whl (3.8 MB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

ferro_hgvs-0.17.2-cp310-abi3-macosx_10_13_x86_64.whl (4.0 MB view details)

Uploaded CPython 3.10+macOS 10.13+ x86-64

File details

Details for the file ferro_hgvs-0.17.2.tar.gz.

File metadata

  • Download URL: ferro_hgvs-0.17.2.tar.gz
  • Upload date:
  • Size: 7.4 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ferro_hgvs-0.17.2.tar.gz
Algorithm Hash digest
SHA256 95c2a148efccf88b156d2a3a3f5b2173992eff8037cf7fd82f780d263886122f
MD5 e044c4b769c9336208804aa390674f45
BLAKE2b-256 313d9611a0b0b5f7f42df7b1dc17f119e70ab027c3d0312f6362c9cd063975df

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferro_hgvs-0.17.2.tar.gz:

Publisher: release-wheels.yml on fulcrumgenomics/ferro-hgvs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferro_hgvs-0.17.2-cp310-abi3-win_amd64.whl.

File metadata

  • Download URL: ferro_hgvs-0.17.2-cp310-abi3-win_amd64.whl
  • Upload date:
  • Size: 4.0 MB
  • Tags: CPython 3.10+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for ferro_hgvs-0.17.2-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 aee766d41c34375c0f0bd7020483a3aa116cfc25f6d9b9702ad9848f462cdab2
MD5 2f0b88e8433d36c1bc878cac879cd6ec
BLAKE2b-256 11f8a50ea50a63e7d997e0d54539e137c26ab2a73521f8075ccd0bd73ac86733

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferro_hgvs-0.17.2-cp310-abi3-win_amd64.whl:

Publisher: release-wheels.yml on fulcrumgenomics/ferro-hgvs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferro_hgvs-0.17.2-cp310-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for ferro_hgvs-0.17.2-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 3e905ac919926f30970513b02c103e66cbaae5902076caecef03297ae57248ed
MD5 4f2fb23f7b58d0cf0871107123f3bc6b
BLAKE2b-256 054b0626fce462eab18c6a423588a0ba4d814539295e00df726bdd62a693f3c1

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferro_hgvs-0.17.2-cp310-abi3-musllinux_1_2_x86_64.whl:

Publisher: release-wheels.yml on fulcrumgenomics/ferro-hgvs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferro_hgvs-0.17.2-cp310-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for ferro_hgvs-0.17.2-cp310-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 b6dcf1c334fb7332b0ccbd2b793989d345483521f8af7361ffa85dfc23fadb9d
MD5 cfa60b96ad8b70a65ecbc34483adf747
BLAKE2b-256 694d8ff9dbb7b01c096e2cca26d722f042b427feb0fe0cc15daaf1cedbc62666

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferro_hgvs-0.17.2-cp310-abi3-musllinux_1_2_aarch64.whl:

Publisher: release-wheels.yml on fulcrumgenomics/ferro-hgvs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferro_hgvs-0.17.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for ferro_hgvs-0.17.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 36e4d96e2c249bf2372a8cdee134c61f93192b50eebdcd741298c06e8895a479
MD5 2a6e728ef86be7f15e5dcb71a04d590e
BLAKE2b-256 0a8cedc4ad40ee684c96e21b3ffd820c0385ea54dc49100741acc435048731fb

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferro_hgvs-0.17.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release-wheels.yml on fulcrumgenomics/ferro-hgvs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferro_hgvs-0.17.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for ferro_hgvs-0.17.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 ceeaa2afd3e8b2cd2fe2afa8aadf5407c503c78e69aa23e9810d3313da827523
MD5 8ff60dbbc9f80c5adafc2c03a72b31d0
BLAKE2b-256 8566a2759921a38852319b248a063b5b2baf49eddf7fbfda9700441dee54f156

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferro_hgvs-0.17.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release-wheels.yml on fulcrumgenomics/ferro-hgvs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferro_hgvs-0.17.2-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for ferro_hgvs-0.17.2-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 1aff041683358a07cd48c8b31db810a3677506f0f79f5b76bbc73f0675a21d02
MD5 fe69a066c2f05d3dd5769de7ef49f1fc
BLAKE2b-256 5b20c558dea12583b7eefe515f061ab4237db375fef3b831db0cd3874a2e420e

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferro_hgvs-0.17.2-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release-wheels.yml on fulcrumgenomics/ferro-hgvs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ferro_hgvs-0.17.2-cp310-abi3-macosx_10_13_x86_64.whl.

File metadata

File hashes

Hashes for ferro_hgvs-0.17.2-cp310-abi3-macosx_10_13_x86_64.whl
Algorithm Hash digest
SHA256 e10d1b2b54f1ded1ac3a9278b9c81b048a9aef00c44c3c7ca01d0de01cd41cbf
MD5 6876c3b96d4ab8b7930c1a47f250cc58
BLAKE2b-256 35a1216366523dd5d53bd4be86124c317d5b7e80a234d137fcb389faa68269a1

See more details on using hashes here.

Provenance

The following attestation bundles were made for ferro_hgvs-0.17.2-cp310-abi3-macosx_10_13_x86_64.whl:

Publisher: release-wheels.yml on fulcrumgenomics/ferro-hgvs

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.0.0

8 files

This release

0.17.2 This release

8 files

0.17.1

8 files

0.17.0

8 files

0.16.0

8 files

0.15.0

8 files

0.14.0

8 files

0.13.1

8 files

0.13.0

8 files

0.12.0

8 files

0.11.0

8 files

0.10.1

8 files

0.10.0

8 files

0.9.1

8 files

0.9.0

8 files

0.8.1

8 files

0.8.0

8 files

0.7.1

8 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page