spectral_unmixing.unmix

spectral_unmixing.unmix(input_path, output_path, alpha=None, alpha_mode=None, alpha_reference_t=0, source_channel=0, target_channel=1, signal_percentile=99.0, target_low_percentile=None, background_percentile=1.0, clip_negative=True, output_dtype='float32', verbose=True, method='mean_ratio', bidirectional=False, alpha_reverse=None, method_reverse=None, preprocess_alpha_inputs=True, alpha_max=1.0, signal_percentile_reverse=None, background_percentile_reverse=None, target_low_percentile_reverse=None, alpha_max_reverse=None, mi_bins=64, mi_bins_reverse=None, max_alpha_voxels=500000, random_state=0, min_mask_voxels=16)[source]

Remove bleed-through from one source channel into one target channel in a TZCYX stack.

Parameters:

  • input_path (str or Path) – Path to the input microscopy stack readable by OMIO.

  • output_path (str or Path) – Path to the output stack to be written via OMIO. A JSON sidecar report with the same name plus .json is written alongside it.

  • alpha (float or None, optional) – User-provided bleed-through coefficient. Required when the effective alpha mode is "fixed".

  • alpha_mode ({“fixed”, “reference_t”, “per_t”} or None, optional) – Strategy that determines whether alpha is taken directly from alpha, estimated once from a reference time point, or estimated separately for each time point. If None, a provided alpha implies "fixed"; otherwise method="manual" raises an error and the remaining methods default to "reference_t" with the supplied alpha_reference_t.

  • alpha_reference_t (int, optional) – Reference time point used when alpha_mode="reference_t".

  • source_channel (int, optional) – Channel whose signal bleeds into the target channel.

  • target_channel (int, optional) – Channel from which the source contribution should be removed.

  • signal_percentile (float, optional) – Percentile used to define a bright-source signal mask for automatic alpha estimation.

  • target_low_percentile (float or None, optional) – Optional low-target constraint for the alpha-estimation mask.

  • background_percentile (float, optional) – Low percentile used for optional percentile-based background subtraction during alpha estimation.

  • clip_negative (bool, optional) – If True, clip negative corrected target values to zero.

  • output_dtype (str or numpy.dtype, optional) – Data type used for the written output stack.

  • verbose (bool, optional) – If True, print processing progress and estimated coefficients.

  • method ({“manual”, “mean_ratio”, “linear_fit”, “corr_min”, “mi_min”}, optional) – Method used to obtain alpha. "manual" is meaningful only together with an effective alpha_mode="fixed"; the other methods estimate alpha from the data.

  • bidirectional (bool, optional) – If True, estimate or use coefficients for both source_channel -> target_channel and target_channel -> source_channel and solve the resulting 2x2 linear mixing model by matrix inversion.

  • alpha_reverse (float or None, optional) – Optional fixed reverse-direction bleed-through coefficient, i.e. from target_channel back into source_channel. If None and bidirectional=True, the forward alpha value is reused.

  • method_reverse ({“manual”, “mean_ratio”, “linear_fit”, “corr_min”, “mi_min”} or None, optional) – Optional reverse-direction alpha-estimation method. If None and bidirectional=True, the forward method value is reused.

  • preprocess_alpha_inputs (bool, optional) – If True, apply percentile-based background subtraction and clipping before automatic alpha estimation.

  • alpha_max (float, optional) – Upper search bound for optimization-based alpha-estimation methods.

  • signal_percentile_reverse (float or None, optional) – Optional reverse-direction source-mask percentile. Falls back to signal_percentile when None.

  • background_percentile_reverse (float or None, optional) – Optional reverse-direction background percentile. Falls back to background_percentile when None.

  • target_low_percentile_reverse (float or None, optional) – Optional reverse-direction low-target percentile. Falls back to target_low_percentile when None.

  • alpha_max_reverse (float or None, optional) – Optional reverse-direction optimization bound. Falls back to alpha_max when None.

  • mi_bins (int, optional) – Number of histogram bins used by the mutual-information estimator.

  • mi_bins_reverse (int or None, optional) – Optional reverse-direction histogram-bin count used by mi_min. Falls back to mi_bins when None.

  • max_alpha_voxels (int or None, optional) – Optional cap on the number of voxels used for alpha estimation after masking.

  • random_state (int, optional) – Random seed used for optional voxel subsampling during alpha estimation.

  • min_mask_voxels (int, optional) – Minimum number of voxels required for a valid alpha-estimation mask.

Return type:

Path

Returns:

Path – Actual path of the written output stack.

Raises:

ValueError – If the input configuration is inconsistent or would overwrite the input.

Notes

Only target_channel is modified. source_channel remains unchanged in the output stack. Automatic alpha estimation is performed on prepared data, but the final subtraction is applied to the original stack intensities cast to float32.

If bidirectional=True, both selected channels are corrected jointly by inverting the 2x2 linear mixing model. In that mode, clip_negative applies to both corrected channels.