FlowKit

FlowKit provides a structured learning path through a series of notebooks that cover the core object model and functional modules. The series progresses from basic class definitions to complex session and workspace management:

1. Sample Class: Introduction to the fundamental data structures.
2. Transforms Module & Matrix Class: Working with mathematical transformations and matrix operations.
3. Gating Strategy & Gating Results: Understanding how to define and store gating logic and its outcomes.
4. Gates Module: Using the gates module for population analysis.
5. Session Class: Managing data sessions.
6. Workspace Class: Organizing multiple sessions and data within a workspace.

To install FlowKit from the source repository, clone the repository and ensure your pip is up-to-date before installing the local package.

Note for macOS Apple Silicon users: You may need to upgrade pip prior to installation to ensure required dependencies install correctly.

git clone https://github.com/whitews/flowkit
cd flowkit
pip install --upgrade pip
pip install .

FlowKit provides extensive learning resources through Jupyter notebooks:

Tutorials

Located in the docs/notebooks directory, these cover:

• Part 1: Sample Class
• Part 2: transforms Module & Matrix Class
• Part 3: GatingStrategy & GatingResults Classes
• Part 4: gates Module
• Part 5: Session Class
• Part 6: Workspace Class

Advanced Examples

Located in docs/notebooks/advanced, these include practical workflows such as:

• Comparing Mean Fluorescence Intensity (MFI) in gated populations.
• Replicating FlowJo 10 WSP analysis in FlowKit.
• Boolean combinations of gates.
• Dimension reduction on gated populations.
• Clustering comparisons (Leiden vs Louvain).
• Saving data as AnnData objects for ScanPy.

Before performing downstream analysis like clustering, you should analyze the samples within the workspace and then extract specific gated populations into pandas DataFrames. This allows you to filter for relevant cell populations (e.g., live single cells) and remove unwanted data like doublets or dead cells.

1. Call workspace.analyze_samples(sample_group) to process the data.
2. Use workspace.get_gate_events(sample_id, gate_name="...") to retrieve the events for a specific gate as a DataFrame.

# 1. Analyze the samples in a specific group
workspace.analyze_samples(sample_group)

# 2. Extract events for a specific gate across multiple samples
dfs = []
for sample_id in sample_ids:
    df = workspace.get_gate_events(sample_id, gate_name="aAmine-")
    dfs.append(df)

To begin analyzing flow cytometry data, create a flowkit.Workspace object by providing the path to a FlowJo .wsp workspace file and the directory containing the .fcs sample files. This object serves as the central entry point for accessing sample groups, sample IDs, and gate hierarchies.

import flowkit as fk
import os

base_dir = "../../../data/8_color_data_set/"
sample_path = os.path.join(base_dir, "fcs_files")
wsp_path = os.path.join(base_dir, "8_color_ICS.wsp")

workspace = fk.Workspace(wsp_path, fcs_samples=sample_path)

For complex workflows, FlowKit provides advanced notebooks covering specialized analysis tasks:

• Clustering Comparison: Comparing Leiden vs. Louvain clustering algorithms.
• Dimension Reduction: Performing dimensionality reduction specifically on gated populations.
• MFI Comparison: Comparing Median Fluorescence Intensity (MFI) of gated events.
• FlowJo Replication: Replicating .wsp (FlowJo Workspace) files.
• Boolean Logic: Implementing boolean combinations of gates.
• Scanpy Integration: Creating and using AnnData objects within the Scanpy ecosystem.

The easiest way to install FlowKit is using pip from the Python Package Index.

pip install flowkit

GML (GatingML) gate classes are specialized internal implementations used to convert XML-based GatingML elements into an intermediate gate representation.

Key characteristics of GML gates:

• Tree Assembly: Unlike standard gate classes, GML gates retain a parent reference, which is used to assemble the gate tree from XML data.
• Conversion: GML gates provide a convert_to_parent_class() method. This method should be called to transform the GML-specific instance into its corresponding public-facing parent class (e.g., converting a GMLRectangleGate into a RectangleGate) for use in a GatingStrategy.

The GatingStrategy handles different gate types with specific logic during the gate_sample process:

• BooleanGate: These gates require a DataFrame of results from their referenced gates (gate_refs). The strategy retrieves the events from each reference and passes them as a pd.DataFrame to the gate's apply method.
• QuadrantGate: These gates split the results into multiple quadrants. When a gate's parent is a QuadrantGate, the strategy correctly resolves the quadrant-specific results to ensure hierarchical gating (logical AND between parent quadrant and child gate) is maintained.
• Standard Gates: For other gate types, the strategy performs event pre-processing (compensation and transformation) before calling the gate's apply method.