Protein collections and FASTA

effects.to_proteome() converts Varcode's native results into ORFdata's Proteome. Use it to combine predicted proteins with a reference proteome, export FASTA, group equal sequences, or save the predictions and their provenance together. Install the optional integration with pip install 'varcode[orf]'.

import varcode
from orfdata import Proteome

variants = varcode.load_vcf("tumor.vcf", genome="GRCh38:95")
effects = variants.effects(extra_orfs="all")
predicted = effects.to_proteome(sample_id="tumor-1")

predicted.write_fasta("predicted.fasta")
predicted.save("predicted.proteome.json.gz")
restored = Proteome.load("predicted.proteome.json.gz")  # offline

extra_orfs="all" delegates ncORF loading and placement to ORFdata for the variants' reference. Pass an ORFdata evidence rule or already loaded ORFs to choose a subset; omit extra_orfs for ordinary transcript annotation alone. See ncORF annotation for source and reference selection. The free function varcode.to_proteome(effects) remains equivalent.

sample_id and run_id are optional. Conversion reads the supplied native results and their reference transcript properties; it does not rerun variant annotation. Loading the saved collection requires neither a genome database nor the original ORF catalogue, and never reconstructs Python objects from the embedded native archive.

Alternatives and missing products

The adapter accepts an EffectCollection or an iterable of effects, EffectCandidate, RealizedEffectCandidate, ClassifiedOutcome, ORFAnnotation, or ORFOutcome objects. A single native result is accepted directly too. Every realized outcome is visited, including full proteins that differ outside the local windows used to group candidates. Identical mutant sequences with different baselines, splice assumptions, phase, or evidence remain separate.

For standalone ORF annotations, use the same function. It retains failed bindings whose effect is None, as well as the successful predictions.

predicted = varcode.to_proteome(annotation)   # one ORF
predicted = varcode.to_proteome(annotations)  # any iterable, including failures

The existing orf_annotations= keyword is also supported, including when combining standalone ORF annotations with ordinary effects.

The collection's records contain varcode.proteome.v1 events and comparisons. Its links connect events to comparisons and comparisons to proteins. For an EffectCollection, a collection record also retains source filenames and the supplied annotation timestamp, without splitting identical predictions that appeared in different input collections. Comparison payloads retain baseline and mutant products, focal variants, hypotheses, affected intervals, coordinate conventions, and candidate context. Each comparison also retains its native mechanism and transcript-model evidence, so cryptic splice positions and equal-sequence fusion models keep separate links to their outcomes. Comparison identities do not depend on sibling order. Standalone alternatives retain their mechanism coordinates and model evidence in event identity too. Known germline phase and nearby variants remain attached even when annotation returns only one hypothesis. Fusion transcript aliases use the transcript ID and source reference, keeping native JSON round trips stable. Varcode 10.19.1 corrects source keys for these affected predictions. Earlier snapshots remain readable; regenerate affected exports before combining them with results exported by the corrected adapter. Baseline proteins need not be members of the search collection. Native graphs retain reference models, edits, ordered fusion segments and evidence.

Available sequences become proteins. Missing sequences, known empty products, annotation failures, failed ORF bindings, unresolved results and hypothesis limits have distinct statuses and omission reasons. Explicit partial boundaries and unknown boundaries remain distinct. The manifest describes the supplied results; it does not claim exhaustive hypothesis enumeration. Ordinal rank, probability, and phase mass remain separate fields. RNA or reference-ORF evidence is not relabeled as experimental support for a mutant protein.

Sequence grouping and composition

sources_by_sequence = predicted.by_sequence()
sources_by_accession = predicted.by_accession()

# The default FASTA keeps one protein per distinct source prediction.
# Opt into exact sequence grouping and retain its token-to-source mapping:
predicted.write_fasta("unique.fasta", deduplicate=True)
token_to_sources = predicted.fasta_index(deduplicate=True)

reference = Proteome.from_genome(variants[0].genome)
combined = reference.merge(predicted)
combined.save("combined.proteome.json.gz")

The same merge() accepts an ORFdata Proteome from isovar.to_proteome(...). The Varcode tests compose reference, Varcode, and Isovar-shaped results through that shared interface.

Known conflicting taxa, assemblies, annotation contexts and source identities raise errors. A collection with missing or mixed source references remains unscoped. Merging it with a reference requires an explicit shared policy, such as reference.merge(predicted, compatibility="allow_unknown"); this does not override known conflicts or assign the host's taxon to unknown sources.

FASTA uses ORFdata's readable tokens and headers, with available origin, producer, gene, transcript/ORF identifiers, boundaries and change attribution. Supplied amino acids are exported unchanged, including any terminal *. Keep the snapshot alongside FASTA: a header cannot represent every baseline comparison, alternative hypothesis or evidence record. Unsupported nonportable extension metadata raises an error instead of disappearing during conversion.

