flowkit

FlowKit

使用する場面

FlowKit は、サイトメトリーのゲーティング戦略を適用または構築したり、FCS サンプルのバッチを解析したり、対応している FlowJo ワークスペース解析を再現したりするために使用します。GatingML 2.0 と FlowJo 10 の機能の一部 をサポートしています。インポートが成功しただけでは、FlowJo との一致が確立されたことにはなりません。

例と同梱のヘルパーは、Python 3.13 上の FlowKit 1.3.2 を対象としています。上流では追加の Python バージョンもサポートされていますが、ここでは検証していません。ヘルパーと例は合成 FCS データでテストされており、公開されている FlowJo 10.7.1 の合成ワークスペースフィクスチャも含まれます。これらは生物学的な検証ではありません。

インストール

別の環境を使用してください。FlowKit 1.3.2 には NumPy >2 と pandas <3 が必要です:

uv venv --python 3.13 .venv-flowkit
uv pip install --python .venv-flowkit/bin/python "flowkit==1.3.2"
.venv-flowkit/bin/python -c "import flowkit; print(flowkit.__version__)"

この科学パッケージは BSD-3-Clause ライセンスで、このスキルは MIT ライセンスです。

ワークフロー

1. 解析定義を特定します。 プログラムによる戦略または GatingML 戦略には Session を使用し、FlowJo のサンプル固有のゲート、補正、変換には Workspace を使用します。生物学的なしきい値が提供されていない場合は、実際の戦略またはコントロールを要求してください。
2. サンプルとチャネルの識別情報を確認します。 検出器/PnN ラベルを補正マトリクスとゲートの次元に照合します。PnS マーカー名は空だったり、重複していたりする場合があります。サンプル ID を検証してください。既定では FCS の $FIL が使われますが、これは現在のファイル名と異なる場合があります。バッチを読み込む前に ID の衝突を拒否してください。
3. 座標系を確立します。 提供されたイベントがすでに補正済みかどうかを判断します。非線形変換の前に補正を適用し、ゲートのしきい値を同じ変換済みまたは未変換の座標に合わせます。補正とゲーティングを参照してください。
4. 階層を確認します。 root を含む親ゲートと完全なゲートパスを保持します。研究の場合、そのパネルに応じて取得/時間安定性、デブリ除外、シングレット、生存率、表現型ゲートを確認します。補正には単染色コントロールを、陽性判定には適切な陰性/FMO コントロールを使用してください。デモ用のしきい値はそのまま移せる生物学ではありません。
5. 解析して確認します。 すべてのイベントで実行し、その後ゲートのオーバーレイとサンプルレベルの QC を確認します。プロットのサブサンプルは母集団の分母ではありません。警告を確認し、代表的なインポート結果を FlowJo と比較してください。
6. 分母と来歴を付けてカウントをエクスポートします。 ゲートパス、サンプル ID、総イベント数、入力ハッシュ、パッケージバージョン、解析定義を保持します。生物学的反復を識別可能な状態に保ってください。1 つの検体からのイベントは独立した実験的反復ではありません。

既存の戦略を適用する

FLOWKIT_SKILL_DIR をこのスキルのインストール先ディレクトリに設定します。リポジトリのルートからは skills/flowkit です。以下のパスはユーザーのローカル入力を表します。

FLOWKIT_SKILL_DIR="skills/flowkit"
uv run --no-project --python 3.13 --with "flowkit==1.3.2" \
  python "$FLOWKIT_SKILL_DIR/scripts/analyze_gates.py" \
  --gatingml gates.xml --fcs sample.fcs --output-dir results-gatingml

FlowJo ワークスペースの場合は、選択したグループ内のすべての FCS ファイルを指定してください:

uv run --no-project --python 3.13 --with "flowkit==1.3.2" \
  python "$FLOWKIT_SKILL_DIR/scripts/analyze_gates.py" \
  --workspace study.wsp --group "Study" \
  --fcs sample-a.fcs sample-b.fcs --output-dir results-workspace

ヘルパーは gate_report.csv と provenance.json を新しいディレクトリに書き出します。各行には sample_event_count、parent_event_count、完全な population_path が含まれます。親が空の場合のパーセンテージは空白になり、relative_percent_defined=False でフラグが付けられます。重複するサンプル ID、ワークスペースグループに存在しない/余分なサンプル、イベント数ゼロのサンプル、ゲートのない戦略は拒否されます。明示的な入力ファイルを使用し、ワークスペースに埋め込まれたパスには従わず、マルチプロセシングや変換済みイベントのキャッシュなしで実行されます。それでも各サンプルをメモリに読み込みます。大規模な研究では Python API を通じて扱いやすいバッチに分けてください。

