Skip to main content

VariantFold

Classify Variants of Uncertain Significance (VUS) using AlphaFold-predicted protein structures and Graph Neural Networks.

VariantFold leverages protein structure predictions from ColabFold/AlphaFold and a Graph Convolutional Network (GCN) to classify VUS based on the standardised ACMG-AMP variant classification system.

Workflow

ClinVar data → Parse variants → Mutate sequences → ColabFold 3-D prediction
    → PDB-to-graph conversion → Train GCN (benign vs pathogenic) → Classify VUS
  1. Parse — Extract missense variants from ClinVar downloads (benign, pathogenic, VUS).
  2. Mutate — Apply each variant to the reference protein sequence.
  3. Predict — Run ColabFold to generate 3-D structure models for every variant.
  4. Convert — Transform PDB files into PyTorch Geometric residue-level graphs with rich node features (one-hot amino acid, 3-D coordinates, pLDDT).
  5. Train — Train a multi-layer GCN on the benign vs pathogenic graph dataset.
  6. Classify — Run the trained model on VUS structures to predict likely benign / likely pathogenic with probabilities.

Installation

# Core package (graph conversion + GCN training/inference)
pip install .

# With ColabFold for structure prediction (GPU recommended)
pip install ".[structure]"

# With visualisation tools
pip install ".[viz]"

# Everything
pip install ".[all]"

Quick start — Python API

from variantfold import VariantFoldConfig, VariantFoldPipeline

cfg = VariantFoldConfig(
    gene_symbol="VHL",
    entrez_email="your_email@example.com",
)

pipe = VariantFoldPipeline(cfg)
pipe.step1_parse_variants()       # Parse ClinVar files + fetch sequence
# pipe.step2_predict_structures() # Run ColabFold (long — needs GPU)
pipe.step3_collect_models()       # Gather best PDB models
metrics = pipe.step4_train()      # Train GCN
print(f"Test accuracy: {metrics['accuracy']:.2%}")

vus_df = pipe.step5_classify_vus()
print(vus_df)

Quick start — CLI

# Run steps 1, 3, 4, 5 (assumes PDB libraries are already populated)
variantfold run --gene VHL --email you@example.com --steps 1,3,4,5

# Standalone inference on new PDB files
variantfold predict --model variantfold_VHL/variantfold_model.pt \
                    --pdb-dir ./new_vus_pdbs/

Input data

Place these files in the working directory (./variantfold_<gene>/):

File Description
clinvar_result_bng.txt ClinVar download filtered to benign variants
clinvar_result_ptg.txt ClinVar download filtered to pathogenic variants
clinvar_result_vus.txt ClinVar download filtered to VUS (optional)

Download from ClinVar using the tab-delimited download with default settings.

Configuration

All parameters are set via VariantFoldConfig:

cfg = VariantFoldConfig(
    gene_symbol="TP53",
    entrez_email="you@example.com",
    distance_threshold=6.5,   # Å, residue contact cutoff
    gcn_hidden_dim=64,        # GCN layer width
    gcn_num_layers=3,         # depth
    epochs=200,
    learning_rate=0.01,
    train_fraction=0.8,
    use_residue_features=True, # 24-dim features (set False for legacy 1-dim)
)

Development

pip install -e ".[dev]"
pytest

Licence

MIT

Metadata

Release files for variantfold 2.2.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 variantfold 2.2.0
File Size Uploaded Provenance Actions
variantfold-2.2.0.tar.gz 34.9 kB Without provenance Details for variantfold-2.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 70.0 kB

Release files / variantfold-2.2.0.tar.gz

Download URL variantfold-2.2.0.tar.gz
Size 34.9 kB
Tags Source
SHA-256 checksum
How to use checksums
c28a80d8fc27a7de2f1ae2ac539a4f2bb1d79479b98042ca20cefa048b2fa4fe
BLAKE2b-256 checksum
How to use checksums
b3d9a2fba7b0cd0179a0ba7ce7fe148cdeb9af1e3cf16999084b4742b5575e63
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Release files / variantfold-2.2.0-py3-none-any.whl

Download URL variantfold-2.2.0-py3-none-any.whl
Size 35.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4ba9205cb0a12810c80449f940ad384dce3f9a5e362eb35660b8bc854d6756de
BLAKE2b-256 checksum
How to use checksums
4b292fd7ed0a02cdfc54c5dd19fa4de4497fb2345ae20f54f83384467ab24eb5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.13

Security for variantfold 2.2.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.

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