Skip to content

GUIDE.md

Latest commit

 

History

History
190 lines (124 loc) · 8.1 KB

GUIDE.md

File metadata and controls

190 lines (124 loc) · 8.1 KB
Raw

SeqStudio 使用手册（统一说明）

本文档为 唯一详细说明：安装、安装后补充项、数据文件、依赖与发布范围、两种注释流程与目录约定。根目录 README.md（English）与 README_zh.md（中文）提供项目展示、主图、分层环境配置摘要（Full setup / 完整环境配置）与快速命令；全部参数、路径与发布边界仍以本手册为准。

1. 项目结构与命名约定

路径 是什么 不是什么
seq_annotation/ Python 包：FASTA + PDB 批量注释；入口 python -m seq_annotation 不是独立脚本文件
seqstudio_pipeline/ Python 包：UniProt 风格 JSON.gz 管线；入口 python -m seqstudio_pipeline 根目录不再提供与之同名的 seqstudio_pipeline.py，避免「文件 vs 目录」混淆
utils/ 与 tools/ 两套管线共用的库代码 —
scripts/ Bash 封装（可选）：run_fasta_pdb_annotation.sh（调用 python -m seq_annotation）、run_uniprot_json_gz_shards.example.sh 核心逻辑仍在 Python 包内
data/ raw_data/ 含三份辅助 JSON（已提交）；datasets/ 为可选扁平输入说明 BLAST/Foldseek 等大库仍不放入 Git
examples/ 最小可跑通示例 —
docs/ 文档（本手册 + 结构说明） —

更简图示见 LAYOUT.md。

2. 安装

若你希望先建立整体心智模型，可对照根 README 中的 「完整环境配置」：A 机器资源 → B Python → C setup.sh → D 手工项 → E 数据；再回到本节逐步执行。

2.1 Conda 与 pip

conda env create -f environment.yml
conda activate bioanalysis
pip install -r requirements.txt

2.2 外部工具与数据库

bash setup.sh

完成后按终端提示配置 BLASTDB、FOLDSEEK_DB（若已写入 ~/.bashrc，新开 shell 或 source）。

3. 安装完成后必须自行补充（setup.sh 不做）

3.1 环境与变量（建议每次任务前）

source "$(conda info --base)/etc/profile.d/conda.sh"
conda activate bioanalysis
export JAVA_HOME=/path/to/jdk-11   # InterProScan 需要 Java 11
export PATH="$JAVA_HOME/bin:$PATH"
# export BLASTDB=...  export FOLDSEEK_DB=...  # 若 setup.sh 未写入 shell

3.2 TMHMM

将 tmhmm 放入 PATH，或通过命令行 --tmhmm_path 指定。注意许可证。

3.3 辅助 JSON（三条）

本开源仓库已自带于 data/raw_data/（合计约 145 MB，单文件均低于 GitHub 100 MB 限制），便于复现；也可自行从官方或 Hugging Face 数据集（SeqStudio） 下载更新版本覆盖，或通过参数覆盖路径：

文件 用途
all_pfam_descriptions.json Pfam 描述
go.json GO 定义
interpro_data.json InterPro 元数据

许可与再分发说明见 data/raw_data/README.md。

3.4 LLM API

export EXTERNAL_API_KEY="your-secret-key"
# 可选：EXTERNAL_API_URL、EXTERNAL_MODEL_NAME

禁止将密钥写入仓库或 shell 模板并提交。

3.5 输入数据

  • FASTA + PDB：见下文第 5 节。
  • UniProt JSON.gz：自备符合 seqstudio_pipeline/parsers.py 的 gzip JSON（results 数组等）。

3.6 可选：ijson

极大 JSON.gz 建议：pip install ijson。

3.7 自检

which python blastp foldseek tmhmm interproscan.sh 2>/dev/null || true
test -f data/raw_data/go.json && echo "go.json OK" || echo "缺少 go.json"

4. 本仓库发布范围与 GitHub 可上传内容

须自行安装/下载：InterProScan 解压目录、BLAST 索引、Foldseek 数据库、TMHMM、自有 UniProt JSON.gz 输入与 API 密钥等（三份辅助 JSON 已随仓库放在 data/raw_data/，无需再下载即可使用默认路径）。

