Troubleshooting

Import or kernel problems

Check sys.executable in the notebook, then install the package in that interpreter’s Python 3.10 environment. Use python -m pip check to inspect dependency conflicts. A documentation build uses a separate interpreter and does not need to import the segmentation stack.

No images, unmatched masks, or missing channels

Check the dataset folder, TIFF extension, selected phase suffix, and field names. Compare image dimensions. Masks must be integer and consecutively labeled. Duplicate field identities are rejected. Missing channels are recorded rather than silently matched to another field. See Images, channels, and masks.

Segmentation failure

Check the returned boolean and processing_summary before making image objects. An existing mask on disk does not automatically rescue a failed segmentation in the same collection. Confirm model availability and CPU/GPU setup; restart with a fresh collection only when intentionally reusing verified masks.

Unexpected geometry or too few cells

Inspect masks, join/split settings, smoothing, and neighbor prefilter statistics. Check large-mesh filtering and SVM rejection counts. A saved table reflects retained cells, not necessarily every original label.

SVM schema error

Use the matching supplied model or train a model on the named feature dataframe. The model must carry feature_names_in_ and its order must match. Do not bypass the schema guard by guessing a column order.

Missing object features

Check whether detection actually found contours for the cell and channel. Check object mesh errors and the retention option for contour-only measurements. Missing rows must not automatically be counted as zero objects. Review cell_errors even when summary status says completed.

Export fails or contains unexpected columns

Recalculate and merge in the intended order. reset=True discards prior tables; reset=False replaces repeated pairs. A merge can lose entirely missing columns, and shared channel/feature names use the first nonmissing value. A filename must stay within the image folder, and a Parquet name must end in .parquet.

Plots cannot find a cell

The selected cell may have been removed during processing or curation. Select from the current image.cells list and ensure the relevant channel/detections exist. Saved notebook cell IDs are illustrative, not stable for new settings.