Source-linked AI summary
FoldKit: A Python library for efficient storage and retrieval of co-folding predictions
Jonathan A. Levine, Melissa Pathil, Samuel Nitz, Olga Lyudovyk, Benjamin D. Greenbaum
TL;DR
Large-scale AF3 co-folding produces JSON outputs that are costly to store and cumbersome to analyze. FoldKit converts these outputs into compact structured data with programmatic metric and ensemble access, reducing storage needs while preserving relevant analysis capabilities. Its current evaluation covers AF3 datasets with protein-only inputs, while broader tool and input support remains future work.
Problem
AF3 co-folding produces large JSON outputs that are inefficient to store and require substantial parsing and custom code for metric extraction.
Method
FoldKit converts raw AF3 outputs into compressed structured representations and provides Python interfaces for confidence metrics, individual predictions, and ensembles.
Results
FoldKit reduces storage costs by roughly an order of magnitude while preserving direct programmatic access to per-residue, per-interface, individual-prediction, and ensemble outputs.
Takeaways & Limitations
FoldKit provides a lightweight solution for storage and accessibility in large-scale AF3 co-folding studies, with benefits that increase for complex multi-chain inputs.
Takeaways & Limitations
FoldKit currently supports AF3 outputs, and its compression generalization beyond protein-only inputs and the three benchmark dataset types remains to be tested.
Abstract
from arXiv · showhide
AlphaFold 3 (AF3) enables structure prediction of biomolecular complexes through co-folding multiple interacting molecules, making it increasingly useful for de novo protein design and for large-scale studies of protein-protein, protein-peptide, and other biomolecular interactions. However, systematic co-folding experiments can produce large volumes of output data, particularly when multiple random seeds and samples are generated for each input complex. We introduce FoldKit, a Python package for efficient storage and analysis of large-scale AF3 co-folding results. FoldKit converts raw AF3 outputs into a compact, structured representation while preserving the metadata needed for downstream analysis. The FoldKit Python library provides convenient programmatic access to global, single chain, and interface confidence metrics such as pLDDT, pTM, ipTM, ipAE, and ipSAE, as well as an ensemble-level interface for accessing and aggregating these metrics for a single input across multiple seeds and samples. We benchmark FoldKit on three types of AF3 co-folding datasets: (i) a protein design campaign with 2 chains per input, (ii) a TCR-pMHC dataset with 4 chains per input, and (iii) a pooled-AF3 protein-protein interaction dataset with up to 22 chains per input. We find that FoldKit reduces storage requirements by approximately 5-15-fold compared to native AF3 outputs, depending on dataset composition, while maintaining direct programmatic access to individual predictions, ensembles, and confidence metrics. By reducing storage requirements and facilitating programmatic access to relevant outputs, FoldKit facilitates large-scale computational studies of biomolecular interactions. FoldKit is available from PyPI and can be installed using pip.
INTRODUCTION
Co-folding supports diverse biomolecular-interaction studies, but AF3 produces large JSON outputs that are cumbersome to parse and store. FoldKit addresses these storage and metric-access problems.
- Co-folding uses AF3 to predict complexes and assess interactions in protein design, native complexes, and pooled interaction screens.
- AF3 confidence outputs include pLDDT, PAE, pTM, and interface metrics such as ipAE, ipTM, and ipSAE.
- AF3 stores confidence values in large JSON files alongside predicted structures.
- Extracting interchain or subchain metrics can require substantial parsing and custom code, especially across many heterogeneous predictions.
- Numerical values stored as text make large co-folding result directories inefficient and potentially prohibitively expensive to store.
- FoldKit was developed to address these storage and analysis issues.
FOLDKIT
FoldKit combines compressed AF3 storage with a Python interface for extracting customizable metrics from individual predictions and ensembles.
- The FoldKit Python API loads AF3 results from server or local runs and extracts or aggregates confidence metrics.
- Users can customize aggregation, select chain or interchain data, and extract features from partial chain subsequences.
- The API supports ensemble-level extraction across multiple random seeds and samples for one sequence input.
- The FoldKit CLI converts raw AF3 JSON files into compressed structured .npz representations integrated with the Python API.
FOLDKIT COMPRESSION ON SYNTHETIC DATA
On a synthetic dataset varying chain count and residues per chain, FoldKit substantially compressed individual AF3 outputs, with savings increasing for larger complexes.
- 5- to 20-fold: FoldKit reduced storage requirements for individual AF3 outputs in the synthetic benchmark.The benchmark used one AF3 seed and one sample while varying chains and residues per chain.
- Larger AF3 complexes derived progressively greater storage savings from FoldKit.The compression factor increased with complex size because raw and FoldKit outputs followed different scaling exponents.
FOLDKIT COMPRESSION ON PUBLIC DATA
Across three public AF3 datasets spanning different ensemble sizes and chain counts, FoldKit reduced storage requirements, with benefits increasing for larger and more complex inputs.
- Three datasets covered binder-target pairs, approximately 5500 four-chain TCR-pMHC complexes, and approximately 2100 pooled complexes containing 4–22 proteins.The datasets used ensemble sizes of 3, 20, and 5, respectively.
- Across all three datasets, FoldKit substantially reduced storage requirements compared with raw AF3 outputs.FoldKit outputs scaled more shallowly with the number of complexes, producing progressively larger savings as datasets grew.
- FoldKit’s storage benefits depended on the size and complexity of individual complexes.
- Increasing chain count adds pairwise confidence information, making pairwise data increasingly important in raw outputs.
- FoldKit provided particularly substantial storage benefits for large multi-chain jobs generated by pooled-AF3 approaches.
DISCUSSION
FoldKit addresses the storage and accessibility bottleneck of large-scale AF3 co-folding by compacting outputs while preserving programmatic access to predictions and confidence metrics. Its storage benefits increase with input complexity, while broader tool and dataset support remain future work.
- Across three real datasets, FoldKit outputs scale more shallowly with the number of input complexes than raw AF3 outputs, producing progressively larger savings.
- FoldKit reduces storage costs while preserving direct programmatic access to per-residue and per-interface metrics, individual predictions, and ensembles.
- Storage savings increase with chain complexity because pairwise confidence matrices grow quadratically with the number of chains.This is especially relevant to pooled co-folding jobs containing dozens of chains.
- FoldKit’s included ipSAE implementation uses NumPy broadcasting to speed calculations for AF3 outputs with many chains.
- FoldKit currently supports AF3 outputs, while broader validation on non-protein complexes and support for other co-folding tools remain future directions.The benchmarks cover binder design, TCR-pMHC, and pooled interaction prediction datasets.
- FoldKit is presented as a lightweight solution for storage and accessibility challenges that grow as co-folding expands across structural biology.
CODE AVAILABILITY
FoldKit is openly available through its GitHub repository, with installation via pip and documentation hosted online.
- FoldKit’s source code, pip installation instructions, and full documentation are available through its GitHub repository and documentation site.