plesty.fss.sine
===============

.. py:module:: plesty.fss.sine

.. autoapi-nested-parse::

   Sine fit of a line position against a polarization rotator angle.

   The two components of a fine-structure doublet are linearly polarized at
   right angles. While they are closer than the linewidth they appear as one
   line, and behind a rotating analyser the fitted centre of that line
   oscillates between them::

       centre(θ) = mean + A·cos(k·(θ − axis))

   ``k`` is the harmonic of the rotator: a half-wave plate turns the polarization
   by twice its angle, so a doublet repeats every 90° of plate angle (``k = 4``);
   a rotating polarizer repeats every 180° (``k = 2``). Behind either, the
   peak-to-peak amplitude of the oscillation, ``2·A``, is the splitting.

   A quarter-wave plate in front of a fixed polarizer also gives ``k = 4``, at half
   the contrast. A component linearly polarized at ``φ`` passes it with weight
   ``½[1 + ½·cos 2φ + ½·cos(4θ − 2φ)]`` (the Stokes analysis of a rotating QWP), so
   the centre of the doublet swings by only half the splitting, around a mean
   shifted by a constant the fit absorbs. The splitting is then ``2·A / ½``:
   :data:`CONTRAST` holds the fraction of the splitting each rotator shows.

   The model is linear in ``mean``, ``A·sin(k·axis)`` and ``A·cos(k·axis)``, so
   the fit is a weighted linear least-squares solve: no starting values, no
   convergence to fail.



Attributes
----------

.. autoapisummary::

   plesty.fss.sine.HARMONICS
   plesty.fss.sine.CONTRAST


Classes
-------

.. autoapisummary::

   plesty.fss.sine.SineFit


Functions
---------

.. autoapisummary::

   plesty.fss.sine.fit_sine
   plesty.fss.sine._sigma
   plesty.fss.sine._undetermined


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

.. py:data:: HARMONICS
   :type:  dict[str, int]

.. py:data:: CONTRAST
   :type:  dict[str, float]

.. py:class:: SineFit

   Result of :func:`fit_sine`, each value with its one-sigma error.

   :ivar mean: Mean line position (the unit of the positions).
   :ivar amplitude: Half the peak-to-peak oscillation of the position, ``≥ 0``.
   :ivar axis_deg: Rotator angle of the longest position, in ``[0, period)``.
   :ivar harmonic: ``k`` of the model.
   :ivar r_squared: Coefficient of determination.
   :ivar n_points: Finite points the fit used.
   :ivar values: The raw parameters ``(mean, a, b)`` of ``mean + a·sin(kθ) + b·cos(kθ)``.
   :ivar covariance: Their covariance, in :attr:`values` order.



   .. py:attribute:: mean
      :type:  float


   .. py:attribute:: mean_err
      :type:  float


   .. py:attribute:: amplitude
      :type:  float


   .. py:attribute:: amplitude_err
      :type:  float


   .. py:attribute:: axis_deg
      :type:  float


   .. py:attribute:: axis_deg_err
      :type:  float


   .. py:attribute:: harmonic
      :type:  int


   .. py:attribute:: r_squared
      :type:  float


   .. py:attribute:: n_points
      :type:  int


   .. py:attribute:: values
      :type:  tuple[float, float, float]


   .. py:attribute:: covariance
      :type:  numpy.ndarray


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


      Rotator angle over which the position repeats.


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

      Evaluate the fitted position at rotator angles in degrees.



.. py:function:: fit_sine(angle_deg: numpy.typing.ArrayLike, position: numpy.typing.ArrayLike, harmonic: int, sigma: numpy.typing.ArrayLike | None = None) -> SineFit

   Fit ``mean + A·cos(k·(θ − axis))`` to positions over rotator angles.

   Non-finite points are dropped. With *sigma* the fit is weighted by
   ``1/σ²``; as in :func:`plesty.lib.analyzer.fit_spectrum`, the covariance
   is scaled by the reduced chi-square, so the weights are relative. A point
   without a positive, finite error is dropped too — an unweighted point
   cannot be combined with weighted ones — unless no point has one, when the
   fit is unweighted.

   :param angle_deg: Rotator angle of each point, in degrees.
   :param position: Line position at each angle.
   :param harmonic: ``k`` — 4 for a half-wave plate, 2 for a polarizer.
   :param sigma: One-sigma error of each position.

   :returns: The fit; every value is ``nan`` when fewer than four points remain or
             the angles do not determine the model.

   :raises ValueError: If the arrays differ in shape or *harmonic* is not positive.


.. py:function:: _sigma(gradient: numpy.ndarray, covariance: numpy.ndarray) -> float

   Return the one-sigma error of a linear combination of the parameters.


.. py:function:: _undetermined(harmonic: int, n_points: int) -> SineFit

   Return a fit whose every value is ``nan``.