Model¶
Package¶
model
¶
psyphy.model¶
Model-layer API: everything model-related in one place.
Includes
- WPPM (core model)
- Priors (Prior)
- Tasks (TaskLikelihood base, OddityTask)
- Noise models (GaussianNoise, StudentTNoise)
All functions/classes use JAX arrays (jax.numpy as jnp) for autodiff and optimization with Optax.
Typical usage
1 | |
Classes:
| Name | Description |
|---|---|
CovarianceField |
Protocol for spatially-varying covariance fields Σ(x). |
CredibleBand |
A pointwise credible band on the contour radii, with its provenance. |
GaussianNoise |
|
Model |
Abstract base class for psychophysical models. |
OddityTask |
Three-alternative forced-choice oddity task (MC-based only). |
OddityTaskConfig |
Configuration for :class: |
Prior |
Prior distribution over WPPM parameters |
StudentTNoise |
|
TaskLikelihood |
Abstract base class for task likelihoods. |
WPPM |
Wishart Process Psychophysical Model (WPPM). |
WPPMCovarianceField |
Covariance field for WPPM with Wishart process |
WPPMCovarianceFieldSamples |
N draws of the WPPM covariance field, with the reductions over them. |
Functions:
| Name | Description |
|---|---|
contour_radii |
Distance from the center to the one-standard-deviation ellipse, per direction. |
covariance_to_arviz |
Per-sample covariance Σ(x) at chosen points, as an ArviZ DataTree. |
CovarianceField
¶
Bases: Protocol
Protocol for spatially-varying covariance fields Σ(x).
A covariance field maps stimulus locations x ∈ R^d to covariance matrices Σ(x) ∈ R^{dxd}.
Methods:
| Name | Description |
|---|---|
__call__ |
Evaluate field at one or more locations. Supports both single points and arbitrary batch dimensions. |
sqrt_cov |
Evaluate U(x) such that Σ(x) = U(x) @ U(x)^T + λI. |
Notes
This protocol enables polymorphic use of covariance fields from different sources (prior samples, fitted posteriors, custom parameterizations).
The field is callable for mathematical elegance and JAX compatibility: Sigma = field(x) # Single point or batch
sqrt_cov
¶
CredibleBand
¶
Bases: NamedTuple
A pointwise credible band on the contour radii, with its provenance.
Attributes:
| Name | Type | Description |
|---|---|---|
points |
(ndarray, shape(n_points, d))
|
Stimulus locations the band was evaluated at. |
directions |
(ndarray, shape(n_directions, d))
|
Unit directions the radii are measured along, in order. Closed, so the last direction repeats the first and a filled polygon has no seam. |
lower, median, upper |
(ndarray, shape(n_points, n_directions) or (n_levels, n_points, n_directions))
|
Interval endpoints and the posterior median radius: the first shape
for a single |
ci_prob |
float | tuple[float, ...]
|
Nominal probability each interval carries. A tuple when several levels were requested, in the order the arrays are stacked. |
ci_kind |
str
|
|
Notes
The interval is pointwise: it covers the true radius in each direction
separately with probability ci_prob. It does NOT cover the whole
contour jointly at that probability, which is a stronger (simultaneous)
statement requiring a different construction. ci_prob and ci_kind
travel with the arrays so a figure can state which interval it draws.
GaussianNoise
¶
GaussianNoise(sigma: float = 1.0)
Model
¶
Bases: ABC
Abstract base class for psychophysical models.
Subclasses must implement: - init_params(key) --> sample initial parameters (Prior) - log_likelihood_from_data(params, data) --> compute likelihood
Methods:
| Name | Description |
|---|---|
init_params |
Sample initial parameters from prior. |
log_likelihood_from_data |
Compute log p(data | params). |
init_params
¶
Sample initial parameters from prior.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
Array
|
PRNG key |
required |
Returns:
| Type | Description |
|---|---|
dict
|
Parameter PyTree |
log_likelihood_from_data
¶
log_likelihood_from_data(params: dict, data: ResponseData) -> ndarray
Compute log p(data | params).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
Model parameters |
required |
data
|
ResponseData
|
Observed trials |
required |
Returns:
| Type | Description |
|---|---|
(ndarray, shape())
|
Log-likelihood (scalar) |
Source code in src/psyphy/model/base.py
OddityTask
¶
OddityTask(config: OddityTaskConfig | None = None)
Bases: BernoulliTaskLikelihood
Three-alternative forced-choice oddity task (MC-based only).
Implements the full 3-stimulus oddity task using Monte Carlo simulation: - Samples three internal representations per trial (z0, z1, z2) - Uses proper oddity decision rule with three pairwise distances
Notes
MC simulation in loglik() (full 3-stimulus oddity): 1. Sample three internal representations: z_ref, z_refprime ~ N(ref, Σ_ref), z_comparison ~ N(comparison, Σ_comparison) 2. Compute average covariance: Σ_avg = (2/3) Σ_ref + (1/3) Σ_comparison 3. Compute three pairwise Mahalanobis distances: - d^2(z_ref, z_refprime) = distance between two reference samples - d^2(z_ref, z_comparison) = distance from ref to comparison - d^2(z_refprime, z_comparison) = distance from reference_prime to comparison 4. Apply oddity decision rule: delta = min(d^2(z_ref,z_comparison), d^2(z_refprime,z_comparison)) - d^2(z_ref,z_refprime) 5. Logistic smoothing: P(correct) ~ logistic.cdf(delta / bandwidth) 6. Average over samples, in log space
Examples:
Methods:
| Name | Description |
|---|---|
loglik |
Compute Bernoulli log-likelihood over a batch of trials. |
predict |
Return log p(correct) and log p(incorrect) for a single (ref, comparison) |
simulate |
Simulate observed binary responses for a batch of trials. |
Attributes:
| Name | Type | Description |
|---|---|---|
config |
|
Source code in src/psyphy/model/likelihood/oddity.py
loglik
¶
Compute Bernoulli log-likelihood over a batch of trials.
We vmap predict over trials, then take log p(correct) where the
response is 1 and log p(incorrect) where it is 0, and sum.
Each trial's probability is held in [1e-6, 1 - 1e-6]. A trial the model calls nearly impossible adds log(1e-6), about -13.8, and has no gradient past that bound.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
data
|
Any
|
Object with |
required |
model
|
Any
|
Model instance. |
required |
key
|
Array
|
PRNG key. Passed as independent per-trial subkeys to |
None
|
Returns:
| Type | Description |
|---|---|
(ndarray, shape())
|
Scalar sum of Bernoulli log-likelihoods over all trials. |
Source code in src/psyphy/model/likelihood/base.py
predict
¶
Return log p(correct) and log p(incorrect) for a single (ref, comparison) trial, via MC simulation.
MC controls (num_samples, bandwidth) are read from
:class:OddityTaskConfig. Pass key to control randomness; when
None, config.default_key_seed is used.
Source code in src/psyphy/model/likelihood/oddity.py
simulate
¶
simulate(params: Any, stimuli: ndarray, model: Any, key: Any) -> tuple[ndarray, tuple[ndarray, ...]]
Simulate observed binary responses for a batch of trials.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
stimuli
|
(ndarray, shape(n_trials, k_stim, input_dim))
|
Stimuli. |
required |
model
|
Any
|
Model instance. |
required |
key
|
Array
|
PRNG key (required; split internally for prediction and sampling). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
responses |
jnp.ndarray, shape (n_trials,), dtype int32
|
Simulated binary responses (1 = correct, 0 = incorrect). |
probability parameters : tuple[jnp.ndarray]
|
1-tuple |
Source code in src/psyphy/model/likelihood/base.py
OddityTaskConfig
¶
Configuration for :class:OddityTask.
This is the single source of truth for MC likelihood controls.
Attributes:
| Name | Type | Description |
|---|---|---|
num_samples |
int
|
Number of Monte Carlo samples per trial. |
bandwidth |
float
|
Logistic CDF smoothing bandwidth. |
default_key_seed |
int
|
Seed used when no key is provided (keeps behavior deterministic by default while allowing reproducibility control upstream). |
Prior
¶
Prior(input_dim: int = 2, basis_degree: int = 4, variance_scale: float = 0.004, decay_rate: float = 0.4, extra_embedding_dims: int = 1)
Prior distribution over WPPM parameters
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_dim
|
int
|
Dimensionality of the model space. WPPM.input_dim reads this. |
2
|
basis_degree
|
int
|
Degree of the Chebyshev basis. U(x) is a weighted sum of basis functions up to this degree, with weights W. Must be 0 or more. |
4
|
variance_scale
|
float
|
Prior variance for degree-0 (constant) coefficient. Controls overall scale of covariances. WPPM.variance_scale reads this. |
4e-3
|
decay_rate
|
float
|
Geometric decay rate for prior variance over higher-degree coefficients. Prior variance for degree-d coefficient = variance_scale * (decay_rate^d). Smaller decay_rate -> stronger smoothness prior. WPPM.decay_rate reads this. |
0.4
|
extra_embedding_dims
|
int
|
Additional latent dimensions in U matrices beyond input dimensions. Allows richer ellipsoid shapes. WPPM.embedding_dim reads this. |
1
|
Methods:
| Name | Description |
|---|---|
log_prob |
Compute log prior density (up to a constant) |
param_scales |
Prior standard deviation of every parameter, as a PyTree shaped like |
sample |
Sample n independent parameter draws from the prior. |
sample_params |
Sample initial parameters from the prior. |
Attributes:
| Name | Type | Description |
|---|---|---|
basis_degree |
int
|
|
decay_rate |
float
|
|
extra_embedding_dims |
int
|
|
input_dim |
int
|
|
variance_scale |
float
|
|
log_prob
¶
log_prob(params: Params) -> ndarray
Compute log prior density (up to a constant)
Gaussian prior on W with smoothness via decay_rate log p(W) = Σ_ij log N(W_ij | 0, σ_ij^2) where σ_ij^2 = prior variance
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
Parameter dictionary |
required |
Returns:
| Name | Type | Description |
|---|---|---|
log_prob |
float
|
Log prior probability (up to normalizing constant) |
Source code in src/psyphy/model/prior.py
param_scales
¶
param_scales() -> Params
Prior standard deviation of every parameter, as a PyTree shaped like
sample_params().
The prior std depends only on a coefficient's basis degree, so it is broadcast over the trailing (input_dim, embedding_dim) axes of W.
Used by NUTSSampler to precondition the sampler: coefficients at different degrees have prior scales that differ by orders of magnitude, and sampling W / scale instead of W puts them all on a common O(1) scale.
Returns:
| Name | Type | Description |
|---|---|---|
scales |
dict
|
{"W": array with the same shape as sample_params()["W"]} |
Source code in src/psyphy/model/prior.py
sample
¶
Sample n independent parameter draws from the prior.
The vectorized form of :meth:sample_params: draw i equals
sample_params(jax.random.split(key, n)[i]).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
Number of draws. |
required |
key
|
Array
|
PRNG key, split n ways. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
params |
dict
|
Parameter dictionary with a leading axis of n, so for 2D |
Notes
Satisfies :class:psyphy.posterior.ParameterSource.
Examples:
Source code in src/psyphy/model/prior.py
sample_params
¶
Sample initial parameters from the prior.
Returns {"W": shape (degree+1, degree+1, input_dim, embedding_dim)} for 2D, where embedding_dim = input_dim + extra_embedding_dims
Note: The 3rd dimension is input_dim (output space dimension). This matches the einsum in _compute_sqrt: U = einsum("ijde,ij->de", W, phi) where d indexes input_dim.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
JAX random key
|
|
required |
Returns:
| Name | Type | Description |
|---|---|---|
params |
dict
|
Parameter dictionary |
Source code in src/psyphy/model/prior.py
StudentTNoise
¶
TaskLikelihood
¶
Bases: ABC
Abstract base class for task likelihoods.
Subclasses must implement:
- predict(params, stimuli, model, *, key) -> probability parameters for one trial
The base class provides concrete implementations of:
- loglik(params, data, model, *, key) -> Bernoulli log-likelihood over a batch
- simulate(params, stimuli, model, *, key) -> simulated responses & probability parameters
The Bernoulli log-likelihood step is identical for all binary-response tasks, so it lives here rather than being re-implemented in every subclass.
Methods:
| Name | Description |
|---|---|
loglik |
Compute and return log-likelihood over a batch of trials. |
predict |
Return parameters sufficient to determine probability of any given |
simulate |
Simulate responses for a batch of trials. |
loglik
¶
Compute and return log-likelihood over a batch of trials. Each abstract subclass will concretely implement this for all tasks with the assumption of a given distribution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
data
|
Any
|
Object with |
required |
model
|
Any
|
Model instance (provides covariance structure and |
required |
key
|
Array
|
PRNG key for stochastic tasks. When None, the task falls back to
its |
None
|
Returns:
| Type | Description |
|---|---|
(ndarray, shape())
|
Scalar sum of log-likelihoods over all trials. |
Source code in src/psyphy/model/likelihood/base.py
predict
¶
Return parameters sufficient to determine probability of any given response on a single trial. The parameters will be specific to the distribution (specified by abstract subclass)
BernoulliTaskLikelihood: returns (log p(correct), log p(incorrect)) GaussianTaskLikelihood: returns (mu, sigma), the parameters defining a Gaussian distribution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
stimuli
|
(ndarray, shape(stim_dim, K))
|
stimuli for a given trial (stimulus dimensions, number of stimuli) |
required |
model
|
Any
|
Model instance (provides covariance structure and |
required |
key
|
Array
|
PRNG key for stochastic tasks. When None, the task falls back to
its |
None
|
Returns:
| Type | Description |
|---|---|
parameter(s): jnp.ndarray
|
any number of parameters necessary to specify probability for likelihood calculation - for Bernoulli: log p(correct) and log p(incorrect) (2 scalars) - for Gaussian: mu (r_dim vector), sigma (r_dim x r_dim covariance matrix) |
Source code in src/psyphy/model/likelihood/base.py
simulate
¶
simulate(params: Any, stimuli: ndarray, model: Any, key: Any) -> tuple[ndarray, tuple[ndarray, ...]]
Simulate responses for a batch of trials.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
stimuli
|
(ndarray, shape(n_trials, k_stimuli, input_dim))
|
Stimuli. |
required |
model
|
Any
|
Model instance. |
required |
key
|
Array
|
PRNG key (required; split internally for prediction and sampling). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
responses |
(ndarray, shape(n_trials, r_dim))
|
Simulated responses. |
probability parameters : tuple[jnp.ndarray, ...], each array has shape[0] = n_trials
|
Bernoulli: Estimated (P(correct)) per trial used to draw the responses. shape = (n_trials) Gaussian: Estimated (mu, sigma) per trial used to draw the responses. shape for mu = (n_trials, r_dims); shape for sigma = (n_trials, r_dims, r_dims). |
|
Note |
not yet implemented for Gaussians
|
|
Source code in src/psyphy/model/likelihood/base.py
WPPM
¶
WPPM(prior: Prior, likelihood: TaskLikelihood, noise: Any | None = None, *, diag_term: float = 1e-06, **model_kwargs: Any)
Bases: Model
Wishart Process Psychophysical Model (WPPM).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prior
|
Prior
|
Prior distribution over model parameters. WPPM reads input_dim, embedding_dim, variance_scale, decay_rate and basis_degree from the prior, so each one is set once and the two objects cannot disagree. |
required |
likelihood
|
TaskLikelihood
|
Psychophysical task mapping that defines how discriminability translates to p(correct) and how log-likelihood of responses is computed. (e.g., OddityTask) |
required |
noise
|
Any
|
Noise model describing internal representation noise (e.g., GaussianNoise). |
None
|
diag_term
|
float
|
Small positive value added to the covariance diagonal for numerical stability: Sigma(x) = U(x) U(x)^T + diag_term * I. A WPPM setting, not a property of the prior. |
1e-6
|
**model_kwargs
|
Any
|
Reserved for future keyword arguments accepted by the base |
{}
|
Methods:
| Name | Description |
|---|---|
init_params |
Sample initial parameters from the prior. |
local_covariance |
Return local covariance Σ(x) at stimulus location x. |
log_likelihood_from_data |
Compute log-likelihood directly from a batched data object. |
log_posterior_from_data |
Compute log posterior from data. |
predict_prob |
Predict probability of a correct response for a single stimulus. |
Attributes:
| Name | Type | Description |
|---|---|---|
basis_degree |
int
|
Chebyshev polynomial degree for Wishart process basis expansion. |
decay_rate |
float
|
Smoothness/length-scale for spatial covariance variation. Reads self.prior.decay_rate. |
diag_term |
|
|
embedding_dim |
int
|
Dimension of the embedding space. |
input_dim |
int
|
Dimensionality of the input stimulus space. |
likelihood |
|
|
noise |
|
|
prior |
|
|
variance_scale |
float
|
Global scaling factor for covariance magnitude. Reads self.prior.variance_scale. |
Source code in src/psyphy/model/wppm.py
basis_degree
¶
basis_degree: int
Chebyshev polynomial degree for Wishart process basis expansion.
This property delegates to self.prior.basis_degree to ensure consistency between parameter sampling and basis evaluation.
Returns:
| Type | Description |
|---|---|
int
|
Degree of Chebyshev polynomial basis (0 = constant, 1 = linear, etc.) |
Notes
WPPM gets its basis_degree parameter from Prior.basis_degree.
decay_rate
¶
decay_rate: float
Smoothness/length-scale for spatial covariance variation. Reads self.prior.decay_rate.
embedding_dim
¶
embedding_dim: int
Dimension of the embedding space.
embedding_dim = input_dim + extra_embedding_dims, both read from the prior. The first input_dim coordinates are the observable stimulus features, the rest are latent dimensions.
Returns:
| Type | Description |
|---|---|
int
|
input_dim + extra_embedding_dims |
input_dim
¶
input_dim: int
Dimensionality of the input stimulus space.
Delegates to self.prior.input_dim, the single place this is set.
Returns:
| Type | Description |
|---|---|
int
|
e.g. 2 for the isoluminant plane, 3 for RGB. |
variance_scale
¶
variance_scale: float
Global scaling factor for covariance magnitude. Reads self.prior.variance_scale.
init_params
¶
init_params(key: Array) -> Params
Sample initial parameters from the prior.
Returns:
| Name | Type | Description |
|---|---|---|
params |
dict[str, jnp.ndarray], a parameter pytree
|
For WPPM, |
Source code in src/psyphy/model/wppm.py
local_covariance
¶
local_covariance(params: Params, x: ndarray) -> ndarray
Return local covariance Σ(x) at stimulus location x.
Σ(x) = U(x) @ U(x)^T + diag_term * I where U(x) is rectangular (input_dim, embedding_dim) if extra_embedding_dims > 0. - Varies smoothly with x - Guaranteed positive-definite - Returns stimulus covariance directly (input_dim, input_dim)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
Model parameters: - WPPM: {"W": (degree+1, ..., input_dim, embedding_dim)} |
required |
x
|
(ndarray, shape(input_dim))
|
Stimulus location |
required |
Returns:
| Type | Description |
|---|---|
Σ : jnp.ndarray, shape (input_dim, input_dim)
|
Covariance matrix in stimulus space. |
Source code in src/psyphy/model/wppm.py
log_likelihood_from_data
¶
Compute log-likelihood directly from a batched data object.
Why delegate to the likelihood? - The likelihood knows the decision rule (oddity, 2AFC, ...). - The likelihood can use the model (this WPPM) to fetch discriminabilities. - The likelihood can use the noise model if it needs MC simulation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
Model parameters. |
required |
data
|
TrialData (or any object with refs/comparisons/responses arrays)
|
Collected trial data. |
required |
key
|
Array | None
|
JAX random key for MC likelihood evaluation. When provided, a fresh
noise realization is drawn every call, required for correct stochastic
gradient estimates during optimization. When None, the task falls back
to |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
loglik |
(ndarray, shape())
|
Scalar log-likelihood (task-only; add prior outside if needed). |
Source code in src/psyphy/model/wppm.py
log_posterior_from_data
¶
Compute log posterior from data.
This simply adds the prior log-probability to the task log-likelihood. Inference engines (e.g., MAP optimizer) typically optimize this quantity.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
Model parameters. |
required |
data
|
TrialData
|
Collected trial data. |
required |
key
|
Array | None
|
JAX random key for the MC likelihood. Must be provided during
optimization so each gradient step uses a fresh noise realization.
When None, falls back to |
None
|
Returns:
| Type | Description |
|---|---|
(ndarray, shape())
|
Scalar log posterior = loglik(params | data) + log_prior(params). |
Source code in src/psyphy/model/wppm.py
predict_prob
¶
Predict probability of a correct response for a single stimulus.
Design choice: WPPM computes discriminability & covariance; the LIKELIHOOD defines how that translates to performance. We therefore delegate to: likelihood.predict(params, stimulus, model=self, noise=self.noise)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
|
required |
stimulus
|
tuple[jnp.ndarray, jnp.ndarray], each shape (input_dim,)
|
(reference, comparison) pair in model space. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
p_correct |
(ndarray, shape())
|
Scalar probability of a correct response. |
Source code in src/psyphy/model/wppm.py
WPPMCovarianceField
¶
WPPMCovarianceField(model, params: dict)
Covariance field for WPPM with Wishart process Encapsulates model + parameters to provide clean evaluation interface for Σ(x) and U(x).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
WPPM
|
Model providing evaluation logic (local_covariance, _compute_sqrt) |
required |
params
|
dict
|
Model parameters: - Wishart: {"W": (degree+1, degree+1, input_dim, embedding_dim)} where embedding_dim = input_dim + extra_embedding_dims Note: The 3rd dimension is input_dim (output/stimulus space) and not embedding_dim. This is analogous to the einsum in _compute_sqrt where U(x) has shape (input_dim, embedding_dim). |
required |
Attributes:
| Name | Type | Description |
|---|---|---|
model |
WPPM
|
Associated model instance |
params |
dict
|
Parameter dictionary |
Both attributes are fixed when the object is built. Assigning to one |
|
|
raises ``AttributeError``. After changing an attribute of the model in |
|
|
place, such as ``model.diag_term``, build a new field. The field copies |
|
|
``params`` at construction, so changing the dict you passed in afterwards |
|
|
changes nothing. |
|
Examples:
Notes
Implements the CovarianceField protocol for polymorphic use.
Construct covariance field from model and parameters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
WPPM
|
Model providing evaluation logic |
required |
params
|
dict
|
Parameter dictionary |
required |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
Methods:
| Name | Description |
|---|---|
from_params |
Create field from arbitrary parameters. |
from_posterior |
Create covariance field from fitted posterior. |
from_prior |
Sample a covariance field from the prior. |
sqrt_cov |
Evaluate U(x) such that Σ(x) = U(x) @ U(x)^T + diag_term*I. |
sqrt_cov_batch |
Vectorized evaluation of U(x) at multiple locations. |
Source code in src/psyphy/model/covariance_field.py
from_params
¶
from_params(model, params: dict) -> WPPMCovarianceField
Create field from arbitrary parameters.
Useful for: - Custom initialization - Posterior samples - Intermediate optimization checkpoints - Testing
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
WPPM
|
Model providing evaluation logic |
required |
params
|
dict
|
Parameter dictionary |
required |
Returns:
| Type | Description |
|---|---|
WPPMCovarianceField
|
|
Examples:
Source code in src/psyphy/model/covariance_field.py
from_posterior
¶
from_posterior(posterior) -> WPPMCovarianceField
Create covariance field from fitted posterior.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
posterior
|
ParameterPosterior
|
Fitted posterior (e.g., from model.fit()) |
required |
Returns:
| Type | Description |
|---|---|
WPPMCovarianceField
|
Field representing posterior estimate of Σ(x) |
Notes
Builds the field from posterior.params, i.e. a single parameter set.
- MAP posteriors:
paramsis θ_MAP, so this is Σ(θ_MAP). - Sample-based posteriors (e.g.
MCMCPosterior):paramsis the mean parameter E[W], and Σ(E[W]) is NOT the posterior mean of Σ. It is systematically too small and can collapse toward λI (seeWPPMCovarianceFieldSamplesfor why). We raise aUserWarningwhen the posterior stores more than 1 sample. UseWPPMCovarianceFieldSamples(posterior).mean(x)for E[Σ], orposterior.sample(n, key=...)for individual samples.
Examples:
Source code in src/psyphy/model/covariance_field.py
from_prior
¶
from_prior(model, key: Array) -> WPPMCovarianceField
Sample a covariance field from the prior.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
WPPM
|
Model defining prior distribution |
required |
key
|
Array
|
PRNG key for sampling |
required |
Returns:
| Type | Description |
|---|---|
WPPMCovarianceField
|
Field sampled from p(Σ(x)) |
Examples:
Source code in src/psyphy/model/covariance_field.py
sqrt_cov
¶
Evaluate U(x) such that Σ(x) = U(x) @ U(x)^T + diag_term*I.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
x
|
(ndarray, shape(input_dim))
|
Stimulus location |
required |
Returns:
| Type | Description |
|---|---|
(ndarray, shape(input_dim, embedding_dim))
|
Rectangular square root matrix U(x). embedding_dim = input_dim + extra_embedding_dims |
Notes
U is of shape (input_dim, embedding_dim).
Examples:
Source code in src/psyphy/model/covariance_field.py
sqrt_cov_batch
¶
Vectorized evaluation of U(x) at multiple locations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
(ndarray, shape(n_points, input_dim))
|
Multiple stimulus locations |
required |
Returns:
| Type | Description |
|---|---|
(ndarray, shape(n_points, input_dim, embedding_dim))
|
Rectangular square root matrices at each location. embedding_dim = input_dim + extra_embedding_dims |
Notes
In the rectangular design (Hong et al.), U is (input_dim, embedding_dim).
Examples:
Source code in src/psyphy/model/covariance_field.py
WPPMCovarianceFieldSamples
¶
WPPMCovarianceFieldSamples(posterior, *, n_samples: int | None = None, key=None)
N draws of the WPPM covariance field, with the reductions over them.
A fit gives many parameter draws, so it gives many covariance fields. This
class holds the draws and evaluates them: fields(x) for every draw,
:meth:mean for :math:\mathbb{E}[\Sigma(x)], :meth:credible_band for a credible
band on the contour. The draws are taken when the object is built, so the
three reductions are three views of one sample.
:meth:mean averages :math:\Sigma over the draws. A field built from the
averaged parameters gives contours several times too small, because
:math:\Sigma(x) = U(x) U(x)^\top + \lambda I is nonlinear in :math:W.
:meth:sqrt_cov gives :math:U(x) for every draw. The mean matrix has no
:math:U, because an average of :math:U U^\top is not :math:U U^\top
for any single :math:U. For a factor of the mean matrix, use
jnp.linalg.cholesky(fields.mean(x)).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
posterior
|
ParameterPosterior
|
A fitted posterior, typically an |
required |
n_samples
|
int
|
How many samples to take. Omit it for every stored sample, which needs
the posterior to expose |
None
|
key
|
Array
|
PRNG key for the subsample. Required when |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Attributes:
| Name | Type | Description |
|---|---|---|
model |
WPPM
|
The model the draws belong to. |
samples |
dict
|
The draws, leading axis |
n_samples |
int
|
Draws held. |
All three are fixed when the object is built. Assigning to one raises |
|
|
``AttributeError``. After changing an attribute of the model in place, such |
|
|
as ``model.diag_term``, build a new object. |
|
See Also
WPPMCovarianceField : one parameter set, so one field and its square root. covariance_to_arviz : per-draw Σ with the chain axis kept, for diagnostics.
Examples:
Methods:
| Name | Description |
|---|---|
credible_band |
Pointwise credible band on the one-standard-deviation ellipse at each point. |
from_params |
1 parameter set, such as a ground truth or a published W. |
from_prior |
Samples from the model's prior. |
mean |
Posterior mean of the covariance field, :math: |
sqrt_cov |
Evaluate the square root :math: |
Source code in src/psyphy/model/covariance_field.py
credible_band
¶
credible_band(points: ndarray, *, n_directions: int = 181, ci_prob: float | Sequence[float] = 0.89, ci_kind: str = 'eti') -> CredibleBand
Pointwise credible band on the one-standard-deviation ellipse at each point.
The posterior-interval counterpart to :meth:mean (a posterior mean)
and :func:covariance_to_arviz (posterior samples, for diagnostics).
Every draw gives one covariance field, hence one contour per point.
Writing each contour as a radius per direction
(:func:contour_radii) makes it a scalar per draw, so an interval
follows from quantiles over draws. For a :math:1-\alpha interval, at
each direction separately, the band runs between
:math:q_{\alpha/2}\{r_i\} and :math:q_{1-\alpha/2}\{r_i\} over the
:math:N draws.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
points
|
(ndarray, shape(n_points, 2))
|
Stimulus locations, usually the reference points we report. |
required |
n_directions
|
int
|
Directions per contour. The grid is closed, so the last direction repeats the first, and 181 gives 180 distinct directions, one every two degrees. The number is a magic default with nothing behind it: large enough that a filled band looks smooth, small enough to stay cheap. Nothing in the result depends on the choice. |
181
|
ci_prob
|
float or sequence of float
|
How much posterior mass the interval holds. At 0.89, 89% of the
draws of the radius lie between |
0.89
|
ci_kind
|
('eti', 'hdi')
|
Which interval of that mass to take, since many of them hold it.
|
"eti"
|
Returns:
| Type | Description |
|---|---|
CredibleBand
|
|
Raises:
| Type | Description |
|---|---|
NotImplementedError
|
If the model is not 2-D. The direction grid is a circle, and higher dimensions have no single analogous grid. |
ValueError
|
If the object holds 1 sample, as after a MAP fit or
:meth: |
Examples:
Source code in src/psyphy/model/covariance_field.py
1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 | |
from_params
¶
from_params(model, params: dict) -> WPPMCovarianceFieldSamples
1 parameter set, such as a ground truth or a published W.
The result holds 1 sample, so fields(x)[0] is the covariance at
x. No key, since nothing is drawn. After a fit, pass the posterior
to the constructor instead.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
WPPM
|
Model that evaluates the parameters. |
required |
params
|
dict
|
1 parameter set, with no leading sample axis. For WPPM:
|
required |
Returns:
| Type | Description |
|---|---|
WPPMCovarianceFieldSamples
|
With |
Raises:
| Type | Description |
|---|---|
TypeError
|
If |
Examples:
Source code in src/psyphy/model/covariance_field.py
from_prior
¶
from_prior(model, *, n_samples: int, key) -> WPPMCovarianceFieldSamples
Samples from the model's prior.
A prior stores no samples, so n_samples and key are both required.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
WPPM
|
Model whose prior we draw from. |
required |
n_samples
|
int
|
Draws to take. |
required |
key
|
Array
|
PRNG key, split n_samples ways. |
required |
Returns:
| Type | Description |
|---|---|
WPPMCovarianceFieldSamples
|
|
Examples:
Source code in src/psyphy/model/covariance_field.py
mean
¶
Posterior mean of the covariance field, :math:\mathbb{E}[\Sigma(x)].
Evaluates :math:\Sigma(x) for every draw and averages the resulting
matrices. Averaging the parameters first instead gives contours several
times too small, because :math:\Sigma is nonlinear in :math:W.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
x
|
(ndarray, shape(d) or (..., d))
|
One stimulus location, or any batch of them. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Sigma |
(ndarray, shape(d, d) or (..., d, d))
|
The mean matrix per location, with no draws axis. |
Examples:
Source code in src/psyphy/model/covariance_field.py
sqrt_cov
¶
Evaluate the square root :math:U(x) for every draw.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
x
|
(ndarray, shape(d) or (..., d))
|
One stimulus location, or any batch of them. The last axis must
have size |
required |
Returns:
| Name | Type | Description |
|---|---|---|
U |
(ndarray, shape(n_samples, d, m) or (n_samples, ..., d, m))
|
One matrix per draw per location, |
Examples:
Source code in src/psyphy/model/covariance_field.py
contour_radii
¶
Distance from the center to the one-standard-deviation ellipse, per direction.
For a covariance :math:\Sigma, the contour
:math:\{v : v^\top \Sigma^{-1} v = 1\} meets the ray along a unit
direction :math:u at distance
.. math:: r(u) = 1 / \sqrt{u^\top \Sigma^{-1} u}
Writing a point on the ray as :math:v = r\,u turns the contour condition
into :math:r^2 u^\top \Sigma^{-1} u = 1, which is the expression above.
Along an eigenvector this is :math:\sqrt{\lambda}, i.e. exactly the
semi-axis :func:psyphy.viz.ellipse_segments draws at scale=1. For the
oddity task this radius is the discrimination threshold, the just
noticeable difference, in direction u.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
covs
|
(ndarray, shape(..., d, d))
|
One or more covariance matrices. Leading axes are broadcast over. |
required |
directions
|
(ndarray, shape(n_directions, d))
|
Unit directions. We do not normalize them, and a non-unit direction rescales the radius. |
required |
Returns:
| Type | Description |
|---|---|
(ndarray, shape(..., n_directions))
|
|
Notes
This is a polar parameterization of the same ellipse that
ellipse_segments produces, and the two are not interchangeable. That
function maps a circle through the Cholesky factor, so its parameter angle
is not the direction from the center. Any statistic taken across samples at
fixed angle, a quantile or a mean, must use this parameterization, or it
compares points lying in different directions.
Source code in src/psyphy/model/covariance_field.py
covariance_to_arviz
¶
Per-sample covariance Σ(x) at chosen points, as an ArviZ DataTree.
Use this, not posterior.to_arviz(), for convergence diagnostics
(R-hat, ESS, trace plots) of a WPPM fit.
Why Σ and not W
W is only identified up to an orthogonal rotation R of its embedding axis: W -> W R gives U(x) -> U(x) R and leaves Σ(x) = U Uᵀ + λI, and the prior, unchanged. Chains can therefore settle at different orientations that describe exactly the same covariance field. R-hat on W reports that as non-convergence, although no ellipse, threshold or prediction depends on the orientation. Σ(x) is invariant, so its diagnostics measure what the fit is actually used for.
Why points must be chosen
Unlike W, Σ is a function of the stimulus location x, so a diagnostic of Σ
is a diagnostic at some x. This function has no default for
points: which locations to check is a modeling decision. Sensible
choices are the locations you report (e.g. the reference points of the
plotted ellipses), optionally plus a grid covering the stimulus space,
since away from the data the posterior relies more on the prior. Report
the worst value over all points. A modest number of points suffices: Σ is
a low-degree polynomial in x, so dense grids add mostly near-duplicates.
Quantities
For each sample and point, the d x d matrix Σ is summarized by its d log variances and d(d-1)/2 correlations, which together determine Σ:
log_var_i= log Σ_iicorr_i_j= Σ_ij / sqrt(Σ_ii Σ_jj), for i < j
(2D: log_var_0, log_var_1, corr_0_1.) The off-diagonal is not
counted twice. Logs make the variances less skewed; note that ArviZ's
default rank-normalized R-hat is unchanged by such monotone transforms
anyway.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
posterior
|
MCMCPosterior
|
A sample-based posterior with |
required |
points
|
(array_like, shape(n_points, input_dim))
|
Stimulus locations at which to evaluate Σ. |
required |
Returns:
| Type | Description |
|---|---|
DataTree
|
|
Raises:
| Type | Description |
|---|---|
TypeError
|
If the posterior has no |
ValueError
|
If |
ImportError
|
If ArviZ is not installed ( |
Examples:
Source code in src/psyphy/model/covariance_field.py
648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 | |
Wishart Psyochophysical Process Model (WPPM)¶
wppm
¶
wppm.py
Wishart Process Psychophysical Model (WPPM)
Goals
Wishart Process Psychophysical Model (WPPM): - Read input_dim, embedding_dim, variance_scale, decay_rate and basis_degree from the Prior it is built with, so each one has a single place where it is set. - Add diag_term, the numerical stabilizer in Sigma(x) = U(x) U(x)^T + diag_term * I, which is a WPPM setting rather than a property of the prior distribution.
All numerics use JAX (jax.numpy as jnp) to support autodiff and optax optimizers
Classes:
| Name | Description |
|---|---|
WPPM |
Wishart Process Psychophysical Model (WPPM). |
Attributes:
| Name | Type | Description |
|---|---|---|
Params |
|
|
Stimulus |
|
WPPM
¶
WPPM(prior: Prior, likelihood: TaskLikelihood, noise: Any | None = None, *, diag_term: float = 1e-06, **model_kwargs: Any)
Bases: Model
Wishart Process Psychophysical Model (WPPM).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prior
|
Prior
|
Prior distribution over model parameters. WPPM reads input_dim, embedding_dim, variance_scale, decay_rate and basis_degree from the prior, so each one is set once and the two objects cannot disagree. |
required |
likelihood
|
TaskLikelihood
|
Psychophysical task mapping that defines how discriminability translates to p(correct) and how log-likelihood of responses is computed. (e.g., OddityTask) |
required |
noise
|
Any
|
Noise model describing internal representation noise (e.g., GaussianNoise). |
None
|
diag_term
|
float
|
Small positive value added to the covariance diagonal for numerical stability: Sigma(x) = U(x) U(x)^T + diag_term * I. A WPPM setting, not a property of the prior. |
1e-6
|
**model_kwargs
|
Any
|
Reserved for future keyword arguments accepted by the base |
{}
|
Methods:
| Name | Description |
|---|---|
init_params |
Sample initial parameters from the prior. |
local_covariance |
Return local covariance Σ(x) at stimulus location x. |
log_likelihood_from_data |
Compute log-likelihood directly from a batched data object. |
log_posterior_from_data |
Compute log posterior from data. |
predict_prob |
Predict probability of a correct response for a single stimulus. |
Attributes:
| Name | Type | Description |
|---|---|---|
basis_degree |
int
|
Chebyshev polynomial degree for Wishart process basis expansion. |
decay_rate |
float
|
Smoothness/length-scale for spatial covariance variation. Reads self.prior.decay_rate. |
diag_term |
|
|
embedding_dim |
int
|
Dimension of the embedding space. |
input_dim |
int
|
Dimensionality of the input stimulus space. |
likelihood |
|
|
noise |
|
|
prior |
|
|
variance_scale |
float
|
Global scaling factor for covariance magnitude. Reads self.prior.variance_scale. |
Source code in src/psyphy/model/wppm.py
basis_degree
¶
basis_degree: int
Chebyshev polynomial degree for Wishart process basis expansion.
This property delegates to self.prior.basis_degree to ensure consistency between parameter sampling and basis evaluation.
Returns:
| Type | Description |
|---|---|
int
|
Degree of Chebyshev polynomial basis (0 = constant, 1 = linear, etc.) |
Notes
WPPM gets its basis_degree parameter from Prior.basis_degree.
decay_rate
¶
decay_rate: float
Smoothness/length-scale for spatial covariance variation. Reads self.prior.decay_rate.
embedding_dim
¶
embedding_dim: int
Dimension of the embedding space.
embedding_dim = input_dim + extra_embedding_dims, both read from the prior. The first input_dim coordinates are the observable stimulus features, the rest are latent dimensions.
Returns:
| Type | Description |
|---|---|
int
|
input_dim + extra_embedding_dims |
input_dim
¶
input_dim: int
Dimensionality of the input stimulus space.
Delegates to self.prior.input_dim, the single place this is set.
Returns:
| Type | Description |
|---|---|
int
|
e.g. 2 for the isoluminant plane, 3 for RGB. |
variance_scale
¶
variance_scale: float
Global scaling factor for covariance magnitude. Reads self.prior.variance_scale.
init_params
¶
init_params(key: Array) -> Params
Sample initial parameters from the prior.
Returns:
| Name | Type | Description |
|---|---|---|
params |
dict[str, jnp.ndarray], a parameter pytree
|
For WPPM, |
Source code in src/psyphy/model/wppm.py
local_covariance
¶
local_covariance(params: Params, x: ndarray) -> ndarray
Return local covariance Σ(x) at stimulus location x.
Σ(x) = U(x) @ U(x)^T + diag_term * I where U(x) is rectangular (input_dim, embedding_dim) if extra_embedding_dims > 0. - Varies smoothly with x - Guaranteed positive-definite - Returns stimulus covariance directly (input_dim, input_dim)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
Model parameters: - WPPM: {"W": (degree+1, ..., input_dim, embedding_dim)} |
required |
x
|
(ndarray, shape(input_dim))
|
Stimulus location |
required |
Returns:
| Type | Description |
|---|---|
Σ : jnp.ndarray, shape (input_dim, input_dim)
|
Covariance matrix in stimulus space. |
Source code in src/psyphy/model/wppm.py
log_likelihood_from_data
¶
Compute log-likelihood directly from a batched data object.
Why delegate to the likelihood? - The likelihood knows the decision rule (oddity, 2AFC, ...). - The likelihood can use the model (this WPPM) to fetch discriminabilities. - The likelihood can use the noise model if it needs MC simulation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
Model parameters. |
required |
data
|
TrialData (or any object with refs/comparisons/responses arrays)
|
Collected trial data. |
required |
key
|
Array | None
|
JAX random key for MC likelihood evaluation. When provided, a fresh
noise realization is drawn every call, required for correct stochastic
gradient estimates during optimization. When None, the task falls back
to |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
loglik |
(ndarray, shape())
|
Scalar log-likelihood (task-only; add prior outside if needed). |
Source code in src/psyphy/model/wppm.py
log_posterior_from_data
¶
Compute log posterior from data.
This simply adds the prior log-probability to the task log-likelihood. Inference engines (e.g., MAP optimizer) typically optimize this quantity.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
Model parameters. |
required |
data
|
TrialData
|
Collected trial data. |
required |
key
|
Array | None
|
JAX random key for the MC likelihood. Must be provided during
optimization so each gradient step uses a fresh noise realization.
When None, falls back to |
None
|
Returns:
| Type | Description |
|---|---|
(ndarray, shape())
|
Scalar log posterior = loglik(params | data) + log_prior(params). |
Source code in src/psyphy/model/wppm.py
predict_prob
¶
Predict probability of a correct response for a single stimulus.
Design choice: WPPM computes discriminability & covariance; the LIKELIHOOD defines how that translates to performance. We therefore delegate to: likelihood.predict(params, stimulus, model=self, noise=self.noise)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
|
required |
stimulus
|
tuple[jnp.ndarray, jnp.ndarray], each shape (input_dim,)
|
(reference, comparison) pair in model space. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
p_correct |
(ndarray, shape())
|
Scalar probability of a correct response. |
Source code in src/psyphy/model/wppm.py
Priors¶
prior
¶
prior.py
Prior distributions for WPPM parameters
Hyperparameters: * variance_scale : global scaling factor for covariance magnitude * decay_rate : smoothness controlling spatial variation * extra_embedding_dims : embedding dimension for basis expansions
Connections
- WPPM calls Prior.sample_params() to initialize model parameters
- Prior.sample(n, key=...) draws n of them at once
- WPPM adds Prior.log_prob(params) to task log-likelihoods to form the log posterior
- Prior will generate structured parameters for basis expansions and decay_rate-controlled smooth covariance fields
Classes:
| Name | Description |
|---|---|
Prior |
Prior distribution over WPPM parameters |
Attributes:
| Name | Type | Description |
|---|---|---|
Params |
|
Prior
¶
Prior(input_dim: int = 2, basis_degree: int = 4, variance_scale: float = 0.004, decay_rate: float = 0.4, extra_embedding_dims: int = 1)
Prior distribution over WPPM parameters
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
input_dim
|
int
|
Dimensionality of the model space. WPPM.input_dim reads this. |
2
|
basis_degree
|
int
|
Degree of the Chebyshev basis. U(x) is a weighted sum of basis functions up to this degree, with weights W. Must be 0 or more. |
4
|
variance_scale
|
float
|
Prior variance for degree-0 (constant) coefficient. Controls overall scale of covariances. WPPM.variance_scale reads this. |
4e-3
|
decay_rate
|
float
|
Geometric decay rate for prior variance over higher-degree coefficients. Prior variance for degree-d coefficient = variance_scale * (decay_rate^d). Smaller decay_rate -> stronger smoothness prior. WPPM.decay_rate reads this. |
0.4
|
extra_embedding_dims
|
int
|
Additional latent dimensions in U matrices beyond input dimensions. Allows richer ellipsoid shapes. WPPM.embedding_dim reads this. |
1
|
Methods:
| Name | Description |
|---|---|
log_prob |
Compute log prior density (up to a constant) |
param_scales |
Prior standard deviation of every parameter, as a PyTree shaped like |
sample |
Sample n independent parameter draws from the prior. |
sample_params |
Sample initial parameters from the prior. |
Attributes:
| Name | Type | Description |
|---|---|---|
basis_degree |
int
|
|
decay_rate |
float
|
|
extra_embedding_dims |
int
|
|
input_dim |
int
|
|
variance_scale |
float
|
|
log_prob
¶
log_prob(params: Params) -> ndarray
Compute log prior density (up to a constant)
Gaussian prior on W with smoothness via decay_rate log p(W) = Σ_ij log N(W_ij | 0, σ_ij^2) where σ_ij^2 = prior variance
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
Parameter dictionary |
required |
Returns:
| Name | Type | Description |
|---|---|---|
log_prob |
float
|
Log prior probability (up to normalizing constant) |
Source code in src/psyphy/model/prior.py
param_scales
¶
param_scales() -> Params
Prior standard deviation of every parameter, as a PyTree shaped like
sample_params().
The prior std depends only on a coefficient's basis degree, so it is broadcast over the trailing (input_dim, embedding_dim) axes of W.
Used by NUTSSampler to precondition the sampler: coefficients at different degrees have prior scales that differ by orders of magnitude, and sampling W / scale instead of W puts them all on a common O(1) scale.
Returns:
| Name | Type | Description |
|---|---|---|
scales |
dict
|
{"W": array with the same shape as sample_params()["W"]} |
Source code in src/psyphy/model/prior.py
sample
¶
Sample n independent parameter draws from the prior.
The vectorized form of :meth:sample_params: draw i equals
sample_params(jax.random.split(key, n)[i]).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n
|
int
|
Number of draws. |
required |
key
|
Array
|
PRNG key, split n ways. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
params |
dict
|
Parameter dictionary with a leading axis of n, so for 2D |
Notes
Satisfies :class:psyphy.posterior.ParameterSource.
Examples:
Source code in src/psyphy/model/prior.py
sample_params
¶
Sample initial parameters from the prior.
Returns {"W": shape (degree+1, degree+1, input_dim, embedding_dim)} for 2D, where embedding_dim = input_dim + extra_embedding_dims
Note: The 3rd dimension is input_dim (output space dimension). This matches the einsum in _compute_sqrt: U = einsum("ijde,ij->de", W, phi) where d indexes input_dim.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
JAX random key
|
|
required |
Returns:
| Name | Type | Description |
|---|---|---|
params |
dict
|
Parameter dictionary |
Source code in src/psyphy/model/prior.py
Noise¶
noise
¶
Classes:
| Name | Description |
|---|---|
GaussianNoise |
|
StudentTNoise |
|
GaussianNoise
¶
GaussianNoise(sigma: float = 1.0)
Likelihood (defined by Tasks)¶
likelihood
¶
psyphy.model.likelihood
Task likelihoods for psychophysical experiments: the mapping from a model and a set of stimuli to the likelihood of an observed response.
Likelihoods are grouped by response distribution. The log-likelihood is written
once per distribution, and a new task only implements predict:
Modules:
| Name | Description |
|---|---|
base : TaskLikelihood, BernoulliTaskLikelihood, GaussianTaskLikelihood, |
log_probs_from_logit |
oddity : OddityTaskConfig, OddityTask |
|
Every public name is re-exported here, so existing imports are unaffected:: |
from psyphy.model.likelihood import OddityTask, TaskLikelihood |
Classes:
| Name | Description |
|---|---|
BernoulliTaskLikelihood |
Intermediate abstract subclass for task likelihoods. |
GaussianTaskLikelihood |
Intermediate abstract subclass for task likelihoods. |
OddityTask |
Three-alternative forced-choice oddity task (MC-based only). |
OddityTaskConfig |
Configuration for :class: |
TaskLikelihood |
Abstract base class for task likelihoods. |
Functions:
| Name | Description |
|---|---|
log_probs_from_logit |
Log-probabilities of a correct and an incorrect response, from a logit. |
BernoulliTaskLikelihood
¶
Bases: TaskLikelihood
Intermediate abstract subclass for task likelihoods.
Subclasses must implement:
- predict(params, stimuli, model, *, key) -> (log_p, log_1mp) for one
trial: log p(correct) and log p(incorrect), each of shape ()
This abstract subclass provides concrete implementations of:
- loglik(params, data, model, *, key) -> Bernoulli log-likelihood over a batch
- simulate(params, inputs, model, *, key) -> simulated responses
predict returns log-probabilities, not p(correct), and doesn't clip them.
exp(log_p) can round to exactly 1.0, where log(1 - p) is -inf. Use
log_1mp for log p(incorrect).
loglik holds each trial's probability in [1e-6, 1 - 1e-6]. A task with a
logit returns :func:log_probs_from_logit. A task that averages over
samples, like :class:OddityTask, takes logsumexp over the samples'
log-probabilities.
Examples:
A task whose logit grows with the distance between the 2 stimuli:
Methods:
| Name | Description |
|---|---|
loglik |
Compute Bernoulli log-likelihood over a batch of trials. |
predict |
Return parameters sufficient to determine probability of any given |
simulate |
Simulate observed binary responses for a batch of trials. |
loglik
¶
Compute Bernoulli log-likelihood over a batch of trials.
We vmap predict over trials, then take log p(correct) where the
response is 1 and log p(incorrect) where it is 0, and sum.
Each trial's probability is held in [1e-6, 1 - 1e-6]. A trial the model calls nearly impossible adds log(1e-6), about -13.8, and has no gradient past that bound.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
data
|
Any
|
Object with |
required |
model
|
Any
|
Model instance. |
required |
key
|
Array
|
PRNG key. Passed as independent per-trial subkeys to |
None
|
Returns:
| Type | Description |
|---|---|
(ndarray, shape())
|
Scalar sum of Bernoulli log-likelihoods over all trials. |
Source code in src/psyphy/model/likelihood/base.py
predict
¶
Return parameters sufficient to determine probability of any given response on a single trial. The parameters will be specific to the distribution (specified by abstract subclass)
BernoulliTaskLikelihood: returns (log p(correct), log p(incorrect)) GaussianTaskLikelihood: returns (mu, sigma), the parameters defining a Gaussian distribution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
stimuli
|
(ndarray, shape(stim_dim, K))
|
stimuli for a given trial (stimulus dimensions, number of stimuli) |
required |
model
|
Any
|
Model instance (provides covariance structure and |
required |
key
|
Array
|
PRNG key for stochastic tasks. When None, the task falls back to
its |
None
|
Returns:
| Type | Description |
|---|---|
parameter(s): jnp.ndarray
|
any number of parameters necessary to specify probability for likelihood calculation - for Bernoulli: log p(correct) and log p(incorrect) (2 scalars) - for Gaussian: mu (r_dim vector), sigma (r_dim x r_dim covariance matrix) |
Source code in src/psyphy/model/likelihood/base.py
simulate
¶
simulate(params: Any, stimuli: ndarray, model: Any, key: Any) -> tuple[ndarray, tuple[ndarray, ...]]
Simulate observed binary responses for a batch of trials.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
stimuli
|
(ndarray, shape(n_trials, k_stim, input_dim))
|
Stimuli. |
required |
model
|
Any
|
Model instance. |
required |
key
|
Array
|
PRNG key (required; split internally for prediction and sampling). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
responses |
jnp.ndarray, shape (n_trials,), dtype int32
|
Simulated binary responses (1 = correct, 0 = incorrect). |
probability parameters : tuple[jnp.ndarray]
|
1-tuple |
Source code in src/psyphy/model/likelihood/base.py
GaussianTaskLikelihood
¶
Bases: TaskLikelihood
Intermediate abstract subclass for task likelihoods.
Subclasses must implement:
- predict(params, stimuli, model, *, key) -> (mu, sigma) of distribution for one trial
This abstract subclass provides concrete implementations of:
- loglik(params, data, model, *, key) -> Gaussian log-likelihood over a batch
- simulate(params, inputs, model, *, key) -> simulated responses
The Gaussian log-likelihood step is identical for all tasks with the assumption of Gaussian response distributions, so it lives here rather than being re-implemented in every subclass.
Methods:
| Name | Description |
|---|---|
loglik |
Compute Gaussian log-likelihood over a batch of trials. |
predict |
Return parameters sufficient to determine probability of any given |
simulate |
Simulate observed responses for a batch of trials. |
loglik
¶
Compute Gaussian log-likelihood over a batch of trials.
This is a concrete base-class method: it vmaps predict over trials
then applies the Gaussian log-likelihood formula. Subclasses only need
to implement predict.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
data
|
Any
|
Object with |
required |
model
|
Any
|
Model instance. |
required |
key
|
Array
|
PRNG key. Passed as independent per-trial subkeys to |
None
|
Returns:
| Type | Description |
|---|---|
(ndarray, shape())
|
Scalar sum of Gaussian log-likelihoods over all trials. |
Source code in src/psyphy/model/likelihood/base.py
predict
¶
Return parameters sufficient to determine probability of any given response on a single trial. The parameters will be specific to the distribution (specified by abstract subclass)
BernoulliTaskLikelihood: returns (log p(correct), log p(incorrect)) GaussianTaskLikelihood: returns (mu, sigma), the parameters defining a Gaussian distribution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
stimuli
|
(ndarray, shape(stim_dim, K))
|
stimuli for a given trial (stimulus dimensions, number of stimuli) |
required |
model
|
Any
|
Model instance (provides covariance structure and |
required |
key
|
Array
|
PRNG key for stochastic tasks. When None, the task falls back to
its |
None
|
Returns:
| Type | Description |
|---|---|
parameter(s): jnp.ndarray
|
any number of parameters necessary to specify probability for likelihood calculation - for Bernoulli: log p(correct) and log p(incorrect) (2 scalars) - for Gaussian: mu (r_dim vector), sigma (r_dim x r_dim covariance matrix) |
Source code in src/psyphy/model/likelihood/base.py
simulate
¶
simulate(params: Any, stimuli: ndarray, model: Any, key: Any) -> tuple[ndarray, tuple[ndarray, ...]]
Simulate observed responses for a batch of trials.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
stimuli
|
(ndarray, shape(n_trials, k_stim, input_dim))
|
Stimuli. |
required |
model
|
Any
|
Model instance. |
required |
key
|
Array
|
PRNG key (required; split internally for prediction and sampling). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
responses |
(ndarray, shape(n_trials, r_dims))
|
Simulated responses. |
prob_params |
(ndarray, shape(n_trials))
|
Estimated (mu, sigma) per trial used to draw the responses. |
Source code in src/psyphy/model/likelihood/base.py
OddityTask
¶
OddityTask(config: OddityTaskConfig | None = None)
Bases: BernoulliTaskLikelihood
Three-alternative forced-choice oddity task (MC-based only).
Implements the full 3-stimulus oddity task using Monte Carlo simulation: - Samples three internal representations per trial (z0, z1, z2) - Uses proper oddity decision rule with three pairwise distances
Notes
MC simulation in loglik() (full 3-stimulus oddity): 1. Sample three internal representations: z_ref, z_refprime ~ N(ref, Σ_ref), z_comparison ~ N(comparison, Σ_comparison) 2. Compute average covariance: Σ_avg = (2/3) Σ_ref + (1/3) Σ_comparison 3. Compute three pairwise Mahalanobis distances: - d^2(z_ref, z_refprime) = distance between two reference samples - d^2(z_ref, z_comparison) = distance from ref to comparison - d^2(z_refprime, z_comparison) = distance from reference_prime to comparison 4. Apply oddity decision rule: delta = min(d^2(z_ref,z_comparison), d^2(z_refprime,z_comparison)) - d^2(z_ref,z_refprime) 5. Logistic smoothing: P(correct) ~ logistic.cdf(delta / bandwidth) 6. Average over samples, in log space
Examples:
Methods:
| Name | Description |
|---|---|
loglik |
Compute Bernoulli log-likelihood over a batch of trials. |
predict |
Return log p(correct) and log p(incorrect) for a single (ref, comparison) |
simulate |
Simulate observed binary responses for a batch of trials. |
Attributes:
| Name | Type | Description |
|---|---|---|
config |
|
Source code in src/psyphy/model/likelihood/oddity.py
loglik
¶
Compute Bernoulli log-likelihood over a batch of trials.
We vmap predict over trials, then take log p(correct) where the
response is 1 and log p(incorrect) where it is 0, and sum.
Each trial's probability is held in [1e-6, 1 - 1e-6]. A trial the model calls nearly impossible adds log(1e-6), about -13.8, and has no gradient past that bound.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
data
|
Any
|
Object with |
required |
model
|
Any
|
Model instance. |
required |
key
|
Array
|
PRNG key. Passed as independent per-trial subkeys to |
None
|
Returns:
| Type | Description |
|---|---|
(ndarray, shape())
|
Scalar sum of Bernoulli log-likelihoods over all trials. |
Source code in src/psyphy/model/likelihood/base.py
predict
¶
Return log p(correct) and log p(incorrect) for a single (ref, comparison) trial, via MC simulation.
MC controls (num_samples, bandwidth) are read from
:class:OddityTaskConfig. Pass key to control randomness; when
None, config.default_key_seed is used.
Source code in src/psyphy/model/likelihood/oddity.py
simulate
¶
simulate(params: Any, stimuli: ndarray, model: Any, key: Any) -> tuple[ndarray, tuple[ndarray, ...]]
Simulate observed binary responses for a batch of trials.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
stimuli
|
(ndarray, shape(n_trials, k_stim, input_dim))
|
Stimuli. |
required |
model
|
Any
|
Model instance. |
required |
key
|
Array
|
PRNG key (required; split internally for prediction and sampling). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
responses |
jnp.ndarray, shape (n_trials,), dtype int32
|
Simulated binary responses (1 = correct, 0 = incorrect). |
probability parameters : tuple[jnp.ndarray]
|
1-tuple |
Source code in src/psyphy/model/likelihood/base.py
OddityTaskConfig
¶
Configuration for :class:OddityTask.
This is the single source of truth for MC likelihood controls.
Attributes:
| Name | Type | Description |
|---|---|---|
num_samples |
int
|
Number of Monte Carlo samples per trial. |
bandwidth |
float
|
Logistic CDF smoothing bandwidth. |
default_key_seed |
int
|
Seed used when no key is provided (keeps behavior deterministic by default while allowing reproducibility control upstream). |
TaskLikelihood
¶
Bases: ABC
Abstract base class for task likelihoods.
Subclasses must implement:
- predict(params, stimuli, model, *, key) -> probability parameters for one trial
The base class provides concrete implementations of:
- loglik(params, data, model, *, key) -> Bernoulli log-likelihood over a batch
- simulate(params, stimuli, model, *, key) -> simulated responses & probability parameters
The Bernoulli log-likelihood step is identical for all binary-response tasks, so it lives here rather than being re-implemented in every subclass.
Methods:
| Name | Description |
|---|---|
loglik |
Compute and return log-likelihood over a batch of trials. |
predict |
Return parameters sufficient to determine probability of any given |
simulate |
Simulate responses for a batch of trials. |
loglik
¶
Compute and return log-likelihood over a batch of trials. Each abstract subclass will concretely implement this for all tasks with the assumption of a given distribution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
data
|
Any
|
Object with |
required |
model
|
Any
|
Model instance (provides covariance structure and |
required |
key
|
Array
|
PRNG key for stochastic tasks. When None, the task falls back to
its |
None
|
Returns:
| Type | Description |
|---|---|
(ndarray, shape())
|
Scalar sum of log-likelihoods over all trials. |
Source code in src/psyphy/model/likelihood/base.py
predict
¶
Return parameters sufficient to determine probability of any given response on a single trial. The parameters will be specific to the distribution (specified by abstract subclass)
BernoulliTaskLikelihood: returns (log p(correct), log p(incorrect)) GaussianTaskLikelihood: returns (mu, sigma), the parameters defining a Gaussian distribution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
stimuli
|
(ndarray, shape(stim_dim, K))
|
stimuli for a given trial (stimulus dimensions, number of stimuli) |
required |
model
|
Any
|
Model instance (provides covariance structure and |
required |
key
|
Array
|
PRNG key for stochastic tasks. When None, the task falls back to
its |
None
|
Returns:
| Type | Description |
|---|---|
parameter(s): jnp.ndarray
|
any number of parameters necessary to specify probability for likelihood calculation - for Bernoulli: log p(correct) and log p(incorrect) (2 scalars) - for Gaussian: mu (r_dim vector), sigma (r_dim x r_dim covariance matrix) |
Source code in src/psyphy/model/likelihood/base.py
simulate
¶
simulate(params: Any, stimuli: ndarray, model: Any, key: Any) -> tuple[ndarray, tuple[ndarray, ...]]
Simulate responses for a batch of trials.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
Any
|
Model parameters. |
required |
stimuli
|
(ndarray, shape(n_trials, k_stimuli, input_dim))
|
Stimuli. |
required |
model
|
Any
|
Model instance. |
required |
key
|
Array
|
PRNG key (required; split internally for prediction and sampling). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
responses |
(ndarray, shape(n_trials, r_dim))
|
Simulated responses. |
probability parameters : tuple[jnp.ndarray, ...], each array has shape[0] = n_trials
|
Bernoulli: Estimated (P(correct)) per trial used to draw the responses. shape = (n_trials) Gaussian: Estimated (mu, sigma) per trial used to draw the responses. shape for mu = (n_trials, r_dims); shape for sigma = (n_trials, r_dims, r_dims). |
|
Note |
not yet implemented for Gaussians
|
|
Source code in src/psyphy/model/likelihood/base.py
log_probs_from_logit
¶
log_probs_from_logit(z: ndarray) -> tuple[ndarray, ndarray]
Log-probabilities of a correct and an incorrect response, from a logit.
The logit z is the log-odds of a correct response, so that
p(correct) = sigmoid(z). We return the log of both probabilities without
forming p(correct) first, so neither one is rounded when p(correct) is close
to 0 or 1.
A :class:BernoulliTaskLikelihood task with a logit returns
log_probs_from_logit(z) from its predict.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
z
|
jnp.ndarray, any shape
|
Log-odds of a correct response. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
log_p |
jnp.ndarray, same shape as ``z``
|
log p(correct) = |
log_1mp |
jnp.ndarray, same shape as ``z``
|
log p(incorrect) = |
Examples: