spacr.spacr_cellpose
====================

.. py:module:: spacr.spacr_cellpose




Module Contents
---------------

.. py:function:: parse_cellpose4_output(output)

   Normalize the return value of ``CellposeModel.eval`` into per-image flow lists.

   Accepts both the batched format (4 stacked arrays) and the per-image list
   format so downstream code can iterate uniformly.

   :param output: Raw ``(masks, flows, ...)`` tuple returned by Cellpose.
   :returns: Tuple ``(masks, flows0, flows1, flows2, flows3)`` with per-image entries.
   :raises ValueError: When the flows structure does not match a known layout.


.. py:function:: identify_masks_finetune(settings)

   Generate Cellpose masks for a directory of images using a stock or custom model.

   Iterates in batches, optionally normalizing and resizing the inputs, writes
   the resulting masks under ``<src>/masks``, and prints per-image progress.

   :param settings: Settings dict; canonicalized via
       :func:`spacr.settings.get_identify_masks_finetune_default_settings`.
       Must contain ``src``, ``model_name`` (or ``custom_model``), and standard
       Cellpose parameters (``diameter``, ``flow_threshold``, ``CP_prob``, ...).
   :returns: None.


.. py:function:: generate_masks_from_imgs(src, model, model_name, batch_size, diameter, cellprob_threshold, flow_threshold, grayscale, save, normalize, channels, percentiles, invert, plot, resize, target_height, target_width, remove_background, background, Signal_to_noise, verbose)

   Run a Cellpose model over every ``.tif`` in ``src`` and optionally save masks.

   Batches the workload, respects the model-specific channel convention, and
   writes results to ``<src>/<model_name>``.

   :param src: Directory containing input ``.tif`` images.
   :param model: Instantiated ``cellpose.models.CellposeModel``.
   :param model_name: Model identifier, used both for channel defaults and the
       output subdirectory name.
   :param batch_size: Number of images loaded per iteration.
   :param diameter: Estimated object diameter in pixels.
   :param cellprob_threshold: Cell probability threshold passed to Cellpose.
   :param flow_threshold: Flow error threshold passed to Cellpose.
   :param grayscale: When True, force single-channel input.
   :param save: When True, write masks under ``<src>/<model_name>``.
   :param normalize: When True, load images with normalization/background pipeline.
   :param channels: Channel indices used when loading images.
   :param percentiles: Percentile clipping range applied during normalization.
   :param invert: When True, invert intensities during load.
   :param plot: When True, display mask/flow diagnostics per image.
   :param resize: When True, resize inputs to ``(target_height, target_width)``.
   :param target_height: Target height for resized inputs.
   :param target_width: Target width for resized inputs.
   :param remove_background: When True, subtract background during normalization.
   :param background: Background value used when ``remove_background`` is set.
   :param Signal_to_noise: Minimum SNR threshold for retained signal.
   :param verbose: When True, print Cellpose settings to the console.
   :returns: None.


.. py:function:: check_cellpose_models(settings)

   Run each stock Cellpose model over ``settings['src']`` for side-by-side comparison.

   :param settings: Settings dict; canonicalized via
       :func:`spacr.settings.get_check_cellpose_models_default_settings`.
   :returns: None.


.. py:function:: save_results_and_figure(src, fig, results)

   Persist a comparison DataFrame and figure under ``<src>/results``.

   :param src: Root directory used to locate/create the ``results/`` folder.
   :param fig: Matplotlib figure to save as PDF.
   :param results: DataFrame or list-of-dicts of comparison metrics.
   :returns: None.


.. py:function:: compare_mask(args)

   Return pairwise IoU/F1/AP scores for one image across multiple mask directories.

   Multiprocessing-friendly worker: unpacks its single tuple argument so it can
   be dispatched with ``Pool.map``.

   :param args: Tuple ``(src, filename, dirs, conditions)`` where ``dirs`` are
       the mask directories to compare and ``conditions`` are their labels.
   :returns: Dict of per-pair metrics, or None when the file is missing in
       any directory.


.. py:function:: compare_cellpose_masks(src, verbose=False, processes=None, save=True)

   Compare masks across sibling subdirectories of ``src`` and plot the results.

   :param src: Root directory whose subdirectories each hold masks from a
       different condition/model.
   :param verbose: When True, render per-image mask overlays via
       :func:`spacr.plot.visualize_cellpose_masks`.
   :param processes: Worker-pool size for :func:`compare_mask`. None uses the
       default from ``multiprocessing.Pool``.
   :param save: When True, persist overlay images to disk.
   :returns: None.


