flowio

FlowIO

目的

FlowIO を、フローサイトメトリー標準ファイル用の軽量な低レベルリーダーおよびライターとして使用します。このスキルの例は、2026-07-23 に確認された現行の安定版である FlowIO 1.4.0 を対象としています。

FlowIO は、次の用途に適しています。

• FCS 2.0、3.0、3.1 ファイルの読み込み
• HEADER、TEXT、ANALYSIS、およびチャンネルのメタデータの確認
• イベントデータを二次元の NumPy 配列として取得
• 複数のデータセットを含むレガシーファイルの読み込み
• リストモードの単精度 FCS 3.1 ファイルの書き込み
• pandas、機械学習、または後続のサイトメトリーツール向けのデータ準備

FlowIO は、補正、logicle／双指数変換、ゲーティング、クラスタリング、または 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 に依存します。

操作ワークフロー

1. 操作内容を明確にします。 メタデータの一覧表示、イベントの抽出、ファイルの修復、変換、および後続の生物学的解析を区別します。
2. イベントを読み込む前に確認します。 特に大きなファイルや不慣れなファイルでは、メタデータのみを扱う作業に only_text=True を使用します。
3. イベントの解釈方法を明示的に選択します。 FCS メタデータに基づくゲイン／対数／時間のスケーリングには as_array(preprocess=True) を、DATA セグメントにエンコードされた値には preprocess=False を使用します。選択した方法を記録してください。
4. デフォルトでは厳密な解析を維持します。 オフセットエラーを自動的に無視しないでください。既知のベンダー形式の不具合に限ってチェックを緩和し、その場合は結果のイベントデータを確認します。
5. メタデータには機密情報が含まれる可能性があるものとして扱います。 FCS の TEXT 値には、サンプル、被験者、オペレーター、および装置の識別情報が含まれる場合があります。作業に必要なフィールドのみをエクスポートしてください。
6. 書き込み後は再度開いて検証します。 FCS をエクスポートした後は、イベント数／チャンネル数、ラベル、メタデータ、および代表的な値を確認してください。

重要な仕様

TEXT キーは正規化されます

FlowData.text は、キーを小文字に変換し、標準 FCS キーワードの先頭にある $ を取り除いて格納します。

from flowio import FlowData

flow = FlowData("sample.fcs", only_text=True)
acquisition_date = flow.text.get("date")
instrument = flow.text.get("cyt")
next_dataset = int(flow.text.get("nextdata", "0"))

"$DATE"、"$CYT"、その他の大文字で $ が先頭に付くキーを検索しないでください。TEXT の値は文字列のままです。また、FlowIO 1.4.0 は、値の中にある $ を含め、デコードされた TEXT セグメントからすべての $ 文字を削除します。メタデータの完全な忠実性が重要な場合は、元のファイルを保持してください。

イベントには 2 種類の表現があります

• flow.events は、未処理の一次元に平坦化されたイベント配列です。
• flow.as_array() は、NumPy の float64 配列として形状 (event_count, channel_count) を返します。
• flow.as_array(preprocess=True) は、FCS のゲイン、対数、および時間のスケーリングを適用します。補正や logicle／双指数表示変換は適用しません。
• flow.as_array(preprocess=False) は、これらのスケーリング処理を行わずに、エンコードされたイベント値を整形し直します。

as_array() は、メモリ上に別の配列を作成します。FlowIO は、イベントへのチャンク単位またはメモリマップによるアクセスを提供しません。

チャンネル番号には 2 種類の方式があります

• 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() には、次のものが必要です。

• すでに開かれているバイナリファイルハンドル
• 行優先のイベント／チャンネル順で平坦化された一次元イベントデータ
• チャンネルごとに 1 つの PnN 名
• 省略可能な PnS 名と、metadata_dict を通じて指定する文字列値のメタデータ

FCS 3.1 のリストモード（$MODE=L）による単精度浮動小数点（$DATATYPE=F）データを書き込みます。必須の解釈キーワードは FlowIO が生成するため、メタデータから上書きできません。

