flowio

FlowIO：轻量级 FCS 流式细胞术文件解析库

技能概述

FlowIO 是一个专为解析 FCS（Flow Cytometry Standard）文件设计的 Python 库，支持 FCS 2.0 至 3.1 版本，可快速提取事件数据为 NumPy 数组、读取元数据和通道信息，或将数据转换导出为 CSV/DataFrame 格式。

适用场景

1. FCS 文件解析与数据提取

当你需要从流式细胞仪导出的 FCS 文件中提取事件数据时，FlowIO 提供了简洁的 API。只需几行代码即可读取文件、获取事件数量、通道信息，并将数据转换为 NumPy 数组进行后续分析。特别适合需要快速访问文件元数据而无需加载全部事件的场景。

2. 流式细胞数据格式转换

需要将 FCS 文件转换为 CSV、DataFrame 或其他格式时，FlowIO 可以直接输出 NumPy 数组，轻松集成到 Pandas 工作流中。支持保留原始数据或应用预处理（如增益缩放、对数变换），适用于数据预处理管道或与其他分析工具的对接。

3. 批量处理与数据管道

在后端服务或自动化脚本中处理大量 FCS 文件时，FlowIO 的轻量级设计和高内存效率（支持仅读取元数据模式）使其成为理想选择。可快速验证文件、提取摘要信息、过滤事件并重新导出，适合构建数据处理管道或实验室信息系统。

核心功能

1. FCS 文件读写

FlowIO 提供完整的 FCS 文件读写能力。通过 FlowData 类读取文件并访问版本信息、事件计数、通道标签等；使用 create_fcs() 函数从 NumPy 数组创建符合 FCS 3.1 标准的新文件，支持自定义通道名称和元数据。

2. 元数据与通道信息提取

自动解析 FCS 文件的 TEXT 段，提取仪器名称、采集日期、数据类型等关键元数据。智能识别通道类型（散射光、荧光、时间），提供通道标签、描述名称和范围值，方便了解文件结构而无需加载事件数据。

3. 多数据集与容错处理

支持处理包含多个数据集的 FCS 文件，提供 read_multiple_data_sets() 函数一次性读取所有数据集。针对常见的偏移量不匹配或文件损坏问题，提供 ignore_offset_discrepancy、use_header_offsets 等参数增强鲁棒性。

常见问题

FlowIO 支持哪些 FCS 文件版本？

FlowIO 支持 FCS 2.0、3.0 和 3.1 版本。读取文件时可通过 flow.version 属性查看具体版本号。导出新文件时默认使用 FCS 3.1 格式和单精度浮点数据类型。

如何用 FlowIO 将 FCS 转换为 CSV？

使用 FlowData 读取文件后，调用 as_array() 获取 NumPy 数组，再结合 Pandas 转换为 DataFrame 并导出：

from flowio import FlowData
import pandas as pd

flow = FlowData('sample.fcs')
df = pd.DataFrame(flow.as_array(), columns=flow.pnn_labels)
df.to_csv('output.csv', index=False)

FlowIO 和 FlowKit 有什么区别？

FlowIO 专注于基础的 FCS 文件解析、元数据提取和文件创建，依赖少、速度快。FlowKit 基于 FlowIO 构建，增加了补偿矩阵、门控分析、Flow/GatingML 支持等高级分析功能。如果只需要文件读写和简单预处理，FlowIO 已足够；如需复杂分析，可配合 FlowKit 使用。