plesty.pol_pl.viz
=================

.. py:module:: plesty.pol_pl.viz

.. autoapi-nested-parse::

   Watch a polarization-PL run — live, replayed, or rendered to a video.

   .. code-block:: bash

       uv run python -m plesty.pol_pl.viz monitor                  # follow the newest run
       uv run python -m plesty.pol_pl.viz monitor --replay 2 --record run.mp4
       uv run python -m plesty.pol_pl.viz render --run pol_pl_20260915-160124

   Everything about *watching* — which run, where the share is mounted, live or
   replayed, a window of its own or embedded in a console that has this module
   installed — is :class:`plesty.lib.monitor.Viz`'s. This module says only what
   this experiment's records mean and what to draw from them.

   Three views follow the run: the newest spectrum with every tracked line
   marked, all spectra so far against the half-wave-plate angle, and the fine
   structure of the current dot — each line's shift against the angle while the
   sweep is measured, then the analysis's own fits and splittings.

   Two of them are shipped, not written here. The spectrum and the fine structure
   come from :mod:`plesty.fss.monitor`, whose analyzer measures the splitting, so
   this module tells them which of its record fields hold the sweep and nothing
   else. Only the map is local, and only because it drops cosmic rays first.

   What is genuinely this experiment's is :func:`read_spectrum`: a record names
   the file the spectrometer wrote, and turning that path into columns is the one
   thing no shared view can do for it.

   Watching is passive: these read the records the experiment already committed
   and the spectra they point at, and write nothing.



Attributes
----------

.. autoapisummary::

   plesty.pol_pl.viz.SPIKE_THRESHOLD
   plesty.pol_pl.viz.viz
   plesty.pol_pl.viz.lines


Classes
-------

.. autoapisummary::

   plesty.pol_pl.viz.CleanedMap


Functions
---------

.. autoapisummary::

   plesty.pol_pl.viz.remove_spikes
   plesty.pol_pl.viz.read_spectrum


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

.. py:data:: SPIKE_THRESHOLD
   :value: 20.0


.. py:function:: remove_spikes(counts: numpy.ndarray) -> numpy.ndarray

   Replace single-pixel spikes (cosmic rays) by the mean of their neighbours.

   The map's colour scale runs from the lowest count to the highest, so one
   cosmic ray of tens of thousands of counts would leave every emission line
   black. A spike is a pixel standing more than :data:`SPIKE_THRESHOLD` noise
   levels above the brighter of its two neighbours *and* more than twice that
   neighbour. The peak of an emission line fails the second test — its
   neighbours are nearly as bright — so lines pass unchanged. The noise is
   estimated robustly from the pixel-to-pixel differences.

   :param counts: One spectrum.

   :returns: The spectrum with single-pixel spikes replaced.


.. py:function:: read_spectrum(row: Any, run: Any) -> dict[str, Any]

   Turn the file a record names into the columns the views want.

   A record carries the *path* of the spectrum the spectrometer wrote, not
   the array — that is what keeps a measurement off the network. This is
   called once per row and cached, so the three views load each spectrum once
   between them.

   Read with :meth:`SpectrumData.load` — the same reader the analysis uses —
   for LightField ``.spe`` and for ``.npz`` spectra saved by
   ``SpectrumData.save``. A stack of frames is summed per pixel.

   :param row: One committed record.
   :param run: The run it belongs to; ``run.local`` translates the acquiring
               host's path onto this machine.

   :returns: ``wavelength``, ``counts`` as recorded, and ``clean`` with the cosmic
             rays taken out — the map wants the second, the spectrum view the
             first.


.. py:class:: CleanedMap(values: str = 'counts', row: str = '', *, x: str = 'wavelength', title: str = '', name: str = '', weight: Optional[float] = None, area: str = '', color: str = 'violet', scale: str = 'sqrt', x_label: str = 'Wavelength (nm)', y_label: str = '')

   Bases: :py:obj:`plesty.lib.monitor.common.SpectrumMap`


   The library's map, of the spectra with their cosmic rays taken out.

   Only the map drops them: its colour scale runs from the lowest count to
   the highest, so one ray of tens of thousands of counts would leave every
   emission line black. The spectrum view above shows every count as
   recorded.

   Stack *values* across rows, against *row*.

   :param values: Field holding each row's array.
   :param row: Field holding the swept coordinate, for the axis; empty
               numbers the rows instead.
   :param x: Field holding the sample axis, shared by every row — so
             the map is drawn in the same units as the spectrum above it.
             ``""``, or a field no row carries, numbers the samples.
   :param title: What the view is called.
   :param name: Layout key.
   :param weight: Relative size.
   :param area: Which side of the window it starts on.
   :param color: Palette token the colour map is built from.
   :param scale: ``"sqrt"`` or ``"linear"``.
   :param x_label: Axis label of the sample axis.
   :param y_label: Axis label of the swept axis.


   .. py:method:: block(data: Any) -> Any

      Stack the cleaned spectra rather than the recorded ones.



.. py:data:: viz

.. py:data:: lines