flow-er gating models

Per-gate U-Net models that place flow cytometry gates, used by flow-er: flow cytometry gating that learns each lab's own gates from its data.

Each model answers one gate. It takes the 101 x 101 density image of the gate's parent cells on the gate's two channels and returns, per pixel, the probability of being inside the gate. The architecture is reimplemented from the UNITO paper (Chen, Ionita et al., Nature Communications 2025, PMC11821879): 1 input channel, widths 64-128-256-512, bottleneck 1024, 31.0M parameters. These are not the UNITO authors' weights and no UNITO code is used.

What is here

The folders mirror flow-er's MODELS_DIR, so a download drops straight in:

als/unito_gpu/<gate_id>/        11 per-gate models (model.pt + recipe.json), human ALS ICS panel
labs/als/                       lab "als": template (16 gates), current version v003
labs/mo280/                     lab "mo280" (mouse, 33 gates): v001 points each mouse gate at a human
                                model; v004 (current) is those models adapted by three rounds of
                                flow-er's retrain loop. v002 and v003 are kept as history (their
                                held-out errors and per-gate decisions); their weights were not kept

The mouse lab's adapted weights (labs/mo280/v00*/gates/) are stored as float16, half the size; flow-er loads them into float32.

recipe.json records each model's channels, image recipe, training individuals, hyperparameters and validation Dice. version.json maps each gate to its model, with the retrain decisions and held-out errors. A gate without a model uses template copy (the lab's template polygon).

Use

pip install -U huggingface_hub
hf download <your-username>/flow-er --local-dir path/to/models     # next to the flow-er repo
cd flow-er/backend && uv run python scripts/check_models.py verify

Then ml.autogate(fcs_path, tree, lab="als") (see the repo's docs/runtime-api.md).

Results

Mean |model % of parent - expert %| in percentage points (lower is better), on data never used in training, against the expert's FlowJo gates read with FlowKit:

Test	Template copy	These models
6 unseen human donors (ALS ICS, another screen), 7 gates	1.08 pp	0.93 pp
The same donors, 4 cytokine gates	0.65 pp	0.27 pp
Mouse lab mo280 on never-taught mice: v001 (human models) then three retrain rounds	3.00 pp	25.1 -> 5.3 -> 4.0 -> 1.35 pp

Training data (credit when used)

• Human: ALS ICS study, screens 3 and 4 (Zenodo 16754591, 16754609), CC BY 4.0. Lab als v003: 8 donors.
• Mouse: MO280 aorta/liver/spleen/blood (Figshare 32996177), CC BY 4.0. Lab mo280 learned from blood + spleen of mice 1, 3, 5, 9, 11, 13 and liver + aorta of mice 2, 4, 10, 14.

Individual ids in the recipes (e.g. human:2008) are the public datasets' own group ids.

Limits

• A gate model only fits the panel and gate it was trained for; a new panel starts from template copy or from a similar gate and is adapted by retraining on the lab's kept gates.
• Small test sets (6 donors, 4-6 mice). Research software; not for clinical use.