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_sigma=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_sigma (float | None) – Independent per-point prior on the true x: x_true[i] ~ N(x[i], x_sigma) for every point separately. For axes that are sets of independent measurements rather than a cumulative addition series - e.g. EnSpire wells, each set to its own nominal pH - the random-walk model below is not the right structure, and this is. None (default) leaves the axis fixed unless n_xerr > 0 enables the walk. Takes precedence over n_xerr when set.

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, learn_x_start_between=False, ctr_free_k=False, sample_ppc=False, per_well_ye_mags=None, ye_mag_parameterization='centered', learn_hill=False, hill_prior_sigma=0.2, acid_scale=False, acid_scale_sigma=0.3, 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, ctr_sigma_w_prior=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.

  • learn_x_start_between (bool) – Estimate that between-well scale (x_start_between) instead of pinning it, non-centred so it does not funnel; x_start_between_sigma is then its HalfNormal prior scale. A well’s pH offset shifts its K, so a pinned scale asserts how far apart two wells’ K may sit.

  • 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.

  • acid_scale (bool) – pH titrations: give every well a factor on its most acidic step, shared by all labels (acid_scale ~ LogNormal(0, acid_scale_sigma), dims well), for the loss of emission at the last acid addition. The size of that loss depends on the mutant, so the factor is per well; the step’s label ratio still informs K. False reproduces the plain model exactly.

  • acid_scale_sigma (float) – Log-scale prior SD of that factor.

  • 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.

  • ctr_sigma_w_prior (float | None) – Prior scale, in pH, of K_sigma_w: the spread of a control group’s replicates around the group’s own K. Given, each replicate keeps its own K (still reported as K_free) drawn a HalfNormal-distributed distance from the group’s, instead of sharing one K (ctr_free_k False) or ignoring the group (ctr_free_k True). Controls on these plates miss their mates by more than their intervals allow, and this is the term that says by how much. pH only.

  • 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.