FLow cytometry Automated Gating - toolboX (FLAG-X)

FLAG-X is a Python toolbox for automated, end-to-end cytometry data processing, including:

• Data loading (FCS/CSV → AnnData)
• Alignment of channel names arcoss samples
• Sample-wise preprocessing
• Train/(val)/test splitting on the sample level
• Sample-wise downsampling of training data
• Model Training MLP (supervised), SOM (supervised or unsupervised)
• Model saving
• Inference on new data:
  • Dimensionality reduction (SOM, UMAP, t-SNE, PCA, etc.)
  • Automated gating (cell type prediction)
  • Export of annotated samples to FCS format for downstream analysis using standard flow-cytometry tools.

FLAG-X provides a streamlined pipeline and a command line interface (CLI) for users with little programming experience.

Installation

• Using conda or mamba:

  Ensure correct channel priority:

  conda config --show channels
  conda config --show channel_priority

  Should show:

  channels:
    - conda-forge
    - bioconda
    - defaults
  
  channel_priority: strict

  Create environment, activate, and install flagx:

  mamba create -n flagx-env -y
  mamba activate flagx-env
  mamba install flagx -y

  To enable PyTorch-based functionality (e.g. MLPClassifier) install torch according to your system's requirements (see: PyTorch get started).

  For example:

  # v2.9.1, Linux, CUDA 12.8
  pip install torch
  
  # v2.9.1, Linux, CUDA 12.6
  pip install torch --index-url https://download.pytorch.org/whl/cu126
  
  # v2.9.1, Linux, CPU only
  pip install torch --index-url https://download.pytorch.org/whl/cpu

• From source using conda or mamba and pip:

  git clone git@github.com:bionetslab/FLAG-X.git
  cd FLAG-X
  mamba env create -f environment.yml
  mamba activate flagx
  pip install -e .

• From source using pixi:

  git clone git@github.com:bionetslab/FLAG-X.git
  cd FLAG-X
  pixi install

NOTE: The environments provided in this project install the CPU-only version of PyTorch. Users who require GPU acceleration must install a CUDA-enabled PyTorch build themselves following the instructions at PyTorch get started.

Documentation

Full documentation is available on Read the Docs.

CLI usage example

• Install flagx, see Installation.
• Create a config.yml for GatingPipeline initialization and model training according to flagx.GatingPipeline's signature. For examples see init_train_save_som_config.yml and init_train_save_mlp_config.yml.
• Initialize the GatingPipeline, train, and save:

  flagx init-train-save --config ./example_configs/init_train_save_som_config.yml

• Create a config.yml to load a trained pipeline, perform automated gating, compute dimensionality reductions, and export results to FCS according to flagx.GatingPipeline.inference()'s signature. For examples see load_infer_save_som_config.yml and load_infer_save_mlp_config.yml.
• Load trained GatingPipeline and run inference on new data:

  flagx load-infer-save --config ./example_configs/load_infer_save_som_config.yml

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.