4.3 数据准备与输入规范

4.3.1 常见分析模式

分析路径由实时发现的 BioLine Flow 和 Tool 决定，而不是由本地固定名称或镜像清单决定。

• 全流程分析：将原始输入交给适用的 BioLine Flow；上游成功 finalize 后，再发现下游 Tool 做统计、绘图或报告。
• 仅上游分析：运行 BioLine Flow，并将结果 finalize 到 stage 供后续任务使用。
• 仅下游分析：对已准备的丰度表、通路表、ASV 表、序列表和 metadata.tsv 发现合适的 BioLine Tool 版本。

每个下游 Tool 版本都要核对双语 summary 与 config。summary 应声明 analysis_lane: downstream、fixed_command: false；config 中不能包含固定分析命令。

4.3.2 输入文件要求

具体要求以 Flow/Tool 的真实接口和文档为准。常见输入包括：

• 全流程或上游任务使用 paired-end FASTQ。
• 去宿主步骤可能需要宿主参考基因组 FASTA。
• 丰度表、通路表或 ASV 表通常需要与 metadata.tsv 中的 sample_id 对应。
• 深度学习 Tool 的输入格式由该精确版本的 summary/config 指定。

文件类型	常见用途	准备要点
双端 FASTQ（*_1.fq.gz + *_2.fq.gz）	上游分析	每个样本一对读段，命名保持一致。
宿主参考基因组 FASTA	可能的去宿主步骤	使用与样本宿主相匹配的版本。
metadata.tsv	分组、协变量和解释	sample_id 应与输入表格或样本文件对应。
丰度、通路或 ASV 表	下游统计或微生物组分析	按所选 Tool 要求确认矩阵方向和格式。

4.3.3 数据组织与命名建议

• FASTQ 文件保持成对命名，便于识别 read1 和 read2。
• metadata.tsv 中的 sample_id 与文件名、样本名或表格列名对应。
• 需要去宿主时，准备匹配的参考基因组并核对版本。
• 仅下游分析时，将丰度、通路或 ASV 表与 metadata.tsv 一起整理，并检查样本顺序与缺失值。
• BioLine 路径按项目、队列或批次组织；上游 Flow 必须能够读取对应位置。

4.3.4 BioLine 输入与本地输入的边界

带上游的任务使用 BioLine 可读的数据路径，因为 BioLine Flow 不能直接读取任意本地路径。执行车道通过 fkit 列出 BioLine 文件，并按 inspect 返回的接口生成绑定。上游 FASTQ 留在 BioLine 受控环境，不会为本地下游执行而整体复制回来。成功 finalize 后，只下载下游任务需要的结果或辅助输入到 stage。

仅下游任务可在所配置的边界内使用已准备输入。无论输入来自 BioLine 还是任务本地目录，运行前都必须根据精确 Tool 版本核对格式和权限。

4.3.5 数据要求与不满足时的影响

检查项	核对方式	可能影响
双端 reads	对照 Flow 的必需输入端口	缺少一端时无法按该 Flow 执行。
样本组织	对照批量绑定方式和样本目录	混放文件可能无法正确识别样本。
样本量	根据研究设计和所用统计方法评估	样本不足会限制统计效能。
测序深度与质量	检查数据报告及 Flow 支持的输入范围	低深度或低质量可能降低检出稳定性。
参考基因组	核对宿主和参考版本	不匹配可能导致去宿主失败或错误过滤。
metadata.tsv	核对 sample_id、分组和协变量	键不匹配会阻断分组分析或错误关联样本。
矩阵格式	对照下游 Tool 文档确认行列方向、格式和特征名	格式错误会导致读取失败或分析对象错位。

4.3.6 提交前检查

上游任务前，确认 FASTQ 配对、样本目录、参考基因组和 metadata，并用 fkit 检查 BioLine 路径。仅下游任务前，确认表格与 metadata 的样本键和格式。两类任务都应先发现现有 BioLine Tool/Flow，检查精确版本的文档和资源要求；没有合适能力时，再走独立创作流程。

不存在必须预先构建或安装的历史镜像集合。下游镜像在选择 BioLine Tool 版本后按需拉取。