Calibration, unmixing and deconvolution

Calibration products are inputs to later image operations. Preserve their units, coordinate frame and validity masks. In particular, signed camera-corrected measurements cannot simply be supplied to a Poisson-only fitting model.

Available operations

camera

Source.

Entry points: RepeatMomentsKernel, CameraCalibrationKernel, ApplyCameraKernel.

Stable repeat mean/variance/count, per-pixel photon-transfer gain/offset/read-noise estimates, and signed electron correction. Repeated acquisitions need matched exposure/temperature and stable illumination. Dark variance includes other temporal noise unless those terms are negligible.

Execution: Bounded repeated-frame batches via TupleOp; small per-voxel fits. Current kernels use f64.

The statistical axis is repeated acquisition, not space. A voxel’s repeat mean and unbiased variance use measurements at the same sensor position. The tuple kernels therefore have zero spatial reach, while the number of attached repeat frames affects memory. Carrying prior count/mean/variance allows bounded batches instead of opening every exposure simultaneously.

Photon transfer fits the slope of ADU variance against dark-subtracted signal mean. The reciprocal slope gives electrons per ADU; dark temporal variance contributes the read-noise estimate only under the stated negligible-other-noise assumption. Camera correction preserves negative electron values created by measurement noise. Those values are valid signed measurements but violate the current Poisson-only spot fitter’s input model.

unmixing

Source.

Entry points: NnlsModel, NnlsKernel, SpectrumSummaryOp, calibrate_spectra.

Estimate normalized spectra from blank/pure controls and solve weighted nonnegative least squares. Inspect matrix conditioning, residuals, KKT violations and validity. Signed observations are allowed, abundances remain nonnegative.

Execution: Planned bounded control summaries and voxelwise f64 tuples. Current limits: 64 detectors and 16 components, with detectors ≥ components.

Why conditioning and constraints are separate diagnostics. The pure-control columns define a detector-by-component matrix. A poorly separated pair of spectra can make abundances unstable even if the residual is small. Construction checks rank and the stated QR-factor condition estimate; the active-set NNLS solver then checks optimality of a nonnegative solution for each observation.

Control means are background-corrected and normalized by column sum, so output abundance units are combined detected signal under that normalization, not absolute molecular concentration. Application is pointwise across detector images: no spatial halo is needed, but all detector values must be physically registered and jointly valid. Saturation or invalid channels produce an invalid fit rather than a fabricated low component abundance.

psf_fit

Source.

Entry points: fit_gaussian, BeadFitOp, PsfAccumulator.

Fit pixel-integrated axis-aligned Gaussian spots under a Poisson model. Reject edge, crowded, saturated or failed candidates; pool accepted aligned patches and fitted models into normalized PSFs. This is isolated-bead calibration, not crowded multi-emitter fitting.

Execution: Resident bounded-window fit and planned candidate fitting; small mergeable PSF accumulators.

Two windows answer two questions. Candidate extraction needs neighboring response values to identify a local maximum, while the statistical fit needs raw pixels over its fitting crop. Isolation checks additionally need enough neighborhood to detect competing candidates. The planned operation derives those windows and assigns each anchor to one core; an image seam must not become a reason to drop or duplicate an otherwise valid bead.

The model integrates a Gaussian over pixel volumes and fits position, independent axis widths, flux and background. Approximate position errors follow the local Fisher model. Pooling accepted patches estimates an empirical PSF, while pooling fitted models gives a separate idealized PSF. Rejecting crowded beads is intentional here: a single Gaussian should not absorb two emitters and report a misleadingly broad optical PSF.

deconvolution

Source.

Entry points: Psf, solve, deconvolve, ZarrSource, ZarrState.

Independent Richardson–Lucy and scaled-heavy-ball reconstruction with arbitrary finite nonnegative 3D PSFs. State boundary normalization, initialization, iteration/stopping policy and missing-data treatment explicitly.

Execution: f32 FFT-based solver with per-convolution halos and region Source/StateStore; zarr enables four reusable disk-backed state images. This solver does not use the general iterative executor.

Why a finite PSF bounds each pass, not the whole iteration history. Each forward or adjoint convolution needs only the corresponding PSF support around its output. After that pass is committed to state storage, the next pass reads the updated neighboring state. This explicit exchange prevents the halo from growing with iteration count while preserving the iterative coupling between blocks.

The PSF can be asymmetric and nonseparable, so forward and adjoint directions must be distinguished. The solver’s valid-data sensitivity normalization handles missing/outside observations under its declared boundary model. Initialization, positive floors, stopping/divergence checks and RL versus heavy-ball updates affect results and runtime. Four reusable state images bound the disk-backed working design; they do not imply zero disk traffic or a generic resident FFT allocation independent of block size.

deconvolve

Source.

Entry points: PointSpread, Deconvolution, DeconvolveOp.

Older spatial separable fixed-count RL-style deconvolution with clamped boundaries. It remains a distinct API with different numerical/boundary conventions from deconvolution.

Execution: Planned composed operation, with halo growing as 2 × radius × iterations; resident helper also available.

Why this older API has an iteration-dependent halo. It executes a fixed sequence of spatial forward/backprojection updates inside one operation. Without committing/exchanging intermediate image state between global passes, the final core depends transitively on input farther away at every iteration. The declared 2 × radius × iterations bound pays for that history.

For radius four and ten iterations this is 80 voxels per side, which can dwarf a small output block. The separate finite-PSF solver avoids that growth by storing pass state, and has its own boundary normalization and numerical conventions. Do not switch between the two solely by matching a nominal iteration count; compare reconstruction outputs under their actual models.

flowchart LR
  D[Dark and flat repeats] --> C[Camera maps]
  B[Bead image] --> F[Isolated spot fits]
  F --> P[Measured or model PSF]
  I[Image] --> R[Finite-PSF reconstruction]
  P --> R

Camera calibration and PSF fitting currently have different noise contracts; the arrows above do not imply a camera read-noise likelihood has already been added to the bead fitter. Runnable calibration and restoration examples document the accepted inputs and diagnostics.