README.md

---
frameworks:
- PyTorch
language:
- en
license: mit
tags:
- OneScience
- bioscience
- protein-domain-prediction
- protein-structure-analysis
- Chainsaw
tasks: []
datasets: []
---

<p align="center">
  <strong>
    <span style="font-size: 30px;">Chainsaw</span>
  </strong>
</p>

# Model Introduction

Chainsaw is a fully convolutional neural network designed to predict protein domain boundaries from three-dimensional protein structures. The model extracts residue-distance features and STRIDE secondary-structure features from PDB or mmCIF structures, predicts the probability that residue pairs belong to the same structural domain, and then applies post-processing to generate the final domain segmentation.

Paper: [Chainsaw: protein domain segmentation with fully convolutional neural networks](https://doi.org/10.1093/bioinformatics/btae296)

# Model Description

Chainsaw takes a three-dimensional protein structure as input rather than an amino acid sequence alone. Its main processing pipeline is as follows:

1. Parse the specified protein chain and generate a residue-distance matrix;
2. Run STRIDE to calculate secondary-structure features;
3. Use a fully convolutional neural network to predict residue-pair domain co-membership;
4. Convert the predicted matrix into continuous or discontinuous domain boundaries and output confidence scores.

The model package includes three versions of the official pretrained weights, with `model_v3` used by default. Basic inference does not require downloading additional weights or retraining the model.

# Use Cases

| Use Case | Description |
| :---: | :--- |
| Single-structure prediction | Segment a protein chain from a PDB or mmCIF file into structural domains. |
| Batch structure prediction | Process multiple PDB or mmCIF structure files in a directory. |
| AlphaFold structure analysis | Identify domain boundaries in AlphaFold-predicted structures. |
| Domain boundary screening | Output the number of domains, residue ranges, confidence scores, and runtime for downstream analysis. |

# 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**

- Supports inference on both CPU and DCU;
- STRIDE, structure parsing, and part of the post-processing pipeline are executed on CPU.

### 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/Chainsaw --local-dir ./Chainsaw
cd Chainsaw
```

### Install the Runtime Environment

**DCU Environment**

```bash
conda create -n onescience311 python=3.11 -y
conda activate onescience311

pip install onescience[bio-dcu] \
  -i http://mirrors.onescience.ai:3141/pypi/simple/ \
  --trusted-host mirrors.onescience.ai
```

### Compile STRIDE

Chainsaw relies on STRIDE to generate secondary-structure features. The STRIDE source code is located in `scripts/stride/`. Before the first run, execute:

```bash
cd scripts/stride
make
chmod +x stride
cd ../..
```

By default, the inference script looks for the STRIDE executable at:

```text
scripts/stride/stride
```

When running commands from the root directory of the Hugging Face model package, no additional path configuration is required.

If you need to specify the STRIDE executable explicitly, use:

```bash
export STRIDE_EXE=scripts/stride/stride
```

### Weights and Data Preparation

The Hugging Face model package already contains the official weights and configuration files required for basic inference. No additional model weights need to be downloaded at runtime.

| Model Version | Weights | Configuration |
| --- | --- | --- |
| model_v1 | `weight/model_v1/weights.pt` | `conf/model_v1/` |
| model_v2 | `weight/model_v2/weights.pt` | `conf/model_v2/` |
| model_v3 (default) | `weight/model_v3/weights.pt` | `conf/model_v3/` |

Input structures must be provided by the user. Both PDB and mmCIF files are supported.

The example files included in:

```text
scripts/example_files/
```

can be used for basic validation without downloading any training dataset.

### Quick Inference

All commands below should be executed from the root directory of the downloaded Hugging Face model package.

If the output directory does not exist, the inference script will create it automatically.

**DCU Inference**

```bash
unset CUDA_VISIBLE_DEVICES
export TORCHDYNAMO_DISABLE=1

python scripts/get_predictions.py \
  --structure_file scripts/example_files/AF-A0A1W2PQ64-F1-model_v4.pdb \
  --output output/inference/predictions_dcu.tsv
```

**CPU Inference**

```bash
export CUDA_VISIBLE_DEVICES=""
export TORCHDYNAMO_DISABLE=1

python scripts/get_predictions.py \
  --structure_file scripts/example_files/AF-A0A1W2PQ64-F1-model_v4.pdb \
  --output output/inference/predictions_cpu.tsv
```

**Batch Processing of Structure Files**

Place the structures to be predicted in:

```text
input/structures/
```

Then run:

```bash
python scripts/get_predictions.py \
  --structure_directory input/structures \
  --output output/inference/batch_predictions.tsv
```

**Using Another Official Model Version**

```bash
python scripts/get_predictions.py \
  --model_dir weight/model_v1 \
  --config_dir conf/model_v1 \
  --structure_file input/protein.pdb \
  --output output/inference/model_v1_predictions.tsv
```

### Output

The inference result is saved as a TSV file, with one row corresponding to each input structure chain.

| Field | Description |
| --- | --- |
| `chain_id` | Identifier of the input protein chain. If no chain is explicitly specified, the first available chain is used. |
| `sequence_md5` | MD5 hash of the input amino acid sequence. |
| `nres` | Number of valid residues. |
| `ndom` | Number of predicted structural domains. |
| `chopping` | Predicted domain residue ranges. Underscores connect fragments belonging to the same discontinuous domain, while commas separate different domains. |
| `confidence` | Prediction confidence score. |
| `time_sec` | Inference time for a single structure, in seconds. |

### Training

The upstream repository does not publicly provide the complete training dataset, an executable end-to-end training entry point, or the full set of training hyperparameters such as learning rate, batch size, and number of epochs.

Therefore, this Hugging Face model package does not provide a training command.

The official pretrained weights included in the package can be used directly for the intended inference tasks.

# 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: [Chainsaw: protein domain segmentation with fully convolutional neural networks](https://doi.org/10.1093/bioinformatics/btae296)
- Official implementation: https://github.com/JudeWells/chainsaw
- Chainsaw is distributed under the MIT License.
- STRIDE and other third-party components are subject to their respective original copyright notices, licenses, and terms of use.