如何使用Stoic模型：从安装到预测的完整生物信息学指南

如何使用Stoic模型：从安装到预测的完整生物信息学指南

【免费下载链接】stoic 项目地址: https://ai.gitcode.com/hf_mirrors/PickyBinders/stoic

Stoic是一款强大的蛋白质化学计量预测工具，能够直接从序列预测蛋白质复合物组件的拷贝数，并可基于预测的化学计量导出AF3-ready JSON文件。本文将为生物信息学新手提供从安装到预测的完整指南，帮助您快速掌握Stoic模型的使用方法。

1. 准备工作：环境搭建

1.1 创建并激活虚拟环境

使用venv

python -m venv .venv
source .venv/bin/activate

使用conda/mamba

mamba create -n stoic-env python=3.10 -y
mamba activate stoic-env

1.2 安装Stoic模型

从本地克隆安装（可编辑模式）

git clone https://gitcode.com/hf_mirrors/PickyBinders/stoic
cd stoic
python -m pip install --upgrade pip
python -m pip install -e .

直接从GitHub安装

python -m pip install git+https://gitcode.com/hf_mirrors/PickyBinders/stoic.git

注意：首次推理运行需要互联网连接，以便从Hugging Face下载模型权重。后续运行将重用~/.cache/huggingface中的缓存文件，因此模型缓存后可离线使用。

2. 使用命令行预测蛋白质化学计量

stoic_predict_stoichiometry命令支持三种输入方式：序列列表、单个FASTA文件或FASTA文件目录（每个FASTA文件视为一个单独的复合物）。

2.1 基本命令参数

usage: stoic_predict_stoichiometry [-h]
                                   [--sequences SEQ [SEQ ...] | --input-path INPUT_PATH]
                                   [--model MODEL]
                                   [--top-n TOP_N]
                                   [--return-residue-weights]
                                   [--max-inference-seq-len MAX_INFERENCE_SEQ_LEN]
                                   [--output-dir OUTPUT_DIR]
                                   [--device DEVICE]

2.2 不同输入方式的使用示例

序列列表输入

stoic_predict_stoichiometry \
  --sequences "SENECA" "VIRTVS" \
  --top-n 3

单个FASTA文件输入

stoic_predict_stoichiometry \
  --input-path path/to/complex.fasta \
  --top-n 3

FASTA文件目录输入

stoic_predict_stoichiometry \
  --input-path path/to/fasta_dir \
  --top-n 3 \
  --output-dir stoic_predictions

在目录模式下，输出将按复合物保存（<fasta_stem>.json、<fasta_stem>_af3_input.json以及可选的残基预测）。

2.3 输出文件说明

当提供--output-dir参数时：

• 单个输入（序列列表或单个FASTA）：

  • results.json
  • af3_input.json
  • residue_predictions.pkl（如果使用--return-residue-weights）

• FASTA目录输入：

  • <complex_name>.json
  • <complex_name>_af3_input.json
  • <complex_name>_residue_predictions.pkl（如果使用--return-residue-weights）

3. 使用Python API进行预测

3.1 高级推理助手

from stoic.predict_stoichiometry import predict_stoichiometry

results = predict_stoichiometry(
    sequences=["SENECA", "VIRTVS"],  # 或FASTA路径/FASTA目录路径
    model_name="PickyBinders/stoic",
    top_n=3,
)
print(results)

3.2 直接从Hugging Face加载模型

import torch
from stoic.model import Stoic


device = "cuda" if torch.cuda.is_available() else "cpu"
model = Stoic.from_pretrained("PickyBinders/stoic")
model.eval().to(device)
pred = model.predict_stoichiometry(["SENECA", "VIRTVS"], top_n=3)
print(pred)

4. 模型配置说明

Stoic模型的配置文件config.json包含了多种可调整的参数，例如：

• seq_embed_model_name: 使用的序列嵌入模型，默认为"facebook/esm2_t33_650M_UR50D"
• max_seq_len: 最大序列长度，默认为514
• stoichiometry_classes_to_use: 支持的化学计量类别
• load_in_4bit: 是否使用4位量化加载模型，默认为true

通过修改这些参数，可以根据具体需求调整模型的性能和行为。

5. 引用Stoic

如果您在研究中使用了Stoic，请引用以下文献：

@article{litvinov2026stoic,
  title   = {Stoic: Fast and accurate protein stoichiometry prediction},
  author  = {Litvinov, Daniil and Pantolini, Lorenzo and {\v{S}}krinjar, Peter and Tauriello, Gerardo and McCafferty, Caitlyn L and Engel, Benjamin D and Schwede, Torsten and Durairaj, Janani},
  journal = {bioRxiv},
  year    = {2026},
  doi     = {10.64898/2026.03.13.711535},
  url     = {https://www.biorxiv.org/content/10.64898/2026.03.13.711535v1}
}

通过本指南，您应该已经掌握了Stoic模型的基本安装和使用方法。无论是通过命令行还是Python API，Stoic都能为您的生物信息学研究提供快速准确的蛋白质化学计量预测支持。

【免费下载链接】stoic 项目地址: https://ai.gitcode.com/hf_mirrors/PickyBinders/stoic