VarSim — HGVS Variant Toolkit

Note on Naming: VarSim is an HGVS variant toolkit. It is not affiliated with, and should not be confused with, the "VarSim" read simulator (PMID: 25524895).

VarSim is a comprehensive toolkit for HGVS variant nomenclature — parsing, validation, normalization, backtranslation, format conversion, extraction, liftover, transcription, and translation. All powered by NCBI Entrez.

Installation

pip install varsim

Configuration

Set two environment variables to query NCBI Entrez:

• EMAIL — (Required) A valid email so NCBI can contact you about query issues.
• API_KEY — (Recommended) An NCBI API key for higher query rates. Obtain one from your NCBI account settings.

Linux/macOS:

export EMAIL="your.email@example.com"
export API_KEY="your_api_key_here"

Windows (PowerShell):

$env:EMAIL="your.email@example.com"
$env:API_KEY="your_api_key_here"

Usage

import varsim

1. HGVS Parsing & Validation

Parse HGVS strings into structured objects or validate syntax and semantics.

>>> tag = varsim.parse("NM_000207.3:c.1A>G")
>>> tag.variant_type, tag.ref, tag.alt
('substitution', 'A', 'G')
>>> varsim.validate("NM_000207.3:c.1A>G")
[]
>>> varsim.is_valid("NM_000207.3:c.1A>G", ref_seq="ATGCGTACG...")
True

2. HGVS Normalization

Normalize variants to canonical form per HGVS recommendations.

>>> varsim.normalize("c.4A>G", ref_seq="AAGC")
'c.2A>G'

>>> varsim.normalizer.ins_to_dup("NM_000207.3:c.4_5insA", ref_seq="TAAA")
'NM_000207.3:c.3dup'

3. Backtranslation

Determine which nucleotide changes could produce a given protein variant.

>>> varsim.backtranslate_protein("p.(V42G)")
['c.125T>G']
>>> varsim.backtranslate("G6PD", "p.(V42G)")  # validates against real CDS
['NM_001360016.2:c.125T>G']

4. Format Conversion

Convert between HGVS, VCF, and SPDI formats.

>>> varsim.hgvs_to_vcf("NC_000023.11:g.123456A>G")
{'CHROM': 'NC_000023.11', 'POS': 123456, 'ID': '.', 'REF': 'A', 'ALT': 'G'}
>>> varsim.vcf_to_hgvs("X", 123456, "A", "G", acc="NC_000023.11")
'NC_000023.11:g.123456A>G'

5. Variant Extraction

Diff two sequences and produce the minimal HGVS description.

>>> varsim.extract("ATGC", "ATTC", prefix="c.")
'NM_000207.3:c.3G>T'
>>> varsim.extract("ATGC", "ATC", prefix="c.")
'NM_000207.3:c.3del'

6. Liftover

Remap genomic variants between assemblies via the NCBI Remap API.

>>> varsim.liftover_g_to_assembly("NC_000001.10:g.12345A>G", "GRCh38")
'NC_000001.11:g.12345A>G'
>>> varsim.liftover_transcript("G6PD", "c.1A>G", "GRCh38")
'NC_000023.11:g.153760607T>C'

7. Transcription

Convert between coding and genomic coordinate systems using exon structure.

>>> varsim.c_to_g("NM_001360016.2:c.1A>G", "G6PD")
'NC_000023.11:g.153760607A>G'
>>> varsim.transcription.get_cds_exon_map("G6PD")
[{'exon': 1, 'cds_start': 0, 'cds_end': 138, 'genomic_start': ..., 'strand': -1}, ...]

8. Translation

Translate coding variants to their protein consequences.

>>> varsim.translate_variant("NM_000207.3:c.1A>G", "INS")
'NP_000198.1:p.(M1?)'
>>> eff = varsim.get_protein_effect("NM_000207.3:c.4A>G", "INS")
>>> eff["effect_type"]
'missense'

API Reference

License

MIT License

Note on Naming: This package is not affiliated with the read simulator "VarSim" (PMID: 25524895).