2. 生物实验数据来源与格式解析
自动报告工程的第一道关口不是排版，而是“把文件读对”。生物实验产出的原始文件往往来自不同厂商、不同版本、不同操作系统，同一类实验也可能出现多种格式。若在读取阶段把样本名、分组、时间点或单位解析错，后续统计与图表再精美也是错的。本节围绕测序、qPCR、ELISA、流式、显微成像、代谢组六类常见产出，梳理文件类型、内部结构、读取方式、校验要点与元数据抽取方法，最后落到一份可执行的多源数据清单。
一、六类实验产出的文件形态
测序类最典型的是 FASTQ 与 BAM/VCF。FASTQ 每条读长由四行组成：以 @ 开头的标识行、碱基序列行、以 + 开头的分隔行、质量值行。质量值采用 Phred 编码，常见 Phred+33，即字符 ASCII 码减 33 得到 Q 值。读取时可用 Biopython 的 SeqIO.parse("sample.fastq","fastq")，校验重点是读长是否一致、是否存在空序列、质量字符是否落在合法区间。BAM 是二进制比对文件，需 pysam.AlignmentFile 读取，元数据在头部 @RG、@PG 行中，包含样本、平台、比对命令。VCF 则记录变异位点，头部 ## 行携带参考基因组版本，正文列含 CHROM、POS、REF、ALT、QUAL、INFO、FORMAT 与各样本基因型。
qPCR 类常见导出为 CSV 或 XLSX，典型列包括 Well、Sample Name、Target Name、Ct（或 Cq）、Melt Temperature。不同仪器对“未检出”的表示不同，可能是 Undetermined、N/A 或空值，读取时必须统一为缺失值而非 0。校验要点：内参基因 Ct 是否稳定、同一样本技术重复的 Ct 极差是否超过 0.5、熔解曲线是否单峰。
ELISA 类多为酶标仪导出的 XLSX 或 TXT，核心是 96 孔板布局与 OD 值。读取时需同时解析“板布局表”和“读数表”，按孔位 A1–H12 对齐。校验重点是标准曲线拟合优度 R²、空白孔 OD 是否异常偏高、复孔变异系数 CV 是否小于 15%。
流式类标准格式为 FCS 3.0/3.1，由 HEADER、TEXT、DATA 三段组成。TEXT 段保存 $PnN（通道名）、$PnV（通道标签）、$TOT（事件数）等关键字，DATA 段是二进制或 ASCII 的荧光强度矩阵。可用 flowio 或 fcsparser 读取，校验事件数与 $TOT 是否一致、通道数是否与 $PAR 匹配。
显微成像类常见 TIFF、OME-TIFF、CZI、ND2。OME-TIFF 在图像之外嵌入 XML 元数据，记录像素物理尺寸、通道波长、Z 层数、时间序列。读取可用 tifffile 或 aicsimageio，校验重点是维度顺序（TCZYX）与像素尺寸单位（µm）。
代谢组类常见 mzML、mzXML 与厂商原始格式，以及导出的 CSV 峰表。mzML 为 XML 结构，含 spectrum 列表、保留时间、m/z 与强度数组；峰表 CSV 通常含 m/z、RT、样本强度列。校验重点是保留时间漂移、缺失值比例与内标响应。
二、读取与校验的通用做法
读取阶段建议遵循“先探结构、再定解析器”的顺序。对文本类文件，先用 pandas.read_csv(path, sep=None, engine="python", nrows=5) 探测分隔符与表头行；对二进制文件，先读头部关键字再决定是否全量加载。所有原始列名应原样保留一份，另建标准化列名映射，避免后续脚本因列名变化而崩溃。
校验可分为三层。第一层是结构校验：文件能否打开、行数/事件数/维度是否与声明一致、必需列是否存在。第二层是数值校验：Ct 是否在 10–40 合理区间、OD 是否非负、荧光强度是否超出量程、m/z 是否在扫描范围。第三层是生物学校验：内参是否稳定、标准曲线 R² 是否达标、复孔 CV 是否合格、空白孔是否干净。三层都通过才允许进入报告生成。
validate_*.py 小函数，返回 (ok, messages)，把校验结果写入清单的“校验状态”列，而不是直接抛异常中断整批处理。三、元数据抽取：把“文件”变成“可分析对象”
元数据是自动报告的骨架。抽取时至少覆盖四类字段：样本标识（样本名、编号、分组、时间点、生物学重复）、实验条件（仪器型号、试剂批号、操作日期、操作人）、技术参数（读长、循环数、通道、像素尺寸、扫描范围）、文件属性（路径、格式、大小、校验和）。
抽取方式因格式而异：FASTQ 从标识行按约定分隔符切分；BAM 读 @RG 行；FCS 读 TEXT 段关键字；OME-TIFF 解析内嵌 XML；qPCR 与 ELISA 从表头或板布局表提取。若文件名本身携带信息（如 20240512_KD1_qPCR.csv），可用正则 (\d{8})_([A-Za-z0-9]+)_(\w+)\.csv 抽取日期、样本与实验类型，但必须与文件内部字段交叉核对，不能只信文件名。
四、多源数据清单整理任务
本节的可交付成果是一份多源数据清单。它既是读取脚本的输入，也是报告生成时的溯源依据。建议字段如下表，实际使用时按项目增删。
| 字段 | 说明 | 示例 |
|---|---|---|
| file_id | 清单内唯一编号 | F001 |
| path | 相对项目根目录的路径 | raw/qpcr/20240512_KD1.csv |
| exp_type | 实验类型 | qPCR |
| format | 文件格式 | CSV |
| sample_id | 样本标识 | KD1 |
| group | 分组 | knockdown |
| timepoint | 时间点 | 24h |
| instrument | 仪器/平台 | QuantStudio 5 |
| key_params | 关键技术参数 | Target=GAPDH, Ct范围 |
| validate_status | 校验状态 | pass / warn / fail |
| validate_note | 校验说明 | 复孔CV=8.2% |
| owner | 负责人 | 张三 |
| date | 入库日期 | 2024-05-13 |
整理时按“先分类、再逐文件登记、最后统一校验”的顺序推进。分类可按实验类型建目录，如 raw/seq/、raw/qpcr/、raw/elisa/、raw/fcs/、raw/imaging/、raw/metabolomics/。登记完成后运行批量校验脚本，把 validate_status 为 warn 或 fail 的行单独导出复查。只有清单中所有关键文件状态为 pass，才进入下一阶段的清洗与统计。
Undetermined 当 0 参与均值计算；把 FCS 的 $TOT 与实际读入事件数不一致的文件直接使用；把 OME-TIFF 的像素尺寸单位当成 mm；把不同参考基因组版本的 VCF 合并。这些都会在报告阶段以“看似合理但错误”的图表形式暴露出来。完成本节任务后，你应当能够：识别六类实验产出的文件类型与内部结构；为每类文件选择合适的读取库并写出最小读取代码；执行结构、数值、生物学三层校验；从文件内部与文件名中抽取样本、条件、参数、属性四类元数据；并产出一份字段完整、状态可追踪的多源数据清单，作为后续自动报告流程的可靠输入。