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 clophfit.fitting.data_structures.NoiseModelParams clophfit.fitting.data_structures.PlateNoiseModel Functions --------- .. autoapisummary:: clophfit.fitting.data_structures.compute_noise_variance 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, colors = 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 :param colors: Optional dictionary mapping labels to matplotlib color strings. Defaults to {"1": "tab:blue", "2": "tab:orange", "0": "tab:blue"}. :type colors: dict[str, str] | 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, odrpack.Output, or xr.DataTree 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. .. py:function:: compute_noise_variance(y, sigma_floor, gain = 1.0, alpha = 0.0) Compute heteroscedastic noise variance from detector physics. ``var = floor^2 + gain * max(y, 0) + (alpha * y)^2`` :param y: Signal values. :type y: ArrayF :param sigma_floor: Baseline noise floor (scalar or per-point array). :type sigma_floor: float | ArrayF :param gain: Poisson shot-noise scaling factor. Pass ``0`` to disable the Poisson term entirely. :type gain: float :param alpha: Proportional error coefficient. Pass ``0`` to disable the proportional term. :type alpha: float :returns: Variance array, clipped to a minimum of 1.0 to prevent division-by-zero in downstream weighting. :rtype: ArrayF .. py:class:: NoiseModelParams Noise model parameters for a single label. .. attribute:: sigma_floor Baseline read-noise floor. :type: float .. attribute:: gain Poisson shot-noise scaling factor. Pass ``0`` to disable the Poisson term. :type: float .. attribute:: alpha Proportional error coefficient. Pass ``0`` to disable the proportional term. :type: float .. attribute:: sigma_ph pH-pipetting noise (std dev in pH units). Pass ``0`` to disable the pH-dependent term. :type: float .. py:method:: compute_y_err(y, dS_dph = None) Compute per-point error from the noise model. ``sigma = sqrt(floor^2 + gain * max(y, 0) + (alpha * y)^2 + (sigma_ph * dS/dpH)^2)`` :param y: Signal values. :type y: ArrayF :param dS_dph: Per-point derivative ``∂S/∂pH``. If ``None`` (or *sigma_ph* is 0), the pH-dependent term is disabled. :type dS_dph: ArrayF | None :returns: Per-point error estimate. :rtype: ArrayF .. py:class:: PlateNoiseModel(dict=None, /, **kwargs) Bases: :py:obj:`collections.UserDict`\ [\ :py:obj:`str`\ , :py:obj:`NoiseModelParams`\ ] Container for noise parameters of all labels on a plate. Behaves like a dictionary mapping label names to NoiseModelParams, but provides convenient properties to extract individual parameters and apply the noise model to a Dataset. .. py:property:: sigma_floor :type: dict[str, float] Get baseline noise floor per label. .. py:property:: gain :type: dict[str, float] Get Poisson shot-noise scaling factor per label. .. py:property:: alpha :type: dict[str, float] Get proportional error coefficient per label. .. py:method:: apply_to(ds, slopes = None) Apply noise model to a single Dataset in-place on a deep copy. :param ds: Dataset to update. :type ds: Dataset :param slopes: Per-label ``∂S/∂pH`` arrays. If *sigma_ph* > 0 on any label, these are required for the pH-dependent term. :type slopes: dict[str, ArrayF] | None :returns: Deep copy of *ds* with ``y_errc`` assigned from this noise model. :rtype: Dataset .. py:method:: apply_to_plate(datasets, plate_slopes = None) Apply noise model to every Dataset in a plate. :param datasets: Plate datasets keyed by well. :type datasets: dict[str, Dataset] :param plate_slopes: Per-well per-label ``∂S/∂pH`` arrays, keyed ``[well][label]``. Required if *sigma_ph* > 0 on any label. :type plate_slopes: dict[str, dict[str, ArrayF]] | None :returns: New dict with the noise model applied to each dataset. :rtype: dict[str, Dataset]