OneScience-Group/Chainsaw

Chainsaw

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

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

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:

pip install -U huggingface_hub

hf download OneScience-Group/Chainsaw --local-dir ./Chainsaw
cd Chainsaw

Install the Runtime Environment

DCU Environment

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:

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

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

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:

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:

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

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

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:

input/structures/

Then run:

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

Using Another Official Model Version

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
• 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.