{"id":47636921,"url":"https://github.com/fulcrumgenomics/ferro-hgvs","last_synced_at":"2026-04-02T00:21:02.604Z","repository":{"id":339439328,"uuid":"1161928092","full_name":"fulcrumgenomics/ferro-hgvs","owner":"fulcrumgenomics","description":"A high-performance HGVS variant nomenclature parser and normalizer written in Rust","archived":false,"fork":false,"pushed_at":"2026-03-30T07:57:26.000Z","size":1300,"stargazers_count":11,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-30T08:34:39.660Z","etag":null,"topics":["bioinformatics","genomics","hgvs","parser","rust","variant-nomenclature"],"latest_commit_sha":null,"homepage":"https://docs.rs/ferro-hgvs","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fulcrumgenomics.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-19T17:19:13.000Z","updated_at":"2026-03-30T07:35:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fulcrumgenomics/ferro-hgvs","commit_stats":null,"previous_names":["fulcrumgenomics/ferro-hgvs"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/fulcrumgenomics/ferro-hgvs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fulcrumgenomics%2Fferro-hgvs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fulcrumgenomics%2Fferro-hgvs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fulcrumgenomics%2Fferro-hgvs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fulcrumgenomics%2Fferro-hgvs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fulcrumgenomics","download_url":"https://codeload.github.com/fulcrumgenomics/ferro-hgvs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fulcrumgenomics%2Fferro-hgvs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31293356,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","genomics","hgvs","parser","rust","variant-nomenclature"],"created_at":"2026-04-02T00:20:57.339Z","updated_at":"2026-04-02T00:21:02.592Z","avatar_url":"https://github.com/fulcrumgenomics.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CI](https://github.com/fulcrumgenomics/ferro-hgvs/actions/workflows/ci.yml/badge.svg)](https://github.com/fulcrumgenomics/ferro-hgvs/actions/workflows/ci.yml)\n[![Codecov](https://codecov.io/gh/fulcrumgenomics/ferro-hgvs/branch/main/graph/badge.svg)](https://codecov.io/gh/fulcrumgenomics/ferro-hgvs)\n[![Crates.io](https://img.shields.io/crates/v/ferro-hgvs.svg)](https://crates.io/crates/ferro-hgvs)\n[![Documentation](https://docs.rs/ferro-hgvs/badge.svg)](https://docs.rs/ferro-hgvs)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/ferro-hgvs/README.html)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18703104.svg)](https://doi.org/10.5281/zenodo.18703104)\n\n# ferro-hgvs\n\nA high-performance HGVS variant nomenclature parser and normalizer written in Rust.\n\n**WARNING: ALPHA SOFTWARE - USE AT YOUR OWN RISK**\n\nThis software is currently in **ALPHA**. While we have extensively tested it\nacross a wide variety of HGVS patterns, **no guarantees are made** regarding\ncorrectness or stability.\n\n\u003cp\u003e\n\u003ca href=\"https://fulcrumgenomics.com\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/fulcrumgenomics/fgumi/main/.github/logos/fulcrumgenomics.svg\" alt=\"Fulcrum Genomics\" height=\"100\"/\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ca href=\"mailto:contact@fulcrumgenomics.com?subject=[GitHub inquiry]\"\u003e\u003cimg src=\"https://img.shields.io/badge/Email_us-brightgreen.svg?\u0026style=for-the-badge\u0026logo=gmail\u0026logoColor=white\"/\u003e\u003c/a\u003e\n\u003ca href=\"https://www.fulcrumgenomics.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/Visit_Us-blue.svg?\u0026style=for-the-badge\u0026logo=wordpress\u0026logoColor=white\"/\u003e\u003c/a\u003e\n\n## Features\n\n- **Full HGVS Parsing**: All coordinate systems (g/c/n/r/p/m/o) and edit types\n- **Variant Normalization**: 3'/5' shifting per HGVS specification\n- **High Performance**: ~2.5M variants/sec parsing, zero-copy with nom\n- **Type-Safe**: Leverages Rust's type system for correctness\n\n## Installation\n\nAdd to your `Cargo.toml`:\n\n```toml\n[dependencies]\nferro-hgvs = \"0.1\"\n```\n\nOr install the CLI:\n\n```bash\ncargo install ferro-hgvs\n```\n\n## Quick Start\n\n### CLI\n\n```bash\n# Parse a variant\nferro parse \"NM_000088.3:c.459A\u003eG\"\n\n# Parse from file\nferro parse -i variants.txt -f json\n\n# Prepare reference data (downloads RefSeq, genome, cdot)\nferro prepare --output-dir ferro-reference\n\n# Verify reference data is ready\nferro check --reference ferro-reference\n\n# Normalize with reference\nferro normalize \"NM_000088.3:c.459del\" --reference ferro-reference/\n```\n\n### Library\n\n```rust\nuse ferro_hgvs::{parse_hgvs, HgvsVariant};\n\nfn main() -\u003e Result\u003c(), ferro_hgvs::FerroError\u003e {\n    let variant = parse_hgvs(\"NM_000088.3:c.459A\u003eG\")?;\n\n    match \u0026variant {\n        HgvsVariant::Cds(v) =\u003e println!(\"CDS variant: {}\", v),\n        HgvsVariant::Genome(v) =\u003e println!(\"Genomic variant: {}\", v),\n        _ =\u003e println!(\"Other: {}\", variant),\n    }\n\n    Ok(())\n}\n```\n\n## Supported HGVS Syntax\n\n| Type | Prefix | Example |\n|------|--------|---------|\n| Genomic | `g.` | `NC_000001.11:g.12345A\u003eG` |\n| Coding DNA | `c.` | `NM_000088.3:c.459A\u003eG` |\n| Non-coding | `n.` | `NR_000001.1:n.100A\u003eG` |\n| RNA | `r.` | `NM_000088.3:r.459a\u003eg` |\n| Protein | `p.` | `NP_000079.2:p.Val600Glu` |\n| Mitochondrial | `m.` | `NC_012920.1:m.3243A\u003eG` |\n\n### Edit Types\n\n- Substitution: `A\u003eG`, `Val600Glu`\n- Deletion: `del`, `100_200del`\n- Insertion: `100_101insATG`\n- Deletion-Insertion: `100_102delinsATG`\n- Duplication: `100_102dup`\n- Inversion: `100_200inv`\n- Repeat: `100CAG[20]`\n\n## CLI Commands\n\nThe `ferro` CLI provides commands beyond parsing and normalization:\n\n| Command | Description |\n|---------|-------------|\n| `prepare` | Download and prepare reference data for normalization |\n| `check` | Verify reference data setup |\n| `parse` | Parse and validate HGVS variants |\n| `normalize` | Normalize HGVS variants (3'/5' shifting) |\n| `explain` | Explain error/warning codes (e.g., `ferro explain W1001`) |\n| `annotate-vcf` | Annotate VCF files with HGVS notation |\n| `vcf-to-hgvs` | Convert VCF records to HGVS |\n| `hgvs-to-vcf` | Convert HGVS to VCF format |\n| `liftover` | Liftover coordinates between genome builds |\n| `describe` | Generate HGVS from reference/observed sequences |\n| `effect` | Predict protein effect from variant |\n| `backtranslate` | Reverse translate protein to DNA variants |\n| `convert-gff` | Convert GFF3/GTF to transcripts.json |\n| `generate` | Generate HGVS descriptions from components |\n| `extract-hgvs` | Extract HGVS from VEP-annotated VCFs |\n\n## Error Handling\n\nferro-hgvs provides configurable error handling with three modes:\n\n| Mode | Behavior |\n|------|----------|\n| `strict` | Reject non-conformant input (default) |\n| `lenient` | Auto-correct with warnings |\n| `silent` | Auto-correct silently |\n\n```bash\n# Use lenient mode to auto-correct common issues\nferro parse --error-mode lenient \"p.val600glu\"  # Corrects to p.Val600Glu\n\n# Ignore specific warnings\nferro parse --ignore W1001,W2001 \"p.val600glu\"\n\n# Get help on any error/warning code\nferro explain W1001\nferro explain --list\n```\n\n### Configuration File\n\nCreate `.ferro.toml` in your project directory:\n\n```toml\n[error-handling]\nmode = \"lenient\"\nignore = [\"W1001\", \"W2001\"]  # Silently correct these\nreject = [\"W4002\"]           # Always reject these\n```\n\n## Why ferro-hgvs?\n\nferro-hgvs provides the most comprehensive HGVS variant normalization across all pattern types, with performance orders of magnitude faster than alternatives.\n\n### Normalization Capabilities Comparison\n\n| Pattern Type | ferro | mutalyzer | biocommons | hgvs-rs |\n|--------------|:-----:|:---------:|:----------:|:-------:|\n| Genomic (g.) | ✓ | ✓ | ✓ | ✓ |\n| Coding (c.) exonic | ✓ | ✓ | ✓ | ✓ |\n| Coding (c.) intronic | ✓ | ✓* | ✗ | ✗ |\n| Non-coding (n.) | ✓ | ✓ | ✓ | ✓ |\n| RNA (r.) | ✓ | ✓ | ✓ | ✓ |\n| Protein (p.) | ✓ | Net** | ✗ | ✓ |\n\n\\* mutalyzer intronic support requires genomic context rewriting (enabled by default)\n\\** mutalyzer protein normalization requires network access for NP_→NM_ lookups\n\n### Performance Comparison\n\n| Tool | Speed (local) | Speed (network) | ferro Speedup |\n|------|---------------|-----------------|---------------|\n| **ferro-hgvs** | ~4M patterns/sec | N/A (offline) | — |\n| mutalyzer | ~20 patterns/sec | ~1 pattern/sec | **200,000x** |\n| biocommons/hgvs | ~20 patterns/sec | ~0.2 patterns/sec | **200,000x** |\n| hgvs-rs | ~2 patterns/sec | ~0.2 patterns/sec | **2,000,000x** |\n\n### Reference Data: What ferro Prepares\n\nThe `ferro prepare` command downloads and organizes all reference data needed for comprehensive normalization. This data is then shared with other tools (mutalyzer, biocommons, hgvs-rs) to enable their local operation.\n\n| Data Type | Source | Size | Enables |\n|-----------|--------|------|---------|\n| **RefSeq transcripts** | NCBI | ~1GB | NM_/NR_/XM_ normalization |\n| **cdot metadata** | MANE | ~200MB | Transcript-to-genome mappings |\n| **GRCh38 + GRCh37 genomes** | NCBI | ~4GB | NC_ genomic normalization |\n| **RefSeqGene** | NCBI | ~600MB | NG_ gene region normalization |\n| **LRG sequences** | EBI | ~50MB | LRG_ stable reference normalization |\n| **Protein sequences** | Derived from CDS | ~200MB | NP_/XP_ protein normalization |\n| **Legacy transcript versions** | NCBI | ~50MB | Historical ClinVar variants |\n\n**Key insight**: Without ferro's reference preparation, other tools require network access for each variant lookup (adding 100-1000ms latency per variant). With ferro's cached reference data, all tools can operate fully offline with consistent, reproducible results.\n\n## Benchmark: Reference Data \u0026 Tool Comparison\n\nThe 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.\n\n| Command | Description |\n|---------|-------------|\n| `prepare \u003ctool\u003e` | Prepare reference data for a tool |\n| `check \u003ctool\u003e` | Verify tool configuration and dependencies |\n| `parse \u003ctool\u003e` | Parse HGVS patterns with specified tool |\n| `normalize \u003ctool\u003e` | Normalize HGVS patterns with specified tool |\n| `compare results` | Compare parse/normalize results between tools |\n| `extract` | Extract patterns from ClinVar, VCFs, or create samples |\n| `setup` | Set up UTA database, SeqRepo, and other services |\n| `generate` | Generate summary reports and configs |\n| `collate` | Aggregate sharded results |\n\n### Quick Start\n\n```bash\n# Prepare ferro reference (main binary - no special features needed)\nferro prepare --output-dir data/ferro\n\n# Check reference data\nferro check --reference data/ferro\n\n# Normalize with ferro\nferro normalize -i patterns.txt --reference data/ferro\n\n# For tool comparison, build with benchmark support\ncargo build --release --features benchmark\n\n# Prepare other tools (uses ferro reference for transcript data)\nferro-benchmark prepare mutalyzer --ferro-reference data/ferro --output-dir data/mutalyzer\nferro-benchmark prepare biocommons --seqrepo-dir data/seqrepo --uta-dump uta_20210129b.pgd.gz --ferro-reference data/ferro\n\n# Compare results between tools\nferro-benchmark normalize mutalyzer -i patterns.txt -o mutalyzer.json --mutalyzer-settings data/mutalyzer/mutalyzer_settings.conf\nferro-benchmark compare results normalize ferro.json mutalyzer.json -o comparison.json\n```\n\n**Supported tools**: ferro-hgvs, mutalyzer, biocommons/hgvs, hgvs-rs\n\n\u003e **Note**: The `pixi.toml` and `pixi.lock` files in this repository define a [pixi](https://pixi.sh) environment for the Python-based external tools (mutalyzer, biocommons/hgvs, seqrepo) used in benchmarking. Run `pixi shell` to activate it.\n\nSee [docs/BENCHMARK_GUIDE.md](docs/BENCHMARK_GUIDE.md) for detailed usage.\n\n## Development\n\n```bash\ncargo build\ncargo test\ncargo clippy -- -D warnings\n```\n\n## License\n\nLicensed under the MIT License. See [LICENSE](LICENSE) for details.\n\n## Disclaimer\n\nThis software is under active development.\nWhile 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](https://github.com/fulcrumgenomics/ferro-hgvs/blob/main/LICENSE) for details).\nPlease submit an [issue](https://github.com/fulcrumgenomics/ferro-hgvs/issues), and better yet a [pull request](https://github.com/fulcrumgenomics/ferro-hgvs/pulls) as well, if you discover a bug or identify a missing feature.\nPlease contact [Fulcrum Genomics](https://www.fulcrumgenomics.com) if you are considering using this software or are interested in sponsoring its development.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffulcrumgenomics%2Fferro-hgvs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffulcrumgenomics%2Fferro-hgvs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffulcrumgenomics%2Fferro-hgvs/lists"}