clophfit.fitting.data_structures

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

DataArray	Represent matched x, y, and optional w (weight) arrays.
Dataset	A dictionary-like container for storing DataArray.
MiniProtocol	A very small common interface for all minimizers / backends.
FitResult	Result container of a fitting procedure.
SpectraGlobResults	A dataclass representing the results of both svd and bands fits.
NoiseModelParams	Noise model parameters for a single label.
PlateNoiseModel	Container for noise parameters of all labels on a plate.

Functions

compute_noise_variance(y, sigma_floor[, gain, alpha])

Compute heteroscedastic noise variance from detector physics.

Module Contents

class clophfit.fitting.data_structures.DataArray

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

Parameters:

• xc (ArrayF) – x at creation.

• yc (ArrayF) – y at creation.

• x_errc (ArrayF, optional) – x_err at creation.

• y_errc (ArrayF, optional) – y_err at creation.

property mask: clophfit.clophfit_types.ArrayMask

Mask.

Return type:

clophfit.clophfit_types.ArrayMask

property x: clophfit.clophfit_types.ArrayF

Masked x.

Return type:

clophfit.clophfit_types.ArrayF

property y: clophfit.clophfit_types.ArrayF

Masked y.

Return type:

clophfit.clophfit_types.ArrayF

property y_err: clophfit.clophfit_types.ArrayF

Masked y_err.

Return type:

clophfit.clophfit_types.ArrayF

property x_err: clophfit.clophfit_types.ArrayF

Masked x_err.

Return type:

clophfit.clophfit_types.ArrayF

class clophfit.fitting.data_structures.Dataset(data, *, is_ph=False)

Bases: collections.UserDict[str, DataArray]

A dictionary-like container for storing DataArray.

Parameters:

• data (dict[str, DataArray]) – Maps keys to DataArray instances.

• is_ph (bool)

is_ph: bool = False

Indicates whether x values represent pH. Default is False.

classmethod from_da(da, *, is_ph=False)

Alternative constructor to create Dataset from a list of DataArray.

Parameters:

• da (DataArray | list[DataArray]) – The DataArray objects to populate the dataset.

• is_ph (bool, optional) – Indicate if x values represent pH (default is False).

Returns:

The constructed Dataset object.

Return type:

Dataset

apply_mask(combined_mask)

Correctly distribute and apply the combined mask across all DataArrays.

Parameters:

combined_mask (ArrayMask) – Boolean array where True keeps the data point, and False masks it out.

Raises:

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

Return type:

None

copy(keys=None)

Return a copy of the Dataset.

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

Parameters:

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

Returns:

A copy of the dataset.

Return type:

Dataset

Raises:

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

clean_data(n_params)

Remove too small datasets.

Parameters:

n_params (int)

Return type:

None

concatenate_data()

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

Optimized version with pre-allocation for better memory efficiency.

Return type:

tuple[clophfit.clophfit_types.ArrayF, clophfit.clophfit_types.ArrayF, clophfit.clophfit_types.ArrayF, clophfit.clophfit_types.ArrayF]

export(filep)

Export this dataset into a csv file.

Parameters:

filep (str | pathlib.Path)

Return type:

None

plot(*, title=None, ax=None, colors=None)

Plot the dataset with error bars.

Parameters:

• title (str | None) – Plot title.

• ax (Axes | None) – Axes to plot on. If None, creates a new figure.

• colors (dict[str, str] | None) – Optional dictionary mapping labels to matplotlib color strings. Defaults to {“1”: “tab:blue”, “2”: “tab:orange”, “0”: “tab:blue”}.

Returns:

The figure containing the plot.

Return type:

Figure

class clophfit.fitting.data_structures.MiniProtocol

Bases: Protocol

A very small common interface for all minimizers / backends.

class clophfit.fitting.data_structures.FitResult[MiniType: MiniProtocol]

Result container of a fitting procedure.

figure: matplotlib.figure.Figure | None = None

Matplotlib figure visualizing the fit, if generated.

result: lmfit.minimizer.MinimizerResult | _Result | None = 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.

mini: MiniType | None = None

The primary backend object (e.g., lmfit.Minimizer, odrpack.Output, or xr.DataTree for PyMC).

dataset: Dataset | None = None

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

pprint()

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

Return type:

str

is_valid()

Whether figure, result, and minimizer exist.

Return type:

bool

class clophfit.fitting.data_structures.SpectraGlobResults

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

svd: FitResult[lmfit.minimizer.Minimizer] | None = None

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

gsvd: FitResult[lmfit.minimizer.Minimizer] | None = None

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

bands: FitResult[lmfit.minimizer.Minimizer] | None = None

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

clophfit.fitting.data_structures.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

Parameters:

• y (ArrayF) – Signal values.

• sigma_floor (float | ArrayF) – Baseline noise floor (scalar or per-point array).

• gain (float) – Poisson shot-noise scaling factor. Pass 0 to disable the Poisson term entirely.

• alpha (float) – Proportional error coefficient. Pass 0 to disable the proportional term.

Returns:

Variance array, clipped to a minimum of 1.0 to prevent division-by-zero in downstream weighting.

Return type:

ArrayF

class clophfit.fitting.data_structures.NoiseModelParams

Noise model parameters for a single label.

sigma_floor

Baseline read-noise floor.

Type:

float

gain

Poisson shot-noise scaling factor. Pass 0 to disable the Poisson term.

Type:

float

alpha

Proportional error coefficient. Pass 0 to disable the proportional term.

Type:

float

sigma_ph

pH-pipetting noise (std dev in pH units). Pass 0 to disable the pH-dependent term.

Type:

float

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)

Parameters:

• y (ArrayF) – Signal values.

• dS_dph (ArrayF | None) – Per-point derivative ∂S/∂pH. If None (or sigma_ph is 0), the pH-dependent term is disabled.

Returns:

Per-point error estimate.

Return type:

ArrayF

class clophfit.fitting.data_structures.PlateNoiseModel(dict=None, /, **kwargs)

Bases: collections.UserDict[str, 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.

property sigma_floor: dict[str, float]

Get baseline noise floor per label.

Return type:

dict[str, float]

property gain: dict[str, float]

Get Poisson shot-noise scaling factor per label.

Return type:

dict[str, float]

property alpha: dict[str, float]

Get proportional error coefficient per label.

Return type:

dict[str, float]

apply_to(ds, slopes=None)

Apply noise model to a single Dataset in-place on a deep copy.

Parameters:

• ds (Dataset) – Dataset to update.

• slopes (dict[str, ArrayF] | None) – Per-label ∂S/∂pH arrays. If sigma_ph > 0 on any label, these are required for the pH-dependent term.

Returns:

Deep copy of ds with y_errc assigned from this noise model.

Return type:

Dataset

apply_to_plate(datasets, plate_slopes=None)

Apply noise model to every Dataset in a plate.

Parameters:

• datasets (dict[str, Dataset]) – Plate datasets keyed by well.

• plate_slopes (dict[str, dict[str, ArrayF]] | None) – Per-well per-label ∂S/∂pH arrays, keyed [well][label]. Required if sigma_ph > 0 on any label.

Returns:

New dict with the noise model applied to each dataset.

Return type:

dict[str, Dataset]