plesty.fss.report
=================

.. py:module:: plesty.fss.report

.. autoapi-nested-parse::

   What a fine-structure analysis found, as a report a reader renders without this module.

   :meth:`plesty.fss.FineStructure.report` returns it; the experiment saves it
   beside the outputs (:meth:`plesty.lib.report.Report.save`). Three blocks:

   1. **A sentence** — how many lines were measured over which sweep, which of
      them split and by how much, and which did not.
   2. **A table**, one row per line — the line, the splitting as an energy and as
      a wavelength under one "Splitting" heading, the polarization axis, and the
      linewidth as an energy. A line whose position moves by at least its
      linewidth is marked: that oscillation is the fit hopping between lines,
      not a splitting. A splitting below :data:`SIGNIFICANCE` standard errors has
      no axis to quote.
   3. **A figure** — every line's energy shift against the rotator angle with its
      fitted sine, drawn by the same function as the live
      :class:`~plesty.fss.monitor.FineStructureView`.



Attributes
----------

.. autoapisummary::

   plesty.fss.report.SIGNIFICANCE
   plesty.fss.report.ROTATORS
   plesty.fss.report._HOP
   plesty.fss.report._UNRESOLVED


Functions
---------

.. autoapisummary::

   plesty.fss.report.fine_structure_report
   plesty.fss.report._resolved
   plesty.fss.report._summary
   plesty.fss.report._table
   plesty.fss.report._count
   plesty.fss.report._join


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

.. py:data:: SIGNIFICANCE
   :value: 3.0


.. py:data:: ROTATORS

.. py:data:: _HOP
   :value: '†'


.. py:data:: _UNRESOLVED
   :value: '‡'


.. py:function:: fine_structure_report(fine_structure: plesty.fss.data.FineStructureData, fit: plesty.lib.data.SpectrumFitData, *, title: str = 'Fine structure', provenance: Optional[dict[str, Any]] = None) -> plesty.lib.report.Report

   Build the report of one fine-structure analysis.

   :param fine_structure: The analyzer's ``fine_structure`` output.
   :param fit: The analyzer's ``fit`` output.
   :param title: The report's title.
   :param provenance: The analyzer's stamp.

   :returns: A sentence, the table of lines, and the figure of the sweep.


.. py:function:: _resolved(fine_structure: plesty.fss.data.FineStructureData, index: int) -> bool

   Whether a line's splitting is real and above :data:`SIGNIFICANCE`.


.. py:function:: _summary(fine_structure: plesty.fss.data.FineStructureData, fit: plesty.lib.data.SpectrumFitData, unit: str, rotator: str) -> str

   One paragraph: the sweep, the lines that split, the lines that did not.


.. py:function:: _table(fine_structure: plesty.fss.data.FineStructureData, unit: str, to_nm: float) -> plesty.lib.report.Table

   One row per line, the splitting as an energy and a wavelength under one heading.


.. py:function:: _count(number: int, noun: str) -> str

   ``"one line"``, ``"two lines"``, ``"12 lines"``.


.. py:function:: _join(items: list[str]) -> str

   ``"a"``, ``"a and b"``, ``"a, b and c"``.