FLow cytometry Automated Gating - toolboX

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

• Data loading (FCS/CSV → AnnData)

• Alignment of channel names across 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.

FLAG-X API

• FLAG-X API
  • flagx.pipeline
  • flagx.gating
  • flagx.io
  • flagx.dimred

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, install flagx, and activate:

  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:

  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 by following the instructions at PyTorch get started.

Usage examples

For usage examples please refer to GitHub.

License

This project is licensed under the GNU General Public License v3.0.