plesty.lib.analyzer
===================

.. py:module:: plesty.lib.analyzer

.. autoapi-nested-parse::

   Analyzer framework: schema-declared transforms from raw device data to results.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /reference/plesty/lib/analyzer/base_analyzer/index


Exceptions
----------

.. autoapisummary::

   plesty.lib.analyzer.AnalysisValidationError
   plesty.lib.analyzer.AnalyzerSchemaError


Classes
-------

.. autoapisummary::

   plesty.lib.analyzer.Analyzer


Package Contents
----------------

.. py:exception:: AnalysisValidationError

   Bases: :py:obj:`ValueError`


   Raised when analysis inputs or outputs violate the declared schema.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:class:: Analyzer(**params: Any)

   Bases: :py:obj:`abc.ABC`


   Base class for PLESTY analyzers: schema-declared data transforms.

   Subclasses declare ``input_schema``/``output_schema`` and implement
   exactly one method, :meth:`analyze`. Analysis parameters (including
   calibration objects or references) are passed as keyword arguments to
   the constructor and stored on :attr:`params`, from where they enter the
   provenance stamp of every result.

   Schema entries map an input/output name to a dict with keys:

   * ``dtype`` — **required**: a dtype token understood by
     :func:`plesty.lib.data.types.resolve_dtype` (``float``, ``array_float``,
     ``table2d``, …).
   * ``unit`` — unit filled onto outputs that do not set one.
   * ``description`` — human-readable meaning; filled onto outputs.
   * ``shape`` — arrays only: expected shape; ``None`` entries are free
     dimensions, e.g. ``[None, 2]``.
   * ``required`` — inputs only: whether the input must be supplied
     (default ``True``).

   Store the analysis parameters and validate the schema declarations.

   :param \*\*params: Analysis parameters and calibration handles. They are
                      introspectable via :attr:`params` and recorded in the
                      provenance stamp of every result.


   .. py:attribute:: input_schema
      :type:  ClassVar[dict[str, dict[str, Any]]]

      name → schema entry.

      :type: Declared inputs of :meth:`analyze`


   .. py:attribute:: output_schema
      :type:  ClassVar[dict[str, dict[str, Any]]]

      name → schema entry.

      :type: Declared outputs of :meth:`analyze`


   .. py:attribute:: params
      :type:  dict[str, Any]

      Analysis parameters passed to the constructor (calibration included).


   .. py:method:: analyze(**inputs: Any) -> dict[str, Any]
      :abstractmethod:


      Transform the schema-declared inputs into the schema-declared outputs.

      Implementations receive validated inputs as keyword arguments and
      return a dict with exactly the ``output_schema`` names as keys.
      Output metadata (name/unit/description) may be left unset — the base
      machinery fills it from the schema.

      :param \*\*inputs: Validated inputs, one keyword per ``input_schema`` name.

      :returns: Mapping of output name to result value.



   .. py:method:: __call__(**inputs: Any) -> dict[str, Any]

      Validate inputs, run :meth:`analyze`, validate and stamp outputs.

      :param \*\*inputs: One keyword per ``input_schema`` name; optional inputs
                         may be omitted.

      :returns: Mapping of output name to result value; array/table results carry
                a ``provenance`` attribute.

      :raises AnalysisValidationError: If inputs or outputs violate the schema.



   .. py:method:: provenance() -> dict[str, Any]

      Return the provenance stamp: analyzer identity, version, parameters.



   .. py:method:: _validate_schema(schema: dict[str, dict[str, Any]], allowed_keys: frozenset[str], label: str) -> None
      :staticmethod:


      Validate a schema declaration, raising :class:`AnalyzerSchemaError`.



   .. py:method:: _validate_inputs(inputs: dict[str, Any]) -> dict[str, Any]

      Check input names, dtypes, and shapes against ``input_schema``.



   .. py:method:: _finalize_outputs(outputs: Any) -> dict[str, Any]

      Validate outputs, fill schema metadata, and stamp provenance.



   .. py:method:: _conform(name: str, value: Any, entry: dict[str, Any], direction: str) -> Any

      Check one value against its schema entry, coercing raw arrays.



   .. py:method:: _conform_array(name: str, value: Any, entry: dict[str, Any], direction: str) -> plesty.lib.data.array.PlestyArray

      Coerce array-likes to :class:`PlestyArray` and check the shape.



   .. py:method:: _conform_scalar(name: str, value: Any, expected: type, direction: str) -> Any
      :staticmethod:


      Check a scalar value, accepting ints where floats are declared.



.. py:exception:: AnalyzerSchemaError

   Bases: :py:obj:`ValueError`


   Raised when an analyzer's schema declaration is invalid.

   Initialize self.  See help(type(self)) for accurate signature.