hgvs - manipulate biological sequence variants according to Human Genome Variation Society recommendations

The hgvs package provides a Python library to parse, format, validate, normalize, and map sequence variants according to Variation 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 to issues for limitations.

Information

Wang M, Callenberg KM, Dalgleish R, Fedtsov A, Fox N, Freeman PJ, et al.
hgvs: A Python package for manipulating sequence variants using HGVS nomenclature: 2018 Update.
Hum Mutat. 2018. doi:10.1002/humu.23615

Important Notes

• You are encouraged to browse

• Use a pip package specification to stay within minor releases.

Installing HGVS Locally

Important: For more detailed installation and configuration instructions, see the HGVS readthedocs

Prerequisites

python3

hgvs uses psycopg with its prebuilt binary wheels to talk to UTA, so no PostgreSQL client libraries or compiler are required for a standard install.

Installation Steps

By default, hgvs uses remote data sources, which makes installation easy. If you would like to use local instances of the data sources, see the readthedocs.

1. Create a virtual environment using your preferred method.

python3 -m venv venv

1. Run the following commands in your virtual environment:

See Installation instructions for details, including instructions for installing Universal Transcript Archive (UTA) and SeqRepo locally.

Examples and Usage

See examples and readthedocs for usage.

Developer Setup

The hgvs package is a community effort. Please see Contributing to get started in submitting source code, tests, or documentation. Thanks for getting involved!

Install Prerequisites

These tools are required to get started:

• git: Version control system
• GNU make: Current mechanism for consistent invocation of developer tools.
• uv: An extremely fast Python package and project manager, written in Rust.

MacOS or Linux Systems

• Install brew
• brew install git make uv

Linux (Debian-based systems)

You may also install using distribution packages:

sudo apt install git make

Then install uv using the uv installation instructions.

One-time development setup

Create a Python virtual environment, install dependencies, install pre-commit hooks, and install an editable package:

make devready

Development

N.B. Developers are expected to use make to invoke tools to ensure consistency with the CI/CD pipelines. Type make to see a list of supported targets. A subset are listed here:

» make 🌟🌟 biocommons conventional make targets 🌟🌟

Using these targets promots consistency between local development and ci/cd commands.

usage: make [target ...]

BASIC USAGE help Display help message

SETUP, INSTALLATION, PACKAGING devready Prepare local dev env: Create virtual env, install the pre-commit hooks build Build package publish publish package to PyPI

FORMATTING, TESTING, AND CODE QUALITY cqa Run code quality assessments test Test the code with pytest

DOCUMENTATION docs-serve Build and serve the documentation docs-test Test if documentation can be built without warnings or errors

CLEANUP clean Remove temporary and backup files cleaner Remove files and directories that are easily rebuilt cleanest Remove all files that can be rebuilt distclean Remove untracked files and other detritus

Testing

Existing tests use a cache that is committed with the repo to ensure that tests do not require external networking. To develop new tests, which requires loading the cache, you should install UTA and Seqrepo (and the rest service) locally.

docker compose --project-name biocommons -f ./misc/docker-compose.yml up

IMPORTANT: Loading the test caches is currently hampered by #551, #760, and #761. To load reliably, use make test-relearn-iteratively for now.