plesty.fss.data
===============

.. py:module:: plesty.fss.data

.. autoapi-nested-parse::

   The ``fine_structure`` data kind: what a polarization sweep says about each line.

   Importing this module registers the kind, so ``ExperimentData.load`` rebuilds
   a saved result and ``fine_structure`` resolves as an analyzer schema dtype.



Classes
-------

.. autoapisummary::

   plesty.fss.data.FineStructureData


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

.. py:class:: FineStructureData(values: Mapping[str, numpy.typing.ArrayLike], wavelength_unit: str | None = 'nm', metadata: dict[str, Any] | None = None, provenance: dict[str, Any] | None = None)

   Bases: :py:obj:`plesty.lib.data.ExperimentData`


   Fine structure of each fitted line, one entry per line.

   Produced by :class:`plesty.fss.FineStructure`. Every array has shape
   ``(peaks,)``, ``nan`` where a line's sweep could not be fitted.

   ======================  ====================================================
   ``fss``                 fine-structure splitting (µeV)
   ``fss_wavelength``      the same splitting as a wavelength (wavelength unit)
   ``axis_deg``            rotator angle of the longer-wavelength line (deg)
   ``mean_center``         mean line position over the sweep (wavelength unit)
   ``r_squared``           coefficient of determination of the sweep fit
   ``n_points``            sweep points the fit used
   ``fwhm``                median fitted linewidth over the sweep (wavelength unit)
   ``fss_valid``           1 when ``fss_wavelength < fwhm`` (``fss`` is a splitting), else 0
   ======================  ====================================================

   ``fss``, ``fss_wavelength``, ``axis_deg`` and ``mean_center`` each have a
   one-sigma ``<name>_err`` array. ``metadata`` records the ``rotator``, the
   sweep coordinate (``angle``) and its ``period_deg``.

   The splitting is the peak-to-peak amplitude of the oscillation of one
   fitted line's position with the rotator angle, divided by the rotator's
   contrast (½ for a quarter-wave plate, else 1). It measures a doublet only
   while the doublet's two components are closer than the linewidth and
   appear as one line, whose position cannot then move by more than that
   linewidth. An oscillation at least as wide as the line (``fss_valid == 0``)
   means the fit followed a different line from frame to frame — typically
   because the two components are further apart than their linewidth and
   appear as two separate lines — and ``fss`` is then not a splitting.

   Validate the arrays and attach their units.

   :param values: Every name in :meth:`names`, as arrays.
   :param wavelength_unit: Unit of the fitted spectrum's axis.
   :param metadata: Sweep context (``rotator``, ``angle``, ``period_deg``).
   :param provenance: Origin of the data.

   :raises ValueError: If a name is missing, the metadata lacks ``period_deg``,
       or the shapes disagree.


   .. py:attribute:: kind
      :value: 'fine_structure'


      Registry key and schema dtype token, e.g. ``"spectrum"``.


   .. py:attribute:: schema_version
      :value: 1


      Version of the array layout this class writes and reads.


   .. py:attribute:: QUANTITIES
      :type:  ClassVar[tuple[str, ...]]
      :value: ('fss', 'fss_wavelength', 'axis_deg', 'mean_center')



   .. py:attribute:: columns

      array name → entry, in reading order.

      An entry's keys, all optional:

      * ``label`` — the column heading, inline markup and ``$math$`` allowed;
        the array name when left out.
      * ``unit`` — used when the array carries none of its own.
      * ``description`` — one line of meaning.
      * ``result`` — ``False`` for an array the analysis kept but a reader does
        not need (a fit quality, a point count); default ``True``.
      * ``error`` — name of the array holding this one's one-sigma uncertainty,
        so the two are shown as one ``value ± error``.

      Arrays left out are not tabulated.

      :type: What each array means to a reader


   .. py:attribute:: values
      :type:  dict[str, plesty.lib.data.PlestyArray]

      Every array by name.


   .. py:method:: names() -> tuple[str, ...]
      :classmethod:


      Return every array name, in storage order.



   .. py:method:: _units(wavelength: str | None) -> dict[str, str | None]
      :staticmethod:


      Return the unit of each array.



   .. py:method:: __getitem__(name: str) -> plesty.lib.data.PlestyArray

      Return the array called *name*, e.g. ``result["fss"]``.



   .. py:property:: n_peaks
      :type: int


      Number of lines.


   .. py:property:: period_deg
      :type: float


      Rotator angle over which each line's position repeats.


   .. py:method:: evaluate(angle_deg: numpy.typing.ArrayLike) -> numpy.ndarray

      Evaluate each line's fitted position at rotator angles.

      :param angle_deg: Rotator angles in degrees, 1-D.

      :returns: Positions of shape ``(angles, peaks)``, in the wavelength unit.



   .. py:method:: to_arrays() -> dict[str, plesty.lib.data.PlestyArray]

      Return every array by name.



   .. py:method:: from_arrays(arrays: dict[str, plesty.lib.data.PlestyArray], metadata: dict[str, Any], provenance: dict[str, Any]) -> Self
      :classmethod:


      Rebuild the result from :meth:`to_arrays`; units travel with the arrays.



   .. py:method:: example() -> Self
      :classmethod:


      Return one line at 775 nm with a 40 µeV splitting seen through a half-wave plate.