
1.0.0 (2017-04-08)
###################

Changes since 0.4.0 (2015-09-09).

This is a major release of the hgvs package that includes new features
and behavior changes.  Some client code may require minor
modification.  (Note: Previously, we had tentatively called this
release 0.5.0.  The magnitude of the changes and the desire to migrate
to public API versioning led us release as 1.0.0.)

See :ref:`Installing hgvs` for installation instructions.



Major Features and Changes
$$$$$$$$$$$$$$$$$$$$$$$$$$$


*This section highlights import behavior or interface changes relative
to the 0.4.x series.  Code modifications are likely for most of the
features listed below.*

**★ EasyVariantMapper renamed to AssemblyMapper, now with GRCh38 and
PAR support.** EasyVariantMapper was renamed to AssemblyMapper to
better reflect its role.  AssemblyMapper defaults to GRCh38.
Transcripts in pseudoautosomal regions have alignments to X and Y.
Previously, EVM would refuse to guess which alignment to use and raise
an exception.  AssemblyMapper has a new argument, `in_par_assume`,
which enables callers to prefer X or Y alignments.

**★ VariantMapper validates variants before mapping.** Several bug
reports resulted from attempting to project invalid variants, such as
as variants with insertions between non-adjacent nucleotides. These
generated exceptions or unexpected results. Intrinsic validation is
now peformed before mapping and normalization, and callers may wish to
catch these.

**★ Fully local installations -- no network access required.**
`hgvs` requires access to transcripts and sequences for most
operations.  By default, hgvs will use public remote resources at
runtime, which incurs significant latency and, in principle, presents
a minor privacy concern.  While UTA has always been available for
local installation, the more significant delay was in sequence lookup.
A new package, `SeqRepo <https://github.com/biocommons/seqrepo/>`__,
provides a local sequence database that is synchronized with UTA.
When used together, these packages completely obviate network
connectivity and improve speed by approximately 50x.

**★ hgvs transitions to public API versioning conventions.** By
transitioning from major version 0 ("initial development") to 1
("public API"), we are indicating that the API is expected to be
stable.  In practice, this change will mean that x.y.z versions will
clearly distinguish bug fix releases (increment z),
backward-compatible feature additions (increment y), and API
incompatible changes (increment x).  See `Semantic Versioning
<http://semver.org/>`__ for more information.

**★ Changes in p. formatting to better conform to current varnomen
recommendations.** Inferred changes with unknown p. effects are now
represented with `p.?` rather than `p.(?)` (`#393 <https://github.com/biocommons/hgvs/issues/393/>`_).  In addition,
silent SNV mutations now include the amino acid, as in
`NP_000050.2:p.Lys2597=` rather than `NP_000050.2:p.(=)` (`#317 <https://github.com/biocommons/hgvs/issues/317/>`_).  Both
changes improve conformance with current `varnome recommendations
<http://varnomen.org/>`__.

**★ By default, do not show reference sequence in dels and dups.**
For example, `NM_000059.3:c.22_23delAAinsT` would be shown as
`NM_000059.3:c.22_23delinsT`. Users may configure `max_ref_length`
(default 0) order to change this behavior (`#404 <https://github.com/biocommons/hgvs/issues/404/>`_).

**★ BaseOffsetPosition datums now use enums, defined in hgvs.enums.**
For example, previous `hgvs.location.SEQ_START` must be replaced with
`hgvs.enums.Datum.SEQ_START` (`#396 <https://github.com/biocommons/hgvs/issues/396/>`_).

**★ Unknown protein effect are now internally represented with
`var.posedit=None`.** This case is printed as `NP_01234.5:p.?` (`#412 <https://github.com/biocommons/hgvs/issues/412/>`_).



Deprecations and Removals
$$$$$$$$$$$$$$$$$$$$$$$$$$

* `#349 <https://github.com/biocommons/hgvs/issues/349/>`_: drop support for dupN [`0dbe440 <https://github.com/biocommons/hgvs/commit/0dbe440>`_]
* `#360 <https://github.com/biocommons/hgvs/issues/360/>`_: HGVSValidationError removed; used HGVSInvalidVariantError instead.


Bug Fixes
$$$$$$$$$$

