Posterior¶
Package Overview¶
posterior
¶
posterior¶
Posterior representations.
This subpackage provides: - ParameterSource: protocol for anything we can draw parameters from, including a Prior - ParameterPosterior: a source that also carries p(θ | data) and its model - MAPPosterior: point estimate at θ_MAP (a delta distribution)
Two-tier design
- ParameterPosterior: represents p(θ | data)
- PredictivePosterior: represents p(f(X*) | data)
Future extensions
- LaplacePosterior: Gaussian approximation N(θ_MAP, Σ)
Classes:
| Name | Description |
|---|---|
MAPPosterior |
MAP (Maximum A Posteriori) posterior: the point estimate θ_MAP. |
MCMCPosterior |
Backend-agnostic container for MCMC posterior samples. |
ParameterPosterior |
Protocol for posterior distributions over model parameters p(θ | data). |
ParameterSource |
Protocol for anything we can draw model parameters from. |
PredictivePosterior |
Protocol for predictive distributions p(f(X*) | data) at test stimuli. |
ThresholdConfig |
Configuration for :class: |
WPPMPredictivePosterior |
Predictive posterior for WPPM models. |
MAPPosterior
¶
MAP (Maximum A Posteriori) posterior: the point estimate θ_MAP.
Carries no uncertainty. It stores θ_MAP as 1 chain with 1 sample, the same
layout an MCMCPosterior uses for its samples, so
WPPMCovarianceFieldSamples(map_posterior) needs no n_samples and no
key. The chain axis is only a layout: no sampler ran.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
WPPM
|
Model instance used for predictions |
required |
params
|
dict
|
MAP parameter dictionary (θ_MAP) |
required |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
Notes
This implements the ParameterPosterior protocol.
Methods:
| Name | Description |
|---|---|
sample |
Return n copies of the point estimate θ_MAP. |
Attributes:
| Name | Type | Description |
|---|---|---|
model |
Return the associated model. |
|
n_chains |
int
|
Number of chains, always 1. |
n_draws |
int
|
Number of samples per chain, always 1. |
params |
Return the MAP parameters (θ_MAP). |
|
samples |
dict
|
θ_MAP as 1 chain with 1 sample. |
Source code in src/psyphy/posterior/posterior.py
samples
¶
samples: dict
θ_MAP as 1 chain with 1 sample.
Returns:
| Type | Description |
|---|---|
dict
|
|
sample
¶
sample(n: int, key)
Return n copies of the point estimate θ_MAP.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
Number of samples |
required |
key
|
Array
|
PRNG key. A point estimate has no randomness, so the key goes unread. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Parameter PyTree with leading dimension n. Each array has shape (n, ...) with identical values. |
Notes
Every row is the same parameter set, so a mean over the draws is θ_MAP and their spread is zero.
Source code in src/psyphy/posterior/posterior.py
MCMCPosterior
¶
Backend-agnostic container for MCMC posterior samples.
Satisfies the ParameterPosterior protocol:
- params: posterior mean parameter over all chains and draws (for
WPPM, do not turn this into a covariance field -- see params)
- model: the fitted WPPM instance
- sample(n, key): draw n parameter vectors from the chain pool
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
WPPM
|
The model instance used during inference. |
required |
samples
|
dict
|
Parameter samples. Each value has shape |
required |
sampler_stats
|
dict | None
|
Per-chain diagnostics returned by the sampler, each of shape
|
None
|
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
Notes
Implements the ParameterPosterior protocol (i.e., structural, not inherited).
Methods:
| Name | Description |
|---|---|
sample |
Draw n parameter vectors from the pooled chain samples. |
to_arviz |
Convert MCMC samples to an ArviZ InferenceData object. |
Attributes:
| Name | Type | Description |
|---|---|---|
model |
The WPPM instance used during inference. |
|
n_chains |
int
|
Number of chains. |
n_draws |
int
|
Number of draws per chain. |
params |
dict
|
Posterior mean of the parameters over all chains and draws. |
sampler_stats |
|
|
samples |
dict
|
All draws, chain structure preserved. |
Source code in src/psyphy/posterior/mcmc_posterior.py
params
¶
params: dict
Posterior mean of the parameters over all chains and draws.
Returns:
| Type | Description |
|---|---|
dict
|
Parameter PyTree with the same structure as a single draw.
For WPPM: |
Warnings
For WPPM, do not build a covariance field from this, e.g.
WPPMCovarianceField(model, posterior.params). That gives Σ(E[W]),
which is not the posterior mean of Σ and is systematically too small:
- Σ = U Uᵀ + λI is quadratic in W, so E[Σ] = Σ(E[W]) + Cov[U] and averaging W first drops the (positive semidefinite) Cov[U] term.
- W is only identified up to an orthogonal rotation of its embedding axis (W -> W R leaves Σ unchanged), so draws at different orientations partly cancel in E[W], pulling Σ(E[W]) toward λI.
For the posterior mean covariance field use
WPPMCovarianceFieldSamples(posterior).mean(x); for
individual covariance draws use sample(n). E[W] remains a valid parameter set, e.g. as
init_params for another fit.
samples
¶
samples: dict
All draws, chain structure preserved.
Returns:
| Type | Description |
|---|---|
dict
|
|
Notes
This is the raw posterior, not a summary: use it to persist a fit, to
pass the draws to another library, or for any computation that needs
the per-chain layout (diagnostics do). For a random subset of draws use
:meth:sample; for the posterior mean parameter use :attr:params.
The returned dict is a fresh mapping, so adding or removing keys does not affect the posterior, but the arrays themselves are shared (JAX arrays are immutable).
sample
¶
Draw n parameter vectors from the pooled chain samples.
Pools all chains and draws into a flat collection of
n_chains * n_draws samples, then randomly subsamples n
of them (without replacement if n <= total, with replacement otherwise).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
Number of samples to return. |
required |
key
|
Array
|
PRNG key for the subsample. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Parameter PyTree with leading dimension |
Notes
For every stored sample, read :attr:samples instead. It keeps the chain
axis and takes no key.
Source code in src/psyphy/posterior/mcmc_posterior.py
to_arviz
¶
Convert MCMC samples to an ArviZ InferenceData object.
Requires arviz to be installed::
1 | |
Returns:
| Type | Description |
|---|---|
DataTree
|
ArviZ >= 1.0 returns xarray's DataTree; |
Notes
ArviZ handles arbitrary-dimensional variables natively, no flattening required. R-hat and ESS are computed per scalar element.
If sampler_stats were provided at construction (e.g.
acceptance_rate), they are included in the sample_stats
group.
Examples:
Source code in src/psyphy/posterior/mcmc_posterior.py
216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 | |
ParameterPosterior
¶
Bases: ParameterSource, Protocol
Protocol for posterior distributions over model parameters p(θ | data).
Returned by InferenceEngine.fit(model, data). Used for diagnostics, parameter sampling, uncertainty.
A :class:ParameterSource that also carries params and model.
Methods:
| Name | Description |
|---|---|
sample |
Draw n parameter vectors. |
Attributes:
| Name | Type | Description |
|---|---|---|
model |
Associated generative model. |
|
params |
dict
|
Point estimate or posterior mean parameters. |
model
¶
Associated generative model.
Returns:
| Type | Description |
|---|---|
Model
|
The WPPM or (other model) instance used for predictions. |
params
¶
params: dict
Point estimate or posterior mean parameters.
Returns:
| Type | Description |
|---|---|
dict
|
Parameter PyTree (e.g., {"W": jnp.ndarray}) |
Notes
- MAP: θ_MAP
- MCMC: posterior mean of the parameter samples. This is a parameter average, not an average of model outputs: for WPPM, Σ(params) is not the posterior mean covariance (use WPPMCovarianceFieldSamples).
sample
¶
Draw n parameter vectors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
Number of draws. |
required |
key
|
Array
|
PRNG key for the draw. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Parameter PyTree with a leading axis of n, so for WPPM {"W": (n, *W_shape)}. |
Notes
What a draw is depends on the source:
- a
Priorgenerates independent draws - a
MAPPosteriorrepeats one parameter set, so the draws are identical - an
MCMCPosteriorsubsamples its stored draws, without replacement while n fits
The draws are unweighted, so reduce them with a plain mean or quantile.
Source code in src/psyphy/posterior/parameter_posterior.py
ParameterSource
¶
Bases: Protocol
Protocol for anything we can draw model parameters from.
Satisfied by Prior, MAPPosterior and MCMCPosterior.
Notes
sample pools the chains. For chain-shaped draws, use MCMCPosterior.samples
or :func:psyphy.model.covariance_to_arviz, both of which are MCMC-only.
A source draws parameters and cannot score them: there is no log_prob here.
Methods:
| Name | Description |
|---|---|
sample |
Draw n parameter vectors. |
sample
¶
Draw n parameter vectors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
Number of draws. |
required |
key
|
Array
|
PRNG key for the draw. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Parameter PyTree with a leading axis of n, so for WPPM {"W": (n, *W_shape)}. |
Notes
What a draw is depends on the source:
- a
Priorgenerates independent draws - a
MAPPosteriorrepeats one parameter set, so the draws are identical - an
MCMCPosteriorsubsamples its stored draws, without replacement while n fits
The draws are unweighted, so reduce them with a plain mean or quantile.
Source code in src/psyphy/posterior/parameter_posterior.py
PredictivePosterior
¶
Bases: Protocol
Protocol for predictive distributions p(f(X*) | data) at test stimuli.
Returned by Model.posterior(X) for use in acquisition functions.
Methods:
| Name | Description |
|---|---|
rsample |
Reparameterized samples from p(f(X*) | data). |
Attributes:
| Name | Type | Description |
|---|---|---|
mean |
ndarray
|
Posterior predictive mean E[f(X*) | data]. |
variance |
ndarray
|
Posterior predictive marginal variances Var[f(X*) | data]. |
mean
¶
Posterior predictive mean E[f(X*) | data].
Returns:
| Type | Description |
|---|---|
(ndarray, shape(n_test) or (n_test, output_dim))
|
The first for scalar outputs, the second for vector outputs (future). |
Notes
Computed via Monte Carlo integration over parameter posterior.
:class:WPPMPredictivePosterior in threshold_pred=True mode is a
documented exception to the shapes above: it returns matrix-valued
moments, shape (n_test, input_dim, input_dim) -- a threshold
covariance per test point, not a scalar or vector. See its own
mean/variance docstrings.
variance
¶
Posterior predictive marginal variances Var[f(X*) | data].
Returns:
| Type | Description |
|---|---|
(ndarray, shape(n_test) or (n_test, output_dim))
|
The first for scalar outputs, the second for vector outputs (future). |
Notes
Captures both aleatoric (model) and epistemic (parameter) uncertainty.
Same WPPM threshold_pred=True exception as :attr:mean applies.
rsample
¶
rsample(sample_shape: tuple = (), *, key: Array) -> ndarray
Reparameterized samples from p(f(X*) | data).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sample_shape
|
tuple
|
Shape of sample batch |
()
|
key
|
Array
|
PRNG key |
required |
Returns:
| Type | Description |
|---|---|
(ndarray, shape(*sample_shape, n_test) or (*sample_shape, n_test, output_dim))
|
The first for scalar outputs, the second for vector outputs. |
Notes
Enables gradient-based acquisition optimization via reparameterization trick.
Source code in src/psyphy/posterior/predictive_posterior.py
ThresholdConfig
¶
ThresholdConfig(n_theta: int = 16, n_length: int = 200, bounds: tuple[float, float] = (0.0005, 0.3), target_prob_correct: float = 2.0 / 3.0, chunk: int = 2000)
Configuration for :class:WPPMPredictivePosterior's threshold_pred mode.
Controls the oddity-task inversion that recovers a threshold covariance
Σ_thres(x), the contour where the probability correct reaches
target_prob_correct, from a
fitted noise field. There is no closed form for this inversion (see
:class:~psyphy.model.likelihood.OddityTask), so it is done numerically:
probe n_theta directions around each reference point, brute-force
search n_length candidate distances per direction for the one closest
to target_prob_correct, then fit an ellipsoid to the resulting boundary
points.
Attributes:
| Name | Type | Description |
|---|---|---|
n_theta |
int
|
Number of directions probed around each reference point. Must be at
least |
n_length |
int
|
Number of candidate distances probed per direction. Brute-force search rather than bisection: P(correct) is only monotone in distance up to Monte Carlo noise, so a root-finder can walk off a noisy plateau where a dense-grid argmin cannot. |
bounds |
tuple[float, float]
|
|
target_prob_correct |
float
|
The probability correct that defines the threshold contour. 2/3 is the oddity task's standard criterion. |
chunk |
int
|
Batch size for the Monte Carlo sweep, bounding peak memory;
|
Notes
Cost per (posterior sample, reference point) pair is
n_theta * n_length calls to the task's MC-simulated predict, each
itself an average over OddityTaskConfig.num_samples draws. Total cost
for a call to :class:WPPMPredictivePosterior scales as
n_samples * n_test * n_theta * n_length * num_samples; a warning is
emitted when n_samples * n_test alone exceeds 200.
WPPMPredictivePosterior
¶
WPPMPredictivePosterior(param_posterior: ParameterPosterior, X: ndarray, n_samples: int = 100, threshold_pred: bool = False, threshold_config: ThresholdConfig | None = None, *, key: Array)
Predictive posterior for WPPM models.
Computes p(f(X*) | data) via Monte Carlo integration over parameter posterior p(θ | data).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
param_posterior
|
ParameterPosterior
|
Posterior over model parameters |
required |
X
|
(ndarray, shape(n_test, k_stimuli, input_dim) or (n_test, input_dim))
|
Test stimuli. Shape depends on
|
required |
n_samples
|
int
|
Number of posterior samples for MC integration |
100
|
threshold_pred
|
bool
|
Whether to compute threshold covariances (Σ_thres, the
contour where the probability correct reaches
|
False
|
threshold_config
|
ThresholdConfig
|
Settings for the threshold inversion. Only used when
|
None
|
key
|
(Array, keyword - only)
|
PRNG key, split once here into a key for drawing parameters and a key
for the threshold sweep's Monte Carlo. |
required |
Attributes:
| Name | Type | Description |
|---|---|---|
param_posterior |
ParameterPosterior
|
Wrapped parameter posterior |
X |
(ndarray, shape(n_test, k_stimuli, input_dim) or (n_test, input_dim))
|
Test stimuli |
n_samples |
int
|
MC sample count |
threshold_pred |
bool
|
Whether this instance predicts thresholds rather than probabilities |
threshold_config |
ThresholdConfig or None
|
Threshold-inversion settings ( |
Notes
Uses lazy evaluation: moments computed on first access.
Methods:
| Name | Description |
|---|---|
rsample |
Sample predictions from p(f(X*) | data). |
Source code in src/psyphy/posterior/predictive_posterior.py
mean
¶
E[f(X*) | data].
Shape (n_test,): predicted probabilities, unless
threshold_pred=True, in which case shape is
(n_test, input_dim, input_dim): the posterior-mean threshold
covariance Σ_thres at each reference point, averaged arithmetically
over posterior parameter samples (the PD cone is convex, so this
stays PD; not a geometric/Bures mean).
variance
¶
Var[f(X*) | data].
Shape (n_test,) unless threshold_pred=True, in which case shape
is (n_test, input_dim, input_dim): elementwise variance of the
per-sample threshold covariances (not a variance of a matrix in
any distributional sense; just jnp.var over the sample axis,
entry by entry).
rsample
¶
rsample(sample_shape: tuple = (), *, key: Array) -> ndarray
Sample predictions from p(f(X*) | data).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sample_shape
|
tuple
|
Batch shape |
()
|
key
|
Array
|
PRNG key |
required |
Returns:
| Type | Description |
|---|---|
(ndarray, shape(*sample_shape, n_test) or (*sample_shape, n_test, input_dim, input_dim))
|
The first unless |
Source code in src/psyphy/posterior/predictive_posterior.py
Parameter Protocols¶
parameter_posterior
¶
parameter_posterior.py
Protocols for things we can draw model parameters from.
2 of them, one nested in the other: - ParameterSource: anything that hands back n parameter draws. A Prior is one, and so is every posterior - ParameterPosterior: a source that ALSO carries a point estimate and the model it was fitted to, representing p(θ | data)
Design
Different inference engines produce different posterior representations: - MAP: a point estimate - MCMC: collection of samples
All implement a common protocol for polymorphic use.
Classes:
| Name | Description |
|---|---|
ParameterPosterior |
Protocol for posterior distributions over model parameters p(θ | data). |
ParameterSource |
Protocol for anything we can draw model parameters from. |
ParameterPosterior
¶
Bases: ParameterSource, Protocol
Protocol for posterior distributions over model parameters p(θ | data).
Returned by InferenceEngine.fit(model, data). Used for diagnostics, parameter sampling, uncertainty.
A :class:ParameterSource that also carries params and model.
Methods:
| Name | Description |
|---|---|
sample |
Draw n parameter vectors. |
Attributes:
| Name | Type | Description |
|---|---|---|
model |
Associated generative model. |
|
params |
dict
|
Point estimate or posterior mean parameters. |
model
¶
Associated generative model.
Returns:
| Type | Description |
|---|---|
Model
|
The WPPM or (other model) instance used for predictions. |
params
¶
params: dict
Point estimate or posterior mean parameters.
Returns:
| Type | Description |
|---|---|
dict
|
Parameter PyTree (e.g., {"W": jnp.ndarray}) |
Notes
- MAP: θ_MAP
- MCMC: posterior mean of the parameter samples. This is a parameter average, not an average of model outputs: for WPPM, Σ(params) is not the posterior mean covariance (use WPPMCovarianceFieldSamples).
sample
¶
Draw n parameter vectors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
Number of draws. |
required |
key
|
Array
|
PRNG key for the draw. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Parameter PyTree with a leading axis of n, so for WPPM {"W": (n, *W_shape)}. |
Notes
What a draw is depends on the source:
- a
Priorgenerates independent draws - a
MAPPosteriorrepeats one parameter set, so the draws are identical - an
MCMCPosteriorsubsamples its stored draws, without replacement while n fits
The draws are unweighted, so reduce them with a plain mean or quantile.
Source code in src/psyphy/posterior/parameter_posterior.py
ParameterSource
¶
Bases: Protocol
Protocol for anything we can draw model parameters from.
Satisfied by Prior, MAPPosterior and MCMCPosterior.
Notes
sample pools the chains. For chain-shaped draws, use MCMCPosterior.samples
or :func:psyphy.model.covariance_to_arviz, both of which are MCMC-only.
A source draws parameters and cannot score them: there is no log_prob here.
Methods:
| Name | Description |
|---|---|
sample |
Draw n parameter vectors. |
sample
¶
Draw n parameter vectors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
Number of draws. |
required |
key
|
Array
|
PRNG key for the draw. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Parameter PyTree with a leading axis of n, so for WPPM {"W": (n, *W_shape)}. |
Notes
What a draw is depends on the source:
- a
Priorgenerates independent draws - a
MAPPosteriorrepeats one parameter set, so the draws are identical - an
MCMCPosteriorsubsamples its stored draws, without replacement while n fits
The draws are unweighted, so reduce them with a plain mean or quantile.
Source code in src/psyphy/posterior/parameter_posterior.py
Parameter Posterior Implementations¶
posterior
¶
posterior.py
Concrete ParameterPosterior implementations.
This module provides: - MAPPosterior: point estimate at θ_MAP
Classes:
| Name | Description |
|---|---|
MAPPosterior |
MAP (Maximum A Posteriori) posterior: the point estimate θ_MAP. |
MAPPosterior
¶
MAP (Maximum A Posteriori) posterior: the point estimate θ_MAP.
Carries no uncertainty. It stores θ_MAP as 1 chain with 1 sample, the same
layout an MCMCPosterior uses for its samples, so
WPPMCovarianceFieldSamples(map_posterior) needs no n_samples and no
key. The chain axis is only a layout: no sampler ran.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
WPPM
|
Model instance used for predictions |
required |
params
|
dict
|
MAP parameter dictionary (θ_MAP) |
required |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
Notes
This implements the ParameterPosterior protocol.
Methods:
| Name | Description |
|---|---|
sample |
Return n copies of the point estimate θ_MAP. |
Attributes:
| Name | Type | Description |
|---|---|---|
model |
Return the associated model. |
|
n_chains |
int
|
Number of chains, always 1. |
n_draws |
int
|
Number of samples per chain, always 1. |
params |
Return the MAP parameters (θ_MAP). |
|
samples |
dict
|
θ_MAP as 1 chain with 1 sample. |
Source code in src/psyphy/posterior/posterior.py
samples
¶
samples: dict
θ_MAP as 1 chain with 1 sample.
Returns:
| Type | Description |
|---|---|
dict
|
|
sample
¶
sample(n: int, key)
Return n copies of the point estimate θ_MAP.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
Number of samples |
required |
key
|
Array
|
PRNG key. A point estimate has no randomness, so the key goes unread. |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Parameter PyTree with leading dimension n. Each array has shape (n, ...) with identical values. |
Notes
Every row is the same parameter set, so a mean over the draws is θ_MAP and their spread is zero.
Source code in src/psyphy/posterior/posterior.py
Predictive Posterior¶
predictive_posterior
¶
predictive_posterior.py
Predictive posterior distributions p(f(X*) | data) at test stimuli.
This module defines posteriors over predictions (not parameters), used by acquisition functions for Bayesian optimization.
Design
PredictivePosterior wraps a ParameterPosterior and computes predictions via: E[f(X) | data] pprox (1/N) Σ_i f(X; θ_i) where θ_i ~ p(θ | data)
This separates concerns: - ParameterPosterior: represents uncertainty over θ - PredictivePosterior: represents uncertainty over f(X*) (decision-making) - effectively decoupling how we FIT the model from how we USE the fitted model
Classes:
| Name | Description |
|---|---|
PredictivePosterior |
Protocol for predictive distributions p(f(X*) | data) at test stimuli. |
ThresholdConfig |
Configuration for :class: |
WPPMPredictivePosterior |
Predictive posterior for WPPM models. |
PredictivePosterior
¶
Bases: Protocol
Protocol for predictive distributions p(f(X*) | data) at test stimuli.
Returned by Model.posterior(X) for use in acquisition functions.
Methods:
| Name | Description |
|---|---|
rsample |
Reparameterized samples from p(f(X*) | data). |
Attributes:
| Name | Type | Description |
|---|---|---|
mean |
ndarray
|
Posterior predictive mean E[f(X*) | data]. |
variance |
ndarray
|
Posterior predictive marginal variances Var[f(X*) | data]. |
mean
¶
Posterior predictive mean E[f(X*) | data].
Returns:
| Type | Description |
|---|---|
(ndarray, shape(n_test) or (n_test, output_dim))
|
The first for scalar outputs, the second for vector outputs (future). |
Notes
Computed via Monte Carlo integration over parameter posterior.
:class:WPPMPredictivePosterior in threshold_pred=True mode is a
documented exception to the shapes above: it returns matrix-valued
moments, shape (n_test, input_dim, input_dim) -- a threshold
covariance per test point, not a scalar or vector. See its own
mean/variance docstrings.
variance
¶
Posterior predictive marginal variances Var[f(X*) | data].
Returns:
| Type | Description |
|---|---|
(ndarray, shape(n_test) or (n_test, output_dim))
|
The first for scalar outputs, the second for vector outputs (future). |
Notes
Captures both aleatoric (model) and epistemic (parameter) uncertainty.
Same WPPM threshold_pred=True exception as :attr:mean applies.
rsample
¶
rsample(sample_shape: tuple = (), *, key: Array) -> ndarray
Reparameterized samples from p(f(X*) | data).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sample_shape
|
tuple
|
Shape of sample batch |
()
|
key
|
Array
|
PRNG key |
required |
Returns:
| Type | Description |
|---|---|
(ndarray, shape(*sample_shape, n_test) or (*sample_shape, n_test, output_dim))
|
The first for scalar outputs, the second for vector outputs. |
Notes
Enables gradient-based acquisition optimization via reparameterization trick.
Source code in src/psyphy/posterior/predictive_posterior.py
ThresholdConfig
¶
ThresholdConfig(n_theta: int = 16, n_length: int = 200, bounds: tuple[float, float] = (0.0005, 0.3), target_prob_correct: float = 2.0 / 3.0, chunk: int = 2000)
Configuration for :class:WPPMPredictivePosterior's threshold_pred mode.
Controls the oddity-task inversion that recovers a threshold covariance
Σ_thres(x), the contour where the probability correct reaches
target_prob_correct, from a
fitted noise field. There is no closed form for this inversion (see
:class:~psyphy.model.likelihood.OddityTask), so it is done numerically:
probe n_theta directions around each reference point, brute-force
search n_length candidate distances per direction for the one closest
to target_prob_correct, then fit an ellipsoid to the resulting boundary
points.
Attributes:
| Name | Type | Description |
|---|---|---|
n_theta |
int
|
Number of directions probed around each reference point. Must be at
least |
n_length |
int
|
Number of candidate distances probed per direction. Brute-force search rather than bisection: P(correct) is only monotone in distance up to Monte Carlo noise, so a root-finder can walk off a noisy plateau where a dense-grid argmin cannot. |
bounds |
tuple[float, float]
|
|
target_prob_correct |
float
|
The probability correct that defines the threshold contour. 2/3 is the oddity task's standard criterion. |
chunk |
int
|
Batch size for the Monte Carlo sweep, bounding peak memory;
|
Notes
Cost per (posterior sample, reference point) pair is
n_theta * n_length calls to the task's MC-simulated predict, each
itself an average over OddityTaskConfig.num_samples draws. Total cost
for a call to :class:WPPMPredictivePosterior scales as
n_samples * n_test * n_theta * n_length * num_samples; a warning is
emitted when n_samples * n_test alone exceeds 200.
WPPMPredictivePosterior
¶
WPPMPredictivePosterior(param_posterior: ParameterPosterior, X: ndarray, n_samples: int = 100, threshold_pred: bool = False, threshold_config: ThresholdConfig | None = None, *, key: Array)
Predictive posterior for WPPM models.
Computes p(f(X*) | data) via Monte Carlo integration over parameter posterior p(θ | data).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
param_posterior
|
ParameterPosterior
|
Posterior over model parameters |
required |
X
|
(ndarray, shape(n_test, k_stimuli, input_dim) or (n_test, input_dim))
|
Test stimuli. Shape depends on
|
required |
n_samples
|
int
|
Number of posterior samples for MC integration |
100
|
threshold_pred
|
bool
|
Whether to compute threshold covariances (Σ_thres, the
contour where the probability correct reaches
|
False
|
threshold_config
|
ThresholdConfig
|
Settings for the threshold inversion. Only used when
|
None
|
key
|
(Array, keyword - only)
|
PRNG key, split once here into a key for drawing parameters and a key
for the threshold sweep's Monte Carlo. |
required |
Attributes:
| Name | Type | Description |
|---|---|---|
param_posterior |
ParameterPosterior
|
Wrapped parameter posterior |
X |
(ndarray, shape(n_test, k_stimuli, input_dim) or (n_test, input_dim))
|
Test stimuli |
n_samples |
int
|
MC sample count |
threshold_pred |
bool
|
Whether this instance predicts thresholds rather than probabilities |
threshold_config |
ThresholdConfig or None
|
Threshold-inversion settings ( |
Notes
Uses lazy evaluation: moments computed on first access.
Methods:
| Name | Description |
|---|---|
rsample |
Sample predictions from p(f(X*) | data). |
Source code in src/psyphy/posterior/predictive_posterior.py
mean
¶
E[f(X*) | data].
Shape (n_test,): predicted probabilities, unless
threshold_pred=True, in which case shape is
(n_test, input_dim, input_dim): the posterior-mean threshold
covariance Σ_thres at each reference point, averaged arithmetically
over posterior parameter samples (the PD cone is convex, so this
stays PD; not a geometric/Bures mean).
variance
¶
Var[f(X*) | data].
Shape (n_test,) unless threshold_pred=True, in which case shape
is (n_test, input_dim, input_dim): elementwise variance of the
per-sample threshold covariances (not a variance of a matrix in
any distributional sense; just jnp.var over the sample axis,
entry by entry).
rsample
¶
rsample(sample_shape: tuple = (), *, key: Array) -> ndarray
Sample predictions from p(f(X*) | data).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sample_shape
|
tuple
|
Batch shape |
()
|
key
|
Array
|
PRNG key |
required |
Returns:
| Type | Description |
|---|---|
(ndarray, shape(*sample_shape, n_test) or (*sample_shape, n_test, input_dim, input_dim))
|
The first unless |