---
title: Cytometry quickstart
description: >-
  Step-by-step workflows for FlowSOM clustering and IMC segmentation and
  spatial analysis.
tags:
  - cytometry
  - quickstart
---

> **Retired tools**

> `flow_gate`, `flow_cluster` and `flow_differential` are retired and can no longer be run. For FCS clustering use `flowsom`. There is no hosted tool for automated gating or differential abundance; ask Ivy to run those in Python in the chat's [code workspace](/docs/sandbox).

You want reproducible populations and spatial biology out of your cytometry data. This guide runs the fastest path through three workflows — FlowSOM clustering, IMC cell segmentation, and IMC spatial analysis — each in a few steps.

## Cytometry quickstart

This guide covers three common workflows: FlowSOM clustering, IMC cell segmentation, and IMC spatial analysis.

> **Configure-manually tables go beyond the implemented tools**

> The IMC "configure manually" parameter tables below describe the intended interface, not the one `imc_segment` and `imc_spatial` currently accept. See the note on the [Cytometry overview](/docs/cytometry) for what each tool accepts.

## Workflow 1: FlowSOM clustering

### Step 1: Upload your FCS file

Upload an FCS file through the chat interface or data panel. Flow cytometry data should be compensated before upload; CyTOF data does not need compensation.

### Step 2: Run clustering

```
Cluster my CyTOF data using FlowSOM with 20 metaclusters
```

Or configure:

| Parameter | Value |
|-----------|-------|
| `fcs_key` | The uploaded FCS file |
| `cols_to_use` | `["CD3", "CD4", "CD8", "CD19", "CD56", "CD14", "CD16"]` |
| `n_clusters` | `20` |
| `xdim` / `ydim` | `10` / `10` |

Use lineage markers (CD3, CD4, CD8, CD19, CD56, etc.) for population identification.

### Step 3: Review cluster results

`flowsom` returns the size and fraction of events in each metacluster, the median marker intensities per metacluster, per-event cluster labels as a CSV, and an optional star plot of the SOM grid. Read the high-intensity markers of each metacluster to name it.

### Step 4: Compare groups (optional)

There is no hosted differential-abundance tool. Take the per-event cluster labels from `flowsom` and ask Ivy to run the group comparison in the chat's [code workspace](/docs/sandbox).

## Workflow 2: IMC cell segmentation

### Step 1: Upload your IMC image

Upload a multi-channel TIFF or MCD file containing your imaging mass cytometry acquisition.

### Step 2: Run segmentation

```
Segment cells in my IMC image using Cellpose with Ir193 as nuclear marker and CD45 as membrane marker
```

Or configure:

| Parameter | Value |
|-----------|-------|
| Method | `cellpose` |
| Nuclear markers | `["Ir193"]` |
| Membrane markers | `["CD45", "Na-K-ATPase"]` |
| Min cell area | `50` pixels |
| Max cell area | `5000` pixels |

### Step 3: Review segmentation results

| Field | Example Value |
|-------|---------------|
| Total cells segmented | 3,847 |
| Mean cell area | 312 px |
| Median markers per cell | 35 |
| Oversegmentation rate | 2.1% |
| Undersegmentation rate | 4.3% |

### Step 4: Extract per-cell marker intensities

The segmentation output includes a cell-by-marker matrix with mean intensities for each channel within each cell mask. This matrix is the input for downstream clustering and spatial analysis.

## Workflow 3: IMC spatial analysis

### Step 1: Prepare segmented data

Use the output from `imc_segment`, or provide your own cell data with X/Y coordinates and cell type labels.

### Step 2: Run spatial analysis

```
Analyze spatial interactions between CD8 T cells and tumor cells in my tissue section
```

Or configure:

| Parameter | Value |
|-----------|-------|
| Analysis type | `neighborhood` |
| Cell types | `["CD8_T", "Tumor", "Macrophage", "Stroma"]` |
| Radius | `30` microns |
| Permutations | `1000` |

### Step 3: Review spatial results

| Cell Type A | Cell Type B | Interaction Score | p-value | Relationship |
|-------------|-------------|-------------------|---------|-------------|
| CD8 T | Tumor | 2.34 | 0.001 | Attraction |
| Macrophage | Tumor | 1.87 | 0.008 | Attraction |
| CD8 T | Stroma | 0.45 | 0.012 | Avoidance |

### Step 4: Interpret interaction scores

| Score | Interpretation |
|-------|----------------|
| > 1.5 | Strong spatial attraction (cells are closer than expected by chance) |
| 1.0 - 1.5 | Mild attraction |
| 0.7 - 1.0 | Random distribution |
| < 0.7 | Spatial avoidance (cells are farther apart than expected) |

## Next steps

- See [inputs](/docs/cytometry/inputs) for all parameters, file formats, and algorithm options
- See [outputs](/docs/cytometry/outputs) for result field descriptions and score interpretation
- Use [Genomics](/docs/genomics) tools to look up marker gene information
- Use [Literature](/docs/pubmed) tools to find papers about identified cell populations

## Read next