Cytometry troubleshooting

This page helps you diagnose problems across the cytometry tools — clustering that over- or under-splits populations, and imaging mass cytometry segmentation issues.

Cytometry troubleshooting

Clustering produces too many or too few clusters

Symptom: FlowSOM returns clusters that split known populations or merge distinct populations.

Fixes:

• Adjust n_clusters. If populations are split, reduce it. If populations are merged, increase it
• Check which markers are included. Pass only informative lineage markers in cols_to_use for initial clustering, and leave out activation or functional markers
• Make sure the file is compensated (flow cytometry) and, for CyTOF, bead-normalized before upload
• Subsample first for exploration. Set max_events to iterate quickly on parameters before running on the full file

Clustering results are not reproducible

Symptom: Running the same data twice produces different cluster assignments.

Fixes:

• Set seed to a fixed value (the default is 42). FlowSOM uses random initialization
• Changing xdim, ydim or n_clusters changes the result by design

FCS file fails to load

Symptom: "Invalid file format" or parsing error when uploading FCS.

Fixes:

• Verify the file is FCS 3.0 or 3.1 format. Older FCS 2.0 files may not parse correctly
• Check file size. Maximum is 500 MB per file. For larger files, downsample in your acquisition software before export
• Ensure the file is not corrupted. Try opening it in FlowJo, FCS Express, or another cytometry tool to verify
• If exporting from FlowJo, use "Export as FCS file" (not "Export as CSV"). FlowJo CSV exports work but must include all parameter columns
• Some FCS files from older instruments have non-standard headers. Try exporting from your acquisition software with default settings

IMC segmentation misses cells or merges neighbors

Symptom: Segmentation mask has too few cells (undersegmentation) or splits cells incorrectly (oversegmentation).

Fixes:

• For undersegmentation (merged cells), reduce the expand_radius parameter. Default is 3 pixels. Try 1-2 pixels for densely packed tissue
• For oversegmentation (split cells), increase min_area to filter out fragment-sized objects. Also check if your nuclear marker has granular staining that creates multiple seeds per cell
• Add membrane markers if not already included. Nuclear-only segmentation estimates cell boundaries by expansion, which works poorly for irregularly shaped cells
• Switch segmentation methods. Cellpose handles diverse morphologies well. DeepCell/Mesmer is optimized for tissue and may perform better on packed epithelial tissue
• Adjust pixel_size to match your acquisition resolution. Incorrect pixel size confuses the deep learning model's scale expectations

IMC spatial analysis produces non-significant results

Symptom: All interaction p-values are above the significance threshold.

Fixes:

• Increase the number of permutations. With only 100 permutations, the minimum possible p-value is 0.01. Use at least 1,000 for reliable significance testing
• Adjust the neighborhood radius. Default is 30 microns. If cells are sparsely distributed, increase to 50-100 microns. If tissue is dense, decrease to 15-20 microns
• Check cell type labels. If most cells are labeled as one type (e.g., "unknown"), there is no basis for interaction analysis. Ensure cell typing was performed (e.g., via clustering) before spatial analysis
• Verify that the minimum cell count threshold is met. Cell types with fewer than min_cells events are excluded. Lower this threshold for rare types
• Some tissues genuinely have random spatial organization. Not all cell types exhibit spatial preferences

Memory or timeout errors with large datasets

Symptom: Job fails with out-of-memory or timeout error.

Fixes:

• For clustering, set max_events to cap the number of events used for training
• For spatial analysis, reduce the radius parameter. Larger radii require more pairwise distance calculations
• For IMC segmentation, ensure your image is not excessively large. Images above 10,000 x 10,000 pixels may require tiling
• Split multi-sample FCS files and process them individually, then merge the results

Getting help

If issues persist:

1. Check the tool error message for specific suggestions
2. Verify your input file format and marker names
3. Try running with default parameters on a smaller subset of your data
4. Describe the issue to Ivy

Read next