COFOLDER

COFOLDER is a collection of command-line workflows for protein-ligand co-folding and pre-cofolding diagnostics.

The supported public entry points are:

• bias: inspect protein and ligand reference overlap directly from system.yaml
• validate: run a single runner-backed co-folding workflow
• screen: run validate-style workflows across a ligand library
• oracle: return one scalar metric from a runner-backed run

COFOLDER has a backend-free base install for configuration, input handling, resource access, and analysis-independent library paths. Install the analysis extra for clustering, affinity statistics, interaction processing, and plotting; prediction workflows additionally use one backend extra. Structural-confidence outputs, validation metrics, and affinity-related outputs are treated as distinct concepts; structural confidence should not be described as a proxy for binding affinity.

Start Here

If you are new to the repository, use this path:

1. Install COFOLDER with the backend you need. See docs/getting-started/installation.md.
2. Run your first command. See docs/getting-started/quickstart.md.
3. Pick the workflow that matches your task. See docs/user-guide/overview.md.
4. Move to worked examples and hands-on tutorials. Use examples/README.md, docs/tutorials/index.md, and tutorials/README.md.

Installation

COFOLDER requires Python 3.11 or 3.12.

Base install:

git clone https://github.com/CDDLeiden/COFOLDER.git
cd COFOLDER
python -m pip install -e .

Recommended analysis and prediction install with the default backend:

python -m pip install -e ".[analysis,boltz2]"

OpenFold3 install:

python -m pip install -e ".[analysis,openfold3]"
cofolder-tools setup-openfold3

The bias workflow does not require a co-folding backend. Install .[analysis] for its complete plotting artifact set and other optional analysis features.

Installed setup and data-preparation helpers are grouped under cofolder-tools. Run cofolder-tools --help to copy the bundled examples, prepare OpenFold3, install MMseqs2, or fetch/build bias-training data.

Common Commands

cofolder [-h] [-v] {bias,validate,screen,oracle}

Examples:

cofolder bias \
  --system_path system.yaml \
  --wrk_dir ./bias_out \
  --custom_protein_reference_path custom_protein.csv \
  --custom_ligand_reference_path custom_ligand.csv

cofolder validate \
  -s examples/system.yaml \
  -o examples/options.yaml \
  -w ./validate_out

cofolder screen \
  -s examples/system_screen.yaml \
  -o examples/options.yaml \
  -c examples/ligand_screen.csv \
  --col_id compound_id \
  --ligand_chain B --smiles_column smiles \
  -w ./screen_out

cofolder oracle \
  -s examples/system.yaml \
  -o examples/options.yaml \
  --input_smiles "CCO" \
  --output_metric system__confidence_score \
  --scoring_functions confidence_metrics \
  --aggregate first

For detailed setup, workflow selection, and command options, use:

• docs/getting-started/installation.md
• docs/getting-started/quickstart.md
• docs/user-guide/overview.md

For CLI-independent execution and backend integration, use the Python API flow references:

• Bias recipe
• Validate recipe
• Screen recipe
• Oracle recipe
• Constructing a new backend runner

Repository Guide

These top-level paths now have distinct roles:

• docs/: authoritative public documentation for installation, workflow selection, tutorials, and API reference
• examples/: copyable input files and small fixtures used by quickstarts and docs
• tutorials/: interactive notebook tutorials for hands-on exploration
• scripts/: helper utilities for optional setup and bias-data preparation
• LICENSE and THIRD_PARTY_SOFTWARE.md: repository licensing and third-party attribution

For a short tour of how these pieces fit together, see docs/getting-started/repository-tour.md.

Folder-Specific Notes

• examples/README.md explains which example files to use first.
• tutorials/README.md gives a recommended notebook order.
• scripts/README.md separates supported helpers from maintainer-oriented utilities.

Documentation

The MkDocs site is the best public-facing documentation surface. To build it locally:

python -m pip install -e ".[docs]"
mkdocs serve

The docs site complements, rather than replaces, the repository tutorials:

• docs/ is the curated reading path
• examples/ is the copy-and-run path
• tutorials/ is the interactive notebook path

Licenses

COFOLDER is released under the MIT License. Third-party attributions for adapted or bundled components are listed in THIRD_PARTY_SOFTWARE.md.

Citation metadata for COFOLDER 1.0.0 is provided in CITATION.cff. The publication and archival identifier will be added after those records are final.