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.
`ResidualsMixin`	Shared canonical-residual accessor for fit-result containers.
`FitResult`	Result container of a fitting procedure.
`MultiFitResult`	Container for multi-well Bayesian results.
`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

mask_steps(steps)#

Exclude the given step indices from the fit, in place.

Masks positions in the original (unmasked) array while preserving any existing mask. Out-of-range indices are ignored.

Parameters:: steps (Iterable[int]) – Step indices to mask out (e.g. [0, 6] for the pH extremes).
Return type:: None

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

mask_label_steps(label, steps)#

Exclude step indices for one label’s DataArray, in place.

Drops a known-bad measurement region on a single channel without touching the others — e.g. the extreme-pH endpoints on a noisy, boosted-gain label:

ds.mask_label_steps("1", [0, 6])

Parameters:

label (str) – Label key into the dataset.
steps (Iterable[int]) – Step indices to mask out.

Raises:

KeyError – If label is not present in the dataset.

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.ResidualsMixin#

Shared canonical-residual accessor for fit-result containers.

Subclasses must implement residual_table(). They may add extra keyword-only parameters to it (FitResult adds well).

property residuals: pandas.DataFrame#

Canonical per-observation residual table for this fit.

Lazily computed, cached, and returned in the schema shared across the package (clophfit.fitting.model_validation.RESIDUAL_TABLE_COLUMNS: raw_res, yhat, sigma, std_res, …). Robustness is auto-detected. Use residual_table() to override the model or the robust settings.

Return type:: pandas.DataFrame

abstractmethod residual_table()#

Compute the canonical residual table. Implemented by subclasses.

Return type:: pandas.DataFrame

class clophfit.fitting.data_structures.FitResult#

Bases: ResidualsMixin

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: lmfit.minimizer.Minimizer | None = None#: The lmfit Minimizer object (for conf_interval, emcee, userargs). None for non-lmfit backends.

trace: xarray.DataTree | None = None#: The PyMC posterior trace. None for non-PyMC backends.

odr: odrpack.OdrResult | None = None#: The odrpack output (res_var, outlier detection). None for non-ODR backends.

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 a figure, a result, and at least one backend object exist.

Return type:: bool

residual_table(*, binding_function=None, robust=None, student_t_nu=None, outlier_threshold=3.0, well='')#

Compute the canonical residual table with explicit settings.

Parameters:

binding_function (Callable[..., object] | None) – Model to evaluate the prediction; defaults to binding_1site.
robust (bool | None) – Force the robust standardization of std_res. None auto-detects from the trace.
student_t_nu (float | None) – Student-t degrees of freedom for the robust score. None uses the detected/default value.
outlier_threshold (float) – Threshold for the is_residual_outlier flag.
well (str) – Value placed in the well column (single-fit label).

Returns:

The canonical residual table (see residuals).

Return type:

pd.DataFrame

class clophfit.fitting.data_structures.MultiFitResult#

Bases: ResidualsMixin

Container for multi-well Bayesian results.

Parameters:

trace (xr.DataTree) – Shared PyMC trace from the multi-well fit.
results (dict[str, FitResult]) – Per-well fit results reconstructed from the shared trace.

residual_table(*, binding_function=None, robust=None, student_t_nu=None, outlier_threshold=3.0)#

Compute the canonical multi-well residual table with explicit settings.

Parameters:

binding_function (Callable[..., object] | None) – Model to evaluate; defaults to binding_1site.
robust (bool | None) – Force robust standardization of std_res (None auto-detects).
student_t_nu (float | None) – Student-t degrees of freedom (None uses detected/default).
outlier_threshold (float) – Threshold for the is_residual_outlier flag.

Returns:

The canonical residual table (see residuals).

Return type:

pd.DataFrame

class clophfit.fitting.data_structures.SpectraGlobResults#

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

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

gsvd: FitResult | None = None#: The FitResult object representing the outcome of the global svd fit, or None if the svd fit was not performed.

bands: FitResult | 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 only away from zero so downstream weighting cannot divide by it.

Return type:

ArrayF

Notes

The clip used to be at 1.0, which silently discarded any genuine variance below it. A read-noise floor under one count is ordinary on the second label – measured floors here run from 0.17 to 4.04 – so on seven of eleven plates the returned sigma was 1.0 rather than the floor, an inflation of up to 5.9x that no diagnostic reported. The clip exists to avoid division by zero, and for that a tiny positive number suffices.

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]#

The baseline noise floor per label.

Return type:: dict[str, float]

property gain: dict[str, float]#

The Poisson shot-noise scaling factor per label.

Return type:: dict[str, float]

property alpha: dict[str, float]#

The 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]