FlowIO 流式细胞术 FCS 处理

要解决什么问题

流式细胞实验产出的 FCS（Flow Cytometry Standard） 文件往往体积大、段结构复杂：HEADER 偏移、TEXT 键值元数据、二进制 DATA 事件区，有时还带 ANALYSIS 段或多数据集合并。后端脚本、批处理流水线或 Web 上传服务若自己解析二进制格式，容易在偏移不一致、空通道、PnE 对数变换等细节上踩坑。

技能如何工作

FlowIO 以 最小依赖 提供 FCS 2.0 / 3.0 / 3.1 读写。核心入口是 FlowData：标准读取事件为形状 (n_events, n_channels) 的 NumPy 数组；只需元数据时可用 only_text=True 降低内存。库会自动识别散射、荧光、时间等通道类型，并支持从 TEXT 段提取常见关键字。

典型步骤包括：读取或容错读取（如 ignore_offset_discrepancy=True）、按需开启 预处理（PnG 增益、PnE 指数变换、时间缩放）、修改事件后用 create_fcs() / write_fcs() 以 FCS 3.1 单精度 重新导出。多数据集文件应检测 MultipleDataSetsError，改用 read_multiple_data_sets() 按集读取；需要设门、补偿或 FlowJo/GatingML 时，文档建议与 FlowKit 配合，而不是在 FlowIO 里硬做高级分析。

适用边界与注意点

• FlowIO 不支持就地改事件矩阵，需提取 → 修改 → create_fcs() 重建。
• 大文件优先元数据探查或分块策略；空通道可用 null_channel_list 排除。
• 复杂 FCS 操作与完整 API/异常说明见技能内 references/api_reference.md。