goatpy.plotting
===============

.. py:module:: goatpy.plotting


Functions
---------

.. autoapisummary::

   goatpy.plotting.check_batch
   goatpy.plotting.plot_spectrum
   goatpy.plotting.plot_spectra_comparison


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

.. py:function:: check_batch(sdata, table_name: str = 'maldi_adata', batch_col: str = 'batch', show: bool = True)

.. py:function:: plot_spectrum(sdata: spatialdata.SpatialData, peaks_csv: Optional[Union[str, pathlib.Path]] = None, mz_col: Optional[str] = None, label_col: Optional[str] = None, table_name: str = 'maldi_adata', pixel_index: Optional[int] = None, reduce: str = 'mean', mz_range: Optional[Tuple[float, float]] = None, tolerance: float = 0.1, label_top_n: int = 20, label_min_intensity_pct: float = 5.0, figsize: Tuple[float, float] = (14, 5), spectrum_color: str = '#3a6fa8', peak_color: str = '#d9534f', peak_linewidth: float = 1.2, spectrum_linewidth: float = 0.8, ax: Optional[matplotlib.pyplot.Axes] = None, title: Optional[str] = None, show: bool = True, save_path: Optional[Union[str, pathlib.Path]] = None) -> matplotlib.pyplot.Axes

   Plot the binned spectrum from a SpatialData object, with optional overlay
   of a curated peak list CSV.

   :param sdata: Output of ``bin_imzml``, ``bin_and_align``, or ``load_and_align``.
   :type sdata: SpatialData
   :param peaks_csv: Path to a CSV file with curated peak m/z values (PEAKS.csv format or
                     glycan_list.csv format).  When supplied, each curated peak is marked
                     on the spectrum with a vertical dashed line.
   :type peaks_csv: str or Path, optional
   :param mz_col: Column name for m/z values in ``peaks_csv``.  Auto-detected when None.
   :type mz_col: str, optional
   :param label_col: Column name for peak labels in ``peaks_csv`` (e.g. "Composition").
                     Labels are drawn above the highest-intensity annotated peaks.
   :type label_col: str, optional
   :param table_name: Table to read from ``sdata.tables``.
   :type table_name: str, default "maldi_adata"
   :param pixel_index: Plot a single pixel's spectrum.  Plots the mean across all pixels
                       when None.
   :type pixel_index: int, optional
   :param reduce: Reduction applied across all pixels when ``pixel_index`` is None.
   :type reduce: "mean" | "median" | "max" | "sum", default "mean"
   :param mz_range: Restrict the x-axis to this m/z window.
   :type mz_range: (lo, hi), optional
   :param tolerance: m/z tolerance (Da) used to match curated peaks to binned bin centres.
                     A curated peak at 1257.5 Da will be matched if a bin centre lies
                     within ±``tolerance`` Da.
   :type tolerance: float, default 0.1
   :param label_top_n: Maximum number of peak labels drawn (to avoid overlap).  The
                       highest-intensity matched peaks are labelled first.
   :type label_top_n: int, default 20
   :param label_min_intensity_pct: Only draw a label if the matched bin's intensity is ≥ this percentage
                                   of the maximum spectrum intensity.
   :type label_min_intensity_pct: float, default 5.0
   :param figsize:
   :type figsize: (width, height), default (14, 5)
   :param spectrum_color: Line colour for the binned spectrum.
   :type spectrum_color: str, default "#3a6fa8"
   :param peak_color: Colour for curated peak overlay lines and labels.
   :type peak_color: str, default "#d9534f"
   :param peak_linewidth:
   :type peak_linewidth: float, default 1.2
   :param spectrum_linewidth:
   :type spectrum_linewidth: float, default 0.8
   :param ax: Plot into an existing Axes.  A new figure is created when None.
   :type ax: matplotlib Axes, optional
   :param title: Axes title.  Auto-generated when None.
   :type title: str, optional
   :param show: Call ``plt.show()`` at the end.
   :type show: bool, default True
   :param save_path: If supplied, save the figure to this path before showing.
   :type save_path: str or Path, optional

   :returns: **ax**
   :rtype: matplotlib Axes

   .. rubric:: Examples

   >>> plot_spectrum(sdata)
   >>> plot_spectrum(sdata, peaks_csv="goatpy/data/PEAKS.csv",
   ...              mz_range=(900, 2000))
   >>> plot_spectrum(sdata, peaks_csv="goatpy/data/glycan_list.csv",
   ...              mz_col="Theoretical m/z [M+Na]",
   ...              label_col="Composition",
   ...              label_top_n=30)
   >>> ax = plot_spectrum(sdata, show=False)   # embed in larger figure


.. py:function:: plot_spectra_comparison(sdata: spatialdata.SpatialData, pixel_indices: list[int], peaks_csv: Optional[Union[str, pathlib.Path]] = None, mz_col: Optional[str] = None, label_col: Optional[str] = None, table_name: str = 'maldi_adata', mz_range: Optional[Tuple[float, float]] = None, tolerance: float = 0.1, label_top_n: int = 15, figsize: Tuple[float, float] = (14, 5), show: bool = True, save_path: Optional[Union[str, pathlib.Path]] = None) -> matplotlib.pyplot.Axes

   Overlay spectra from multiple pixels on a single axes.

   :param sdata:
   :type sdata: SpatialData
   :param pixel_indices: Row indices to overlay.
   :type pixel_indices: list of int
   :param peaks_csv:
   :param mz_col:
   :param label_col:
   :param table_name:
   :param mz_range:
   :param :
   :param tolerance:
   :type tolerance: same as ``plot_spectrum``
   :param label_top_n:
   :type label_top_n: same as ``plot_spectrum``
   :param figsize:
   :type figsize: same as ``plot_spectrum``
   :param show:
   :type show: same as ``plot_spectrum``
   :param save_path:
   :type save_path: same as ``plot_spectrum``

   :returns: **ax**
   :rtype: matplotlib Axes