Skip to content

README.md

Latest commit

 

History

History
429 lines (332 loc) · 15.9 KB

README.md

File metadata and controls

429 lines (332 loc) · 15.9 KB
Raw

OpenRare Pipeline — 罕见病变异注释与宽表输出全流程

从患者 VCF 出发，串联 Beagle phasing、VCF 前置处理、假基因注释、VEP 多插件注释、INFO 回填、GENOS-VarRisk 注释与 HLA 过滤，一键产出可解读的宽表 CSV；支持命令行与 FastAPI 两种调用方式。

目录

安装与快速开始

环境要求

项目 要求
操作系统 Linux x86_64
Pixi 用于安装运行环境（推荐）
Python ≥ 3.11（pixi 自动提供）
Java ≥ 17（pixi 提供 openjdk，供 Beagle 使用）
磁盘 VEP cache + 注释库较大，建议预留数十 GB（见 vep_runner README）

Pixi 环境包含：ensembl-vep 115.x、bcftools、openjdk、fastapi、uvicorn 等（见本目录 pixi.toml）。

1. 克隆并安装依赖

cd /path/to/OpenRare/modules/pipeline
pixi install

2. 配置外部数据路径

大型数据库（VEP cache、CADD、phasing 参考等）不随仓库提交，通过本目录 .env 配置：

cp .env.example .env
# 编辑 .env，至少填写以下四项：
#   OPENRARE_DATA_ROOT
#   OPENRARE_PUBLIC_DATA_ROOT
#   FULL_PIPELINE_REF_DIR
#   FULL_PIPELINE_BEAGLE_JAR

pixi run、Shell 脚本与 Python 会自动加载 .env；shell 中已 export 的变量不会被覆盖。

3.（可选）安装 VEP 插件

若 OPENRARE_DATA_ROOT 下尚无插件 .pm / LoFTEE：

pixi run vep-setup-plugins          # 下载插件 Perl 模块 + LoFTEE
pixi run vep-verify-plugins         # 校验数据文件与 tabix 索引

安装目标目录取决于 .env 中的 OPENRARE_DATA_ROOT，详见 modules/vep_runner/README.md。

4. 一键回归测试

pixi run pipeline-test    # P001 样本、chr1、约 2 分钟量级（视机器而定）

成功标志：生成 tmp/openrare_pipeline_test/07_hla_filter/vep_output.no_hla.csv（默认 hla_filter=yes）。

常用 Pixi Task

Task 说明
pixi run vep-dry-run 打印 VEP 命令（含插件），不实际运行
pixi run vep-setup-plugins 安装 VEP 插件 .pm + LoFTEE（可选 cache）
pixi run vep-verify-plugins 校验插件数据与索引
pixi run pipeline-test P001 + chr1 全流程回归
pixi run api 启动 FastAPI（默认 127.0.0.1:18901）
pixi run api-test 测试 /health、/run、/run-upload
pixi run mock-smoke-test mock 库 + 全开关 dry-run 连通性
pixi run hla-filter-test HLA 区域行过滤单测

使用示例

命令行：最小调用

cd /path/to/OpenRare/modules/pipeline
pixi run bash scripts/run_full_pipeline.sh \
  --input-vcf /path/to/patient.vcf.gz \
  --out-dir /path/to/output \
  --fork 4

带患者 HPO（影响 HPO → 组织 → GTEx 加权的转录本选择）：

pixi run bash scripts/run_full_pipeline.sh \
  --input-vcf /path/to/patient.vcf.gz \
  --out-dir /path/to/output \
  --fork 4 \
  --hpo-id HP:0001250

命令行：预期输出片段

流程结束后终端会打印各步产物路径，并生成汇总文件：

step                          path
original_input_vcf            /path/to/patient.vcf.gz
...
vep_csv                       /path/to/output/07_hla_filter/vep_output.no_hla.csv
full_log                      /path/to/output/logs/full_pipeline.log

最终 CSV 表头示例（列较多，此处仅示意）：

#CHROM,POS,REF,ALT,...,Gene,Consequence,CLIN_SIG,...,GENOS-VarRisk,...
chr1,1197557,G,A,...,TTLL10,missense_variant,...,0.42,...

