sda.analysis.viz
================

.. py:module:: sda.analysis.viz

.. autoapi-nested-parse::

   Shared Plotly building-blocks for SDA analysis dashboards.

   Provides two reusable figure components:

   * :func:`iso_power_traces` — iso-power hyperbola lines for an Energy × Frequency
     scatter plot.
   * :func:`background_heatmap_trace` — griddata-interpolated background heatmap.



Functions
---------

.. autoapisummary::

   sda.analysis.viz.iso_power_traces
   sda.analysis.viz.background_heatmap_trace


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

.. py:function:: iso_power_traces(x_min, x_max, y_min, y_max, power_candidates = None)

   Return ``(traces, annotations)`` for iso-power hyperbolas.

   Each power level P (watts, since kHz·mJ = W) is drawn as a faint
   dotted line with a semi-transparent annotation label.  A wide transparent
   overlay trace carries a detailed hover tooltip without affecting visuals.

   :param x_min:
   :type x_min: :py:class:`Data range for the x-axis (Energy per pulse`, :py:class:`mJ).`
   :param x_max:
   :type x_max: :py:class:`Data range for the x-axis (Energy per pulse`, :py:class:`mJ).`
   :param y_min:
   :type y_min: :py:class:`Data range for the y-axis (Frequency`, :py:class:`kHz).`
   :param y_max:
   :type y_max: :py:class:`Data range for the y-axis (Frequency`, :py:class:`kHz).`
   :param power_candidates: range are skipped automatically.
   :type power_candidates: :py:class:`Power levels in W` to :py:class:`consider.  Levels outside the data`

   :returns: * **traces** (:py:class:`List` of ``go.Scatter`` traces to :py:class:`extend into the figure.`)
             * **annotations** (:py:class:`List` of :py:class:`annotation dicts` to :py:class:`pass` to ``fig.update_layout``.)


.. py:function:: background_heatmap_trace(x_pts, y_pts, z_pts, x_range, y_range, colorscale = 'RdYlGn', zmin = None, zmax = None, grid_size = 80, opacity = 0.4)

   Return a griddata-interpolated ``go.Heatmap`` trace, or ``None``.

   Requires at least **3 data points** to interpolate; returns ``None``
   when that threshold is not met.

   :param x_pts:
   :type x_pts: :py:class:`Scatter coordinates` and :py:class:`values.`
   :param y_pts:
   :type y_pts: :py:class:`Scatter coordinates` and :py:class:`values.`
   :param z_pts:
   :type z_pts: :py:class:`Scatter coordinates` and :py:class:`values.`
   :param x_range:
   :type x_range: :py:class:```(min`, :py:class:`max)`` tuples that define the grid extent.`
   :param y_range:
   :type y_range: :py:class:```(min`, :py:class:`max)`` tuples that define the grid extent.`
   :param colorscale:
   :type colorscale: :py:class:`Plotly colorscale name (default `````"RdYlGn"``:py:class:```).`
   :param zmin:
   :type zmin: :py:class:`Color axis limits.  Inferred from *z_pts* when ``None``.`
   :param zmax:
   :type zmax: :py:class:`Color axis limits.  Inferred from *z_pts* when ``None``.`
   :param grid_size:
   :type grid_size: :py:class:`Number` of :py:class:`grid points per axis (default 80).`
   :param opacity:
   :type opacity: :py:class:`Heatmap opacity (default 0.40).`

   :rtype: ``go.Heatmap`` or ``None``.