flowkit

FlowKit

何时使用

使用 FlowKit 应用或构建流式细胞术门控策略、分析批量 FCS 样本，或复现受支持的 FlowJo workspace 分析。它支持 GatingML 2.0 以及 FlowJo 10 功能的子集。仅导入成功并不 意味着与 FlowJo 结果一致。

示例和随附的辅助脚本针对 Python 3.13 上的 FlowKit 1.3.2。 上游支持额外的 Python 版本；此处未对这些版本进行验证。 辅助脚本和示例已在合成 FCS 数据上测试，包括一个公开的 FlowJo 10.7.1 合成 workspace 测试样本。它们并非生物学验证。

安装

使用独立环境；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. 检查样本和通道标识。 将 detector/PnN 标签与 补偿矩阵和门控维度匹配；PnS 标记名称可能为空或 重复。验证样本 ID：默认值为 FCS $FIL，它可能与 当前文件名不同。在加载批次之前拒绝 ID 冲突。
3. 建立坐标系。 确定所提供的事件 是否已经过补偿。在非线性变换之前应用补偿； 将门控阈值匹配到相同的变换后或未变换坐标。 参见 补偿与门控。
4. 检查层级结构。 保留父门和完整门路径，包括 root。对于研究，根据其 panel 酌情审查采集/时间稳定性、碎片排除、 单细胞门、活性门和表型门。使用 单染对照进行补偿，使用合适的阴性/FMO 对照 判断阳性；示范阈值并非可迁移的生物学。
5. 分析并检查。 对所有事件运行，然后检查门控叠加图和 样本级 QC。图上的子采样不是群体分母。 审查警告并将代表性导入结果与 FlowJo 比较。
6. 导出计数及分母和来源信息。 保留门路径、 样本 ID、总事件数、输入哈希、包版本以及 分析定义。保持生物学重复可识别；来自 一个样本的事件不是独立的实验重复。

应用现有策略

将 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 workspace，提供所选组中的每个 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、缺失/多余的 workspace 组样本、 零事件样本以及没有门的策略。它使用显式输入文件， 不跟随 workspace 中嵌入的路径，并且运行时不使用 多进程或变换后事件缓存。它仍会将每个样本加载到 内存中；对于大型研究，请通过 Python API 使用可管理的批次。

--filename-as-id 会故意从 $FIL 切换到文件基名。仅当 这些名称与分析定义匹配时才使用它。关于部分组 分析、结果解释和荧光摘要，参见 workspace 分析。

用 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 出版物：在用于 分析时，请在科学方法中引用该软件及其版本。