ferro-hgvs

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

• 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

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+.

Add to your Cargo.toml:

[dependencies]
ferro-hgvs = "0.1"

Or install the CLI:

cargo install ferro-hgvs

# 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.

Prepared sequence store (automatic): ferro prepare also writes a sequence_store.pac sidecar — the reference sequences decoded once and packed 2 bits per base — and normalize/project load it automatically when it sits beside the reference, skipping the per-access FASTA decode that dominates reference-read time. On a ≈500,000-variant ClinVar batch (single-threaded, warm cache) this is roughly a third faster wall-clock with byte-identical output; exact figures depend on corpus and hardware. Nothing to enable; it fails safe to the FASTA text path if absent or stale. See Reference data → Faster reads.

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.

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(())
}

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])

ferro's normalizer follows seven numbered rules — four about its output, three about procedure. This list is the canonical citation target used throughout the codebase and the ruling ledger (README.md rule N); the full text, scope, and rationale live in docs/src/reference/normalization-rules.md.

1. Conformant — output follows the HGVS recommendations. Absolute — never traded.
2. Recommended form — where the spec prefers among conformant forms, ferro produces it. Best effort.
3. Confluent — inputs denoting one variant produce one output, evaluated over the resulting sequence. Best effort.
4. Deterministic — same input, same output. Absolute.
5. Where the spec is silent, ambiguous, or self-contradictory — file upstream first and cite it, then ship a provisional choice (silent → decide under rule 6 and violate nothing; self-contradictory → a defect).
6. Among multiple conformant forms, the maintainers choose — there are no user options for normalization form.
7. Disclosure — any change to these rules, or any different choice made under 5 or 6, is disclosed (in the changelog before v1, by a major version bump after).

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

• Normalization rules — ferro's output contract: what a normalized description is allowed to be
• Deriving a description from sequences — turn a window of bases into one canonical description, no reference needed
• Normalize variants · Reference data
• Project to another axis — re-express a variant on a transcript; the projected c./r. axis applies the coding-axis rules a genomic axis cannot
• Error handling — strict / lenient / silent modes and warning codes
• Comparing normalization rules (FERRO_PARTITION)
• Benchmarking
• CLI reference · Supported HGVS syntax
• Why ferro-hgvs? — tool comparison — capability matrix, cross-tool benchmarks, and what ferro prepare builds
• Interpreting the HGVS recommendations — how ferro reads each clause

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.

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.

# 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.

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

Licensed under the MIT License. See LICENSE for details.

This software is actively maintained. 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.

See CONTRIBUTING.md for guidelines.