|
Download README.md from OneScience-Group/CombFold: direct link, hf CLI and curl.
- Browser
- Download file 13.2 kB
-
https://huggingface.co/OneScience-Group/CombFold/resolve/main/README.md
- Command line
-
hf download hf://OneScience-Group/CombFold/README.md
-
curl -L -o README.md https://huggingface.co/OneScience-Group/CombFold/resolve/main/README.md
13.2 kB
| frameworks: | |
| - JAX | |
| language: | |
| - en | |
| license: apache-2.0 | |
| tags: | |
| - OneScience | |
| - bioscience | |
| - protein-complex-structure-prediction | |
| - CombFold | |
| - AlphaFold-Multimer | |
| - ColabFold | |
| tasks: [] | |
| datasets: [] | |
| <p align="center"> | |
| <strong> | |
| <span style="font-size: 30px;">CombFold</span> | |
| </strong> | |
| </p> | |
| # Model Introduction | |
| CombFold is an open-source pipeline developed by dina-lab3D for predicting the structures of large protein complexes. Starting from the amino acid sequences of the individual chains in a complex, CombFold uses AlphaFold-Multimer to predict multiple candidate subcomplexes and then applies combinatorial assembly algorithms to construct the complete protein complex. | |
| The original publication reports support for complexes containing at least 18,000 amino acids and up to 32 subunits. | |
| Paper: [Assembly of protein complexes by combining AlphaFold and combinatorial optimization](https://www.nature.com/articles/s41592-024-02174-0) | |
| # Model Description | |
| CombFold consists of four main stages: | |
| 1. Define subunits according to protein domains and chain composition and generate `subunits.json`; | |
| 2. Generate FASTA files for all subunit pairs and predict pairwise subcomplexes using AlphaFold-Multimer; | |
| 3. Optionally predict candidate subcomplexes containing more than two subunits; | |
| 4. Extract relative transformations between subunits from the predicted PDB structures and use a C++ combinatorial optimization algorithm to assemble the complete complex. | |
| The main components included in the Hugging Face model package are: | |
| - `model/CombinatorialAssembler/`: C++17 combinatorial assembler and the `AF2trans` structural transformation tool; | |
| - `scripts/prepare_fastas.py`: generates FASTA files for pairwise or larger subunit combinations; | |
| - `scripts/inference.py`: unified assembly entry point for the Hugging Face model package; | |
| - `scripts/run_on_pdbs.py`: original upstream entry point for assembly from predicted PDB structures; | |
| - `weight/`: official pretrained AlphaFold-Multimer parameters used for offline ColabFold inference; | |
| - `requirements.txt`: additional dependencies required on top of the OneScience base environment. | |
| CombFold itself is not a trainable neural network. Neural-network inference is performed by pretrained AlphaFold-Multimer models, while CombFold is responsible for extracting structural transformations and performing combinatorial assembly. | |
| # Use Cases | |
| | Use Case | Description | | |
| | :---: | :--- | | |
| | Large protein complex prediction | Combine multiple AlphaFold-Multimer subcomplex predictions into a complete complex structure. | | |
| | Homomer prediction | Assemble complexes containing multiple copies of the same unique subunit according to the specified stoichiometry. | | |
| | Heteromer prediction | Integrate predictions from different subunit pairs or groups to construct the complete structure. | | |
| | Assembly from existing AFM results | Directly use existing AlphaFold-Multimer PDB predictions without rerunning AlphaFold-Multimer. | | |
| | Crosslink-guided assembly | Optionally incorporate crosslinking restraints to constrain candidate complex structures. | | |
| # Usage | |
| ## 1. OneCode | |
| You can use the OneCode online environment for an intelligent one-click AI4S programming experience: | |
| [Try OneCode for AI4S Programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home) | |
| ## 2. Manual Installation | |
| **Hardware Requirements** | |
| - The CombFold C++ combinatorial assembly stage requires only CPU resources; | |
| - Local AlphaFold-Multimer subcomplex prediction typically requires an accelerator; | |
| - Memory usage for long-sequence and multi-model inference increases with the total number of residues, MSA depth, number of models, and number of recycles; | |
| - PyTorch is not a direct runtime dependency of CombFold or the current ColabFold inference pipeline. | |
| ### Download the Model Package | |
| Install the Hugging Face command-line tool and download the model repository: | |
| ```bash | |
| pip install -U huggingface_hub | |
| hf download OneScience-Group/CombFold --local-dir ./CombFold | |
| cd CombFold | |
| ``` | |
| ### Install the Runtime Environment | |
| **OneScience DCU Base Environment** | |
| ```bash | |
| conda create -n onescience311 python=3.11 -y | |
| conda activate onescience311 | |
| python -m pip install onescience[bio-dcu] \ | |
| -i http://mirrors.onescience.ai:3141/pypi/simple/ \ | |
| --trusted-host mirrors.onescience.ai | |
| ``` | |
| Install the additional dependencies: | |
| ```bash | |
| python -m pip install --no-deps -r requirements.txt | |
| ``` | |
| ### Compile the Combinatorial Assembler | |
| The combinatorial assembly stage of CombFold is implemented in C++17 and requires the following system-level components. These components cannot be installed through `requirements.txt`. | |
| | Component | Purpose | Description | | |
| | --- | --- | --- | | |
| | C++17 compiler | Compile the C++ source code | `g++` is commonly used on Linux | | |
| | GNU Make | Execute the Makefile | GNU Make 4.2.1 has been validated | | |
| | Boost headers | Compile-time headers | The directory must contain `boost/algorithm/string.hpp` | | |
| | Boost program_options | Link-time runtime library | Usually provided as `libboost_program_options.so` on Linux | | |
| Boost headers are generally portable across Linux distributions, but compiled Boost libraries depend on the operating system, CPU architecture, compiler, and `libstdc++` ABI. Therefore, compiled Boost libraries should not be copied directly between Linux, macOS, Windows, or different CPU architectures. | |
| It is recommended to use Boost headers and runtime libraries from the same Boost version. | |
| The upstream Makefile is configured primarily for macOS Homebrew. On Linux, the following command can be used directly only when Boost is already available in the compiler's default search paths: | |
| ```bash | |
| cd model/CombinatorialAssembler | |
| make | |
| cd ../.. | |
| ``` | |
| #### Specify a Custom Boost Path | |
| If Boost is not installed in the default compiler search paths, define the following environment variables: | |
| ```bash | |
| export COMBFOLD_BOOST_INCLUDE="<Boost source or include directory>" | |
| export COMBFOLD_BOOST_LIB="<Boost library directory>" | |
| ``` | |
| `COMBFOLD_BOOST_INCLUDE` must point to a directory that directly contains the `boost/` subdirectory. | |
| `COMBFOLD_BOOST_LIB` must point to a directory that directly contains the `libboost_program_options` library. | |
| Before compilation, you can verify the paths using: | |
| ```bash | |
| test -f "${COMBFOLD_BOOST_INCLUDE}/boost/algorithm/string.hpp" \ | |
| && echo "Boost headers OK" | |
| find "${COMBFOLD_BOOST_LIB}" -maxdepth 1 \ | |
| -name 'libboost_program_options*' -print | |
| ``` | |
| Compile the assembler: | |
| ```bash | |
| cd model/CombinatorialAssembler | |
| make -j4 \ | |
| BOOST_INCLUDE="${COMBFOLD_BOOST_INCLUDE}" \ | |
| BOOST_LIB="${COMBFOLD_BOOST_LIB}" | |
| cd ../.. | |
| ``` | |
| ### Weights and Data Preparation | |
| The CombFold combinatorial assembler itself does not require model weights. | |
| Local generation of AlphaFold-Multimer subcomplex predictions requires the five official AlphaFold-Multimer v3 parameter files: | |
| | Asset | Location in the Model Package | Purpose | | |
| | --- | --- | --- | | |
| | `params_model_1_multimer_v3.npz` | `weight/alphafold/params/` | AFM v3 model 1 | | |
| | `params_model_2_multimer_v3.npz` | `weight/alphafold/params/` | AFM v3 model 2 | | |
| | `params_model_3_multimer_v3.npz` | `weight/alphafold/params/` | AFM v3 model 3 | | |
| | `params_model_4_multimer_v3.npz` | `weight/alphafold/params/` | AFM v3 model 4 | | |
| | `params_model_5_multimer_v3.npz` | `weight/alphafold/params/` | AFM v3 model 5 | | |
| Use the following ColabFold data path: | |
| ```text | |
| --data weight/alphafold | |
| ``` | |
| If you only use existing AlphaFold-Multimer PDB predictions for combinatorial assembly, AlphaFold-Multimer weights and a DCU device are not required. | |
| ### Define Subunits | |
| The input `subunits.json` is a JSON dictionary keyed by unique subunit names. | |
| Each subunit contains the following fields: | |
| - `name`: unique subunit name; | |
| - `sequence`: amino acid sequence; | |
| - `chain_names`: chain names corresponding to this subunit in the complete complex. The number of entries also defines its stoichiometry; | |
| - `start_res`: starting residue index of the sequence in the original chain. | |
| Example: | |
| ```json | |
| { | |
| "A0": { | |
| "name": "A0", | |
| "chain_names": ["A", "B"], | |
| "start_res": 1, | |
| "sequence": "MKDILEKLEERRAQARLGGGEKRLEAQHKRGKLTARERIELLLDHGSFEE" | |
| } | |
| } | |
| ``` | |
| The Hugging Face model package provides a complete example: | |
| ```text | |
| scripts/example/subunits.json | |
| scripts/example/pdbs/ | |
| ``` | |
| ### Quick Inference: CPU Assembly from Existing PDB Files | |
| This is the shortest CombFold inference path and does not run AlphaFold-Multimer: | |
| ```bash | |
| python scripts/inference.py \ | |
| --subunits scripts/example/subunits.json \ | |
| --pdbs scripts/example/pdbs \ | |
| --output output/example_assembly | |
| ``` | |
| The output directory must either not exist or be empty before execution. | |
| After successful execution, the main results are located at: | |
| ```text | |
| output/example_assembly/assembled_results/output_clustered_0.pdb | |
| output/example_assembly/assembled_results/confidence.txt | |
| ``` | |
| You can also use the original upstream positional-argument entry point: | |
| ```bash | |
| python scripts/run_on_pdbs.py \ | |
| scripts/example/subunits.json \ | |
| scripts/example/pdbs \ | |
| output/example_assembly | |
| ``` | |
| ### Generate Pairwise FASTA Files | |
| Generate FASTA files for every pair of unique subunits defined in `subunits.json`: | |
| ```bash | |
| python scripts/prepare_fastas.py \ | |
| scripts/example/subunits.json \ | |
| --stage pairs \ | |
| --output-fasta-folder output/pair_fastas \ | |
| --max-af-size 1800 | |
| ``` | |
| The output directory must not already exist. | |
| The official example generates files such as: | |
| ```text | |
| A0_A0.fasta | |
| A0_G0.fasta | |
| G0_G0.fasta | |
| ``` | |
| ### Minimal DCU Pairwise Inference | |
| For an offline smoke test on a compute node, you can use `single_sequence`, one model, and one recycle: | |
| ```bash | |
| colabfold_batch \ | |
| output/pair_fastas \ | |
| output/colabfold_pairs \ | |
| --data weight/alphafold \ | |
| --model-type alphafold2_multimer_v3 \ | |
| --model-order 1 \ | |
| --num-models 1 \ | |
| --num-recycle 1 \ | |
| --num-relax 0 \ | |
| --msa-mode single_sequence \ | |
| --disable-unified-memory | |
| ``` | |
| The configuration: | |
| ```text | |
| single_sequence + 1 model + 1 recycle | |
| ``` | |
| is intended only to verify parameter loading, JAX/DCU forward execution, and PDB output generation. | |
| It should not be used to evaluate formal prediction accuracy. | |
| For production-quality predictions, prepare appropriate MSA features and increase the number of models and recycles according to available memory and runtime constraints. | |
| ### End-to-End DCU-to-CPU Inference | |
| At least one predicted PDB structure must be selected for each pair. | |
| To select the top-ranked ColabFold structure: | |
| ```bash | |
| mkdir -p output/combfold_pdbs | |
| find output/colabfold_pairs -maxdepth 1 \ | |
| -type f -name '*rank_001*.pdb' \ | |
| -exec cp {} output/combfold_pdbs/ \; | |
| ``` | |
| Then run the CombFold combinatorial assembly stage: | |
| ```bash | |
| python scripts/inference.py \ | |
| --subunits scripts/example/subunits.json \ | |
| --pdbs output/combfold_pdbs \ | |
| --output output/end2end_assembly | |
| ``` | |
| The unified inference entry point also outputs a machine-readable summary, for example: | |
| ```text | |
| COMBFOLD_INFERENCE_RESULT={"assembled_structures": 5, "format": "pdb", "status": "PASS", ...} | |
| ``` | |
| ### Use Crosslinking Restraints | |
| Use the `--crosslinks` option to provide a crosslink restraint file: | |
| ```bash | |
| python scripts/inference.py \ | |
| --subunits scripts/example/example_xlinks/subunits.json \ | |
| --pdbs scripts/example/example_xlinks/pdbs \ | |
| --crosslinks scripts/example/example_xlinks/crosslinks.txt \ | |
| --output output/crosslink_assembly | |
| ``` | |
| ### Optional Prediction of Larger Subcomplexes | |
| After completing pairwise prediction, larger subcomplex FASTA files can be generated based on the pairwise results: | |
| ```bash | |
| python scripts/prepare_fastas.py \ | |
| scripts/example/subunits.json \ | |
| --stage groups \ | |
| --output-fasta-folder output/group_fastas \ | |
| --max-af-size 1800 \ | |
| --input-pairs-results output/combfold_pdbs | |
| ``` | |
| ### Training | |
| CombFold is an inference algorithm that performs combinatorial assembly using predictions generated by pretrained AlphaFold-Multimer models. | |
| CombFold itself does not contain a trainable neural network, training entry point, optimizer, or training-data pipeline. Therefore, this Hugging Face model package does not provide training commands. | |
| Retraining AlphaFold-Multimer is a separate upstream large-scale model-training task and is not part of the CombFold combinatorial assembly workflow. | |
| # OneScience Official Resources | |
| | Platform | OneScience Main Repository | Skills Repository | | |
| | --- | --- | --- | | |
| | Gitee | https://gitee.com/onescience-ai/onescience | https://gitee.com/onescience-ai/oneskills | | |
| | GitHub | https://github.com/onescience-ai/OneScience | https://github.com/onescience-ai/oneskills | | |
| # Citation and License | |
| - Paper: [Assembly of protein complexes by combining AlphaFold and combinatorial optimization](https://www.nature.com/articles/s41592-024-02174-0) | |
| - Official implementation: https://github.com/dina-lab3D/CombFold | |
| - The CombFold source code is provided under the Apache License 2.0 according to the upstream repository. | |
| - AlphaFold, AlphaFold-Multimer, ColabFold, pretrained parameters, and other third-party components are subject to their respective original copyright notices, model terms, and licenses. |