spacr.core
==========

.. py:module:: spacr.core




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

.. py:function:: preprocess_generate_masks(settings)

   Run the full mask-generation pipeline for one or more experiment folders.

   Consolidates inputs when requested, converts filenames to Yokogawa layout,
   generates per-channel masks via Cellpose/SAM, optionally adjusts cell masks
   against nucleus/pathogen/organelle overlays, and emits overlay plots.

   :param settings: Settings dict; canonicalized via
       :func:`spacr.settings.set_default_settings_preprocess_generate_masks`.
       Must include ``src`` and at least one of ``cell_channel``,
       ``nucleus_channel``, ``pathogen_channel``, or ``organelle_channel``.
   :returns: None.


.. py:function:: generate_image_umap(settings=None, return_fig=False)

   Generate a UMAP or tSNE embedding of per-object features and plot it.

   Reads measurements from the SQLite backend(s), applies preprocessing and
   dimensionality reduction, clusters the embedding, and renders scatter/grid
   plots of the resulting clusters.

   :param settings: Configuration dict; canonicalized via
       :func:`spacr.settings.set_default_umap_image_settings`. Common keys:
       ``src``, ``tables``, ``row_limit``, ``clustering``,
       ``reduction_method`` (``'UMAP'`` or ``'tSNE'``),
       ``embedding_by_controls``, ``col_to_compare``, ``pos``, ``neg``,
       ``plot_images``, ``save_figure``, ``exclude``.
   :param return_fig: When True, return the Matplotlib figure instead of the
       annotated DataFrame.
   :returns: DataFrame of the input rows plus a ``cluster`` column, or a
       Matplotlib ``Figure`` when ``return_fig`` is True.


.. py:function:: reducer_hyperparameter_search(settings=None, reduction_params=None, dbscan_params=None, kmeans_params=None, save=False, show=True, return_fig=False)

   Sweep UMAP/tSNE and DBSCAN/KMeans hyperparameters over the feature table.

   Renders a grid of embeddings, one cell per (reduction, clustering) pair, so
   the caller can eyeball the impact of each parameter combination.

   :param settings: Config dict; canonicalized via
       :func:`spacr.settings.set_default_umap_image_settings`.
   :param reduction_params: Dict or list of dicts of parameters for the
       reduction method. Presence of ``n_neighbors`` selects UMAP,
       ``perplexity`` selects tSNE.
   :param dbscan_params: Dict or list of DBSCAN parameter dicts (each with
       ``eps`` and ``min_samples``).
   :param kmeans_params: Dict or list of KMeans parameter dicts.
   :param save: When True, save the grid figure to ``<src>/results``.
   :param show: When True and not saving, call ``plt.show``.
   :param return_fig: When True, return the Matplotlib figure.
   :returns: The figure when ``return_fig`` is True, otherwise None.


.. py:function:: generate_screen_graphs(settings)

   Build recruitment-metric summary graphs per source and for the combined data.

   Reads per-object measurements, annotates conditions, computes the recruitment
   metric, and generates one plot per source folder plus one combined plot.

   :param settings: Config dict with keys ``src`` (path or list of paths),
       ``tables``, ``cells``, ``controls``, ``controls_loc``, ``graph_type``,
       ``summary_func``, ``y_axis_start``, ``error_bar_type``, ``theme``,
       ``representation``, ``nuclei_limit``, ``pathogen_limit``.
   :returns: None. Figures and CSVs are written under each source's
       ``results/`` folder.


