clophfit.fitting.bayes#

Bayesian (PyMC) fitting utilities and pipelines.

Functions#

process_trace(trace, p_names, ds)

Process the trace to extract parameter estimates and update datasets.

fit_binding_pymc(ds_or_fr, *[, n_sd, n_xerr, ...])

Analyze multi-label titration datasets using PyMC (single model).

fit_binding_pymc_multi(results, scheme, *[, n_sd, ...])

Multi-well PyMC with shared K per control group and per-label noise.

Module Contents#

clophfit.fitting.bayes.process_trace(trace, p_names, ds)#

Process the trace to extract parameter estimates and update datasets.

Parameters:

  • trace (xr.DataTree) – The posterior samples from PyMC sampling.

  • p_names (Iterable[str]) – Parameter names.

  • ds (Dataset) – The dataset containing titration data.

Returns:

The updated fit result with extracted parameter values and datasets. Residuals are WEIGHTED (weight * (obs - pred)) where weight = 1/y_err, computed using posterior mean parameter estimates.

Return type:

FitResult

clophfit.fitting.bayes.fit_binding_pymc(ds_or_fr, *, n_sd=10.0, n_xerr=1.0, min_x_step=0.2, noise=_DEFAULT_NOISE, robust=_DEFAULT_ROBUST, init=_DEFAULT_INIT, sampler=_DEFAULT_SAMPLER, x_prior=None)#

Analyze multi-label titration datasets using PyMC (single model).

Parameters:

  • ds_or_fr (Dataset | FitResult) – Either a Dataset (an initial LS fit is run) or a FitResult whose params seed the PyMC priors.

  • n_sd (float) – Number of standard deviations for parameter priors.

  • n_xerr (float) – Scaling factor for x-error.

  • min_x_step (float) – Minimum inferred change in x between consecutive titration steps when latent-x modeling is enabled.

  • noise (NoiseConfig) – Observation-noise configuration. Default scales y_err by a learned ye_mag multiplier; use NoiseConfig.structured() for a floor/gain/alpha noise model. See NoiseConfig.

  • robust (RobustConfig) – Robust-likelihood configuration (Student-t or contamination mixture). See RobustConfig.

  • init (InitConfig) – Prior-initialization strategy ("lmfit" prefit or "data_priors"). See InitConfig.

  • sampler (SamplerConfig) – NUTS sampling controls.

  • x_prior (XPrior | None) – Plate-level pH-axis prior from a previous multi-well fit, as produced by x_prior_from_trace(). None derives the axis from this dataset’s own x and x_err, as before. See SamplerConfig.

Returns:

Bayesian fitting results.

Return type:

FitResult

clophfit.fitting.bayes.fit_binding_pymc_multi(results, scheme, *, n_sd=5.0, n_xerr=1.0, min_x_step=0.2, x_error_model='deterministic', x_start_between_sigma=_DEFAULT_X_START_BETWEEN_SIGMA, x_prior=None, ctr_free_k=False, sample_ppc=False, per_well_ye_mags=None, ye_mag_parameterization='centered', learn_hill=False, hill_prior_sigma=0.2, well_noise_scale=False, shared_well_noise_scale=False, label_noise_scale_sigma=0.3, well_noise_sd_sigma=0.3, well_noise_scale_sigma=None, noise=_DEFAULT_NOISE, robust=_DEFAULT_ROBUST, init=_DEFAULT_INIT, sampler=_DEFAULT_SAMPLER)#

Multi-well PyMC with shared K per control group and per-label noise.

Parameters:

  • results (Mapping[str, Dataset | FitResult]) – Per-well datasets or initial fit results. Raw datasets are first fitted with fit_binding_glob() to seed the Bayesian model.

  • scheme (PlateScheme) – Plate scheme defining control groups for shared-K priors.

  • n_sd (float) – Prior width multiplier for per-well S0/S1 parameters.

  • n_xerr (float) – Scaling factor applied to x-value uncertainties.

  • min_x_step (float) – Minimum inferred change in x between consecutive titration steps.

  • x_error_model (Literal["deterministic", "per_well"]) – Model for x-error propagation across wells. "deterministic" shares one latent x_true walk across all wells; "per_well" gives each well its own cumulative-additions walk.

  • x_start_between_sigma (float) – Fixed between-well scale for the starting x (pH). Defaults to a small nonzero value, so each well gets its own x_start_well ~ Normal( x_start, x_start_between_sigma) tightly anchored on the shared plate x_start prior (common-mode anchor plus independent per-well jitter). Set to 0.0 for a single shared x_start across all wells.

  • x_prior (XPrior | None) – Plate-level pH axis from a previous fit, typically built by x_prior_from_trace(). None derives the axis from this plate’s own xc/x_errc. Stage two of a two-stage fit passes what stage one learned, so the axis is not rediscovered from scratch; only plate-level moments transfer, never a well’s own deviation.

  • ctr_free_k (bool) – If True, each control replicate gets an independent flat K prior instead of a shared control K.

  • sample_ppc (bool) – If True, add posterior predictive samples to the returned trace.

  • per_well_ye_mags (bool | None) – Learn per-well (not just per-label) ye_mag factors. None follows the noise config’s learn_ye_mags when a structured model is supplied.

  • ye_mag_parameterization (Literal["centered", "hierarchical", "separable", "separable_step"]) – Parameterization of the per-well ye_mag prior. "centered" (default) reproduces the historical independent-per-well construction; "hierarchical" partially pools the labels’ per-well factors with a learned deviation scale (the only per-well form that samples reliably). Applies in both noise modes; a no-op for shared or non-per-well ye_mag.

  • learn_hill (bool) – Fit one plate-wide Hill coefficient, shared across wells and labels, so the transition may be broader or sharper than Henderson-Hasselbalch. False fixes it at 1 and reproduces the plain model exactly. K remains the midpoint at any value, so estimates stay comparable.

  • hill_prior_sigma (float) – Width of the LogNormal(0, sigma) prior on that coefficient. The default keeps 95% of its mass between about 0.68 and 1.48, so the data must pull it off 1.

  • well_noise_scale (bool) – Enable a per-well multiplicative noise scale.

  • shared_well_noise_scale (bool) – Share the well-noise scale across labels.

  • label_noise_scale_sigma (float) – LogNormal prior scale for the per-label noise scale.

  • well_noise_sd_sigma (float) – HalfNormal prior scale for the per-well noise spread.

  • well_noise_scale_sigma (float | None) – Backwards-compatible alias for well_noise_sd_sigma.

  • noise (NoiseConfig) – Observation-noise configuration (ye_mag multiplier or structured floor/gain/alpha). See NoiseConfig.

  • robust (RobustConfig) – Robust-likelihood configuration (Student-t or contamination mixture). See RobustConfig.

  • init (InitConfig) – Prior-initialization strategy ("lmfit" prefit or "data_priors"). See InitConfig.

  • sampler (SamplerConfig) – NUTS sampling controls. See SamplerConfig.

Returns:

Shared PyMC trace together with reconstructed per-well fit results.

Return type:

MultiFitResult

Raises:

ValueError – If no valid dataset is found in results.