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, n_samples, ...])

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 (KeysView[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[xr.DataTree]

clophfit.fitting.bayes.fit_binding_pymc(ds_or_fr, n_sd=10.0, n_xerr=1.0, n_samples=2000, nuts_sampler='default', *, n_tune=None, target_accept=None, max_treedepth=None, noise_model=None, robust=False, floor_mode=None, gain_mode=None, alpha_mode=None, learn_ye_mags=False, min_x_step=0.2)#

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

Parameters:

  • ds_or_fr (Dataset | FitResult[MiniT]) – Either a Dataset (will run initial LS fit) or a FitResult with initial params.

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

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

  • n_samples (int) – Number of MCMC samples.

  • nuts_sampler (str) – NUTS sampler backend: "default" (PyMC C/pytensor), "blackjax", "numpyro", or "nutpie".

  • n_tune (int | None) – Number of tuning steps. If None (default), use n_samples // 2.

  • target_accept (float | None) – NUTS target acceptance probability. If None (default), 0.95 is used when n_xerr > 0 and 0.9 otherwise.

  • max_treedepth (int | None) – Maximum tree depth for NUTS sampler. If None (default), PyMC’s default is used.

  • noise_model (PlateNoiseModel | None) – Noise model specification. None (default) uses a simple per-label ye_mag_{lbl} HalfNormal to scale the existing y_err. Pass a PlateNoiseModel to infer per-label floor, gain, and alpha from the full heteroscedastic noise model.

  • robust (bool) – If True, use StudentT likelihood (nu=3) for robust regression.

  • floor_mode (NoiseParamMode | None) – How to treat the floor parameter. None (default) resolves to "centered" for pre-fit FitResult input and "free" for raw Dataset input.

  • gain_mode (NoiseParamMode | None) – How to treat the gain parameter. None follows the same input-based rule as floor_mode.

  • alpha_mode (NoiseParamMode | None) – How to treat the alpha (rel_error) parameter. None follows the same input-based rule as floor_mode.

  • learn_ye_mags (bool) – If True, learn per-label scaling factors (ye_mag_{lbl}) even when a full noise_model is provided.

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

Returns:

Bayesian fitting results.

Return type:

FitResult[xr.DataTree]

clophfit.fitting.bayes.fit_binding_pymc_multi(results, scheme, n_sd=5.0, n_xerr=1.0, n_samples=2000, nuts_sampler='default', *, noise_model=None, shared_alpha=True, shared_gain=False, n_tune=None, target_accept=None, max_treedepth=None, x_error_model='deterministic', acid_drop_between_sigma=0.005, ctr_free_k=False, sample_ppc=False, robust=False, floor_mode=None, gain_mode=None, alpha_mode=None, learn_ye_mags=False, shared_ye_mags=False, min_x_step=0.2)#

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

Parameters:

  • results (Mapping[str, Dataset | FitResult[MiniT]]) – 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.

  • n_samples (int) – Number of MCMC posterior samples per chain.

  • nuts_sampler (str) – NUTS sampler backend ("default", "blackjax", "numpyro", "nutpie").

  • noise_model (PlateNoiseModel | None) – Noise model specification. None (default) uses per-label ye_mag_{lbl} HalfNormal to scale existing y_err. Pass a PlateNoiseModel to infer floor, gain, and alpha from the full heteroscedastic noise model.

  • shared_alpha (bool) – If True (default), use a single rel_error variable for all labels (comprehensive model). If False, use per-label rel_error_{lbl} (proportional model). Only used when noise_model is provided.

  • shared_gain (bool) – If True, use a single gain variable for all labels. If False (default), use per-label gain_{lbl}. Only used when noise_model is provided and gain terms are present.

  • n_tune (int | None) – Number of tuning steps for MCMC. If None, defaults to n_samples // 2.

  • target_accept (float | None) – NUTS target acceptance probability. If None (default), 0.95 is used when n_xerr > 0 and 0.9 otherwise.

  • max_treedepth (int | None) – Maximum tree depth for NUTS sampler. If None (default), PyMC’s default is used.

  • x_error_model (Literal["deterministic", "per_well", "hierarchical_per_well"]) – Model for x-error propagation. "deterministic" uses one shared x_true across all wells. "per_well" gives each well its own independent x_step (shared x_start, per-well cumulative additions constrained by min_x_step). "hierarchical_per_well" uses an acid-addition formulation: shared acid_drop_global per step (uncertainty from quadrature sum of adjacent x_errc), per-well acid_drop_well deviating at fixed acid_drop_between_sigma scale (not inferred).

  • acid_drop_between_sigma (float) – Fixed between-well scale for the acid_drop variation used by "hierarchical_per_well" (not inferred — set to the experimental tolerance). 0.005 (default) is very tight — suitable when all wells receive identical 2 uL additions. Increase to 0.01–0.02 for larger pipetting/buffer differences.

  • ctr_free_k (bool) – If True, each CTR replicate well gets its own independent flat K prior Normal(group_mean, 0.2) — identical to UNK well treatment, no hierarchical shrinkage. The spread of K posteriors across replicates then quantifies between-replicate accuracy. If False (default), all replicates of the same CTR share a single K.

  • sample_ppc (bool) – If True, generates posterior predictive samples and adds them to the returned InferenceData object. Needed for plot_ppc_well.

  • robust (bool) – If True, use StudentT likelihood (nu=3) for robust regression instead of Normal.

  • floor_mode (NoiseParamMode | None) – How to treat the floor parameter. None (default) resolves to "centered" when every input is already a FitResult and to "free" when any raw Dataset is supplied.

  • gain_mode (NoiseParamMode | None) – How to treat the gain parameter. None follows the same input-based rule as floor_mode.

  • alpha_mode (NoiseParamMode | None) – How to treat the alpha (rel_error) parameter. None follows the same input-based rule as floor_mode.

  • learn_ye_mags (bool) – If True, learn per-label scaling factors (ye_mag_{lbl}) even when a full noise_model is provided.

  • shared_ye_mags (bool) – If True, use a single shared ye_mag variable for all labels instead of per-label ye_mag_{lbl}. Only used when learn_ye_mags is True. Default False.

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

Returns:

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

Return type:

MultiFitResult

Raises:

ValueError – If no valid dataset is found in results.