spacr.psf_pipeline¶

Opt-in PSF and enhancement-chain preparation and provenance for segmentation inputs.

Kernels are captured once per run. Only private intensity arrays are processed; raw stacks and mask labels are never rewritten by this module. V1 reuse checks both the requested kernel/settings and the exact completed archive bytes.

THE ENHANCEMENT CHAIN TRAVELS THE SAME ROUTE. Make Masks’ chain (spacr.qt.detect_chain) is written into a settings file as the enhance_* keys and read back here by prepare_chain(), with the psf_* settings folded in as the chain’s PSF stage, so one plate run applies exactly the steps a curator tuned, in the chain’s own order: background, PSF, denoise, contrast, sharpen. The session applies it per selected channel at the stage the PSF already ran – after illumination correction and before normalization – and its provenance goes into the same psf/segmentation_application.json record, so a changed chain is refused on resume the way a changed kernel is. With no chain step on, a run is byte for byte what it was before the chain existed.

SPECTRAL UNMIXING COMES FIRST. With unmix on, a bleed-through matrix is estimated from the single-stain control wells unmix_controls names and every raw field is unmixed across all its channels before illumination correction, the PSF and the chain; the matrix joins the same record. Measure estimates its own over the measured channels and unmixes each field before its preprocessing hooks, recording the matrix in the saved run settings and measurements/bleed_through.json.

SELF-SUPERVISED DENOISING COMES BEFORE THE CHAIN. With n2v_denoise on, a Noise2Void (N2V2) model per segmentation channel is trained by CAREamics, in its own environment, on a sample of the run’s own raw fields – no clean images are needed – or read from n2v_model. Each field’s selected channels are denoised after illumination correction and before the PSF and the chain, while the noise is still independent from pixel to pixel, which is what Noise2Void assumes. The checkpoints’ hashes and the training record join the same provenance record.

Classes¶

PSFPlan

Immutable calibrated processing configuration, safe to pass to workers.

Functions¶

`apply_chain`(image, chain, *[, cancel])	Run `chain` over every channel of one YXC field, strictly.
`chain_problems`(settings)	Every `enhance_*` value the chain cannot run with, as `(setting, message)`.
`prepare_chain`(settings[, plan])	The enhancement chain a run applies, read from its `enhance_*` settings.
`prepare_psf`(settings, *[, ndim])	Capture and validate an optional PSF before processing starts.
`processing_requested`(settings)	Whether these settings ask for a PSF or an enhancement step at all.
`validate_psf_resume`(settings, root, channels, *, ...)	Refuse V1 archive reuse after a PSF change or incomplete processing.

Module Contents¶

class spacr.psf_pipeline.PSFPlan[source]¶

Immutable calibrated processing configuration, safe to pass to workers.

Parameters:

operation – convolve or deconvolve.
kernel – captured immutable measured or Gaussian kernel.
sampling_um – image spacing in spatial array order, in micrometers.
iterations – Richardson–Lucy iterations; unused for convolution.

apply(image, *, cancel=None)[source]¶

Process one spatial image with an explicit last channel axis.

Parameters:

image – YXC or ZYXC intensity array, never a merged label stack.
cancel – optional process-safe event shared with a parent worker.

Returns:

float32 processed intensities without source mutation.

provenance()[source]¶: Return JSON-safe identity of every scientifically relevant setting.

spacr.psf_pipeline.apply_chain(image, chain, *, cancel=None)[source]¶

Run chain over every channel of one YXC field, strictly.

Parameters:

image – YXC intensity array, never a merged label stack.
chain – a spacr.qt.detect_chain.Chain from prepare_chain().
cancel – optional process-safe event shared with a parent worker; cancellation raises spacr.cancellation.PipelineCancelled between stages and inside PSF iterations, as the PSF path does.

Returns:

float32 processed intensities, the source untouched.

spacr.psf_pipeline.chain_problems(settings)[source]¶

Every enhance_* value the chain cannot run with, as (setting, message).

Read by the preflight so a run refuses before any field is touched, and by prepare_chain(), which raises on the first.

Parameters:: settings – the run’s settings; absent enhance_* keys are off.
Returns:: a list of (setting, message) pairs, empty when all is well.

spacr.psf_pipeline.prepare_chain(settings, plan=None)[source]¶

The enhancement chain a run applies, read from its enhance_* settings.

The chain is spacr.qt.detect_chain.Chain, the value Make Masks detects with, built from the settings spacr.qt.detect_chain.chain_settings() writes; the optional PSFPlan is folded in as the chain’s PSF stage so the run’s order is the chain’s own – background before the PSF, then denoise, contrast and sharpen – rather than the PSF first.

Parameters:

settings – the run’s settings; enhance_<field> per spacr.qt.detect_chain.SETTINGS_FIELDS, off when absent.
plan – the run’s captured PSFPlan, or None.

Returns:

the chain, or None when no enhance_* step is switched on – the PSF alone stays on its own path, which is byte for byte the path it had before the chain reached Mask.

Raises:

ValueError – for a value the chain cannot run with, or a PSF that is not two-dimensional.

spacr.psf_pipeline.prepare_psf(settings, *, ndim=2)[source]¶

Capture and validate an optional PSF before processing starts.

Parameters:

settings – psf_operation (none/convolve/deconvolve), source (gaussian/measured), image sampling, Gaussian FWHM or measured path and kernel sampling, and iteration count. Lengths are in micrometers, YX for two dimensions or ZYX for three. No calibration is inferred.
ndim – number of spatial dimensions, two or three.

Returns:

immutable PSFPlan, or None when disabled (the default).

Raises:

ValueError – for invalid operations, calibration or kernels.

spacr.psf_pipeline.processing_requested(settings)[source]¶

Whether these settings ask for a PSF or an enhancement step at all.

A requested chain that cannot be built counts as requested: the run then refuses with the reason rather than reusing inputs made without it.

Parameters:: settings – the run’s psf_*, enhance_*, unmix and n2v_denoise settings.
Returns:: True when any is switched on or the chain cannot be read.

spacr.psf_pipeline.validate_psf_resume(settings, root, channels, *, expected_fields)[source]¶

Refuse V1 archive reuse after a PSF change or incomplete processing.

Parameters:

settings – requested PSF, enhance_* and unmix settings; off also checks a prior PSF, chain or unmixing run.
root – experiment root containing masks/ and psf/.
channels – source intensity indices in archive order.
expected_fields – exact field stems carried by the input archives.

Returns:

None for a compatible completed set or untouched legacy inputs.

Raises:

ValueError – if archives cannot be proven to match this request.