适合上传 GitHub：seq_annotation/、seqstudio_pipeline/、utils/、tools/、scripts/、docs/、assets/、data/raw_data/*.json（约 145 MB）、setup.sh、environment.yml、requirements.txt、examples/、LICENSE 等。

勿上传：大体量数据库与压缩包、生产 output/、*.jsonl / 大 *.json.gz、密钥、个人绝对路径。

功能范围：本仓库提供可复现的注释管线代码（FASTA+PDB 与 UniProt JSON.gz 两条入口）。论文中的大规模评测、人机协同 triage、独立 Web 服务器等属于研究工作与工程部署范畴，不以本精简代码树为唯一载体；若后续单独发布服务或完整实验栈，将在项目主页与文档中说明。

5. FASTA + PDB 注释

5.1 命令

python -m seq_annotation --help
# 或
PROTEINS_ROOT=examples bash scripts/run_fasta_pdb_annotation.sh

5.2 每蛋白一子目录（推荐）

父目录下每个子目录 = 一个蛋白，内含 .fasta/.fa 与至少一个 .pdb。示例：examples/demo_protein/。

python -m seq_annotation --proteins_root examples --external_api_key "$EXTERNAL_API_KEY"

默认输出：output/seq_annotation/<父目录名>_annotated/。

5.3 扁平多数据集

在 data/datasets/<数据集名>/ 下按 相同 stem 放置 xxx.fasta 与 xxx.pdb，然后：

python -m seq_annotation --datasets MyBatch1

（未使用 --proteins_root 时，必须提供至少一个 --datasets。）

6. UniProt 风格 JSON.gz 注释

python -m seqstudio_pipeline \
  --input_json_gz /path/to/part0000.json.gz \
  --output_dir ./output/seqstudio_run1 \
  --temp_dir ./temp_run1 \
  --pdb_dir ./pdb_run1

多分片顺序跑：参考 scripts/run_uniprot_json_gz_shards.example.sh（脚本内已改为 python -m seqstudio_pipeline）。

7. 版本与可复现性

以 environment.yml 与 setup.sh 为准：Python 3.10、OpenJDK 11、InterProScan 5.75-106.0、BLAST 2.16.0 等。请在实际上传论文补充材料前，在本机执行 python --version、java -version、blastp -version、foldseek version 等并记录输出。

8. 发布到 GitHub

bash scripts/init_github_repo.sh
git remote add origin https://github.com/OpenRaiser/SeqStudio.git
git push -u origin main
git push origin "$(tr -d '[:space:]' < RELEASE_VERSION)"

若本树嵌在父 monorepo 且父级 .gitignore 全局忽略 data/，建议将本目录作为独立仓库根再推送。

9. 附录：工具、数据库与 data/ 体量（是否适合 GitHub）

以下为数量级参考（随 UniProt / InterPro 版本与是否含完整 Panther 数据等变化）；你本机实测可用 du -sh <目录>。

资源 典型体量 是否适合直接上传 GitHub
data/raw_data/（本仓库已提交三份 JSON） 约 145 MB（单文件 <100 MB） 已纳入开源内容；若后续单文件超过 GitHub 限制或希望减小 clone 体积，可改为 Git LFS 或外链，并更新 data/raw_data/README.md
blast_db/（SwissProt + 索引） 约 0.5–2 GB（示例约 699 MB） 不适合常规仓库；由 setup.sh 或用户自建
foldseek_db/（AlphaFold/Swiss-Prot 等） 常 数 GB–数十 GB（示例约 2.5 GB；压缩包常见 1–2 GB+） 不适合；用 foldseek databases 或 HF 预打包下载
interproscan/（解压后） 常 数 GB 以上（若含完整数据与缓存可达 数十 GB） 不适合；官方 tarball 约数百 MB–1 GB 级，亦建议外链下载
InterProScan 安装包 .tar.gz 约 400 MB–1 GB 不建议进主仓库；许可证与体积均不利
TMHMM 体积小（可执行文件级） 注意许可证，可文档说明由用户自行安装

结论：GitHub 仓库应只保留源码、小示例、安装脚本与文档；大型数据库与辅助 JSON 用外部存储（HF、机构网盘、对象存储）+ 文档中的下载与路径说明。若必须用 Git LFS，需单独预算 LFS 配额与克隆体验。