クイックスタート：FCS ファイルを読み込む

from pathlib import Path

from flowio import FlowData

flow = FlowData(Path("sample.fcs"))
events = flow.as_array(preprocess=True)

print(
    {
        "version": flow.version,
        "events": flow.event_count,
        "channels": flow.channel_count,
        "shape": events.shape,
        "pnn": flow.pnn_labels,
        "pns": flow.pns_labels,
        "date": flow.text.get("date"),
        "instrument": flow.text.get("cyt"),
    }
)

メタデータのみを読み込む場合：

from flowio import FlowData

flow = FlowData("sample.fcs", only_text=True)
print(flow.version, flow.event_count, flow.pnn_labels)

メタデータのみを読み込んだインスタンスではイベントデータが読み込まれていないため、as_array() を呼び出さないでください。

呼び出し元が所有するファイルハンドルより、パスまたは Path を使用してください。FlowData は解析後に渡されたファイルハンドルを閉じます。FlowIO 1.4.0 では、read_multiple_data_sets(handle) は最初のデータセットの読み込み後にファイルハンドルが閉じられるため、失敗することがあります。複数のデータセットを含むファイルでは、ファイルシステム上のパスを渡してください。

クイックスタート：複数のデータセットを読み込む

$NEXTDATA オフセットを手動で解釈するのではなく、スタンドアロンのヘルパーを使用してください。

from flowio import read_multiple_data_sets

datasets = read_multiple_data_sets("legacy-multi-dataset.fcs")
for index, dataset in enumerate(datasets):
    values = dataset.as_array(preprocess=True)
    print(index, dataset.event_count, dataset.pnn_labels, values.shape)

FCS 3.1 仕様では、1 つのファイルに複数のデータセットを格納する方式は非推奨になりましたが、FlowIO はこの方式を使用するレガシーファイルを読み込めます。

クイックスタート：FCS 3.1 ファイルを作成する

from pathlib import Path

import numpy as np
from flowio import FlowData, create_fcs

values = np.asarray(
    [[100.0, 200.0, 50.0], [150.0, 180.0, 60.0]],
    dtype=np.float32,
)
pnn_labels = ["FSC-A", "SSC-A", "FITC-A"]
pns_labels = ["Forward scatter", "Side scatter", "CD3"]

output = Path("output.fcs")
with output.open("xb") as handle:
    create_fcs(
        handle,
        values.ravel(order="C"),
        pnn_labels,
        opt_channel_names=pns_labels,
        metadata_dict={
            "date": "23-JUL-2026",
            "cyt": "Example instrument",
            "src": "Validated NumPy array",
        },
    )

roundtrip = FlowData(output)
assert roundtrip.event_count == values.shape[0]
assert roundtrip.pnn_labels == pnn_labels
np.testing.assert_allclose(
    roundtrip.as_array(preprocess=False),
    values,
    rtol=1e-6,
    atol=1e-6,
)

メタデータキーは大文字と小文字が混在した形式や $ 付きでも指定できますが、FlowIO の正規化された表現と一致する $ なしの小文字キーを使うと、誤りが起きにくくなります。メタデータの値は文字列である必要があります。

既存ファイルをコピーまたは書き換える

イベントデータを変更する必要がない場合は、write_fcs() を使用してください。

from flowio import FlowData

flow = FlowData("source.fcs")

# Preserve selected source metadata (cyt, date, and spill/spillover when present).
flow.write_fcs("copy.fcs")

# Write only required metadata plus the custom fields supplied here.
flow.write_fcs("deidentified.fcs", metadata={"src": "Deidentified export"})

