bayesmith.reweight
Source-derived signatures and contracts. See the reference index for coverage and conventions.
Experimental composition surface. These primitives do not certify evidence, convergence, global density validity or reference-target overlap. Read the experimental guide before use.
Module contract
Fit hyperparameters by recycling a fixed reference posterior sample. For draws x_i from p_0(x | d), log weights are log p_eta(x_i, d) - log p_0(x_i, d). Their log mean estimates log Z_eta - log Z_0. Add log p(eta) and maximize to obtain a Monte Carlo marginal hyperparameter MAP, integrating out x rather than maximizing x. The reference need not be Gaussian. A fixed linear-Gaussian reference is particularly useful because its draws can come from GCR. This module owns the density-ratio objective; sampling remains with the existing compiler and optimization with bayesmith.optimize.minimize. See docs/reweight.md.
HyperparameterFit
Defined in bayesmith.reweight, line 58.
class HyperparameterFit(NamedTuple)
parameters: Any
log_objective: jax.Array
history: jax.Array
importance: ImportanceEstimate
gradient_norm: jax.ArrayPoint reached after a fixed step budget, without a convergence verdict. Objective and history use the MAXIMIZATION sign. ``parameters`` are in exactly the coordinates supplied to ``fit``. ``gradient_norm`` is the Euclidean norm in those coordinates. ``importance`` is evaluated at the returned point, so its weights describe the plug-in target posterior.
ImportanceEstimate
Defined in bayesmith.reweight, line 41.
class ImportanceEstimate(NamedTuple)
log_mean_weight: jax.Array
weights: jax.Array
ess: jax.Array
ess_fraction: jax.Array
max_weight: jax.ArrayRaw Monte Carlo normalization estimate and weight concentration. ``log_mean_weight`` is log(Z_target/Z_reference) when both callbacks score joint densities. With a normalized proposal denominator it instead estimates log Z_target. It is NOT an absolute log evidence by default. Kish ``ess`` measures weight concentration only, not MCMC autocorrelation or unseen target mass. No field certifies overlap or convergence.
PosteriorReweighting
Defined in bayesmith.reweight, line 217.
PosteriorReweighting(samples: Any, *, reference_log_density: Callable[[Any], jax.Array], target_log_density: Callable[[Any, Any], jax.Array])A fixed sample bank, cached reference scores and a target family. ``samples`` is an array or pytree with one common leading draw axis; combine chain and draw axes explicitly before construction. The bank must contain unweighted draws from the declared reference law. ``reference_log_density(draw)`` may score a normalized proposal or an unnormalized reference joint. ``target_log_density(parameters, draw)`` scores the FULL target joint, including every parameter-dependent normalizer. Only terms identical in both models can be canceled. The bank and cached denominator are held fixed while optimizing. The reference must cover the target support; this cannot be established from a finite bank. Callbacks must be deterministic and JAX compatible.
PosteriorReweighting.from_graphs
from_graphs(cls, reference: Graph, samples: Mapping[str, jax.Array], target: Callable[[Any], Graph]) -> PosteriorReweightingUse complete graph joints, preserving all likelihood/prior terms. ``target(parameters)`` builds the non-Gaussian graph. Both graphs must have the same latent names and condition on the same observed values and masks. All nuisance latents are included in each draw. A conditional block at held nuisance values is not a sample of this full reference posterior. The caller owns reference sampling and its convergence; passing a Gaussian approximation's draws while scoring some other reference joint is invalid. Latent value shapes and supported coordinate measures must agree; batch/event regrouping and same-measure support restrictions are allowed. Draws outside target support receive zero weight. Unsupported custom constraints require the explicit callback constructor. These checks do not establish proposal coverage or a graph-level factor's normalization.
PosteriorReweighting.log_weights
log_weights(self, parameters: Any) -> jax.ArrayFull target minus fixed reference scores; zeros remain -inf. NaN, positive infinity, and an all-zero-weight bank are refused, including under JIT. In particular, a negative Edgeworth correction cannot be clipped or silently dropped to make optimization proceed.
PosteriorReweighting.estimate
estimate(self, parameters: Any) -> ImportanceEstimateEvaluate the raw log mean and normalized posterior weights.
PosteriorReweighting.log_objective
log_objective(self, parameters: Any, *, log_hyperprior: Callable[[Any], jax.Array] | None=None) -> jax.ArrayLog mean weight + log hyperprior, up to a fixed additive constant. This is a Monte Carlo marginal likelihood objective, not the mean log weight, a joint MAP over the field, or an EM lower bound. ``log_hyperprior`` defines the MAP coordinates. For eta=exp(u), log p_eta(exp(u)) finds a mode in eta; adding u changes the density to one in u and generally changes that mode. No Jacobian is added automatically. Without a hyperprior this is marginal ML.
PosteriorReweighting.fit
fit(self, at: Any, *, log_hyperprior: Callable[[Any], jax.Array] | None=None, min_ess: float | None=None, **optimizer_options: Any) -> HyperparameterFitMaximize on this fixed bank using ``optimize.minimize`` settings. Optional ``min_ess`` is an explicit final Kish-ESS floor, not a certification of reliability. A finite objective and gradient are required at entry and exit. Steps do not redraw the reference or clip/smooth the importance ratios. Validate with a fresh bank and reference-chain diagnostics before trusting an optimized result.