--filename-as-id は $FIL からファイルのベース名へ意図的に切り替えます。これらの名前が解析定義と一致する場合にのみ使用してください。部分グループの解析、結果の解釈、蛍光サマリーについては、ワークスペース解析を参照してください。

Python でストラテジーを構築する

この実行可能な例では、sample.fcs を FSC-A、FL1-A、FL2-A とともに使用します。 マトリクス、しきい値、変換パラメータは合成の教材用の値です。研究で検証済みの設定に置き換えてください。

import flowkit as fk
import numpy as np

sample = fk.Sample("sample.fcs")
strategy = fk.GatingStrategy()
strategy.add_comp_matrix(
    "spill", fk.Matrix(
        np.array([[1.0, 0.1], [0.2, 1.0]]), ["FL1-A", "FL2-A"],
        fluorochromes=["FITC", "PE"],
    )
)
logicle = fk.transforms.LogicleTransform(
    param_t=262144, param_w=0.5, param_m=4.5, param_a=0
)
strategy.add_transform("logicle", logicle)
strategy.add_gate(
    fk.gates.RectangleGate("Cells", [
        fk.Dimension("FSC-A", range_min=50, range_max=300)
    ]),
    gate_path=("root",),
)
thresholds = logicle.apply(np.array([50.0, 600.0]))
strategy.add_gate(
    fk.gates.RectangleGate("Positive", [
        fk.Dimension(
            "FL1-A", compensation_ref="spill", transformation_ref="logicle",
            range_min=float(thresholds[0]), range_max=float(thresholds[1]),
        )
    ]),
    gate_path=("root", "Cells"),
)
session = fk.Session(gating_strategy=strategy, fcs_samples=[sample])
session.analyze_samples(use_mp=False)
report = session.get_analysis_report()
print(report[["sample_id", "gate_path", "gate_name", "count",
              "absolute_percent", "relative_percent"]])
with open("gates.xml", "xb") as handle:
    session.export_gml(handle)

GatingML はデフォルトでテンプレートをエクスポートします。サンプルごとのカスタムゲートが存在する場合は、そのサンプルのストラテジーに対して session.export_gml(handle, sample_id=sample.id) を使用してください。単一のテンプレートのエクスポートでは、サンプル固有のすべてのオーバーライドは保持されません。

解釈の確認事項

• count は、ゲートおよびその祖先ゲートを通過したイベントの数です。
• absolute_percent は全サンプルイベントに対する割合です。relative_percent は 直接の親に対する割合です。これらはパーセンテージであり、分数ではありません。
• ゲート名は異なる親の下で繰り返すことがあります。ヘルパーの出力では、 識別子として (sample_id, population_path) を使用してください。パスは CSV セル内の JSON 配列です。FlowKit のネイティブレポートでは、象限の所有者を quadrant_parent に別途保存します。gate_path だけではその所有者が省略されます。
• 親のイベント数がゼロの場合、子のパーセンテージは生物学的に未定義となります。 FlowKit 1.3.2 では、通常の子にはゼロを、象限には NaN を報告します。 ヘルパーは両方を空白としてエクスポートし、明示的な false フラグを付けます。これは、 親にイベントが含まれる空のゲートに対する定義済みの 0% とは異なります。
• 補正後の負の蛍光は正当なものです。対数変換を可能にするためだけに、 それをゼロにクリップしたり、それらのイベントを破棄したりしないでください。
• 「MFI」が平均を意味するのか中央値を意味するのかを定義し、イベントソースを 明記してください。変換後の表示値は、元のスケールにおける強度ではありません。

参考文献

• 補正とゲーティング: イベント ソース、検出器の順序、変換のセマンティクス、ゲートパス、プロット。
• ワークスペースと結果: サンプル のマッチング、欠落した FCS ファイル、FlowJo の制限、ゲート済み蛍光の要約。
• FlowKit API および バージョン付きソース: テスト済みの リリースを超えて使用する場合は、シグネチャを参照してください。
• FlowKit の論文: 解析に使用する場合は、 科学的方法においてソフトウェアとバージョンを引用してください。