API

varcode.to_proteome(effects: Iterable | MutationEffect | EffectCandidate | RealizedEffectCandidate | ClassifiedOutcome | ORFAnnotation | ORFOutcome = (), *, sample_id: str | None = None, run_id: str | None = None, orf_annotations: Iterable[ORFAnnotation] = ()) -> Proteome

Expose supplied native outcomes through ORFdata's shared collection API.

PARAMETER	DESCRIPTION
effects	Native effects, EffectCandidates, RealizedEffectCandidates, ClassifiedOutcomes, ORFAnnotations or ORFOutcomes. A single result is accepted directly. Every realized outcome is retained, including failed ORF bindings with no effect. TYPE: native result, EffectCollection or iterable DEFAULT: ()
sample_id	Explicit source scope. Predictions without a sample are supported. TYPE: str DEFAULT: None
run_id	Explicit source scope. Predictions without a sample are supported. TYPE: str DEFAULT: None
orf_annotations	Standalone ORF annotations, including failed bindings with no effect. TYPE: iterable of ORFAnnotation DEFAULT: ()

RETURNS	DESCRIPTION
Proteome	Available mutant sequences and a versioned graph of native results, baseline comparisons, assumptions and omitted outcomes. Baselines need not be entries. Equal sequences retain distinct source associations.

Notes

Requires the optional orf dependency. Reads native product and reference transcript properties without rerunning annotation or translation. An exact common source reference scopes the result; missing or mixed references remain unscoped and require explicit compatibility when merged with a reference proteome. Unknown taxa remain unknown. Unsupported nonportable extension metadata raises an error.

Source code in varcode/proteome.py

def to_proteome(effects: Iterable | MutationEffect | EffectCandidate | RealizedEffectCandidate |
                ClassifiedOutcome | ORFAnnotation | ORFOutcome = (), *, sample_id: str | None = None,
                run_id: str | None = None, orf_annotations: Iterable[ORFAnnotation] = ()) -> "Proteome":
    """Expose supplied native outcomes through ORFdata's shared collection API.

    Parameters
    ----------
    effects : native result, EffectCollection or iterable
        Native effects, EffectCandidates, RealizedEffectCandidates,
        ClassifiedOutcomes, ORFAnnotations or ORFOutcomes. A single result is
        accepted directly. Every realized outcome is retained, including
        failed ORF bindings with no effect.
    sample_id, run_id : str, optional
        Explicit source scope. Predictions without a sample are supported.
    orf_annotations : iterable of ORFAnnotation
        Standalone ORF annotations, including failed bindings with no effect.

    Returns
    -------
    orfdata.Proteome
        Available mutant sequences and a versioned graph of native results,
        baseline comparisons, assumptions and omitted outcomes. Baselines need
        not be entries. Equal sequences retain distinct source associations.

    Notes
    -----
    Requires the optional ``orf`` dependency. Reads native product and reference
    transcript properties without rerunning annotation or translation. An exact common source reference scopes the
    result; missing or mixed references remain unscoped and require explicit
    compatibility when merged with a reference proteome. Unknown taxa remain
    unknown. Unsupported nonportable extension metadata raises an error.
    """
    try:
        from orfdata import Proteome
    except ImportError as error:
        raise ImportError("to_proteome requires the optional dependency: pip install 'varcode[orf]'") from error
    defaults = {name: getattr(effects, name, None) for name in ("annotator", "annotator_version")}
    export = _Export(sample_id, run_id, defaults)
    collection = None
    if isinstance(effects, EffectCollection):
        metadata = _json(dict(defaults, sources=sorted(effects.sources), annotated_at=effects.annotated_at))
        collection = export.record("collection", _identifier("EffectCollection", metadata), payload=metadata)
    results = ((effects,) if isinstance(effects, (MutationEffect, EffectCandidate, RealizedEffectCandidate,
                                                ClassifiedOutcome, ORFAnnotation, ORFOutcome)) else effects)
    for value in results:
        event_key = export.add(value)
        if collection is not None:
            export.link(collection.key, event_key, "contains")
    for annotation in orf_annotations:
        if not isinstance(annotation, ORFAnnotation):
            raise TypeError("orf_annotations must contain ORFAnnotation objects")
        export.add(annotation)
    reference = next(iter(export.references.values())) if len(export.references) == 1 and not export.unknown_reference else None
    return Proteome.from_proteins(export.proteins, reference=reference,
                                  compatibility="strict" if reference else "mixed",
                                  records=export.records, links=export.links)