Plate and batch-effect correction

spaCR can normalize acquisition-batch effects before Image UMAP, Classify (ML), and phenotype regression. Correction is disabled by default because a plate effect can be real biology when treatments and plates are confounded.

Choosing a method

none

Leave measurements unchanged.

control_center

Recommended when every plate contains the same negative/reference control. For each feature, spaCR subtracts from every row of a plate the difference between that plate’s control median and the median of all control rows. Treatment dispersion and treatment-to-control differences are retained.

robust_zscore

Align plate medians and median absolute deviations (MAD, scaled by 1.4826) to the pooled median and MAD. This is less sensitive to outliers than zscore, but can remove genuine differences if biological conditions are unevenly distributed across plates.

center

Align plate means while preserving the overall mean.

zscore

Align both plate means and standard deviations to the pooled values. Use it only when plate composition is comparable, because a difference in condition mix between plates is removed together with the batch effect.

combat

Empirical-Bayes ComBat (Johnson, Li & Rabinovich, 2007). Each feature is modelled on batch and on the biology named in batch_covariate_column, and only the batch part is removed; per-batch estimates are shrunk across features, which stabilizes the estimates for plates with few samples. It refuses to run until the covariate is answered: name the column(s) to preserve, or pass no_covariate to record that every batch holds the same mixture of conditions. batch_combat_mean_only=True corrects only the additive shift and leaves each batch’s spread alone.

Settings

Set batch_correction to a method above and use batch_column to name the batch identifier (normally plateID). batch_min_samples (default 3) is the minimum number of rows per batch; a smaller batch stops the run with an error.

For control_center, batch_control_column identifies the metadata field that contains the controls and batch_control_values selects one or more reference values. When blank, Image UMAP follows col_to_compare/neg and Classify’s ML family follows location_column (or annotation_column when annotations define the classes) and negative_control_id. Regression requires an explicit reference value. batch_missing_control=error (the default) stops the run when a plate has fewer than batch_min_samples usable reference controls; skip leaves an affected plate unchanged and records a warning.

When correcting multiple batches, skip tolerates missing reference controls on individual plates; it does not bypass the minimum total rows per batch or the minimum matching controls across all plates. If only one batch is present, correction makes no adjustment and records a warning.

Every regression correction writes batch_correction.json next to the regression outputs. Image UMAP and Classify print before/after batch-centroid spread in the run log, while the reproducibility manifest records the exact settings used.

Python API

The shared implementation is spacr.batch_correction.correct_batch_effects(). Most integrations use spacr.batch_correction.correct_from_metadata() with separate feature and metadata frames. The adapter reads batch, control and covariate columns from metadata; it does not remove metadata columns already included in the feature frame. Select only measurement features for that frame, excluding numeric identifiers and other metadata.

Keep features and metadata indexed by the same object identifiers. Metadata is aligned to features.index by label, not by row position. Preserve each object’s index label when filtering or reordering either frame; independently resetting indexes can associate measurements with the wrong metadata.

from spacr.batch_correction import correct_from_metadata

corrected, report = correct_from_metadata(
    features,
    metadata,
    batch_correction="control_center",
    batch_column="plateID",
    batch_control_column="columnID",
    batch_control_values="c1",
)
print(report.to_dict())