FlowIO 的用途定位
FlowIO 是一个轻量级、低层级的流式细胞术标准（Flow Cytometry Standard，FCS）文件读写库。资料中的示例针对 FlowIO 1.4.0，并称其为当前稳定版本。它适合以下任务：读取 FCS 2.0、3.0、3.1 文件；检查 HEADER、TEXT、ANALYSIS 与通道元数据；将事件数据取为二维 NumPy 数组；读取包含多个数据集的旧版文件；写出列表模式、单精度的 FCS 3.1 文件；为 pandas、机器学习或下游流式细胞术工具准备数据。
FlowIO 不执行补偿（compensation）、logicle/biexponential 变换、门控（gating）、聚类或 FlowJo 工作区处理，这些任务需使用 FlowKit 或其他分析包。
安装
在 Python 环境中安装已验证版本：uv pip install "flowio==1.4.0"。可用 uv run python -c "import flowio; print(flowio.version)" 确认运行时版本。FlowIO 1.4.0 支持 Python 3.9 至 3.13，依赖 NumPy。
主要能力与关键语义
TEXT 键会被规范化：FlowData.text 以小写存储键，并去掉标准 FCS 关键字开头的 $，例如用 flow.text.get("date")、flow.text.get("cyt")，不要查询 "$DATE"、"$CYT" 等大写带 $ 的键。TEXT 值保持字符串。资料指出 FlowIO 1.4.0 会从解码后的 TEXT 段中移除所有 $ 字符，包括值内部的 $；若需精确元数据保真，应保留原始文件。
事件有两种表示：flow.events 是未处理的一维扁平事件数组；flow.as_array() 返回形状为 (event_count, channel_count) 的 NumPy float64 数组。as_array(preprocess=True) 会应用 FCS 的增益、对数与时间缩放，但不应用补偿或 logicle/biexponential 显示变换；as_array(preprocess=False) 仅重塑编码的事件值，不做上述缩放。as_array() 会再创建一个内存数组，FlowIO 不提供分块或内存映射的事件访问。
通道编号有两套约定：NumPy 列以及 fluoro_indices、scatter_indices、time_index 使用从 0 开始的索引；flow.channels 使用从 1 开始的 FCS 参数编号。null_channels 包含通过 null_channel_list 提供的 PnN 标签字符串，包括未找到的标签；pns_labels 始终与 pnn_labels 长度一致，缺失的可选 PnS 标签显示为空字符串。
写入能力有意受限：create_fcs() 需要一个已打开的二进制文件句柄、按行主序事件/通道排列的扁平一维事件数据、每个通道一个 PnN 名称，以及可选的 PnS 名称和通过 metadata_dict 提供的字符串元数据。它写出 FCS 3.1 列表模式（$MODE=L）单精度浮点（$DATATYPE=F）数据，必需的解读关键字由 FlowIO 生成，不能通过 metadata 覆盖。
使用方式
读取 FCS 文件：用 FlowData(Path("sample.fcs")) 打开，再调用 as_array(preprocess=True) 获取事件数组，可读取 version、event_count、channel_count、pnn_labels、pns_labels 及 text 中的 date、cyt 等。仅需元数据时使用 FlowData("sample.fcs", only_text=True)，此时不要调用 as_array()，因为事件数据未加载。建议传入路径或 Path 而非调用方持有的文件句柄，FlowData 会在解析后关闭提供的句柄；资料提到 1.4.0 中 read_multiple_data_sets(handle) 可能在第一个数据集后失败，因为句柄已关闭，多数据集文件应传文件系统路径。
读取多个数据集：使用独立辅助函数 read_multiple_data_sets("legacy-multi-dataset.fcs")，而不是手动解读 $NEXTDATA 偏移。FCS 3.1 规范已弃用单文件多数据集，但 FlowIO 可读取使用该方式的旧版文件。
创建 FCS 3.1 文件：准备 float32 的二维数组，用 values.ravel(order="C") 展平，提供 pnn_labels 与可选 pns_labels，以 "xb" 模式打开输出文件后调用 create_fcs()，metadata_dict 的值必须是字符串。资料给出写入后重新打开校验事件数、通道标签与数值的往返示例。
复制或重写已有文件：事件数据不变时可用 flow.write_fcs("copy.fcs")，它会保留所选源元数据（cyt、date 以及存在时的 spill/spillover）；传入 metadata 字典（包括 {}）会替换默认值而非合并。write_fcs() 始终输出 FCS 3.1 浮点结果，非浮点源事件会先被预处理；它以覆盖方式打开目标文件，调用前应拒绝已存在的输出路径，除非确实要替换。对浮点源，它可能保留编码事件但丢弃 PnG 或 timestep，从而改变后续 as_array(preprocess=True) 的结果，应同时校验原始与预处理往返。当事件值、事件数或通道布局变化时，应改用 create_fcs()。
内置检查脚本：scripts/inspect_fcs.py 可在无网络访问下盘点一个或多个数据集，默认只读元数据，输出结构字段与通道标签而不含完整 TEXT/ANALYSIS 值，并拒绝超过可配置大小上限的文件。设置 FLOWIO_SKILL_DIR 为已安装技能目录后，可用 uv run --no-project --with "flowio==1.4.0" python "$FLOWIO_SKILL_DIR/scripts/inspect_fcs.py" sample.fcs 运行；--include-text 包含全部规范化 TEXT 元数据，--stats 加载事件并计算有限值统计，--raw 则基于编码值计算统计。--help 可查看输出文件、输入/数组内存限制、空通道标签与受控偏移恢复选项。
参考资料
资料列出按需阅读的参考文件：references/api_reference.md（FlowIO 1.4.0 公共 API 与签名）、references/workflows.md（盘点、DataFrame/CSV、批处理、写入与往返模式）、references/fcs_semantics.md（FCS 结构、元数据规范化、预处理公式、索引与写入行为）、references/troubleshooting.md（偏移失败、多数据集文件、内存限制、校验、安全与隐私）、references/sources.md（上游权威文档、发布说明、源码与 FCS 3.1 出版物）。
适用场景与限制
适用场景包括：低层级 FCS 元数据与通道检查、将事件数据转为 NumPy 数组以供 pandas 或机器学习使用、读取旧版多数据集文件、写出 FCS 3.1 单精度文件、为下游流式细胞术工具准备数据。
限制与注意事项：不执行补偿、门控、聚类或 FlowJo 工作区处理；as_array(preprocess=True) 的结果不应视为原始采集值；不能把二维数组或路径直接传给 create_fcs()；不能假设 TEXT 键保留 $ 或大写拼写；不应在未记录原因并校验数据的情况下静默忽略偏移错误；事件加载不是流式或分块方式。资料还强调元数据可能敏感（TEXT 值可能含样本、受试者、操作者与仪器标识），只导出任务所需字段；写入后应重新打开校验事件/通道数、标签、元数据与代表性数值。
代理操作流程与完整性规则
资料给出代理操作流程：检查环境（确认工具版本、参考基因组/注释构建与输入格式如 FASTQ、BAM、VCF、h5ad）；明确输入（从数据或用户确认格式、标识符与参数，不确定时询问而非猜测）；先小规模运行（单样本、单染色体或几千个细胞）；按说明与参考执行完整任务；校验结果（QC 指标、样本身份、基因组构建一致性、批次效应）；报告运行内容（版本、命令、参数）、已检查项与仍不确定项。若输入间基因组构建或标识符不匹配，应停止并先协调（liftover、ID 映射）；若说明中的函数、标志或端点在被安装版本中缺失，应查阅该版本自身文档并告知用户，绝不虚构 API；若必需输入、标识符或参数有歧义，应询问用户或明确说明假设后再运行。完整性规则要求：绝不编造结果、参数、标识符、引用或统计；无法运行或验证时如实说明；不超出统计支持范围解读生物学意义，并报告多重检验校正；版本相关细节可能过时，应以已安装版本的官方文档为准；在涉及花钱、占用共享 GPU 或云配额、触碰个人或患者数据、或不可撤销的操作前先询问。