简体中文 | English
面向 Illumina 双端全基因组测序(WGS)数据的 Genome Survey 分析流程。项目使用 Python 串联 fastp、Jellyfish、GenomeScope2、FastK 和 Smudgeplot,完成 reads 过滤、k-mer 统计、基因组特征建模及倍性相关分析,无需输入参考基因组。
文档依据:
code/main.py、code/main.ipynb,以及编写时在项目目录中实际读取的三个code/tools/*.py模块。两份入口文件与用户上传的附件内容一致。本文区分当前代码行为与 Notebook 历史输出;未重新运行真实测序数据,未验证 Docker 镜像当前的可拉取性或跨平台兼容性。
输入目录中的双端 FASTQ.gz
└─ 识别样本与 R1/R2 配对
└─ fastp:过滤 reads,输出质控报告
├─ Jellyfish:统计 canonical k-mer,生成频数直方图
│ └─ GenomeScope2:按指定倍性模型拟合基因组特征
└─ FastK:建立 k-mer 数据库
└─ Smudgeplot hetmers:寻找杂合 k-mer 对
└─ Smudgeplot all:分析与绘图(存在有效 k-mer 对时)
命令行入口按样本依次执行 fastp → Jellyfish/GenomeScope2 → FastK/Smudgeplot。两个下游分析均使用 fastp 过滤后的双端数据;样本之间串行执行,--threads 不代表同时分析的样本数。GenomeScope2 的倍性模型由用户提供,Smudgeplot 结果不会自动反馈给 GenomeScope2 重跑。
survey/
├── README.md # 中文文档
├── README.en.md # English documentation
└── code/
├── main.py # 完整流程的命令行入口
├── main.ipynb # 交互式探索与历史运行示例
└── tools/
├── fastq.py # 文件配对与 fastp 封装
├── jellyfish_genomescope2.py # Jellyfish 与 GenomeScope2 封装
└── fastk_smudgeplot.py # FastK 与 Smudgeplot 封装
tools 是本项目的本地模块,不是需要通过 pip install tools 安装的软件包。仅有 main.py 和 main.ipynb 不足以运行完整流程,必须保留上述目录结构及三个模块。
| 依赖 | 用途与说明 |
|---|---|
| Python ≥ 3.9 | 代码使用 str.removesuffix(),从语法/API 使用可推得此下限;不是已验证的完整版本兼容范围 |
| Docker 客户端及可访问的 Docker daemon | 所有生信软件均通过 docker run 调用;当前用户需要有运行容器和挂载数据目录的权限 |
gzip |
Jellyfish 步骤在宿主机执行 gzip -cd,经标准输入向容器传递解压数据 |
| JupyterLab 或 Notebook(可选) | 仅交互式使用 main.ipynb 时需要 |
当前 Python 源码只导入标准库及本地 tools 模块,命令行流程无需额外的第三方 Python 包。生信软件的依赖由相应容器提供,仅在宿主机安装这些软件不能替代代码中的 Docker 调用。
Notebook 内核元数据记录了 Python 3.14.6;这只是文件中的环境记录,不代表必须使用该版本,也不是本次验证结果。代码采用 Unix 风格路径及容器挂载方式;在 macOS 上还需确认 Docker 的目录共享、镜像架构及资源配置,当前文档不承诺特定操作系统已经验证通过。
| 阶段 | 镜像 |
|---|---|
| fastp | staphb/fastp:1.4.0 |
| Jellyfish | openeuler/jellyfish:2.3.1-oe2403sp4 |
| GenomeScope2 | abner12/genomescope:2.0 |
| FastK | grpiccoli/fastk:latest |
| Smudgeplot | changshengw6/smudgeplot:0.5.3 |
以上是模块中的默认配置,不代表镜像由对应软件作者维护。FastK 使用浮动的 latest 标签;需要复现分析时,请记录实际镜像 ID/digest 及软件版本。
可在准备好 Python 和 Docker 后检查环境并预先拉取镜像:
python3 --version
docker info
gzip --version
docker pull staphb/fastp:1.4.0
docker pull openeuler/jellyfish:2.3.1-oe2403sp4
docker pull abner12/genomescope:2.0
docker pull grpiccoli/fastk:latest
docker pull changshengw6/smudgeplot:0.5.3镜像可用性以实际拉取结果为准。无需为运行命令行流程安装 Jupyter;若要打开 Notebook,可另行安装 jupyterlab。
输入目录直接放置成对、gzip 压缩的 FASTQ 文件,文件名必须为:
datas/
├── sampleA_1.fastq.gz
├── sampleA_2.fastq.gz
├── sampleB_1.fastq.gz
└── sampleB_2.fastq.gz
_1.fastq.gz为 R1,_2.fastq.gz为 R2,去除该后缀后的部分作为样本 ID。- 只扫描输入目录的第一层,不递归扫描子目录。
- 当前不识别
sample_R1.fastq.gz、sample_R2.fastq.gz、.fq.gz或未压缩.fastq等其他命名方式。 - 缺少任一端会抛出
FileNotFoundError;没有符合规则的配对文件会抛出ValueError。 - 按 R1 文件名排序识别样本;不自动合并同一样本的多个 lane,也不预检双端 reads 的 ID、数量或内容是否匹配。
Notebook 中展示过 SRR8455574_1.fastq.gz / SRR8455574_2.fastq.gz 的配对输出;项目不包含自动下载该数据的步骤。
在项目根目录运行,将示例路径替换为实际目录:
python3 code/main.py --help
python3 code/main.py \
--input /path/to/datas \
--output /path/to/output_run01 \
--threads 32 \
--kmer 21 \
--ploidy 2 \
--cutoff 12使用默认分析参数的最简命令:
python3 code/main.py -i ./datas -o ./output_run01相对路径相对于启动命令时的工作目录解析。入口会将输入、输出路径转换为绝对路径,并创建输出目录。建议每次更改数据或分析配置时使用新的输出目录,避免覆盖或误用已有结果。
如需保存整个流程的终端输出,可自行重定向日志:
python3 -u code/main.py -i ./datas -o ./output_run01 > survey_run01.log 2>&1日志重定向不是程序内置功能;该命令会覆盖同名日志文件。
| 参数 | 类型 | 默认值 | 作用 |
|---|---|---|---|
-h, --help |
开关 | — | 显示帮助并退出 |
-i, --input |
路径 | 必填 | 包含双端 .fastq.gz 文件的目录 |
-o, --output |
路径 | 必填 | 输出根目录 |
-t, --threads |
整数 | 32 |
传给各阶段的线程参数;fastp 最终限制在 1–16 |
-k, --kmer |
整数 | 21 |
Jellyfish 和 FastK 共用的 k-mer 长度 |
-p, --ploidy |
整数 | 2 |
GenomeScope2 的模型倍性,不是已推断出的样本倍性 |
--cutoff |
整数 | 12 |
传给 Smudgeplot hetmers -L 的计数下限 |
代码层面的约束和限制:
- 全流程需要
threads ≥ 1、5 ≤ kmer ≤ 31、ploidy ≥ 1、cutoff ≥ 1。这是两个下游模块检查条件的交集,不表示所有组合都适合实际数据或受底层软件支持。 - 参数范围检查分散在下游模块内,非法参数可能在 fastp 已经运行后才报错;命令行解析器本身仅检查整数类型及必填项。
- FastK 的
memory_gb在main.py中固定为32,生成FastK -M32;没有--memory参数。这不代表整个流程的总内存硬上限。 - Jellyfish 的 hash size 默认
1G,FastK 建表使用-t4;两者都未提供 CLI 开关。Smudgeplot 的--cutoff不会修改 FastK 的建表阈值。 - fastp 默认启用双端接头检测,使用
--qualified_quality_phred 20、--unqualified_percent_limit 40、--length_required 50;这些设置未暴露为 CLI 参数。 - 镜像名称、FastK 缓存复用选项、单阶段运行和跳过步骤均未暴露为 CLI 参数。
threads传给 fastp、Jellyfish、FastK 和 Smudgeplothetmers;GenomeScope2 及 Smudgeplotall的容器命令没有显式线程参数。
以下展示当前代码在默认 k=21 下使用的路径。它不是所有底层工具输出文件的完整清单;中间失败、没有有效 k-mer 对等情况可能导致部分文件不存在。
output_run01/
└── <sample_id>/
└── survey/
├── fastp/
│ ├── clean_R1.fastq.gz
│ ├── clean_R2.fastq.gz
│ ├── fastp.html
│ └── fastp.json
├── jellyfish/
│ ├── kmer_21.jf
│ └── kmer_21.histo
├── genomescope2/
│ └── ... # GenomeScope2 实际生成的报告与图表
└── smudge_analysis/
├── fastk/
│ ├── kmer_21.ktab
│ ├── kmer_21.hist
│ └── ... # 可能包含关联分片或隐藏文件
├── tmp/
└── smudgeplot/
├── kmerpairs.smu
├── pipeline_result.json
├── smudgeplot_run.log # 仅执行 all 阶段后写入
└── smudgeplot* # all 使用的输出前缀,具体文件以实际结果为准
kmer_21 中的 21 随 --kmer 改变。代码会在 genomescope2/ 下递归查找 summary.txt,按路径排序后取第一个;若找不到,返回值中的 summary 为 None,但不会因此报错。此处不将具体绘图文件名或扩展名视为已确认的固定接口。
| 结果 | 查看方式与注意事项 |
|---|---|
| fastp 质控 | 打开 fastp.html;需要机器读取时使用 fastp.json |
| Jellyfish 统计 | kmer_<k>.jf 为数据库,kmer_<k>.histo 为交给 GenomeScope2 的直方图 |
| GenomeScope2 | 查看其实际生成的 summary.txt 和拟合图;模块尝试提取基因组长度、杂合度、重复序列长度、拟合度、错误率 |
| Smudgeplot | 查看图表、pipeline_result.json 以及存在时的 smudgeplot_run.log |
GenomeScope2 模块返回的 metrics 是按报告文本匹配得到的字典,数值仍为字符串。当前正则表达式可能无法解析带千位分隔符、单位或不同字段名的结果,因此缺少某个键不等于该指标为零。键 repeat_content 对应原报告的 Genome Repeat Length,不能直接当作重复比例。main.py 没有把该返回字典另存为 JSON,也没有生成跨样本汇总表。
Smudgeplot 的 pipeline_result.json 包含状态、原因、k-mer 参数、有效 k-mer 对计数、覆盖组合行数和输出路径。其中 total_kmer_pairs 是 .smu 文件中有效三列记录的正整数第三列之和,coverage_combinations 是这些记录的行数,两者都不是变异位点数。函数返回字典里的 result_json 路径是在文件写出后才加入的,因此 JSON 文件本身不含该字段。
status |
当前代码中的含义 |
|---|---|
completed |
Smudgeplot all 返回码为 0,仍需人工检查图表及推断结果 |
no_inference |
未找到有效 k-mer 对,跳过 all 分析和绘图 |
failed |
Smudgeplot all 返回码非 0,错误详情写入该阶段日志 |
FastK 或 hetmers 执行失败、输出缺失等更早发生的异常会直接抛出,不保证生成 pipeline_result.json。
GenomeScope2 使用 k-mer 频数模型估计基因组大小、杂合度及重复相关特征。应同时检查拟合图、原始直方图与报告,不能仅凭模型收敛或单个数值认定估计可靠。--ploidy 是建模假设;设置为 2 并不能证明样本为二倍体。参见 GenomeScope2 官方说明。
Smudgeplot 根据杂合 k-mer 对的覆盖关系分析倍性相关结构;其结果依赖数据质量、覆盖度、可用杂合信号和参数选择。completed 仅表示命令执行成功,no_inference 也不等于“单倍体”或“没有杂合性”。应结合 GenomeScope2 和样本背景判断,不能把 k-mer 对数量直接解释为杂合变异数量。参见 Smudgeplot 官方说明。
本项目进行 reads 层面的 Genome Survey,不执行基因组组装、序列比对、变异检测或基因注释,也不直接输出经验证的染色体倍性结论。
批量分析优先使用 code/main.py。Notebook 用于查看中间过程,使用前需要注意:
- 数据与输出路径写死在单元格中,须修改
dir_datas、dir_output;启动内核时要确保code/在模块搜索路径内,例如先进入code/再启动 Jupyter。 - fastp 单元格遍历所有样本,但其后的
result_fastp = result仅保留最后一次结果;GenomeScope2 和 Smudgeplot 单元格不在样本循环内,因此只处理最后一个样本。 - Notebook 的 GenomeScope2 示例使用
threads=128、kmer=17、ploidy=1;Smudgeplot 示例使用threads=32、kmer=17、memory_gb=32、lower_cutoff=12。这些不是 CLI 默认值。 - Notebook 保存的 fastp 输出曾指向
output/fastp/<sample_id>/,而当前单元格及 CLI 使用output/<sample_id>/survey/fastp/,说明保存输出与当前代码不完全同步。 - 历史日志中的样本结果、执行耗时、版本及路径仅是运行记录,不应当作本次重新执行或完整复现的证据。
- 没有完整断点续跑。 fastp 会再次执行;Jellyfish 会删除同名
.jf和.histo后重算;Smudgeplot 会删除同名.smu后重新寻找 k-mer 对。 - FastK 默认复用已有数据库。 同一 k 值的
.ktab和.hist同时存在时即跳过建表,不检查输入数据、过滤条件、镜像版本或关联分片是否变化。修改输入或配置后应使用新输出目录,避免旧数据库与新 reads 混用。 - 已有目录不会被整体清空。 不同运行遗留的图表、日志或报告可能并存;旧文件的存在不能证明本次步骤成功。
- 单个样本异常可能中断整个批次。 大多数外部命令失败会抛出异常,入口没有逐样本捕获并继续的机制。
- 末尾完成提示不保证全部分析成功。 Smudgeplot
all失败时模块返回failed,主程序仍可能继续并打印Genome Survey pipeline completed.;需检查每个样本的状态及日志,不能仅检查末尾提示或进程退出码。 - 没有自动资源规划或参数寻优。 当前不会自动选择 k、倍性或 cutoff,不合并不同 k 值结果,不提供统一汇总报告。FastK 临时解压与数据库分片可能占用额外磁盘空间。
| 现象 | 检查方向 |
|---|---|
No module named 'tools' |
确认三个模块位于 code/tools/,使用 python3 code/main.py;Notebook 另需检查内核工作目录 |
No paired FASTQ files found. |
检查是否直接位于输入目录,且严格使用 _1.fastq.gz / _2.fastq.gz 后缀 |
Missing R1/R2 file for sample |
检查对应样本是否缺少一端,或两端样本名前缀不一致 |
找不到 docker / 无法连接 daemon |
检查 Docker 是否安装、启动,以及当前用户的访问权限 |
| 镜像拉取或挂载失败 | 检查镜像标签、网络、CPU 架构、目录权限及 Docker 目录共享设置 |
| Jellyfish 数据库缺失或为空 | 查看终端日志中的 gzip、Jellyfish 返回码,以及内存、磁盘和 hash size 配置 |
no_inference |
查看 .smu、k-mer 直方图及 cutoff,结合样本是否存在足够杂合信号分析 |
failed |
查看该样本的 smudgeplot_run.log,不要仅依赖主程序末尾提示 |
- fastp:FASTQ 预处理与质控。
- GenomeScope2:k-mer 模型及结果说明。
- Smudgeplot:倍性相关结构推断及运行说明。
用于论文或正式分析时,应记录项目代码版本、完整命令、输入数据来源、实际镜像 digest、软件版本及原始日志,并按所用工具的要求引用其原始文献。