Genomics to structure triage

genomics-to-structure-triage

When to Use

• You have a scored/annotated variant list (e.g. from VEP, VarSeq, or a genomic foundation model) and need to decide which coding variants justify a 3D structure prediction.
• You must pick between AlphaFold2 (monomer), AlphaFold3 (complexes, ligands, nucleic acids), or RoseTTAFold (open-source, Rosetta-integrated workflows).
• You need to rank candidate variants for structural follow-up by combining biological evidence (missense severity, expression impact, allele rarity, splice disruption) with predicted-structure confidence (pLDDT, interface PAE).
• You are building a triage step between a variant-calling/annotation pipeline and a structure-prediction pipeline (e.g. bio-variant-calling-variant-annotation → this skill → alphafold-structure-prediction).

Version Compatibility

• pandas ≥2.0, NumPy ≥1.24, Python ≥3.10
• AlphaFold2 (ColabFold/DeepMind release), AlphaFold3 (2024 release, complexes/ligands/nucleic acids), RoseTTAFold2/RFdiffusion (Baker lab, open-source)
• pLDDT/PAE conventions follow AlphaFold DB schema (pLDDT 0-100 in the B-factor column, PAE in Ångströms, 0-30+ scale)

Prerequisites

• pip install pandas numpy
• A variant table with per-variant fields: coding status, splice-disruption score, expression delta, missense pathogenicity probability, and a rarity/allele-frequency-derived score (e.g. from gnomAD)
• Familiarity with pLDDT/PAE confidence metrics (see alphafold-structure-prediction) and with upstream variant annotation (see bio-variant-calling-variant-annotation)

Model Routing

Goal: pick the right structure-prediction backend for a variant's biological context. Approach: check for hetero-complex/ligand/nucleic-acid requirements first (AlphaFold3), then an explicit open-workflow requirement (RoseTTAFold), then complex-only cases (AlphaFold3), and default to AlphaFold2 for simple monomers.

Scenario	Preferred Model
Monomer baseline	AlphaFold2
Complex / nucleic acids / ligands	AlphaFold3
Rosetta-centric open workflows (e.g. RFdiffusion follow-up)	RoseTTAFold

def choose_structure_model(has_complex: bool, has_ligand_or_nucleic: bool, need_open_rosetta_workflow: bool) -> str:
    """Route a variant's protein context to the appropriate structure-prediction backend.

    Args:
        has_complex: variant's protein participates in a known hetero-complex.
        has_ligand_or_nucleic: prediction must model a bound ligand, RNA, or DNA.
        need_open_rosetta_workflow: downstream steps require an open-source Rosetta-based
            pipeline (e.g. RFdiffusion redesign) rather than AlphaFold.
    Returns:
        One of "AlphaFold2", "AlphaFold3", "RoseTTAFold".
    """
    if has_ligand_or_nucleic:
        return "AlphaFold3"
    if need_open_rosetta_workflow:
        return "RoseTTAFold"
    if has_complex:
        return "AlphaFold3"
    return "AlphaFold2"

Priority Scoring

Goal: rank coding variants for structural follow-up, then discount the ranking by how much the resulting model can actually be trusted. Approach: compute a biology-evidence score (missense probability, expression delta, rarity, splice disruption) for coding variants only, then multiply by a confidence factor derived from AlphaFold pLDDT/PAE once a model exists. pLDDT thresholds follow the AlphaFold DB convention: >90 very high, 70-90 confident, <50 likely disordered (Varadi et al. 2022) — don't over-weight scores in the <50 band even if biology evidence is high.

import numpy as np
import pandas as pd


def structure_priority(coding: bool, max_ds: float, expr_delta: float,
                        missense_prob: float, rarity_score: float) -> float:
    """Score a variant's need for structural follow-up from biology evidence alone.

    Only coding variants are eligible; non-coding variants score 0 and should never
    reach a structure pipeline. Weights sum to 1.0.
    """
    if not coding:
        return 0.0
    return (0.45 * missense_prob + 0.25 * abs(expr_delta)
            + 0.20 * rarity_score + 0.10 * max_ds)


def final_priority(priority: float, mean_plddt: float, interface_pae: float) -> float:
    """Discount a biology-evidence priority by structure-model confidence.

    mean_plddt: average per-residue pLDDT (0-100) over the modeled region.
    interface_pae: predicted aligned error at the interface of interest (Angstroms);
        lower is better. Values are clipped to [0, 30] before scaling.
    """
    conf = 0.6 * (mean_plddt / 100.0) + 0.4 * (1.0 - np.clip(interface_pae / 30.0, 0, 1))
    return priority * conf


def triage_variants(variants: pd.DataFrame) -> pd.DataFrame:
    """Rank a variant table for structural follow-up and assign a routing model.

    Expects columns: coding, max_ds, expr_delta, missense_prob, rarity_score,
    has_complex, has_ligand_or_nucleic, need_open_rosetta_workflow, and (if a
    prior structure exists) mean_plddt, interface_pae.
    """
    out = variants.copy()
    out["priority"] = out.apply(
        lambda r: structure_priority(r.coding, r.max_ds, r.expr_delta,
                                      r.missense_prob, r.rarity_score),
        axis=1,
    )
    has_conf = {"mean_plddt", "interface_pae"}.issubset(out.columns)
    if has_conf:
        out["final_priority"] = out.apply(
            lambda r: final_priority(r.priority, r.mean_plddt, r.interface_pae), axis=1
        )
    else:
        out["final_priority"] = out["priority"]
    out["model"] = out.apply(
        lambda r: choose_structure_model(r.has_complex, r.has_ligand_or_nucleic,
                                          r.need_open_rosetta_workflow),
        axis=1,
    )
    return out.sort_values("final_priority", ascending=False)

Pitfalls

• Non-coding variants must never enter a structure pipeline — structure_priority returns 0.0 for them by design; don't override this.
• Low-confidence regions (pLDDT < 50) reflect either a bad prediction or genuine intrinsic disorder (e.g. unstructured termini) — don't over-interpret RMSD or docking results there without checking PAE too.
• A high biology-evidence score with a low-confidence structure (final_priority near 0) still means "structure not ready to trust," not "variant unimportant" — surface both priority and final_priority in reports.
• Always consider assay/clinical context (ClinVar status, functional assay data) alongside structural predictions before acting on triage output.
• AlphaFold DB confidence statistics are proteome-level averages (Varadi et al. 2022); they do not guarantee any single protein's pLDDT profile.

See Also

• alphafold-structure-prediction — AF2/AF3 usage details and confidence-metric interpretation
• genomic-foundation-models — upstream variant effect scoring feeding missense_prob/rarity_score
• bio-variant-calling-variant-annotation — produces the annotated variant table this skill consumes
• bio-structural-biology-alphafold-predictions — downstream structure retrieval/analysis once routed