启动 API 服务

pixi run api
# 或指定端口：FULL_PIPELINE_API_PORT=18901 pixi run api

健康检查：

curl -s http://127.0.0.1:18901/health | python3 -m json.tool

API：JSON 提交任务

curl -s -X POST http://127.0.0.1:18901/run \
  -H 'Content-Type: application/json' \
  -d '{
    "input_vcf": "/path/to/patient.vcf.gz",
    "output_dir": "/path/to/output",
    "fork": 4,
    "hpo_id": "HP:0001250"
  }'

API：上传 VCF

curl -s -X POST http://127.0.0.1:18901/run-upload \
  -F 'input_vcf=@/path/to/patient.vcf.gz' \
  -F 'fork=4' \
  -F 'chromosomes=1'

查询任务状态与日志：

curl -s http://127.0.0.1:18901/jobs/<job_id>
curl -s http://127.0.0.1:18901/jobs/<job_id>/log

API 文档

默认地址：http://127.0.0.1:18901（FULL_PIPELINE_API_PORT，默认 18901）。

端点一览

方法 路径 说明
GET /health 服务状态、默认资源路径、队列信息
POST /run JSON 提交任务；input_vcf 为服务器上的路径
POST /run-upload multipart 上传 VCF 并提交任务
GET /queue 查看 FIFO 队列
GET /jobs/{job_id} 查询任务状态、命令、输出目录
GET /jobs/{job_id}/files 列出任务输出目录中的文件
GET /jobs/{job_id}/files/{path} 下载指定输出文件
GET /jobs/{job_id}/log 查看任务运行日志
GET /jobs/{job_id}/api-log/download 下载 API 运行日志

POST /run 请求体（RunRequest）

字段 类型 必填 默认值 说明
input_vcf string 是 — 输入 VCF/VCF.GZ 路径
output_dir string 否 api_jobs/<job_id>/output 流水线输出目录
fork int 否 1 VEP --fork
hpo_id string 否 "" HPO ID，逗号分隔多个
phasing string 否 yes 是否运行 Beagle phasing
vaf string 否 yes 是否计算 VAF/REF_DP/ALT_DP
regulatory_annotation string 否 yes 是否运行 cCRE 调控区注释
ncrna_annotation string 否 yes 是否运行 ncRNA 注释
pseudogene_annotation string 否 yes 是否运行假基因注释
hla_filter string 否 yes 是否从最终宽表删除 HLA/MHC 区行
input_assembly string 否 auto auto / GRCh37 / GRCh38
sample_id string 否 自动 样本名
chromosomes string 否 1-22 染色体范围，如 1、1,3,5
ref_dir string 否 .env Beagle CHN 参考 panel
beagle_jar string 否 .env Beagle JAR 路径
keep_raw_vep bool 否 保留 true/false
dry_run bool 否 false 仅打印命令不执行

完整高级字段与命令行参数一一对应，见 命令行参数 与 complete_pipeline/README.md。

POST /run 响应（RunResponse）

字段 类型 说明
job_id string 任务 ID
status string 初始为 queued，随后 running / succeeded / failed
status_url string 状态查询路径，如 /jobs/<job_id>
files_url string 文件列表路径，如 /jobs/<job_id>/files
output_dir string 本次流水线 --out-dir
queue_position int 队列位置；运行中为 0，排队从 1 起

示例：

{
  "job_id": "a1b2c3d4e5f6...",
  "status": "queued",
  "status_url": "/jobs/a1b2c3d4e5f6...",
  "files_url": "/jobs/a1b2c3d4e5f6.../files",
  "output_dir": "/path/to/OpenRare/modules/pipeline/complete_pipeline/api_jobs/a1b2c3d4.../output",
  "queue_position": 1
}

GET /jobs/{job_id} 响应（成功完成后）

字段 类型 说明
status string succeeded / failed / running
output_dir string 输出目录
summary object 各步产物路径（来自 full_pipeline.outputs.tsv）
error string 失败时的错误信息

API 默认目录

未传 output_dir 时：

