plesty.fss.plot
===============

.. py:module:: plesty.fss.plot

.. autoapi-nested-parse::

   Plots of a fine-structure analysis: each line's energy shift against the rotator angle.

   For every emission line the figure has two panels, stacked:

   - **top** — the line's fitted position, as a photon-energy shift in µeV from its
     mean position, against the rotator angle, with one-sigma error bars, the
     fitted sine, and the fine-structure splitting and polarization axis;
   - **bottom** — the residuals of that fit in units of each point's error, with
     guides at ±2.

   A line whose splitting is not valid (``fss_valid == 0``) is drawn the same way,
   marked as such, so the reason is visible in the data.

   Plotting needs matplotlib, shipped in the ``plot`` extra
   (``uv add "plesty-fss[plot]"``).

   .. code-block:: python

       from plesty.fss import FineStructure
       from plesty.fss.plot import plot_fine_structure

       outputs = FineStructure(fit_options={"peaks": [775.2]})(spectrum=spectrum)
       figure = plot_fine_structure(outputs["fine_structure"], outputs["fit"])
       figure.savefig("fine_structure.png", dpi=150)



Attributes
----------

.. autoapisummary::

   plesty.fss.plot._RESIDUAL_GUIDE


Functions
---------

.. autoapisummary::

   plesty.fss.plot._require_matplotlib
   plesty.fss.plot.plot_fine_structure
   plesty.fss.plot.figure_png
   plesty.fss.plot._draw_line


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

.. py:data:: _RESIDUAL_GUIDE
   :value: 2.0


.. py:function:: _require_matplotlib() -> Any

   Import matplotlib's figure class, naming the extra that provides it when missing.


.. py:function:: plot_fine_structure(fine_structure: plesty.fss.data.FineStructureData, fit: plesty.lib.data.SpectrumFitData, lines: Optional[Sequence[int]] = None, panel_size: tuple[float, float] = (4.5, 4.0)) -> matplotlib.figure.Figure

   Draw the fine-structure analysis of every line, one column of two panels per line.

   :param fine_structure: The analyzer's ``fine_structure`` output.
   :param fit: The analyzer's ``fit`` output; its per-frame line
               positions, their errors and the rotator angle are drawn.
   :param lines: Indices of the lines to draw; all by default.
   :param panel_size: Width and height in inches of one line's column.

   :returns: A matplotlib figure, not shown and not saved.

   :raises ValueError: If the two outputs do not describe the same lines, the
       fit carries no rotator angle, or a line index is out of range.
   :raises ImportError: If matplotlib (the ``plot`` extra) is not installed.


.. py:function:: figure_png(figure: matplotlib.figure.Figure, dpi: int = 150) -> bytes

   Return a figure as PNG bytes, e.g. to store it with ``plesty.lib.data.save_result``.

   :param figure: The figure to render.
   :param dpi: Resolution in dots per inch.


.. py:function:: _draw_line(top: Any, bottom: Any, *, angles: numpy.ndarray, centers: numpy.ndarray, errors: numpy.ndarray, smooth_angles: numpy.ndarray, smooth_centers: numpy.ndarray, fine_structure: plesty.fss.data.FineStructureData, index: int, to_nm: float, unit: str, angle_label: str) -> None

   Draw one line's energy shift with its fit (top) and the normalized residuals (bottom).