Skip to main content

Tests Coverage Status PyPI PyPI downloads Docs

Varcode

Varcode is a Python library that predicts what genomic variants do to genes, transcripts, and proteins. Load a VCF or MAF file, and for each variant on each overlapping transcript, Varcode reports the predicted consequence (for example a substitution such as p.L159M, a frameshift, or a gene fusion). Where the sequence can be determined, it also gives the mutant protein.

In the OpenVax tools, Varcode reads gene annotations through PyEnsembl. Isovar reconstructs variant sequences from RNA reads, and Topiary and Vaxrank use Varcode's predicted proteins to choose and rank candidate peptides; see how the libraries fit together.

Install

Requires Python 3.11 or later:

pip install varcode
pyensembl install --release 81 --species human

The second command downloads the gene annotation and transcript sequences used in the example below (Ensembl 81, GRCh38). For your own data, choose an annotation that matches your input's genome build; see reference setup.

Optional extras: varcode[orf] adds ORFdata for noncanonical ORF consequences, and varcode[rna] adds pysam for phasing variants from RNA-seq reads.

Quick start

Predict the effect of a single GRCh38 variant on a CFTR transcript:

from varcode import Variant

variant = Variant("7", 117_531_100, "T", "A", genome=81)
transcript = variant.genome.transcript_by_id("ENST00000003084")
effect = variant.effect_on_transcript(transcript)

print(effect.gene.name, effect.short_description)
protein = effect.mutant_protein_sequence
print(protein[158])  # Python offsets start at zero
CFTR p.L159M
M

Annotate every variant in a VCF called against the same genome build, and print the most severe effect for each:

from varcode import load_vcf

variants = load_vcf("variants.vcf", genome=81)
effects = variants.effects()
for variant, effect in effects.top_priority_effect_per_variant().items():
    print(variant.short_description, effect.short_description)

For a VCF containing only the variant above, this prints:

chr7 g.117531100T>A p.L159M

Before relying on the output, read how to read results. In short: each prediction belongs to one transcript; "top priority" means most severe, not most likely; None means unknown, not unchanged; and a predicted protein is not evidence that it is expressed.

Command line

The varcode command annotates variant files without writing Python and saves one row per variant and transcript:

varcode effects --genome GRCh38 --vcf variants.vcf --output-csv effects.csv

varcode genes lists the genes each variant overlaps, and varcode check-samples screens a cohort of VCFs for possible sample mix-ups. varcode --help lists the subcommands. See the command-line guide and sample identity checks.

Documentation

Full documentation: openvax.github.io/varcode.

Development

./develop.sh   # editable install into the active environment
./lint.sh      # Ruff and mypy
./test.sh      # pytest; needs the Ensembl releases listed in CONTRIBUTING.md
mkdocs build --strict

See CONTRIBUTING.md for the development environment and reference data, and the changelog for release history. For bugs or questions, open an issue.

License

Varcode is released under the Apache 2.0 license.

Metadata

Release files for varcode 11.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for varcode 11.5.0
File Size Uploaded Provenance Actions
varcode-11.5.0.tar.gz 15.4 MB Without provenance Details for varcode-11.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for varcode 11.5.0
File Interpreter ABI Platform Actions
varcode-11.5.0-py3-none-any.whl Python 3 none any Details for varcode-11.5.0-py3-none-any.whl

Total release size: 15.8 MB

Release files / varcode-11.5.0.tar.gz

Download URL varcode-11.5.0.tar.gz
Size 15.4 MB
Tags Source
SHA-256 checksum
How to use checksums
98b1fe7cbb0c29b09ccb36fdfcfbd88cf00dac201c396d63afaa32f8a973d861
BLAKE2b-256 checksum
How to use checksums
654d9902d7af573aea0c088ae687dbc18f4177682e6c980a69cc9beb9a289065
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Release files / varcode-11.5.0-py3-none-any.whl

Download URL varcode-11.5.0-py3-none-any.whl
Size 388.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b2f20d52c9fc94378b6b84c087a5a12c3660f38cf622cd9d570e555a50b54181
BLAKE2b-256 checksum
How to use checksums
edac3d294ce26193be87732f792b8d773c69b8e99294e588457aaba616408fd8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.6

Security for varcode 11.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

11.5.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page