Package: hgvs
Important:biocommons packages require Python 3.6+.MoreThehgvspackage provides a Python library to parse, format,
validate, normalize, and map sequence variants according toVariation
Nomenclature(aka Human Genome Variation Society) recommendations.Specifically, the hgvs package focuses on the subset of the HGVS
recommendations that precisely describe sequence-level variation
relevant to the application of high-throughput sequencing to clinical
diagnostics.  The package does not attempt to cover the full scope of
HGVS recommendations. Please refer toissuesfor limitations.InformationLatest ReleaseDevelopment(main branch)    |FeaturesParsing is based on formal grammar.An easy-to-use object model that represents
most variant types (SNVs, indels, dups, inverstions, etc) and
concepts (intronic offsets, uncertain positions, intervals)A variant normalizer that rewrites variants in canoncial forms and
substitutes reference sequences (if reference and transcript
sequences differ)Formatters that generate HGVS strings from internal representationsTools to map variants between genome, transcript, and protein sequencesReliable handling of regions genome-transcript discrepanciesPluggable data providers support alternative sources of transcript mapping
dataExtensive automated tests, including those for all variant types and
“problematic” transcriptsEasily installed using remote data sources.  Installation with local
data sources is straightforward and completely obviates network
accessImportant NotesYou are encouraged tobrowse issues.  All known issues are
listed there.  Please report any issues you find.Use a pip package specification to stay within minor releases.For example,hgvs>=1.5,<1.6.hgvsusesSemantic Versioning.ExamplesInstallationBy default,hgvsuses remote data sources, which makes installation
easy.$ mkvirtualenv hgvs-test
(hgvs-test)$ pip install --upgrade setuptools
(hgvs-test)$ pip install hgvs
(hgvs-test)$ pythonSeeInstallation instructionsfor
details, including instructions for installingUniversal Transcript
Archive (UTA)andSeqRepolocally.Configurationhgvswill use publicly available data sources unless directed
otherwise through environment variables, like so:# N.B. These are examples. The correct values will depend on your installation
$ export UTA_DB_URL=postgresql://anonymous:anonymous@localhost:5432/uta/uta_20210129
$ export HGVS_SEQREPO_DIR=/usr/local/share/seqrepo/latestAlternatively, if you are unable to pass the postgresql password in the
UTA_DB_URL environment variable (i.e., generating an auth token), you can set
UTA_DB_URL topostgresql://<user>@<host>/<db>/<schema>and set PGPASSWORD. For example:$ export UTA_DB_URL=postgresql://anonymous@localhost:5432/uta/uta_20210129 PGPASSWORD=anonymousSee the installation instructions for details.Parsing and Formatinghgvsparses HGVS variants (as strings) into an object model, and can format
object models back into HGVS strings.>>>importhgvs.parser# start with these variants as strings>>>hgvs_g='NC_000007.13:g.36561662C>T'>>>hgvs_c='NM_001637.3:c.1582G>A'# parse the genomic variant into a Python structure>>>hp=hgvs.parser.Parser()>>>var_g=hp.parse_hgvs_variant(hgvs_g)>>>var_gSequenceVariant(ac=NC_000007.13,type=g,posedit=36561662C>T,gene=None)# SequenceVariants are composed of structured objects, e.g.,>>>var_g.posedit.pos.startSimplePosition(base=36561662,uncertain=False)# format by stringification>>>str(var_g)'NC_000007.13:g.36561662C>T'Projecting (“Mapping”) variants between aligned genome and transcript sequenceshgvsprovides tools to project variants between genome, transcript,
and protein sequences.  Non-coding and intronic variants are
supported.  Alignment data come from theUniversal Transcript Archive
(UTA).>>>importhgvs.dataproviders.uta>>>importhgvs.assemblymapper# initialize the mapper for GRCh37 with splign-based alignments>>>hdp=hgvs.dataproviders.uta.connect()>>>am=hgvs.assemblymapper.AssemblyMapper(hdp,...assembly_name='GRCh37',alt_aln_method='splign',...replace_reference=True)# identify transcripts that overlap this genomic variant>>>transcripts=am.relevant_transcripts(var_g)>>>sorted(transcripts)['NM_001177506.1','NM_001177507.1','NM_001637.3']# map genomic variant to one of these transcripts>>>var_c=am.g_to_c(var_g,'NM_001637.3')>>>var_cSequenceVariant(ac=NM_001637.3,type=c,posedit=1582G>A,gene=None)>>>str(var_c)'NM_001637.3:c.1582G>A'# CDS coordinates use BaseOffsetPosition to support intronic offsets>>>var_c.posedit.pos.startBaseOffsetPosition(base=1582,offset=0,datum=Datum.CDS_START,uncertain=False)Translating coding variants to protein sequencesCoding variants may be translated to their protein consequences.  HGVS
uses the same pairing of transcript and protein accessions as seen in
NCBI and Ensembl.# translate var_c to its protein consequence# The object structure of protein variants is nearly identical to# that of nucleic acid variants and is converted to a string form# by stringification. Per HGVS recommendations, inferred consequences# must have parentheses to indicate uncertainty.>>>var_p=am.c_to_p(var_c)>>>var_pSequenceVariant(ac=NP_001628.1,type=p,posedit=(Gly528Arg),gene=None)>>>str(var_p)'NP_001628.1:p.(Gly528Arg)'# setting uncertain to False removes the parentheses on the# stringified form>>>var_p.posedit.uncertain=False>>>str(var_p)'NP_001628.1:p.Gly528Arg'# formatting can be customized, e.g., use 1 letter amino acids to# format a specific variant# (configuration may also be set globally)>>>var_p.format(conf={"p_3_letter":False})'NP_001628.1:p.G528R'Normalizing variantsSome variants have multiple representations due to instrinsic
biological ambiguity (e.g., inserting a G in a poly-G run) or due to
misunderstanding HGVS recommendations.  Normalization rewrites certain
veriants into a single representation.# rewrite ins as dup (depends on sequence context)>>>importhgvs.normalizer>>>hn=hgvs.normalizer.Normalizer(hdp)>>>hn.normalize(hp.parse_hgvs_variant('NM_001166478.1:c.35_36insT'))SequenceVariant(ac=NM_001166478.1,type=c,posedit=35dup,gene=None)# during mapping, variants are normalized (by default)>>>c1=hp.parse_hgvs_variant('NM_001166478.1:c.31del')>>>c1SequenceVariant(ac=NM_001166478.1,type=c,posedit=31del,gene=None)>>>c1n=hn.normalize(c1)>>>c1nSequenceVariant(ac=NM_001166478.1,type=c,posedit=35del,gene=None)>>>g=am.c_to_g(c1)>>>gSequenceVariant(ac=NC_000006.11,type=g,posedit=49917127del,gene=None)>>>c2=am.g_to_c(g,c1.ac)>>>c2SequenceVariant(ac=NM_001166478.1,type=c,posedit=35del,gene=None)There aremore examples in the documentation.Citing hgvs (the package)hgvs: A Python package for manipulating sequence variants using HGVS nomenclature: 2018 Update.Wang M, Callenberg KM, Dalgleish R, Fedtsov A, Fox N, Freeman PJ, Jacobs KB, Kaleta P, McMurry AJ, Prlić A, Rajaraman V, Hart RKHuman Mutation. 2018Pubmed|Open Access PDFA Python Package for Parsing, Validating, Mapping, and Formatting Sequence Variants Using HGVS Nomenclature.Hart RK, Rico R, Hare E, Garcia J, Westbrook J, Fusaro VA.Bioinformatics. 2014 Sep 30.PubMed|Open Access PDFContributingThe hgvs package is intended to be a community project.  Please seeContributingto get
started in submitting source code, tests, or documentation.  Thanks
for getting involved!See AlsoOther packages that manipulate HGVS variants:pyhgvsMutalyzer