alterlab-flowio

FlowIO：流式细胞术标准文件处理器

概述

FlowIO 是一个轻量级 Python 库，用于读取和写入流式细胞术标准（FCS）文件。可解析 FCS 元数据、提取事件数据，并以最少的依赖项创建新的 FCS 文件。支持 FCS 2.0、3.0 和 3.1 版本，适用于后端服务、数据管道和基本的细胞术文件操作。

何时使用此技能

在以下情况下使用此技能：

• 需要解析 FCS 文件或提取其元数据
• 需要将流式细胞术数据转换为 NumPy 数组
• 需要将事件数据导出为 FCS 格式
• 需要拆分包含多个数据集的 FCS 文件
• 需要提取通道信息（散射、荧光、时间）
• 需要验证或检查细胞术文件
• 高级分析前需要进行预处理

相关工具： 如需高级分析（补偿、变换、门控、导入 FlowJo 10 工作区），建议使用 FlowKit 库（截至 2026-09 为 1.3.2），该库由同一作者基于 FlowIO 构建。

不适用的情况

场景	改用
补偿、变换、门控或 FlowJo/GatingML 工作区操作	FlowKit（配套库，并非此套件中的技能）
细胞术事件的聚类／降维	alterlab-scanpy、alterlab-umap
跨样本比较群体的统计分析	alterlab-statistical-analysis
质谱细胞术或基于成像的空间单细胞数据	alterlab-squidpy-spatial
注册 FCS 文件并为其进行版本管理	alterlab-lamindb

安装

uv pip install flowio     # 1.4.0 as of 2026-09

需要 Python 3.9 或更高版本；NumPy 是唯一的运行时依赖项。

快速入门

from flowio import FlowData

# Read FCS file and inspect
flow = FlowData('experiment.fcs')
print(f"FCS Version: {flow.version}")
print(f"Events: {flow.event_count}")
print(f"Channels: {flow.pnn_labels}")

# Get event data as NumPy array, shape (events, channels)
events = flow.as_array()

import numpy as np
from flowio import create_fcs

# Write a new FCS file from a NumPy array.
# Gotcha: create_fcs takes a WRITABLE BINARY FILE HANDLE (not a path) and a
# FLATTENED 1-D event array — pass data.flatten(), not the 2-D matrix.
data = np.array([[100, 200, 50], [150, 180, 60]], dtype='float32')  # 2 events, 3 channels
with open('output.fcs', 'wb') as fh:
    create_fcs(fh, data.flatten(), ['FSC-A', 'SSC-A', 'FL1-A'])

核心工作流

1. 读取 — 构造一个 FlowData('file.fcs') 实例。元数据读取可使用 only_text=True（节省内存）；对于有问题的文件，可传入偏移量／空通道标志。
2. 检查 — 读取 flow.version、flow.event_count、flow.pnn_labels、flow.pns_labels、通道类型索引以及 flow.text 元数据字典。
3. 提取 — 通过 flow.as_array()（预处理）或 flow.as_array(preprocess=False)（原始数据）获取 NumPy 数组。按需按通道类型切片。
4. 转换／导出 — 转换为 pandas DataFrame 或 CSV；也可以使用 flow.write_fcs(path, ...)（接收路径）或 create_fcs(fh, data.flatten(), ...)（接收二进制文件句柄和展平后的事件）写入新的 FCS 文件。输出始终为 FCS 3.1 单精度浮点数。
5. 多数据集 — 如果文件包含多个数据集，请使用 read_multiple_data_sets()，而不是构造函数。

使用指引

• 需要准确的签名、属性、异常或 FCS 关键字定义？ 阅读 references/api_reference.md。
• 要执行核心操作之一（读取／解析、元数据、创建、导出、多数据集、预处理）？ 阅读 references/workflows.md，查看完整代码。
• 需要任务指南（检查文件、批量处理目录、FCS→CSV、筛选事件、提取通道）？ 阅读 references/recipes.md。
• 遇到错误，或想了解最佳实践／文件结构／故障排除？ 阅读 references/error-handling-and-troubleshooting.md。

参考资料

• references/api_reference.md — 完整的 FlowData 类、实用函数 （read_multiple_data_sets、create_fcs）、异常类、FCS 文件 结构、常见 TEXT 段关键词、通道类型和示例工作流。
• references/workflows.md — 核心操作的完整代码：读取／解析、 元数据与通道提取、创建文件、导出／修改、 多数据集处理和数据预处理。
• references/recipes.md — 操作示例：检查内容、批量处理目录、FCS→CSV 转换、事件筛选与重新导出，以及带统计信息的通道提取。
• references/error-handling-and-troubleshooting.md — 异常处理模式、最佳实践、FCS 文件结构说明、故障排查表，以及集成说明（NumPy、pandas、FlowKit、Web 应用）。

总结

FlowIO 为流式细胞术工作流提供必需的 FCS 文件处理功能，可用于解析、提取元数据和创建文件。对于简单的文件操作和数据提取，仅使用 FlowIO 即可；对于复杂分析（补偿、门控），请与 FlowKit 或其他专用工具集成。

属于 AlterLab Academic Skills 套件。