FlowIO - FCS 文件解析与流式细胞术数据处理库

技能概述

FlowIO 是一个轻量级 Python 库，用于读取和写入 Flow Cytometry Standard (FCS) 文件，支持 FCS 2.0、3.0 和 3.1 版本，可将流式细胞术数据提取为 NumPy 数组或转换为 CSV/DataFrame 格式。

适用场景

1. 后端服务与 Web 应用：FlowIO 依赖最小，适合在服务器端处理用户上传的 FCS 文件，进行文件验证、元数据提取和数据预览，无需部署重量级分析工具。

2. 数据管道与批量处理：在生物信息学数据管道中，FlowIO 可批量解析 FCS 文件、提取元数据和事件数据，为后续分析提供干净的 NumPy 数组或 Pandas DataFrame。

3. 流式细胞术数据预处理：在导入 FlowJo 或其他分析工具之前，使用 FlowIO 进行文件验证、通道信息提取、数据格式转换和质量检查，快速筛选合格样本。

核心功能

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

   • 读取 FCS 2.0/3.0/3.1 文件，解析 HEADER、TEXT、DATA、ANALYSIS 四个段落
   • 提取事件数据为 NumPy 数组（支持预处理和原始数据）
   • 读取通道信息（PnN 短名称、PnS 描述名称、PnR 范围值）
   • 自动识别散射光、荧光和时间通道类型

2. 元数据提取与文件验证

   • 访问完整 TEXT 段落关键词（采集日期、仪器型号、数据类型等）
   • 仅解析元数据选项 (only_text=True) 节省内存
   • 处理偏移量错误和不规范文件格式
   • 检测多数据集 FCS 文件

3. FCS 文件创建与导出

   • 从 NumPy 数组创建标准 FCS 3.1 文件
   • 支持自定义通道名称和描述性名称
   • 添加自定义元数据（来源、日期、仪器等）
   • 导出为 CSV 格式便于跨平台分析

常见问题

FlowIO 支持哪些 FCS 版本？

FlowIO 支持 FCS 2.0、3.0 和 3.1 版本。读取时自动检测文件版本，创建文件默认输出为 FCS 3.1 格式。如果遇到版本兼容性问题，可尝试使用 ignore_offset_discrepancy 或 ignore_offset_error 参数来处理不规范文件。

FlowIO 和 FlowKit 有什么区别？

FlowIO 专注于 FCS 文件的基础读写操作，适合文件解析、元数据提取和数据预处理。FlowKit 基于 FlowIO 构建，提供高级分析功能如荧光补偿、门控分析和 FlowJo/GatingML 支持。如果只需要读取和转换 FCS 文件，FlowIO 的轻量级特性更合适；需要完整分析流程时，建议配合 FlowKit 使用。

如何用 Python 读取 FCS 文件？

使用 FlowIO 读取 FCS 文件只需几行代码：

from flowio import FlowData

# 读取 FCS 文件
flow = FlowData('sample.fcs')

# 获取基本信息
print(f"版本: {flow.version}, 事件数: {flow.event_count}")
print(f"通道: {flow.pnn_labels}")

# 提取事件数据为 NumPy 数组
events = flow.as_array()

如果只需要元数据，可使用 only_text=True 参数跳过数据段，大幅减少内存占用。

FCS 文件解析报错怎么办？

常见错误包括偏移量不匹配 (DataOffsetDiscrepancyError) 和多数据集错误 (MultipleDataSetsError)。偏移量错误可尝试 ignore_offset_discrepancy=True 或 use_header_offsets=True 参数；多数据集文件需使用 read_multiple_data_sets() 函数读取所有数据集。建议在代码中使用 try-except 捕获 FCSParsingError 并根据错误类型选择相应处理策略。

能不能批量处理多个 FCS 文件？

可以。FlowIO 的轻量级设计特别适合批量处理：

from pathlib import Path
from flowio import FlowData

for fcs_file in Path('data/').glob('*.fcs'):
    flow = FlowData(str(fcs_file), only_text=True)
    print(f"{fcs_file.name}: {flow.event_count} 事件")

使用 only_text=True 可快速提取元数据而不加载完整事件数据，大幅提升批量处理速度。

如何提取 FCS 文件中的元数据？

FlowIO 提供完整访问 TEXT 段落的能力：

from flowio import FlowData

flow = FlowData('sample.fcs')
text = flow.text  # 字典格式的元数据

# 常用元数据关键词
date = text.get('$DATE')      # 采集日期
instrument = text.get('$CYT')  # 仪器型号
source = text.get('$SRC')      # 数据来源

也可使用 flow.pnn_labels 和 flow.pns_labels 获取通道名称，使用 flow.scatter_indices 和 flow.fluoro_indices 识别通道类型。

FCS 文件可以转换为 CSV 吗？

可以，通过 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)

DataFrame 可保留 FCS 元数据作为 attrs 属性，便于后续分析时追溯文件来源。

FlowIO 是否支持写入 FCS 文件？

支持。使用 create_fcs() 函数从 NumPy 数组创建 FCS 文件：

import numpy as np
from flowio import create_fcs

# 准备数据（行为事件，列为通道）
data = np.random.rand(10000, 5) * 1000
channels = ['FSC-A', 'SSC-A', 'FL1-A', 'FL2-A', 'Time']

# 创建 FCS 文件
create_fcs('output.fcs', data, channels)

也可添加描述性通道名称和自定义元数据，生成的文件符合 FCS 3.1 标准，可在主流流式细胞术分析软件中打开。