CytoDraft is a desktop application for flow cytometry data analysis. It loads .fcs files, displays scatter plots and histograms, and lets the user define interactive gates directly on the plot.
The current MVP is focused on the core manual workflow used during exploratory cytometry analysis:
- Load one or many FCS samples into the same workspace
- Organize samples into groups such as specimens, controls, unstained, or compensation
- Create hierarchical gates interactively on scatter and histogram views
- Reuse gates across samples, across a group, or across the full workspace
- Calculate per-population statistics and export gated events
CytoDraft is meant to be fast to use at the bench or during analysis sessions, with minimal setup and a UI centered on the gating workflow rather than on pipeline scripting.
Flow cytometry analysis often begins with repetitive manual operations:
- Opening one sample at a time and rebuilding the same gates repeatedly
- Keeping controls, unstained samples, and biological replicates organized by hand
- Comparing subpopulations visually without a quick way to propagate the same gate logic
- Exporting gated events or summary statistics through fragmented tools
CytoDraft reduces that friction by combining plotting, gating, grouping, propagation, and export in a single desktop workspace.
CytoDraft reads FCS files and keeps them in a workspace. Samples can be assigned to explicit groups such as:
Specimen 1Specimen 2Specimen 3ControlsUnstainedCompensation
Groups are first-class objects in the UI: they have color, notes, and can be used as targets for batch gate application.
The app supports:
- Scatter (2D) plots for pairwise channel gating
- Histogram (1D) plots for range gating
- Linear, log10, and asinh axis scaling
- Optional display of direct subpopulations
- Overlay of gate outlines when compatible with the current view
CytoDraft currently supports four gate types:
- Rectangle
- Polygon
- Ellipse (used as the circular/oval gate tool)
- Range
Gates are hierarchical. A gate can be created on All events or on an existing parent population, and child populations are tracked in the workspace tree.
Once a gate is created on one sample, it can be:
- Applied to all samples in the same group
- Applied to every loaded sample
- Propagated as a single gate or as a full gate hierarchy
When propagated, CytoDraft rebuilds the gate on the target sample using channel labels and the original gate geometry.
For the selected population, CytoDraft can compute summary statistics and export:
- gated events to CSV
- gated events to FCS
- statistics tables to CSV
| Multi-sample workspace | Load multiple FCS files into one session and switch between them without losing gates |
| Sample grouping | Organize samples into named groups with color and notes |
| Batch gate propagation | Apply one gate or an entire gate tree to a group or to all samples |
| Interactive gating | Draw rectangle, polygon, ellipse, and range gates directly on the plot |
| Hierarchical populations | Gates can be nested and browsed as parent/child populations |
| Population overlays | Show direct subpopulations on scatter and histogram views |
| Gate outline overlays | Display the gate geometry itself, not only the gated cells |
| Statistics export | Compute per-population statistics and export them to CSV |
| Event export | Export gated populations as CSV or FCS |
| Compensation groundwork | Default Compensation group with per-sample metadata for single-stain controls, target channel, and notes |
CytoDraft now includes the first structural step toward compensation:
- a default
Compensationgroup is created automatically - compensation samples can store metadata such as:
- control type
- fluorochrome
- target channel
- notes
This does not yet compute a spillover matrix. The current implementation prepares the workspace model and UI so the next phase can build:
- a compensation setup table from that group
- spillover matrix estimation
- compensated vs raw visualization
- application of the matrix to analysis samples
Core
Desktop UI
Cytometry I/O
CytoDraft is a local desktop app. There is no backend, no remote service, and no browser dependency for core usage.
cd /path/to/CytoDraft
python3 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]Run the app with:
cytodraftor:
python -m cytodraft.appCytoDraft/
├── README.md
├── pyproject.toml
├── docs/
├── examples/
├── tests/
└── src/
└── cytodraft/
├── app.py ← application entry point
├── core/
│ ├── compensation.py ← compensation module scaffold
│ ├── export.py ← CSV/FCS export helpers
│ ├── fcs_reader.py ← FCS loading and preprocessing
│ ├── gating.py ← geometric mask calculations
│ ├── statistics.py ← population statistics
│ └── transforms.py ← axis scaling transforms
├── gui/
│ ├── main_window.py ← main application workflow
│ ├── panels.py ← left/right control panels
│ ├── plot_widget.py ← central plotting and ROI drawing
│ └── theme.py ← UI styling
├── models/
│ ├── gate.py ← gate models
│ ├── sample.py ← sample and channel models
│ └── workspace.py ← workspace, groups, compensation metadata
└── services/
├── gate_service.py ← gate propagation across samples
└── sample_service.py ← sample loading service
Emiliano Balderas Ramírez
Bioengineer · PhD Candidate in Biochemical Sciences
Instituto de Biotecnología (IBt), UNAM
CellSplit — Neubauer cell counting and passage planning for CHO cultures.
CellBlock — shared biosafety cabinet scheduling for cell culture research groups.
Clonalyzer 2 — browser-based kinetics analysis for CHO fed-batch cultures.