metadata=None を渡すと、FlowIO が選択したデフォルト設定が保持されます。{} を含む任意の辞書を渡すと、デフォルト設定とのマージではなく、それらが置き換えられます。write_fcs() は常に FCS 3.1 の浮動小数点形式で出力します。浮動小数点以外のソースイベントは、書き込み前に前処理されます。出力先は上書きモードで開かれるため、意図的に置き換える場合を除き、呼び出す前に出力先のパスがすでに存在しないことを確認してください。浮動小数点形式のソースでは、エンコード済みイベントを保持しつつ、PnG または timestep を削除することがあり、その結果、後の as_array(preprocess=True) の結果が変わる場合があります。未加工データと前処理済みデータの両方でラウンドトリップを検証してください。

イベント値、イベント数、またはチャンネルの配置を変更する場合は、代わりに create_fcs() を使用してください。

同梱のインスペクター

scripts/inspect_fcs.py は、ネットワークにアクセスせずに 1 つ以上のデータセットを一覧表示します。デフォルトではメタデータのみを読み込み、TEXT/ANALYSIS の値全体を出力せずに構造フィールドとチャンネルラベルを出力し、設定可能なサイズ上限を超えるファイルは拒否します。

FLOWIO_SKILL_DIR にインストール済みスキルのディレクトリを設定してください。このリポジトリのルートからは、skills/flowio を使用してください。

FLOWIO_SKILL_DIR="skills/flowio"

# Metadata and channel inventory
uv run --no-project --with "flowio==1.4.0" \
  python "$FLOWIO_SKILL_DIR/scripts/inspect_fcs.py" sample.fcs

# Include all normalized TEXT metadata; review output for identifiers
uv run --no-project --with "flowio==1.4.0" \
  python "$FLOWIO_SKILL_DIR/scripts/inspect_fcs.py" sample.fcs --include-text

# Load events and compute finite-value statistics using FlowIO preprocessing
uv run --no-project --with "flowio==1.4.0" \
  python "$FLOWIO_SKILL_DIR/scripts/inspect_fcs.py" sample.fcs --stats

# Compute statistics from encoded values instead
uv run --no-project --with "flowio==1.4.0" \
  python "$FLOWIO_SKILL_DIR/scripts/inspect_fcs.py" sample.fcs --stats --raw

出力ファイル、入力／配列のメモリ上限、null チャンネルのラベル、制御されたオフセット復旧オプションについては、--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 の出版物

必須の確認事項

• FlowIO が補正やゲーティングを適用すると主張しないでください。
• as_array(preprocess=True) を生の取得値として扱わないでください。
• 二次元配列やパスを create_fcs() に直接渡さないでください。
• TEXT キーが $ や大文字表記を保持すると想定しないでください。
• オフセットエラーを、理由の説明やデータの検証なしに無視しないでください。
• FlowIO のイベント読み込みをストリーミングまたはチャンク処理と説明しないでください。

エージェントの作業手順

1. 環境を確認します。 ツールのバージョン、参照ゲノム／アノテーションのビルド、および入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を特定します。 データまたはユーザーに確認して、形式、識別子、パラメーターを確定します。結果に影響する値は推測せず、質問してください。
3. まず小規模に実行します。 最初に、小さなサブセット（1サンプル、1染色体、数千個の細胞）でパイプラインを実行します。
4. 上記の手順と参照情報を使用して、タスク全体を実行します。
5. 結果を検証します。 結果を解釈する前に、QC 指標、サンプルの同一性、ゲノムビルドの整合性、バッチ効果を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未解決の点を明示します。

次の状況が発生した場合	対応
入力間でゲノムビルドまたは識別子が一致しない	続行する前に停止し、調整します（liftover、ID マッピング）。
インストール済みバージョンに、これらの手順に記載された関数、フラグ、またはエンドポイントがない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、適宜対応してユーザーに伝えます。API を決してでっち上げないでください。
必須の入力、識別子、またはパラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

インテグリティに関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しないでください。実行または検証できない場合は、その旨を明確に伝えます。
• 統計的な裏付けを超えて生物学的意義を解釈しないでください。多重検定補正について報告します。
• ここに記載されたバージョン固有の詳細は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する操作、共有 GPU やクラウドクォータを消費する操作、個人データまたは患者データに触れる操作、あるいは取り消せない操作を行う前に、確認してください。