modules/pipeline/complete_pipeline/api_jobs/<job_id>/
├── status.json
├── api_run.log
├── input/          # /run-upload 上传的 VCF
└── output/         # 流水线输出（结构同 CLI --out-dir）
    └── 07_hla_filter/vep_output.no_hla.csv

可通过 .env 设置 FULL_PIPELINE_API_JOBS_DIR 修改 jobs 根目录。

Mock 数据（联调 / smoke）

迷你 mock 库位于 resource_mock/，配合 --phasing no 与 mock BED/DB 路径可快速验证流程连通性：

pixi run mock-smoke-test

详见 resource_mock/README.md。

命令行参数

入口：scripts/run_full_pipeline.sh

参数 常用 默认值 说明
--input-vcf FILE 是 — 患者 VCF（.vcf / .vcf.gz）
--out-dir DIR 是 — 输出根目录
--fork N 是 1 VEP fork 数
--hpo-id ID 是 空 HPO ID，逗号分隔
--phasing yes|no 否 yes 是否运行 Beagle phasing
--vaf yes|no 否 yes 是否计算 VAF
--regulatory-annotation yes|no 否 yes 是否运行 cCRE 注释
--ncrna-annotation yes|no 否 yes 是否运行 ncRNA 注释
--pseudogene-annotation yes|no 否 yes 是否运行假基因注释
--hla-filter yes|no 否 yes 是否删除 HLA/MHC 区行
--liftover-filter-standard-chroms yes|no 否 yes 是否仅保留标准染色体（1-22,X,Y,MT）；非标准 contig 写入 00_liftover_filter/
--sample-id ID 否 auto 样本名
--chromosomes SPEC 否 auto Beagle 目标染色体；有参考 panel 的 contig 自动 phase
--ref-dir DIR 否 $FULL_PIPELINE_REF_DIR Beagle 参考 panel
--beagle-jar FILE 否 $FULL_PIPELINE_BEAGLE_JAR Beagle JAR
--java-bin PATH 否 $JAVA_BIN Java 可执行文件
--input-assembly SPEC 否 auto auto / GRCh37 / GRCh38；GRCh37 时在 phasing 前 liftover
--keep-raw-vep yes|no 否 yes 保留 04_vep/raw_vep.tsv
--dry-run 否 关闭 只打印命令 
pixi run bash scripts/run_full_pipeline.sh --help

流程说明

步骤 目录 功能 主输出
00 00_input/ 输入 VCF 规范化（bgzip + 索引） *.vcf.gz
00b 00_liftover/ GRCh37→GRCh38 liftover（--input-assembly 触发） output.grch38.norm.vcf.gz
00c 00_liftover_filter/ 标准染色体过滤（--liftover-filter-standard-chroms，默认开启） input.standard_chromosomes.vcf.gz
01 01_phasing/ Beagle + CHN 参考 phasing/ref-support（可 --phasing no 跳过） *.refsupport.vcf.gz
02 02_vcf_preprocessing/ VAF、cCRE、ncRNA 注释（各步可 no 跳过） preprocessed.regulatory.vcf.gz
03 03_pseudogene_annotation/ 假基因 INFO 注释（可跳过） preprocessed.pseudogene_annotated.vcf.gz
04 04_vep/ VEP + CADD/SpliceAI/dbNSFP/LoFTEE/ClinVar 等 vep_output.base.csv
05 05_vcf_info_to_csv/ VCF INFO/FORMAT 回填到 CSV vep_output.with_info.csv
06 06_genos_evee_annotation/ GENOS-VarRisk 疾病预测分数 vep_output.with_genos_evee.csv
07 07_hla_filter/ 删除 GRCh38 HLA/MHC 区行（可 --hla-filter no 跳过） vep_output.no_hla.csv

输出文件

主结果（默认 hla_filter=yes）：

<out-dir>/07_hla_filter/vep_output.no_hla.csv

若 --hla-filter no，主结果为：

