Metadata-Version: 2.4
Name: cofolder
Version: 1.0.0
Summary: Collection of helpful tools for performing various co-folding tasks using cofolding models (e.g. Boltz.)
Author-email: "Remco L. van den Broek" <r.l.van.den.broek@lacdr.leidenuniv.nl>, Bola Khalil <b.a.a.khalil@lacdr.leidenuniv.nl>
License-Expression: MIT
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_SOFTWARE.md
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pyyaml
Requires-Dist: biopython
Requires-Dist: rdkit
Requires-Dist: gemmi
Requires-Dist: packaging
Provides-Extra: analysis
Requires-Dist: scipy; extra == "analysis"
Requires-Dist: scikit-learn; extra == "analysis"
Requires-Dist: prolif; extra == "analysis"
Requires-Dist: pdb2pqr; extra == "analysis"
Requires-Dist: matplotlib; extra == "analysis"
Requires-Dist: seaborn; extra == "analysis"
Provides-Extra: boltz1
Requires-Dist: boltz==1.0.0; extra == "boltz1"
Provides-Extra: boltz2
Requires-Dist: boltz[cuda]<3,>=2.0.0; extra == "boltz2"
Provides-Extra: boltz-community
Requires-Dist: boltz-community[cuda]==2.10.12; extra == "boltz-community"
Provides-Extra: openfold3
Requires-Dist: openfold3; extra == "openfold3"
Provides-Extra: acceptance
Requires-Dist: marimo<0.24,>=0.23; extra == "acceptance"
Provides-Extra: tutorials
Requires-Dist: marimo<0.24,>=0.23; extra == "tutorials"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Provides-Extra: development
Requires-Dist: black>=23.0.0; extra == "development"
Requires-Dist: build>=1.2.0; extra == "development"
Requires-Dist: ruff>=0.1.0; extra == "development"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Requires-Dist: mkdocs-autorefs>=0.5.0; extra == "docs"
Requires-Dist: black>=23.0.0; extra == "docs"
Requires-Dist: ruff>=0.1.0; extra == "docs"
Dynamic: license-file

# 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](docs/getting-started/installation.md).
2. Run your first command.
   See [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md).
3. Pick the workflow that matches your task.
   See [docs/user-guide/overview.md](docs/user-guide/overview.md).
4. Move to worked examples and hands-on tutorials.
   Use [examples/README.md](examples/README.md), [docs/tutorials/index.md](docs/tutorials/index.md), and [tutorials/README.md](tutorials/README.md).

## Installation

COFOLDER requires Python 3.11 or 3.12.

Base install:

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

Recommended analysis and prediction install with the default backend:

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

OpenFold3 install:

```bash
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

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

Examples:

```bash
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/installation.md)
- [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md)
- [docs/user-guide/overview.md](docs/user-guide/overview.md)

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

- [Bias recipe](docs/reference/python-api/bias-recipe-flow.md)
- [Validate recipe](docs/reference/python-api/validate-recipe-flow.md)
- [Screen recipe](docs/reference/python-api/screen-recipe-flow.md)
- [Oracle recipe](docs/reference/python-api/oracle-recipe-flow.md)
- [Constructing a new backend runner](docs/reference/python-api/new-backend-runner.md)

## Repository Guide

These top-level paths now have distinct roles:

- [`docs/`](docs/): authoritative public documentation for installation, workflow selection, tutorials, and API reference
- [`examples/`](examples/): copyable input files and small fixtures used by quickstarts and docs
- [`tutorials/`](tutorials/): interactive notebook tutorials for hands-on exploration
- [`scripts/`](scripts/): helper utilities for optional setup and bias-data preparation
- [`LICENSE`](LICENSE) and [`THIRD_PARTY_SOFTWARE.md`](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](docs/getting-started/repository-tour.md).

## Folder-Specific Notes

- [examples/README.md](examples/README.md) explains which example files to use first.
- [tutorials/README.md](tutorials/README.md) gives a recommended notebook order.
- [scripts/README.md](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:

```bash
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](THIRD_PARTY_SOFTWARE.md).

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