* `#284 <https://github.com/biocommons/hgvs/issues/284/>`_: validation fails for g variants [`512b882 <https://github.com/biocommons/hgvs/commit/512b882>`_]
* `#292 <https://github.com/biocommons/hgvs/issues/292/>`_: Fix bug in validator when validating m. variants and add tests [`12d9b48 <https://github.com/biocommons/hgvs/commit/12d9b48>`_]
* `#308 <https://github.com/biocommons/hgvs/issues/308/>`_: validation across CDS start and CDS end boundaries [`ac066ee <https://github.com/biocommons/hgvs/commit/ac066ee>`_], [`8c8db03 <https://github.com/biocommons/hgvs/commit/8c8db03>`_]
* `#346 <https://github.com/biocommons/hgvs/issues/346/>`_: ensure that alignment starts at transcript position 0 [`3af24b3 <https://github.com/biocommons/hgvs/commit/3af24b3>`_], [`9f29c87 <https://github.com/biocommons/hgvs/commit/9f29c87>`_]
* `#381 <https://github.com/biocommons/hgvs/issues/381/>`_: fix bug attempting to normalize p. variants; add issue test (test_issues.py) [`834bed9 <https://github.com/biocommons/hgvs/commit/834bed9>`_]
* `#393 <https://github.com/biocommons/hgvs/issues/393/>`_: fix inconsistent representation of unknown p. effect when inferred by c_to_p [`3f1ac48 <https://github.com/biocommons/hgvs/commit/3f1ac48>`_]
* `#409 <https://github.com/biocommons/hgvs/issues/409/>`_: Fix bug in normalizer when normalizing ident variant that is written as delins [`94607ecc30da <https://github.com/biocommons/hgvs/commit/94607ecc30da>`_]
* `#415 <https://github.com/biocommons/hgvs/issues/415/>`_: Limit assembly mapper to NC accessions [`6056fd4414df <https://github.com/biocommons/hgvs/commit/6056fd4414df>`_]


New Features
$$$$$$$$$$$$$

* `#105 <https://github.com/biocommons/hgvs/issues/105/>`_: configurable formatting [`c8b9fd1 <https://github.com/biocommons/hgvs/commit/c8b9fd1>`_]
* `#249 <https://github.com/biocommons/hgvs/issues/249/>`_: Move intrinsic validation to models
* `#253 <https://github.com/biocommons/hgvs/issues/253/>`_: Add p. validation support [`3d3b9da <https://github.com/biocommons/hgvs/commit/3d3b9da>`_], [`ba943ae <https://github.com/biocommons/hgvs/commit/ba943ae>`_]
* `#256 <https://github.com/biocommons/hgvs/issues/256/>`_: rename EasyVariantMapper to AssemblyMapper to better indicate functionality [`d6697d6 <https://github.com/biocommons/hgvs/commit/d6697d6>`_]
* `#258 <https://github.com/biocommons/hgvs/issues/258/>`_, `#330 <https://github.com/biocommons/hgvs/issues/330/>`_, `#342 <https://github.com/biocommons/hgvs/issues/342/>`_: ensure that start and end datums are compatible [`247d8bf <https://github.com/biocommons/hgvs/commit/247d8bf>`_]
* `#260 <https://github.com/biocommons/hgvs/issues/260/>`_, `#322 <https://github.com/biocommons/hgvs/issues/322/>`_: added tests to verify that exceptions are raised when mapping invalid variants [`ac37ae0 <https://github.com/biocommons/hgvs/commit/ac37ae0>`_]
* `#270 <https://github.com/biocommons/hgvs/issues/270/>`_: add is_intronic method to BaseOffsetPosition [`4e40866 <https://github.com/biocommons/hgvs/commit/4e40866>`_]
* `#282 <https://github.com/biocommons/hgvs/issues/282/>`_: preserve position in "identity" variants (e.g., norm(c.123A>A) => c.123= rather than c.=) [`cc523ed <https://github.com/biocommons/hgvs/commit/cc523ed>`_]
* `#295 <https://github.com/biocommons/hgvs/issues/295/>`_: raise exception when validating deletion length for intronic variants [`4575ed8 <https://github.com/biocommons/hgvs/commit/4575ed8>`_]
* `#309 <https://github.com/biocommons/hgvs/issues/309/>`_: make errors more informative when coordinate is outside sequence bounds [`d667d8b <https://github.com/biocommons/hgvs/commit/d667d8b>`_], [`f4cd048 <https://github.com/biocommons/hgvs/commit/f4cd048>`_]
* `#314 <https://github.com/biocommons/hgvs/issues/314/>`_: support parsing identity variants [`9116c72 <https://github.com/biocommons/hgvs/commit/9116c72>`_]
* `#315 <https://github.com/biocommons/hgvs/issues/315/>`_: Validate accession type pairs [`be90d50 <https://github.com/biocommons/hgvs/commit/be90d50>`_]
* `#316 <https://github.com/biocommons/hgvs/issues/316/>`_: provide generalized transcript-to-genome projects to handle coding and non-coding transcripts transparently [`26006c7 <https://github.com/biocommons/hgvs/commit/26006c7>`_]
* `#317 <https://github.com/biocommons/hgvs/issues/317/>`_: Output silent p. variants according to HGVS recommendations [`4babbb5 <https://github.com/biocommons/hgvs/commit/4babbb5>`_]
* `#319 <https://github.com/biocommons/hgvs/issues/319/>`_: added PosEdit.length_change() method [`c191567 <https://github.com/biocommons/hgvs/commit/c191567>`_], [`c71a48b <https://github.com/biocommons/hgvs/commit/c71a48b>`_], [`c70fded <https://github.com/biocommons/hgvs/commit/c70fded>`_]
* `#326 <https://github.com/biocommons/hgvs/issues/326/>`_: provide special handling for disambiguating alignments in pseudoautosomal regions [`acc560e <https://github.com/biocommons/hgvs/commit/acc560e>`_]
* `#330 <https://github.com/biocommons/hgvs/issues/330/>`_: datum-matching [`e05674b <https://github.com/biocommons/hgvs/commit/e05674b>`_], [`461ccd7 <https://github.com/biocommons/hgvs/commit/461ccd7>`_]
* `#336 <https://github.com/biocommons/hgvs/issues/336/>`_: add hgvs-shell as excutable for exploration, debugging, bug submission [`f6b6c3c <https://github.com/biocommons/hgvs/commit/f6b6c3c>`_]
* `#356 <https://github.com/biocommons/hgvs/issues/356/>`_: add position comparision operators [`4f7f7e4 <https://github.com/biocommons/hgvs/commit/4f7f7e4>`_]
* `#365 <https://github.com/biocommons/hgvs/issues/365/>`_: graded validation
* `#366 <https://github.com/biocommons/hgvs/issues/366/>`_: move validation to variantmapper
* `#372 <https://github.com/biocommons/hgvs/issues/372/>`_: rename hgvs/variant.py to hgvs/sequencevariant.py [`2f69d65 <https://github.com/biocommons/hgvs/commit/2f69d65>`_], [`ad604fd <https://github.com/biocommons/hgvs/commit/ad604fd>`_]
* `#379 <https://github.com/biocommons/hgvs/issues/379/>`_: move replace_reference to variantmapper (from evm) [`c0f4be1 <https://github.com/biocommons/hgvs/commit/c0f4be1>`_]
* `#386 <https://github.com/biocommons/hgvs/issues/386/>`_: reject discontiguous alignments [`ea2527c <https://github.com/biocommons/hgvs/commit/ea2527c>`_]
* `#391 <https://github.com/biocommons/hgvs/issues/391/>`_: Attempt reconnection if db connection is lost [`2aef5fac3a61 <https://github.com/biocommons/hgvs/commit/2aef5fac3a61>`_]
* `#399 <https://github.com/biocommons/hgvs/issues/399/>`_: validators should raise only HGVSInvalidVariantError exceptions
* `#404 <https://github.com/biocommons/hgvs/issues/404/>`_: Implement max_ref_length in formatter and don't show reference sequence by default


