Skip to content

Effect annotation

Call effects() to predict the consequences of your variants. If you have not installed reference data yet, start with Getting started.

Annotate variants

import varcode

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

The collection holds one prediction per variant per overlapping transcript, and a variant's effect can differ between transcripts. The loop above prints one summary per variant, picking the most severe effect by Varcode's consequence ordering, not by likelihood or clinical significance. effects.top_priority_effect() instead selects one effect from the entire collection. See how to read results.

The same interface handles structural variants. To include them when loading a VCF, pass parse_structural_variants=True; see SV loading.

Protein sequences

Given an effect from the collection:

protein = effect.mutant_protein_sequence  # may be None

None means the sequence could not be determined, not that the protein is unchanged. The prediction belongs to effect.transcript; intergenic effects have no transcript. For cDNA, partial structures, and sequence evidence, see Transcript models.

To keep only effects that may change the protein, use effects.drop_silent_and_noncoding(). It removes known silent and noncoding predictions but keeps unresolved ones by default; see filtering by protein change.

Alternative outcomes

When Varcode can't decide between several possible consequences, it returns a MultiOutcomeEffect holding every candidate instead of guessing. This happens for splice variants, structural variants, and variants whose phase relative to a nearby germline variant is unknown:

from varcode import MultiOutcomeEffect

if isinstance(effect, MultiOutcomeEffect):
    for candidate in effect.candidates:
        print(candidate.effect.short_description)
        print(candidate.effect.mutant_protein_sequence)
        print(candidate.source, candidate.evidence)

Two shortcuts pick a single candidate, and they answer different questions:

  • most_likely_effect returns the first candidate in the order the predictor listed them. That order reflects the predictor's preference; it is not a calibrated probability.
  • highest_priority_effect returns the most severe candidate.

When you report a candidate's sequence, keep its candidate.source (which predictor or evidence produced it) and candidate.evidence alongside it.