liftAssess v0.2.0a1

Released: 2026-09-13

Changed

• Replaced the legacy aggregate result model with orthogonal factual states, deterministic factual headlines, bounded interpretation, and explicit scope boundaries.
• Introduced schema-v2 single-locus JSON. The redesigned schema intentionally removes obsolete aggregate-result and mapping-selection fields rather than silently redefining them.
• Made human reporting progressively disclose material partial coverage, fragmentation, target discontinuity, multiple mappings, comparative relationships, and genomic context without converting them into a composite confidence score.

Added

• Exact-resource chain indexing for scalable single-locus, reverse, flanking-interval, and batch lookup while retaining the original UCSC chain bytes as scientific provenance.
• Actual reverse-direction chain mapping as a result dimension distinct from UCSC reciprocal-best membership.
• Automatic centered 101-bp flanking-interval checks for 1-bp point queries, with explicit larger odd-width windows available through --context-bases.
• Paired standard liftOver versus all-chain inventory comparison and deterministic provenance-aware comparative relationships.
• Indexed BED3+ and 1-based interval-table batch assessment, including exact target collision/overlap relationships and shared COMPARATIVE resource traversal.
• Authoritative UCSC source-sequence validation for sequence names, aliases, and bounds before mapping is attempted.
• Version-bound UCSC/NCBI target sequence-role reporting when exact assembly metadata is available.
• UCSC Segmental Duplications source/target overlap context with exact provenance and an explicit descriptive-only interpretation boundary.

Validation

• Completed the Milestone 23 held-out language/usability gate across all five pre-registered cases.
• Incorporated post-M23 outside-user feedback that unusual findings should explain why they matter and what a biologist can do next. Non-reciprocal reverse liftOver, multiple mappings, comparative evidence, and Segmental Duplications context now carry bounded interpretation and actionable follow-up without asserting a biological cause or preferred locus.
• Added direct UCSC Genome Browser navigation for unusual single-locus results and documented the scientific literature supporting the interpretation of non-reciprocal genome-build mappings.

liftAssess v0.1.0a1

liftAssess v0.1.0a1 — First Public Alpha

This is the first public alpha release of liftAssess, a tool for evaluating ambiguous genomic coordinate liftOver mappings using transparent, provenance-aware evidence.

Rather than attempting to declare one mapping biologically “correct,” liftAssess assesses how strongly the available evidence supports the candidate mappings and reports one of three outcomes:

• WELL_SUPPORTED
• CONTESTED
• INDETERMINATE

What’s included

• UCSC chain-based candidate mapping
• Comparative evidence from UCSC net and reciprocal-best resources
• Explicit evidence provenance and dependency tracking
• Deterministic assessment logic
• Human-readable summary and detailed reports
• Machine-readable JSON output
• Cache-aware resource acquisition
• Offline assessment using verified cached resources
• CLI support for single-locus assessments
• Public Python API for programmatic use

The release also includes documentation covering:

• getting started
• current features
• design and scientific assumptions
• roadmap
• performance characteristics
• references

Example

assess-liftover \
  canFam3 \
  canFam4 \
  chrUn_JH373233:1845736-1845835

The documented real comparative fixture produces a CONTESTED assessment with multiple candidate mappings and exercises the full comparative-evidence path.

Installation

Because this is an alpha release:

python -m pip install --pre liftassess

The installed CLI is:

assess-liftover --help

Important alpha notes

This is early scientific software.

• WELL_SUPPORTED does not mean “biologically correct.”
• liftAssess is an assessor, not a mapping resolver.
• v1 does not use a numeric confidence score.
• Current CLI assessment is one locus at a time.
• Large UCSC chain resources can make single-locus assessments slow; performance work is planned after the scientific and interface behavior is established.
• Public interfaces and output semantics beginning with this alpha should be treated according to the compatibility boundaries documented in the repository.

Validation

For this release:

• 316 automated tests pass
• Python 3.11–3.14 are exercised in CI
• Ruff, formatting, and strict mypy checks pass
• Wheel and source distributions were smoke-tested independently
• Installation from the published PyPI package was verified successfully

Links

• Documentation: docs/
• PyPI: liftassess
• Source repository: GregRR/lift-assess

This release marks the beginning of the public-alpha phase. Feedback on scientific interpretation, usability, edge cases, and real-world liftOver ambiguity scenarios is especially useful.