Other Changes
$$$$$$$$$$$$$$

* `#276 <https://github.com/biocommons/hgvs/issues/276/>`_: raise error when user attempts to map to/from c. with non-coding transcript [`aaa0ff5 <https://github.com/biocommons/hgvs/commit/aaa0ff5>`_]
* `#363 <https://github.com/biocommons/hgvs/issues/363/>`_: update railroad diagram [`3e23e10 <https://github.com/biocommons/hgvs/commit/3e23e10>`_]


Internal and Developer Changes
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$

* `#236 <https://github.com/biocommons/hgvs/issues/236/>`_: migrate from built-in seqfetcher to bioutils seqfetcher [`5e9a951 <https://github.com/biocommons/hgvs/commit/5e9a951>`_]
* `#237 <https://github.com/biocommons/hgvs/issues/237/>`_: Mock testing data; dropped unmaintained sqlite-based tests
* `#287 <https://github.com/biocommons/hgvs/issues/287/>`_: ensure that modules are also getting doctested (continues `#287 <https://github.com/biocommons/hgvs/issues/287/>`_) [`3cbe93a <https://github.com/biocommons/hgvs/commit/3cbe93a>`_]
* `#347 <https://github.com/biocommons/hgvs/issues/347/>`_: Replace recordtype with attrs
* `#395 <https://github.com/biocommons/hgvs/issues/395/>`_: get ThreadedConnectionPool sizes from config [`a2a216c <https://github.com/biocommons/hgvs/commit/a2a216c>`_]
* `#397 <https://github.com/biocommons/hgvs/issues/397/>`_: use hgvs.config for VariantMapper.__init__() [`154cf5e <https://github.com/biocommons/hgvs/commit/154cf5e>`_]
* `#400 <https://github.com/biocommons/hgvs/issues/400/>`_: make hdp cache mode (for testing) settable via HGVS_CACHE_MODE environment variable [`09303c7 <https://github.com/biocommons/hgvs/commit/09303c7>`_]
* removed sqlite-based uta dataprovider; updated reqs in etc [`e8c9d8d85d35 <https://github.com/biocommons/hgvs/commit/e8c9d8d85d35>`_]
