clophfit.fitting.data_structures
================================

.. py:module:: clophfit.fitting.data_structures

.. autoapi-nested-parse::

   Core data structures in `clophfit`.

   Classes:
   --------
   - DataArray: Represents matched `x`, `y`, and optional `w` arrays.
   - Dataset: Extends `dict` to store `DataArray` as key-value pairs, with optional
     support for pH-specific datasets.



Classes
-------

.. autoapisummary::

   clophfit.fitting.data_structures.DataArray
   clophfit.fitting.data_structures.Dataset
   clophfit.fitting.data_structures.MiniProtocol
   clophfit.fitting.data_structures.FitResult
   clophfit.fitting.data_structures.SpectraGlobResults


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

.. py:class:: DataArray

   Represent matched `x`, `y`, and optional `w` (weight) arrays.

   :param xc: x at creation.
   :type xc: ArrayF
   :param yc: y at creation.
   :type yc: ArrayF
   :param x_errc: x_err at creation.
   :type x_errc: ArrayF, optional
   :param y_errc: y_err at creation.
   :type y_errc: ArrayF, optional


   .. py:property:: mask
      :type: clophfit.clophfit_types.ArrayMask


      Mask.


   .. py:property:: x
      :type: clophfit.clophfit_types.ArrayF


      Masked x.


   .. py:property:: y
      :type: clophfit.clophfit_types.ArrayF


      Masked y.


   .. py:property:: y_err
      :type: clophfit.clophfit_types.ArrayF


      Masked y_err.


   .. py:property:: x_err
      :type: clophfit.clophfit_types.ArrayF


      Masked x_err.


.. py:class:: Dataset(data, *, is_ph = False)

   Bases: :py:obj:`collections.UserDict`\ [\ :py:obj:`str`\ , :py:obj:`DataArray`\ ]


   A dictionary-like container for storing `DataArray`.

   :param data: Maps keys to `DataArray` instances.
   :type data: dict[str, DataArray]
   :param is_ph:
   :type is_ph: bool


   .. py:attribute:: is_ph
      :type:  bool
      :value: False


      Indicates whether `x` values represent pH. Default is False.


   .. py:method:: from_da(da, *, is_ph = False)
      :classmethod:


      Alternative constructor to create Dataset from a list of DataArray.

      :param da: The DataArray objects to populate the dataset.
      :type da: DataArray | list[DataArray]
      :param is_ph: Indicate if x values represent pH (default is False).
      :type is_ph: bool, optional

      :returns: The constructed Dataset object.
      :rtype: Dataset



   .. py:method:: apply_mask(combined_mask)

      Correctly distribute and apply the combined mask across all DataArrays.

      :param combined_mask: Boolean array where True keeps the data point, and False masks it out.
      :type combined_mask: ArrayMask

      :raises ValueError: If the length of the combined_mask does not match the total number of data points.



   .. py:method:: copy(keys = None)

      Return a copy of the Dataset.

      If keys are provided, only data associated with those keys are copied.

      :param keys: List of keys to include in the copied dataset. If None (default),
                   copies all data.
      :type keys: list[str] | set[str] | None, optional

      :returns: A copy of the dataset.
      :rtype: Dataset

      :raises KeyError: If a provided key does not exist in the Dataset.



   .. py:method:: clean_data(n_params)

      Remove too small datasets.



   .. py:method:: concatenate_data()

      Concatenate x, y, x_err, and y_err across all datasets.

      Optimized version with pre-allocation for better memory efficiency.



   .. py:method:: export(filep)

      Export this dataset into a csv file.



   .. py:method:: plot(*, title = None, ax = None)

      Plot the dataset with error bars.

      :param title: Plot title.
      :type title: str | None
      :param ax: Axes to plot on. If None, creates a new figure.
      :type ax: Axes | None

      :returns: The figure containing the plot.
      :rtype: Figure



.. py:class:: MiniProtocol

   Bases: :py:obj:`Protocol`


   A very small common interface for all minimizers / backends.


.. py:class:: FitResult[MiniType: MiniProtocol]

   Result container of a fitting procedure.


   .. py:attribute:: figure
      :type:  matplotlib.figure.Figure | None
      :value: None


      Matplotlib figure visualizing the fit, if generated.


   .. py:attribute:: result
      :type:  lmfit.minimizer.MinimizerResult | _Result | None
      :value: None


      Backend-agnostic fit result exposing a .params attribute along with
      residual, redchi, and success fields (as in lmfit). For lmfit this is a
      MinimizerResult.


   .. py:attribute:: mini
      :type:  MiniType | None
      :value: None


      The primary backend object (e.g., lmfit.Minimizer, scipy.odr.Output, or
      az.InferenceData for PyMC).


   .. py:attribute:: dataset
      :type:  Dataset | None
      :value: None


      Dataset used for the fit (typically a deep copy of the input dataset).


   .. py:method:: pprint()

      Provide a brief summary of the fit, focusing on the K value.



   .. py:method:: is_valid()

      Whether figure, result, and minimizer exist.



.. py:class:: SpectraGlobResults

   A dataclass representing the results of both svd and bands fits.


   .. py:attribute:: svd
      :type:  FitResult[lmfit.minimizer.Minimizer] | None
      :value: None


      The `FitResult` object representing the outcome of the concatenated svd
      fit, or `None` if the svd fit was not performed.


   .. py:attribute:: gsvd
      :type:  FitResult[lmfit.minimizer.Minimizer] | None
      :value: None


      The `FitResult` object representing the outcome of the global svd fit,
      or `None` if the svd fit was not performed.


   .. py:attribute:: bands
      :type:  FitResult[lmfit.minimizer.Minimizer] | None
      :value: None


      The `FitResult` object representing the outcome of the bands fit, or
      `None` if the bands fit was not performed.