macsima-qc

Quality control pipeline for MACSima / MACSiQView cell segmentation

Python package for evaluating and comparing cell segmentation results from the MACSima cyclic immunofluorescence platform, using manual ROI references from Fiji/ImageJ.

Installation

pip install macsima-qc

Or from source (development mode):

git clone https://github.com/mathisbouvet/macsima-qc
cd macsima-qc
pip install -e .

Workflow

MACSiQView segmentation (.csv)
            │
    run_qc_pipeline()  ← Isolation Forest + Mann-Whitney
            │
    ┌───────┴────────────────────────┐
    │ segmentation_test_annotated.csv │  ← OK / KO labels per cell
    │ macsiq_param_suggestions.csv   │  ← MACSiQView adjustment suggestions
    └─────────────────────────────────┘

── Optional ──────────────────────────────────────────────
Fiji ROIs (.zip) ──► generate_masks() ──► run_comparison()  ← KS distances + KDE

Quick start

Minimal usage — built-in reference

No reference file needed. Just point to your MACSiQView segmentation CSV:

from macsima_qc import run_qc_pipeline

df_annotated, df_suggestions = run_qc_pipeline(
    test_path="Segmentation_test.csv",
    contamination=0.10,
    output_dir="figures/",
)

With a custom reference

If you want to use your own manually validated segmentation as reference:

from macsima_qc import run_qc_pipeline

df_annotated, df_suggestions = run_qc_pipeline(
    test_path="Segmentation_test.csv",
    ref_path="my_reference.csv",
    contamination=0.10,
)

1. Exporting data from MACSiQView

1.a What data to export

After segmentation in MACSiQView, navigate to the Feature Table tab and select the following 14 morphological parameters for export. Only morphological descriptors are used, fluorescence intensities are excluded.

These 14 features are mandatory. The pipeline will raise an error if any are missing from the exported CSV.

1.b How to export

1. In MACSiQView, open the Feature Table panel
2. Select the 14 parameters listed above
3. Export as .csv
4. This exported file is your test_path input for run_qc_pipeline()

1.c About the built-in reference

The package ships with a built-in reference segmentation derived from a manually validated MACSima acquisition (DAPI channel, human embryonic tissue). It contains 4,641 cells described by the same 14 morphological features listed above, exported using the exact same MACSiQView protocol.

If your tissue type differs significantly from human embryonic tissue (e.g. non-embryonic tissue, very different cell density or morphology), consider providing your own reference via ref_path.

1.d QC pipeline — Isolation Forest

Before fixing the contamination parameter, the model sensitivity is analyzed across a range of values (0.01 → 0.20). The Isolation Forest is then trained exclusively on the reference data. Each test cell receives a label (Segmentation_OK: 1 or -1) and a continuous anomaly score.

For each feature, OK and KO cells are then compared with a two-sided Mann-Whitney U test. Because MACSima datasets contain thousands of cells, almost any difference becomes statistically significant, so the pipeline also reports an effect size (Cliff's delta, δ ∈ [−1, 1]; δ > 0 means larger values in KO cells) and corrects p-values for the 14 tests (Benjamini-Hochberg q-values).

A MACSiQView adjustment suggestion is emitted only when the difference is both significant and large enough: q < alpha (default 0.01) and |δ| ≥ min_effect (default 0.33, a "medium" effect according to Romano et al., 2006). Both thresholds can be changed in run_qc_pipeline(..., alpha=0.01, min_effect=0.33). Results are exported to macsiq_param_suggestions.csv, sorted by effect size.

All functions that draw a figure accept show=False to save it without displaying it (useful in scripts and batch runs).

Outputs

Anomaly score distribution from the Isolation Forest — cells below the decision threshold are flagged as Segmentation_KO.

2. Creating a reference segmentation (optional)

For the full step-by-step protocol, see the 01_segmentation_qc.

A reference DAPI image is extracted from the MACSima system and exported in .tif format for processing in Fiji. Regions of interest (ROI) are manually drawn to serve as the basis for segmentation masks.

• DAPI Image : exported in tiff format via MACSima
• RoiSet : created and exported from Fiji in zip format

Once the ROIs are defined, four types of masks are generated and imported into MACSiQView as segmentation inputs:

2a. Comparing segmentations

from macsima_qc import run_comparison

distances = run_comparison(
    manual_path = "Segmentation_manuelle.csv",
    auto_paths  = [
        "Mask_3_Single_Cell.csv",
        "Mask_3_Tissue.csv",
        "Mask_4_Import_mask.csv",
        "Mask_4_Single_Cell.csv",
        "Mask_4_Tissue.csv",
    ],
    auto_names  = [
        "Mask 3 - Single Cell",
        "Mask 3 - Tissue",
        "Mask 4 - Import Mask",
        "Mask 4 - Single Cell",
        "Mask 4 - Tissue",
    ],
    output_dir = "figures/",
)

This produces a barplot of average KS distances and KDE distribution curves for the main morphological parameters, identifying the automatic segmentation closest to the manual reference.

• The mean KS distance is computed on area, perimeter, feret and mean_intensity. Cell centroids are loaded but excluded from the score, since cell position depends on the imaged field, not on segmentation quality (change it with features=[...]).
• KDE curves are all expressed on the scale of the manual reference (0–1 = manual min–max), so a systematic size shift of an automatic segmentation stays visible.

Lower KS distance = closer match to the manual reference. Here, Mask 4 – Single Cell performs best across most morphological parameters.

Requirements

• Python ≥ 3.9
• numpy, matplotlib, scikit-image, tifffile, read-roi
• pandas, scikit-learn, scipy, seaborn

Citation

If you use this package in a publication, please cite:

Bouvet M. (2026)

License

MIT