spectral_unmixing.unmix_picasso

spectral_unmixing.unmix_picasso(input_path, output_path=None, channels=None, *, method='picasso', implementation='matlab_3c', alpha_mode='reference_t', alpha_reference_t=0, source_sink_matrix=None, sink_channels=None, neutral_channels=None, background_percentile=1.0, preprocess_alpha_inputs=True, mi_bins=64, alpha_max=1.0, max_iter=200, tolerance=0.0001, max_alpha_voxels=500000, random_state=0, step_size=0.2, qn=100, pixel_bin_size=16, alpha_clip=0.5, negativity_threshold=0.0009, clip_every_n_iterations=50, source_sink_optimize_background=True, source_sink_max_background=0.2, source_sink_n_restarts=4, source_sink_joint_optimization=True, clip_negative=True, output_dtype='float32', verbose=True)[source]

Perform PICASSO-family multi-channel blind unmixing.

This workflow is motivated by the PICASSO publication: Seo, J., Sim, Y., Kim, J. et al. PICASSO allows ultra-multiplexed fluorescence imaging of spatially overlapping proteins without reference spectra measurements. Nature Communications 13, 2475 (2022). https://doi.org/10.1038/s41467-022-30168-z

Parameters:

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

  • output_path (str or Path or None, optional) – Output path for the unmixed stack written via OMIO. If None, a filename ending in "_picasso.tif" is created next to the input.

  • channels (sequence of int or None, optional) – Channel indices to include in blind unmixing. If None, all channels are used.

  • method ({β€œpicasso”}, optional) – Method label reserved for the PICASSO-like workflow.

  • implementation ({β€œmatlab_3c”, β€œmatlab_n”, β€œsource_sink_n”}, optional) – Concrete implementation variant: "matlab_3c" for a close Python port of the original MATLAB 3-channel workflow, "matlab_n" for an N-channel generalization of that workflow, and "source_sink_n" for a source-sink multi-channel model inspired by the napari plugin.

  • alpha_mode ({β€œreference_t”, β€œper_t”}, optional) – Whether to estimate one unmixing matrix from a reference time point or one matrix per time point.

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

  • source_sink_matrix (array-like or None, optional) – Square matrix used only by implementation="source_sink_n". The selected channels define both rows and columns. The diagonal must be 1. Off-diagonal values must be -1 for modeled source-to-sink spillover and 0 otherwise. If None, an all-to-all matrix with diagonal 1 and off-diagonal -1 is used.

  • sink_channels (sequence of int or None, optional) – Convenience alternative to source_sink_matrix for implementation="source_sink_n". Provide actual channel indices from channels that should be corrected as sinks. All selected channels except those listed in neutral_channels may contribute to these sinks.

  • neutral_channels (sequence of int or None, optional) – Convenience option for implementation="source_sink_n". Provide actual channel indices from channels that should remain neutral, meaning they are neither corrected as sinks nor used as sources when a source-sink matrix is auto-generated.

  • background_percentile (float, optional) – Low percentile used for per-channel background subtraction in the selected PICASSO implementation.

  • preprocess_alpha_inputs (bool, optional) – Backward-compatibility parameter retained from earlier PICASSO-like implementations. The current PICASSO-family implementations define their own internal preprocessing and therefore do not switch behavior based on this flag. The value is nevertheless recorded in the JSON sidecar report for reproducibility.

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

  • alpha_max (float, optional) – Upper bound for source-to-sink coefficients in the source-sink implementation.

  • max_iter (int, optional) – Maximum number of iterations for the selected implementation.

  • tolerance (float, optional) – Reserved for compatibility with the previous API. The MATLAB-like implementations follow a fixed iteration count rather than tolerance- based early stopping.

  • max_alpha_voxels (int or None, optional) – Optional cap on the number of voxels used for coefficient estimation in the source-sink implementation.

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

  • step_size (float, optional) – Incremental update step size used by the MATLAB-style implementations.

  • qn (int, optional) – MATLAB-style mutual-information quantization parameter.

  • pixel_bin_size (int, optional) – MATLAB-style 2D binning factor applied before mutual-information evaluation.

  • alpha_clip (float, optional) – Absolute clipping bound applied to each MATLAB-style pairwise alpha estimate before the incremental update matrix is constructed.

  • negativity_threshold (float, optional) – MATLAB-style negativity ratio threshold above which a pairwise alpha is divided by ten.

  • clip_every_n_iterations (int, optional) – Frequency of positivity enforcement during the MATLAB-style iterations.

  • source_sink_optimize_background (bool, optional) – If True, implementation="source_sink_n" jointly optimizes one background parameter beta per modeled source-to-sink relation, following the source-sink formulation used by the napari PICASSO plugin.

  • source_sink_max_background (float, optional) – Upper bound for the optimized source-background parameters in the source-sink implementation. The values operate on globally normalized intensities in the interval [0, 1].

  • source_sink_n_restarts (int, optional) – Number of multi-start optimizer initializations used by the source-sink implementation for each sink.

  • source_sink_joint_optimization (bool, optional) – If True (default), all modeled sources contributing to a given sink are optimized jointly. If False, the package falls back to the older greedy pairwise update strategy.

  • clip_negative (bool, optional) – If True, clip negative unmixed intensities to zero before writing.

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

  • verbose (bool, optional) – If True, print processing progress and output paths.

Return type:

Path

Returns:

Path – Actual path of the written output stack.

Notes

implementation="matlab_3c" is the default and aims to match the published MATLAB 3-channel workflow as closely as possible.

implementation="matlab_n" is an explicit N-channel generalization of that MATLAB workflow.

implementation="source_sink_n" uses a direct source-sink subtraction model inspired by the napari plugin structure. It is not a neural-MINE port of the plugin, but it follows the same idea of user-defined source/sink relations.