FlowIO 流式细胞术文件库

要解决什么问题

流式细胞实验产出的 FCS（Flow Cytometry Standard） 文件往往体积大、段结构复杂：HEADER 定偏移，TEXT 里是增益、对数变换等关键字，DATA 才是事件矩阵。后端服务、批处理流水线或「先验文件再分析」的脚本，需要的是稳定解析元数据、把事件拉成 NumPy、必要时写回 FCS，而不是一上来就绑一整套桌面分析套件。

技能如何工作

FlowIO 以 FlowData 为主入口，覆盖 FCS 2.0 / 3.0 / 3.1 的读写与段访问（header、text、events、analysis）。常见路径包括：

• 只读元数据：only_text=True，避免把整份事件数据载入内存
• 读事件矩阵：事件数据为形状 (events, channels) 的 ndarray，可再转 pandas 做表分析
• 通道语义：自动区分散射、荧光、时间等通道类型，并支持用 null_channel_list 去掉空通道
• 预处理：preprocess=True 时按 TEXT 关键字做增益缩放、PnE 对数变换、时间单位换算
• 多数据集：单文件多 dataset 时用 read_multiple_data_sets()，避免误用构造函数触发 MultipleDataSetsError
• 导出：create_fcs() / write_fcs() 写出 FCS 3.1（单精度浮点）；不支持就地改 events，需提取→修改→重建

解析异常文件时可试 ignore_offset_discrepancy=True；文件操作建议包在 try/except 里，并保留原始 TEXT 关键字以便追溯实验条件。

适用边界

FlowIO 定位在文件 I/O、元数据与事件提取、简单预处理，不负责补偿矩阵、设门（gating）或 FlowJo/GatingML 工作流。这类需求应配合基于 FlowIO 解析层的 FlowKit 或其它专业工具。超大文件若仍内存吃紧，继续用元数据优先策略或分块处理事件数据。