<out-dir>/06_genos_evee_annotation/vep_output.with_genos_evee.csv
路径 说明
<out-dir>/04_vep/vep_output.base.csv VEP 基础 CSV
<out-dir>/04_vep/raw_vep.tsv VEP 原始 TSV（默认保留）
<out-dir>/00_liftover_filter/input.standard_chromosomes.vcf.gz 标准染色体过滤后的 VCF
<out-dir>/00_liftover_filter/input.ignored_nonstandard_chromosomes.tsv 被过滤的非标准 contig 变异
<out-dir>/06_genos_evee_annotation/vep_output.with_genos_evee.csv GENOS-VarRisk 宽表（HLA 过滤前）
<out-dir>/07_hla_filter/vep_output.no_hla.csv 最终宽表（默认）
<out-dir>/full_pipeline.outputs.tsv 各步产物路径索引
<out-dir>/logs/full_pipeline.log 全流程日志

流水线输出由 --out-dir 指定，与 OPENRARE_DATA_ROOT（VEP 数据/插件）无关。

项目结构

modules/pipeline/                    # 本模块（pixi 项目根）
├── pixi.toml
├── .env.example
├── README.md
├── EXTERNAL_PATHS.md
├── scripts/
│   ├── load-env.sh                  # pixi 激活时加载 .env
│   ├── run_full_pipeline.sh         # CLI 全流程入口
│   └── start_full_pipeline_api.sh
├── config/
│   ├── paths.sh
│   └── path_utils.py
├── resource_mock/                   # 迷你 mock 注释库（联调/smoke）
├── complete_pipeline/
│   ├── full_pipeline_api.py         # FastAPI 服务
│   └── api_jobs/                    # API 任务目录（gitignore）
├── modules/                         # 各步骤实现
│   ├── phasing_beagle_refsupport/
│   ├── liftover/                    # 标准染色体过滤（00_liftover_filter）
│   ├── vcf_preprocessing/
│   ├── pseudogene_annotation/
│   ├── vep_runner/
│   ├── vcf_info_to_csv/
│   ├── genos_evee_annotation/
│   ├── hla_filter/
│   └── result_sorting/              # 排序模块保留，当前主流程默认不启用
└── test/
    ├── input/P001.genotyper10000.vcf
    ├── prepare_sites_vcf_with_sample.sh
    └── run_api_integration_test.sh

环境变量与外部数据

变量 用途
OPENRARE_DATA_ROOT VEP cache、插件、CADD/SpliceAI 等注释库
OPENRARE_PUBLIC_DATA_ROOT 假基因 GENCODE / Pseudogene.org / HGNC
FULL_PIPELINE_REF_DIR Beagle CHN reference panel
FULL_PIPELINE_BEAGLE_JAR Beagle JAR
JAVA_BIN Beagle 用 Java（默认 java）
FULL_PIPELINE_API_PORT API 端口（默认 18901）
FULL_PIPELINE_API_JOBS_DIR API 任务根目录

完整说明与数据布局：EXTERNAL_PATHS.md。

VEP 配置 modules/vep_runner/config/vep_runner_config.json 使用 ${OPENRARE_DATA_ROOT} 占位符，运行时由 run_vep_to_csv.py 展开；VEP 可执行文件从 PATH 解析（pixi 的 ensembl-vep）。

更多文档

文档 内容
complete_pipeline/README.md API 与 CLI 详细参数
modules/liftover/README.md 标准染色体过滤（00_liftover_filter）
modules/vep_runner/README.md VEP 插件与注释库安装
modules/genos_evee_annotation/README.md GENOS-VarRisk 注释与数据库构建
modules/hla_filter/README.md HLA/MHC 区行过滤
modules/result_sorting/README.md 可选致病性排序（主流程默认不启用）
resource_mock/README.md 联调用迷你 mock 库
EXTERNAL_PATHS.md 外部路径与中间文件说明

HPO 说明

仅支持标准 HPO ID（如 HP:0001250），不支持自由文本临床描述。传入后用于 HPO → 组织 → GTEx 表达加权，影响转录本选择；不传时仍会做转录本选择，但无 HPO 组织加权。

输入 VCF 说明

  • 支持 .vcf 与 .vcf.gz；未压缩文件会自动 bgzip 到 <out-dir>/00_input/ 并建索引。
  • sites-only VCF（无样本列）可先经 test/prepare_sites_vcf_with_sample.sh 补样本列后再跑流程。