alterlab-flowio

FlowIO：フローサイトメトリー標準ファイルハンドラー

概要

FlowIO は、フローサイトメトリー標準（FCS）ファイルの読み取りと書き込みを行う、軽量な Python ライブラリです。FCS メタデータを解析し、イベントデータを抽出して、最小限の依存関係で新しい FCS ファイルを作成できます。FCS バージョン 2.0、3.0、3.1 に対応しており、バックエンドサービス、データパイプライン、基本的なサイトメトリーファイル操作に最適です。

このスキルを使用するタイミング

次のような場合にこのスキルを使用します。

• FCS ファイルの解析やメタデータの抽出が必要な場合
• フローサイトメトリーデータを NumPy 配列に変換する必要がある場合
• イベントデータを FCS 形式にエクスポートする必要がある場合
• 複数のデータセットを含む FCS ファイルを分割する必要がある場合
• チャネル情報（散乱、蛍光、時間）の抽出が必要な場合
• サイトメトリーファイルの検証や確認が必要な場合
• 高度な解析の前に前処理が必要な場合

関連ツール： 補償、変換、ゲーティング、FlowJo 10 ワークスペースのインポートなど、高度な解析には、同じ作者が FlowIO を基に構築した FlowKit ライブラリ（2026-09 時点で 1.3.2）を推奨します。

対象外のケース

ケース	代わりに使用
補償、変換、ゲーティング、または 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、ウェブアプリ）。

概要

FlowIO は、フローサイトメトリーのワークフローに不可欠な FCS ファイル処理機能を提供します。解析、メタデータの抽出、ファイルの作成に使用できます。シンプルなファイル操作やデータ抽出には FlowIO のみで十分ですが、複雑な解析（補正、ゲーティング）には FlowKit などの専用ツールを組み合わせてください。

AlterLab Academic Skills スイートの一部です。