spectral_unmixing.estimate_alpha_from_volume

spectral_unmixing.estimate_alpha_from_volume(source, target, signal_percentile=99.0, background_percentile=1.0, min_mask_voxels=16, *, method='mean_ratio', target_low_percentile=None, preprocess_alpha_inputs=True, alpha_max=1.0, mi_bins=64, max_alpha_voxels=500000, random_state=0, return_details=False)[source]

Estimate a bleed-through coefficient alpha from matching source and target volumes.

Parameters:

source, target (array-like) – Matching source and target image volumes. Typical microscopy input is a ZYX volume, but any matching shape is accepted.
signal_percentile (float, optional) – Percentile used to define a bright-source signal mask.
background_percentile (float, optional) – Low percentile used for optional percentile-based background subtraction before alpha estimation.
min_mask_voxels (int, optional) – Minimum number of voxels required in the final alpha-estimation mask.
method ({“mean_ratio”, “linear_fit”, “corr_min”, “mi_min”}, optional) – Scalar alpha-estimation strategy.
target_low_percentile (float or None, optional) – Optional extra target constraint for the estimation mask. If provided, voxels are restricted to bright source signal and low target signal whenever that yields enough voxels.
preprocess_alpha_inputs (bool, optional) – If True, apply percentile-based background subtraction and clip negative values to zero before alpha estimation. If False, estimate alpha directly on the original intensities converted to float32.
alpha_max (float, optional) – Upper search bound for optimization-based methods "corr_min" and "mi_min".
mi_bins (int, optional) – Number of histogram bins used by the mutual-information estimator.
max_alpha_voxels (int or None, optional) – Optional cap on the number of voxels used after masking. If the mask is larger, voxels are subsampled without replacement.
random_state (int, optional) – Random seed used for optional voxel subsampling.
return_details (bool, optional) – If True, also return a dictionary describing preprocessing, thresholds, mask size, subsampling, and method-specific diagnostics.

Return type:

float | tuple[float, dict]

Returns:

float or tuple – Estimated alpha, or (alpha, details) if return_details=True.

Raises:

ValueError – If the input data are incompatible, the estimation mask is too small, or the estimated alpha is invalid.