Skip to content

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
from psyphy.model import WPPM, Prior, OddityTask, GaussianNoise

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:OddityTask.

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

sqrt_cov(x: ndarray) -> ndarray

Evaluate "square root" matrix U(x) such that Σ(x) = U(x) @ U(x)^T + λI.

Source code in src/psyphy/model/covariance_field.py
def sqrt_cov(self, x: jnp.ndarray) -> jnp.ndarray:
    """Evaluate "square root" matrix U(x) such that Σ(x) = U(x) @ U(x)^T + λI."""
    ...

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, the second when a sequence was requested. All three carry the same shape, so a loop over levels can index all of them. The median does not depend on the interval probability, so its levels are identical copies.

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

"eti" for equal-tailed, "hdi" for highest-density.

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.

ci_kind

ci_kind: str

ci_prob

ci_prob: float | tuple[float, ...]

directions

directions: ndarray

lower

lower: ndarray

median

median: ndarray

points

points: ndarray

upper

upper: ndarray

GaussianNoise

GaussianNoise(sigma: float = 1.0)

Methods:

Name Description
log_prob
sample_standard

Sample from standard Gaussian (mean=0, var=1).

Attributes:

Name Type Description
sigma float

sigma

sigma: float = 1.0

log_prob

log_prob(residual: float) -> float
Source code in src/psyphy/model/noise.py
def log_prob(self, residual: float) -> float:
    _ = residual
    return -0.5

sample_standard

sample_standard(key: Array, shape: tuple[int, ...]) -> Array

Sample from standard Gaussian (mean=0, var=1).

Source code in src/psyphy/model/noise.py
def sample_standard(self, key: jax.Array, shape: tuple[int, ...]) -> jax.Array:
    """Sample from standard Gaussian (mean=0, var=1)."""
    return jr.normal(key, shape)

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

init_params(key: Any) -> dict

Sample initial parameters from prior.

Parameters:

Name Type Description Default
key Array

PRNG key

required

Returns:

Type Description
dict

Parameter PyTree

Source code in src/psyphy/model/base.py
@abstractmethod
def init_params(self, key: Any) -> dict:  # jax.Array
    """
    Sample initial parameters from prior.

    Parameters
    ----------
    key : jax.Array
        PRNG key

    Returns
    -------
    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
@abstractmethod
def log_likelihood_from_data(self, params: dict, data: ResponseData) -> jnp.ndarray:
    """
    Compute log p(data | params).

    Parameters
    ----------
    params : dict
        Model parameters
    data : ResponseData
        Observed trials

    Returns
    -------
    jnp.ndarray, shape ()
        Log-likelihood (scalar)
    """
    ...

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:

>>> from psyphy.model.likelihood import OddityTask
>>> from psyphy.model.likelihood import OddityTaskConfig
>>> from psyphy.model import WPPM, Prior
>>> from psyphy.model.noise import GaussianNoise
>>> import jax.numpy as jnp
>>> import jax.random as jr
>>>
>>> # Create task and model (task-owned MC controls)
>>> likelihood = OddityTask(
...     config=OddityTaskConfig(num_samples=1000, bandwidth=1e-2)
... )
>>> model = WPPM(
...     prior=Prior(input_dim=2),
...     likelihood=likelihood,
...     noise=GaussianNoise(),
... )
>>> params = model.init_params(jr.PRNGKey(0))
1
2
3
4
5
6
7
8
9
>>> # MC simulation, one trial
>>> from psyphy.data.dataset import ResponseData
>>> ref = jnp.array([0.0, 0.0])  # (2,)
>>> comparison = jnp.array([0.1, 0.0])  # (2,)
>>> data = ResponseData()
>>> data.add_trial((ref, comparison), resp=1)
>>> ll_mc = likelihood.loglik(params, data, model, key=jr.PRNGKey(42))
>>> ll_mc.shape
()

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
def __init__(self, config: OddityTaskConfig | None = None) -> None:
    # No analytical parameters in MC-only mode.
    self.config = config or OddityTaskConfig()

config

config = config or OddityTaskConfig()

loglik

loglik(params: Any, data: Any, model: Any, key: Any = None) -> ndarray

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 .stimuli, .responses array attributes.

required
model Any

Model instance.

required
key Array

PRNG key. Passed as independent per-trial subkeys to predict. When None, falls back to key=jr.PRNGKey(0) (deterministic).

None

Returns:

Type Description
(ndarray, shape())

Scalar sum of Bernoulli log-likelihoods over all trials.

Source code in src/psyphy/model/likelihood/base.py
def loglik(
    self,
    params: Any,
    data: Any,
    model: Any,
    key: Any = None,
) -> jnp.ndarray:
    """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
    ----------
    params : Any
        Model parameters.
    data : Any
        Object with ``.stimuli``, ``.responses`` array attributes.
    model : Any
        Model instance.
    key : jax.Array, optional
        PRNG key. Passed as independent per-trial subkeys to ``predict``.
        When None, falls back to ``key=jr.PRNGKey(0)`` (deterministic).

    Returns
    -------
    jnp.ndarray, shape ()
        Scalar sum of Bernoulli log-likelihoods over all trials.
    """
    stimuli = jnp.asarray(data.stimuli)
    # TrialData stores responses as (N, R): R=1 for binary tasks.
    # Extract the single binary channel to get shape (N,).
    # Without this, jnp.where broadcasts (N, 1) against log_p (N,),
    # treating (N,) as (1, N) and producing an (N, N) result whose
    # sum scrambles the gradient: every p[j] receives signal from all
    # N responses instead of only response[j].

    responses = jnp.asarray(data.responses)
    if responses.ndim == 2:  # shape (N, R)
        responses = responses[:, 0]
    responses = responses.astype(int)
    n_trials = int(stimuli.shape[0])

    base_key = key if key is not None else jr.PRNGKey(0)
    trial_keys = jr.split(base_key, n_trials)

    log_p, log_1mp = jax.vmap(
        lambda stim, k: self.predict(params, stim, model, key=k)
    )(stimuli, trial_keys)  # each (N,)

    log_likelihoods = jnp.where(responses == 1, log_p, log_1mp)  # (N,)
    log_likelihoods = jnp.clip(log_likelihoods, jnp.log(_P_EPS), jnp.log1p(-_P_EPS))

    return jnp.sum(log_likelihoods)

predict

predict(params: Any, stimuli: ndarray, model: Any, key: Any = None) -> tuple[ndarray, ...]

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
def predict(
    self,
    params: Any,
    stimuli: jnp.ndarray,  # (k_stimuli, dimensions)
    model: Any,
    key: Any = None,
) -> tuple[jnp.ndarray, ...]:
    """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.
    """
    num_samples = int(self.config.num_samples)
    bandwidth = float(self.config.bandwidth)
    if key is None:
        key = jr.PRNGKey(int(self.config.default_key_seed))

    ref = stimuli[0, :]
    comparison = stimuli[1, :]

    return self._simulate_trial_mc(
        params=params,
        ref=ref,
        comparison=comparison,
        model=model,
        num_samples=num_samples,
        bandwidth=bandwidth,
        key=key,
    )

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 (p_correct,). p_correct has shape (n_trials,) and holds the estimated P(correct) per trial used to draw the responses, as exp(log_p) of what predict returns.

Source code in src/psyphy/model/likelihood/base.py
def simulate(
    self,
    params: Any,
    stimuli: jnp.ndarray,
    model: Any,
    key: Any,
) -> tuple[jnp.ndarray, tuple[jnp.ndarray, ...]]:
    """Simulate observed binary responses for a batch of trials.

    Parameters
    ----------
    params : Any
        Model parameters.
    stimuli : jnp.ndarray, shape (n_trials, k_stim, input_dim)
        Stimuli.
    model : Any
        Model instance.
    key : jax.Array
        PRNG key (required; split internally for prediction and sampling).

    Returns
    -------
    responses : jnp.ndarray, shape (n_trials,), dtype int32
        Simulated binary responses (1 = correct, 0 = incorrect).
    probability parameters : tuple[jnp.ndarray]
        1-tuple ``(p_correct,)``. ``p_correct`` has shape (n_trials,) and holds
        the estimated P(correct) per trial used to draw the responses, as
        ``exp(log_p)`` of what ``predict`` returns.
    """
    stimuli = jnp.asarray(stimuli)
    n_trials = int(stimuli.shape[0])

    k_pred, k_bernoulli = jr.split(key)
    trial_keys = jr.split(k_pred, n_trials)

    log_p, _ = jax.vmap(lambda stim, k: self.predict(params, stim, model, key=k))(
        stimuli, trial_keys
    )
    p_correct = jnp.exp(log_p)  # (n_trials,)

    responses = jr.bernoulli(k_bernoulli, p_correct).astype(jnp.int32)
    return (responses, (p_correct,))

OddityTaskConfig

OddityTaskConfig(num_samples: int = 1000, bandwidth: float = 0.01, default_key_seed: int = 0)

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

bandwidth

bandwidth: float = 0.01

default_key_seed

default_key_seed: int = 0

num_samples

num_samples: int = 1000

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

basis_degree

basis_degree: int = 4

decay_rate

decay_rate: float = 0.4

extra_embedding_dims

extra_embedding_dims: int = 1

input_dim

input_dim: int = 2

variance_scale

variance_scale: float = 0.004

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
def log_prob(self, params: Params) -> jnp.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
    ----------
    params : dict
        Parameter dictionary

    Returns
    -------
    log_prob : float
        Log prior probability (up to normalizing constant)
    """

    if "W" in params:
        W = params["W"]
        variances = self._compute_W_prior_variances()

        # Gaussian log probability for each entry
        # log N(x | 0, σ^2) = -0.5 * (x^2/σ^2 + log(2πσ^2))
        # Up to constant: -0.5 * x^2/σ^2

        if self.input_dim == 2:
            # Each W[i,j,:,:] ~ Normal(0, variance[i,j] * I)
            return -0.5 * jnp.sum((W**2) / (variances[:, :, None, None] + 1e-10))
        elif self.input_dim == 3:
            return -0.5 * jnp.sum((W**2) / (variances[:, :, :, None, None] + 1e-10))
        elif self.input_dim == 1:
            return -0.5 * jnp.sum((W**2) / (variances[:, None, None] + 1e-10))

    raise ValueError("params must contain weights 'W'")

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
def param_scales(self) -> 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
    -------
    scales : dict
        {"W": array with the same shape as sample_params()["W"]}
    """
    std = jnp.sqrt(self._compute_W_prior_variances())
    embedding_dim = self.input_dim + self.extra_embedding_dims
    # std.shape is the basis grid, e.g. (degree+1, degree+1) for 2D;
    # append the two trailing W axes and broadcast over them.
    W_shape = (*std.shape, self.input_dim, embedding_dim)
    return {"W": jnp.broadcast_to(std[..., None, None], W_shape)}

sample

sample(n: int, key: Any) -> Params

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:

1
2
3
4
5
>>> import jax.random as jr
>>> from psyphy.model import Prior
>>> prior = Prior(input_dim=2, basis_degree=2)
>>> prior.sample(5, key=jr.PRNGKey(0))["W"].shape
(5, 3, 3, 2, 3)
Source code in src/psyphy/model/prior.py
def sample(self, n: int, key: Any) -> Params:
    """
    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
    ----------
    n : int
        Number of draws.
    key : jax.Array
        PRNG key, split n ways.

    Returns
    -------
    params : dict
        Parameter dictionary with a leading axis of n, so for 2D
        {"W": (n, degree+1, degree+1, input_dim, embedding_dim)}

    Notes
    -----
    Satisfies :class:`psyphy.posterior.ParameterSource`.

    Examples
    --------
    >>> import jax.random as jr
    >>> from psyphy.model import Prior
    >>> prior = Prior(input_dim=2, basis_degree=2)
    >>> prior.sample(5, key=jr.PRNGKey(0))["W"].shape
    (5, 3, 3, 2, 3)
    """
    return jax.vmap(self.sample_params)(jr.split(key, n))

sample_params

sample_params(key: Any) -> 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
def sample_params(self, key: Any) -> 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
    ----------
    key : JAX random key

    Returns
    -------
    params : dict
        Parameter dictionary
    """
    # Basis function coefficients W
    variances = self._compute_W_prior_variances()
    embedding_dim = self.input_dim + self.extra_embedding_dims

    if self.input_dim == 2:
        # Sample W ~ Normal(0, variances) for each matrix entry
        # Shape: (degree+1, degree+1, input_dim, embedding_dim)
        # Note: degree+1 to match number of basis functions [T_0, ..., T_degree]
        W = jnp.sqrt(variances)[:, :, None, None] * jr.normal(
            key,
            shape=(
                self.basis_degree + 1,
                self.basis_degree + 1,
                self.input_dim,
                embedding_dim,
            ),
        )
    elif self.input_dim == 3:
        # Shape: (degree+1, degree+1, degree+1, input_dim, embedding_dim)
        W = jnp.sqrt(variances)[:, :, :, None, None] * jr.normal(
            key,
            shape=(
                self.basis_degree + 1,
                self.basis_degree + 1,
                self.basis_degree + 1,
                self.input_dim,
                embedding_dim,
            ),
        )
    elif self.input_dim == 1:
        # Shape: (degree+1, input_dim, embedding_dim)
        W = jnp.sqrt(variances)[:, None, None] * jr.normal(
            key,
            shape=(self.basis_degree + 1, self.input_dim, embedding_dim),
        )
    else:
        raise NotImplementedError(
            f"Wishart process only supports 1D, 2D and 3D. Got input_dim={self.input_dim}"
        )

    return {"W": W}

StudentTNoise

StudentTNoise(df: float = 3.0, scale: float = 1.0)

Methods:

Name Description
log_prob
sample_standard

Sample from standard Student-t (df=self.df).

Attributes:

Name Type Description
df float
scale float

df

df: float = 3.0

scale

scale: float = 1.0

log_prob

log_prob(residual: float) -> float
Source code in src/psyphy/model/noise.py
def log_prob(self, residual: float) -> float:
    _ = residual
    return -0.5

sample_standard

sample_standard(key: Array, shape: tuple[int, ...]) -> Array

Sample from standard Student-t (df=self.df).

Source code in src/psyphy/model/noise.py
def sample_standard(self, key: jax.Array, shape: tuple[int, ...]) -> jax.Array:
    """Sample from standard Student-t (df=self.df)."""
    return jr.t(key, self.df, shape)

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

loglik(params: Any, data: ndarray, model: Any, key: Any = None) -> ndarray

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 .stimuli, .responses array attributes.

required
model Any

Model instance (provides covariance structure and model.noise).

required
key Array

PRNG key for stochastic tasks. When None, the task falls back to its config.default_key_seed.

None

Returns:

Type Description
(ndarray, shape())

Scalar sum of log-likelihoods over all trials.

Source code in src/psyphy/model/likelihood/base.py
@abstractmethod
def loglik(
    self,
    params: Any,
    data: jnp.ndarray,
    model: Any,
    key: Any = None,
) -> jnp.ndarray:
    """
    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
    ----------
    params : Any
        Model parameters.
    data : Any
        Object with ``.stimuli``, ``.responses`` array attributes.
    model : Any
        Model instance (provides covariance structure and ``model.noise``).
    key : jax.Array, optional
        PRNG key for stochastic tasks. When None, the task falls back to
        its ``config.default_key_seed``.

    Returns
    -------
    jnp.ndarray, shape ()
        Scalar sum of log-likelihoods over all trials.
    """
    ...

predict

predict(params: Any, stimuli: ndarray, model: Any, key: Any = None) -> tuple[ndarray, ...]

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 model.noise).

required
key Array

PRNG key for stochastic tasks. When None, the task falls back to its config.default_key_seed.

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
@abstractmethod
def predict(
    self,
    params: Any,
    stimuli: jnp.ndarray,
    model: Any,
    key: Any = None,
) -> tuple[jnp.ndarray, ...]:
    """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
    ----------
    params : Any
        Model parameters.
    stimuli : jnp.ndarray, shape (stim_dim, K)
        stimuli for a given trial (stimulus dimensions, number of stimuli)
    model : Any
        Model instance (provides covariance structure and ``model.noise``).
    key : jax.Array, optional
        PRNG key for stochastic tasks. When None, the task falls back to
        its ``config.default_key_seed``.

    Returns
    -------
    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)
    """
    ...

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
@abstractmethod
def simulate(
    self,
    params: Any,
    stimuli: jnp.ndarray,
    model: Any,
    key: Any,
) -> tuple[jnp.ndarray, tuple[jnp.ndarray, ...]]:
    """Simulate responses for a batch of trials.

    Parameters
    ----------
    params : Any
        Model parameters.
    stimuli : jnp.ndarray, shape (n_trials, k_stimuli, input_dim)
        Stimuli.
    model : Any
        Model instance.
    key : jax.Array
        PRNG key (required; split internally for prediction and sampling).

    Returns
    -------
    responses : jnp.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
    """
    ...

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 Model.__init__. Do not pass WPPM math knobs or task/likelihood knobs here.

{}

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
def __init__(
    self,
    prior: Prior,
    likelihood: TaskLikelihood,
    noise: Any | None = None,
    *,  # everything after here is keyword-only
    diag_term: float = 1e-6,
    **model_kwargs: Any,
) -> None:
    # Base-model configuration.
    #
    # `model_kwargs` is reserved for *future* base `Model.__init__` kwargs.
    # It should NOT be used for WPPM-specific math (e.g. alternative covariance
    # parameterizations) or for task-specific likelihood knobs.
    if model_kwargs:
        task_misuses = {"num_samples", "bandwidth", "online_config"}
        bad_task = sorted(task_misuses.intersection(model_kwargs.keys()))
        if bad_task:
            raise TypeError(
                "Do not pass task-specific kwargs via WPPM(..., **model_kwargs). "
                f"Move {bad_task} into the task config (e.g. OddityTaskConfig)."
            )
        prior_misuses = {
            "input_dim",
            "extra_dims",
            "extra_embedding_dims",
            "variance_scale",
            "decay_rate",
        }
        bad_prior = sorted(prior_misuses.intersection(model_kwargs.keys()))
        if bad_prior:
            raise TypeError(
                f"WPPM no longer takes {bad_prior}. Pass them to Prior; "
                "WPPM.input_dim, .embedding_dim, .variance_scale and "
                ".decay_rate read them from prior."
            )

    super().__init__(**model_kwargs)

    # --- core components ---
    self.prior = prior  # prior over parameter PyTree
    self.likelihood = likelihood  # task mapping and likelihood
    self.noise = noise  # noise model
    self.diag_term = float(diag_term)

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.

diag_term

diag_term = float(diag_term)

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.

likelihood

likelihood = likelihood

noise

noise = noise

prior

prior = prior

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, {"W": array of shape (degree+1, ..., input_dim, embedding_dim)}.

Source code in src/psyphy/model/wppm.py
def init_params(self, key: jax.Array) -> Params:
    """Sample initial parameters from the prior.

    Returns
    -------
    params : dict[str, jnp.ndarray], a parameter pytree
        For WPPM, ``{"W": array of shape (degree+1, ..., input_dim, embedding_dim)}``.
    """
    return self.prior.sample_params(key)

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
def local_covariance(self, params: Params, x: jnp.ndarray) -> jnp.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
    ----------
    params : dict
        Model parameters:
        - WPPM: {"W": (degree+1, ..., input_dim, embedding_dim)}
    x : jnp.ndarray, shape (input_dim,)
        Stimulus location

    Returns
    -------
    Σ : jnp.ndarray, shape (input_dim, input_dim)
        Covariance matrix in stimulus space.
    """
    # WPPM: spatially-varying covariance
    if "W" in params:
        U = self._compute_sqrt(params, x)  # (input_dim, embedding_dim)
        # Σ(x) = U(x) @ U(x)^T + diag_term * I
        # Result is (input_dim, input_dim)
        Sigma = U @ U.T + self.diag_term * jnp.eye(self.input_dim)
        return Sigma

    raise ValueError("params must contain 'W' (weights of WPPM)")

log_likelihood_from_data

log_likelihood_from_data(params: Params, data: Any, key: Array | None = None) -> ndarray

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 OddityTaskConfig.default_key_seed (useful for fixed evaluation and testing, but should not be used during gradient-based optimization).

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
def log_likelihood_from_data(
    self, params: Params, data: Any, key: jax.Array | None = None
) -> jnp.ndarray:
    """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
    ----------
    params : dict
        Model parameters.
    data : TrialData (or any object with refs/comparisons/responses arrays)
        Collected trial data.
    key : jax.Array | None, optional
        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 ``OddityTaskConfig.default_key_seed`` (useful for fixed evaluation
        and testing, but should not be used during gradient-based optimization).

    Returns
    -------
    loglik : jnp.ndarray, shape ()
        Scalar log-likelihood (task-only; add prior outside if needed).
    """
    return self.likelihood.loglik(params, data, self, key=key)

log_posterior_from_data

log_posterior_from_data(params: Params, data: Any, key: Array | None = None) -> ndarray

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 OddityTaskConfig.default_key_seed.

None

Returns:

Type Description
(ndarray, shape())

Scalar log posterior = loglik(params | data) + log_prior(params).

Source code in src/psyphy/model/wppm.py
def log_posterior_from_data(
    self, params: Params, data: Any, key: jax.Array | None = None
) -> jnp.ndarray:
    """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
    ----------
    params : dict
        Model parameters.
    data : TrialData
        Collected trial data.
    key : jax.Array | None, optional
        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 ``OddityTaskConfig.default_key_seed``.

    Returns
    -------
    jnp.ndarray, shape ()
        Scalar log posterior = loglik(params | data) + log_prior(params).
    """
    return self.log_likelihood_from_data(
        params, data, key=key
    ) + self.prior.log_prob(params)

predict_prob

predict_prob(params: Params, stimulus: Stimulus, **likelihood_kwargs: Any) -> ndarray

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
def predict_prob(
    self, params: Params, stimulus: Stimulus, **likelihood_kwargs: Any
) -> jnp.ndarray:
    """
    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
    ----------
    params : dict
    stimulus : tuple[jnp.ndarray, jnp.ndarray], each shape (input_dim,)
         (reference, comparison) pair in model space.

    Returns
    -------
    p_correct : jnp.ndarray, shape ()
        Scalar probability of a correct response.
    """
    # Strict task-owned configuration:
    # - MC control knobs (e.g. num_samples/bandwidth) live in the task config.
    # - WPPM.predict_prob therefore does not accept task-specific kwargs.
    if likelihood_kwargs:
        raise TypeError(
            f"WPPM.predict_prob got unexpected kwargs: {likelihood_kwargs}. "
            "Configure likelihood behavior via the TaskLikelihood object itself."
        )

    if not isinstance(self.likelihood, BernoulliTaskLikelihood):
        raise NotImplementedError(
            "WPPMP currently only supports "
            "BernoulliTaskLikelihood. Gaussian support requires "
            "updating to handle (mu, sigma) returns."
        )

    stimuli = jnp.stack(stimulus, axis=0)
    log_p, _ = self.likelihood.predict(params, stimuli, self)
    return jnp.exp(log_p)

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:

>>> import jax.numpy as jnp
>>> import jax.random as jr
>>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceField
>>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
>>> # from the prior
>>> field = WPPMCovarianceField.from_prior(model, jr.PRNGKey(0))
>>> field(jnp.array([0.5, 0.3])).shape
(2, 2)
>>> # from a MAP fit
>>> from psyphy.inference import MAPOptimizer
>>> map_posterior = MAPOptimizer().fit(model, data)
>>> field = WPPMCovarianceField.from_posterior(map_posterior)
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 model is a dict or params is not one, as when the two arguments are swapped.

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
def __init__(self, model, params: dict):
    """
    Construct covariance field from model and parameters.

    Parameters
    ----------
    model : WPPM
        Model providing evaluation logic
    params : dict
        Parameter dictionary

    Raises
    ------
    TypeError
        If ``model`` is a dict or ``params`` is not one, as when the two
        arguments are swapped.
    """
    if isinstance(model, Mapping) or not isinstance(params, Mapping):
        raise TypeError(
            "WPPMCovarianceField takes the model first: "
            "WPPMCovarianceField(model, params)"
        )
    self._model = model
    self._params = dict(params)
    # Pre-compile JIT batch evaluation path for performance
    self._eval_batch_jitted = jax.jit(self._eval_batch_impl)

model

model

The model that evaluates the field. Fixed when the object is built.

params

params: dict

A shallow copy of the parameter dict. Fixed when the object is built.

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:

1
2
3
4
5
6
7
8
>>> import jax.numpy as jnp
>>> import jax.random as jr
>>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceField
>>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
>>> params = model.init_params(jr.PRNGKey(0))  # {"W": (3, 3, 2, 3)}
>>> field = WPPMCovarianceField.from_params(model, params)
>>> field(jnp.array([0.5, 0.5])).shape
(2, 2)
Source code in src/psyphy/model/covariance_field.py
@classmethod
def from_params(cls, model, params: dict) -> WPPMCovarianceField:
    """
    Create field from arbitrary parameters.

    Useful for:
    - Custom initialization
    - Posterior samples
    - Intermediate optimization checkpoints
    - Testing

    Parameters
    ----------
    model : WPPM
        Model providing evaluation logic
    params : dict
        Parameter dictionary

    Returns
    -------
    WPPMCovarianceField

    Examples
    --------
    >>> import jax.numpy as jnp
    >>> import jax.random as jr
    >>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceField
    >>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
    >>> params = model.init_params(jr.PRNGKey(0))  # {"W": (3, 3, 2, 3)}
    >>> field = WPPMCovarianceField.from_params(model, params)
    >>> field(jnp.array([0.5, 0.5])).shape
    (2, 2)
    """
    return cls(model, params)

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: params is θ_MAP, so this is Σ(θ_MAP).
  • Sample-based posteriors (e.g. MCMCPosterior): params is the mean parameter E[W], and Σ(E[W]) is NOT the posterior mean of Σ. It is systematically too small and can collapse toward λI (see WPPMCovarianceFieldSamples for why). We raise a UserWarning when the posterior stores more than 1 sample. Use WPPMCovarianceFieldSamples(posterior).mean(x) for E[Σ], or posterior.sample(n, key=...) for individual samples.

Examples:

1
2
3
4
5
6
7
8
9
>>> import jax.numpy as jnp
>>> import jax.random as jr
>>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceField
>>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
>>> from psyphy.inference import MAPOptimizer
>>> map_posterior = MAPOptimizer().fit(model, data)
>>> field = WPPMCovarianceField.from_posterior(map_posterior)
>>> field(jnp.array([0.5, 0.5])).shape
(2, 2)
Source code in src/psyphy/model/covariance_field.py
@classmethod
def from_posterior(cls, posterior) -> WPPMCovarianceField:
    """
    Create covariance field from fitted posterior.

    Parameters
    ----------
    posterior : ParameterPosterior
        Fitted posterior (e.g., from model.fit())

    Returns
    -------
    WPPMCovarianceField
        Field representing posterior estimate of Σ(x)

    Notes
    -----
    Builds the field from ``posterior.params``, i.e. a single parameter set.

    - MAP posteriors: ``params`` is θ_MAP, so this is Σ(θ_MAP).
    - Sample-based posteriors (e.g. ``MCMCPosterior``): ``params`` is the
      mean parameter E[W], and Σ(E[W]) is NOT the posterior mean of Σ. It
      is systematically too small and can collapse toward λI (see
      ``WPPMCovarianceFieldSamples`` for why). We raise a ``UserWarning``
      when the posterior stores more than 1 sample. Use
      ``WPPMCovarianceFieldSamples(posterior).mean(x)``
      for E[Σ], or ``posterior.sample(n, key=...)`` for individual samples.

    Examples
    --------
    >>> import jax.numpy as jnp
    >>> import jax.random as jr
    >>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceField
    >>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
    >>> from psyphy.inference import MAPOptimizer
    >>> map_posterior = MAPOptimizer().fit(model, data)  # doctest: +SKIP
    >>> field = WPPMCovarianceField.from_posterior(map_posterior)  # doctest: +SKIP
    >>> field(jnp.array([0.5, 0.5])).shape  # doctest: +SKIP
    (2, 2)
    """
    # stored sample count, by duck typing as in _draws_from. A MAPPosterior
    # stores 1, and the mean of 1 sample is that sample
    n_chains = getattr(posterior, "n_chains", None)
    n_draws = getattr(posterior, "n_draws", None)
    n_stored = int(n_chains or 1) * int(n_draws or 1)
    if n_draws is not None and n_stored > 1:
        warnings.warn(
            f"from_posterior() on a {type(posterior).__name__} builds Σ from the "
            "mean parameter E[W]. Σ is nonlinear in W, so Σ(E[W]) is not the "
            "posterior mean of Σ and comes out systematically too small. Use "
            "WPPMCovarianceFieldSamples(posterior).mean(x) "
            "for E[Σ].",
            UserWarning,
            stacklevel=2,
        )
    return cls(posterior.model, posterior.params)

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:

1
2
3
4
5
6
7
>>> import jax.numpy as jnp
>>> import jax.random as jr
>>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceField
>>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
>>> field = WPPMCovarianceField.from_prior(model, jr.PRNGKey(42))
>>> field(jnp.array([0.5, 0.5])).shape
(2, 2)
Source code in src/psyphy/model/covariance_field.py
@classmethod
def from_prior(cls, model, key: jax.Array) -> WPPMCovarianceField:
    """
    Sample a covariance field from the prior.

    Parameters
    ----------
    model : WPPM
        Model defining prior distribution
    key : jax.Array
        PRNG key for sampling

    Returns
    -------
    WPPMCovarianceField
        Field sampled from p(Σ(x))

    Examples
    --------
    >>> import jax.numpy as jnp
    >>> import jax.random as jr
    >>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceField
    >>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
    >>> field = WPPMCovarianceField.from_prior(model, jr.PRNGKey(42))
    >>> field(jnp.array([0.5, 0.5])).shape
    (2, 2)
    """
    params = model.init_params(key)
    return cls(model, params)

sqrt_cov

sqrt_cov(x: ndarray) -> ndarray

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:

>>> import jax.numpy as jnp
>>> import jax.random as jr
>>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceField
>>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
>>> field = WPPMCovarianceField.from_prior(model, jr.PRNGKey(0))
>>> x = jnp.array([0.5, 0.3])
>>> U = field.sqrt_cov(x)
>>> U.shape  # (input_dim, embedding_dim) for input_dim=2, extra_embedding_dims=1
(2, 3)
>>> # Σ = U @ U^T + λI
>>> bool(jnp.allclose(U @ U.T + model.diag_term * jnp.eye(2), field(x)))
True
Source code in src/psyphy/model/covariance_field.py
def sqrt_cov(self, x: jnp.ndarray) -> jnp.ndarray:
    """
    Evaluate U(x) such that Σ(x) = U(x) @ U(x)^T + diag_term*I.

    Parameters
    ----------
    x : jnp.ndarray, shape (input_dim,)
        Stimulus location

    Returns
    -------
    jnp.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
    --------
    >>> import jax.numpy as jnp
    >>> import jax.random as jr
    >>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceField
    >>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
    >>> field = WPPMCovarianceField.from_prior(model, jr.PRNGKey(0))
    >>> x = jnp.array([0.5, 0.3])
    >>> U = field.sqrt_cov(x)
    >>> U.shape  # (input_dim, embedding_dim) for input_dim=2, extra_embedding_dims=1
    (2, 3)
    >>> # Σ = U @ U^T + λI
    >>> bool(jnp.allclose(U @ U.T + model.diag_term * jnp.eye(2), field(x)))
    True
    """
    if "W" not in self.params:
        raise ValueError(
            "params has no 'W', so sqrt_cov cannot evaluate U(x). "
            "Pass params with a 'W' entry, e.g. from WPPM.init_params."
        )
    return self.model._compute_sqrt(self.params, x)

sqrt_cov_batch

sqrt_cov_batch(X: ndarray) -> ndarray

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:

1
2
3
4
5
6
7
8
>>> import jax.numpy as jnp
>>> import jax.random as jr
>>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceField
>>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
>>> field = WPPMCovarianceField.from_prior(model, jr.PRNGKey(0))
>>> X_grid = jnp.array([[0.1, 0.2], [0.5, 0.5], [0.9, 0.8]])  # (3, 2)
>>> field.sqrt_cov_batch(X_grid).shape  # (n_points, input_dim, embedding_dim)
(3, 2, 3)
Source code in src/psyphy/model/covariance_field.py
def sqrt_cov_batch(self, X: jnp.ndarray) -> jnp.ndarray:
    """
    Vectorized evaluation of U(x) at multiple locations.

    Parameters
    ----------
    X : jnp.ndarray, shape (n_points, input_dim)
        Multiple stimulus locations

    Returns
    -------
    jnp.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
    --------
    >>> import jax.numpy as jnp
    >>> import jax.random as jr
    >>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceField
    >>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
    >>> field = WPPMCovarianceField.from_prior(model, jr.PRNGKey(0))
    >>> X_grid = jnp.array([[0.1, 0.2], [0.5, 0.5], [0.9, 0.8]])  # (3, 2)
    >>> field.sqrt_cov_batch(X_grid).shape  # (n_points, input_dim, embedding_dim)
    (3, 2, 3)
    """
    if "W" not in self.params:
        raise ValueError(
            "params has no 'W', so sqrt_cov_batch cannot evaluate U(x)."
        )
    return jax.vmap(self.sqrt_cov)(X)

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 MCMCPosterior. Its model evaluates the samples. For samples from the prior, use :meth:from_prior.

required
n_samples int

How many samples to take. Omit it for every stored sample, which needs the posterior to expose samples, n_chains and n_draws. MCMCPosterior and MAPPosterior both do, and a MAPPosterior stores 1 sample. For 1 parameter set with no posterior, use :meth:from_params.

None
key Array

PRNG key for the subsample. Required when n_samples is given, and unread otherwise, since every stored sample is taken in order.

None

Raises:

Type Description
ValueError

If n_samples is None and the posterior stores no fixed set of samples, or if n_samples is given without a key.

Attributes:

Name Type Description
model WPPM

The model the draws belong to.

samples dict

The draws, leading axis n_samples. Public, so a per-draw quantity psyphy does not ship can be had with jax.vmap over it.

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:

>>> import jax.numpy as jnp
>>> import jax.random as jr
>>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceFieldSamples
>>> from psyphy.posterior import MCMCPosterior
>>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
>>> keys = jr.split(jr.PRNGKey(1), 100)
>>> W = jnp.stack([model.init_params(k)["W"] for k in keys])  # (100, 3, 3, 2, 3)
>>> posterior = MCMCPosterior(model, {"W": W.reshape(2, 50, *W.shape[1:])})
>>> WPPMCovarianceFieldSamples(posterior).n_samples
100
>>> fields = WPPMCovarianceFieldSamples(posterior, n_samples=50, key=jr.PRNGKey(0))
>>> ref_points = jnp.array([[-0.5, -0.5], [0.5, 0.5]])  # (n_points=2, d=2)
>>> fields(ref_points).shape  # (n_samples, n_points, d, d)
(50, 2, 2, 2)
>>> fields.mean(ref_points).shape  # (n_points, d, d)
(2, 2, 2)
>>> fields.credible_band(ref_points).lower.shape  # (n_points, n_directions)
(2, 181)

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:\mathbb{E}[\Sigma(x)].

sqrt_cov

Evaluate the square root :math:U(x) for every draw.

Source code in src/psyphy/model/covariance_field.py
def __init__(self, posterior, *, n_samples: int | None = None, key=None):
    samples, _ = _draws_from(posterior, n_samples, key)
    leaves = jax.tree.leaves(samples)
    if not leaves:
        raise ValueError(
            f"{type(posterior).__name__} returned no parameter arrays. "
            'Its samples need a leading axis, for example {"W": (n_samples, *W_shape)}.'
        )
    self._model = posterior.model
    self._samples = samples
    self._n_samples = int(leaves[0].shape[0])
    # Pre-compile the batch paths, as in WPPMCovarianceField
    self._eval_batch_jitted = jax.jit(self._eval_batch_impl)
    self._mean_batch_jitted = jax.jit(self._mean_batch_impl)

model

model

The model the draws belong to. Fixed when the object is built.

n_samples

n_samples: int

Draws held. Fixed when the object is built.

samples

samples: dict

A shallow copy of the draws dict. Fixed when the object is built.

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 lower and upper, in each direction separately. 0.89 is ArviZ's default too, so a band and az.summary agree. Pass a sequence for nested bands, and each level gets its own interval stacked on a leading axis.

0.89
ci_kind ('eti', 'hdi')

Which interval of that mass to take, since many of them hold it. "eti" is equal-tailed: it cuts the same probability off each end, so lower and upper are quantiles. "hdi" is highest-density: it takes the narrowest interval holding the mass. The two differ when the draws are skewed. Radii usually are, because a radius cannot go below zero.

"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:from_params. For a band, build it from an MCMC posterior. Also if ci_kind is unknown, or if any ci_prob is outside (0, 1).

Examples:

>>> import jax.numpy as jnp
>>> import jax.random as jr
>>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceFieldSamples
>>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
>>> ref_points = jnp.array([[-0.5, -0.5], [0.5, 0.5]])  # (n_points, 2)
>>> fields = WPPMCovarianceFieldSamples.from_prior(
...     model, n_samples=50, key=jr.PRNGKey(1)
... )
>>> fields.credible_band(ref_points).lower.shape  # (n_points, n_directions)
(2, 181)
>>> nested = fields.credible_band(ref_points, ci_prob=[0.5, 0.8, 0.95])
>>> nested.upper.shape  # (n_levels, n_points, n_directions)
(3, 2, 181)
Source code in src/psyphy/model/covariance_field.py
def credible_band(
    self,
    points: jnp.ndarray,
    *,
    n_directions: int = 181,
    ci_prob: float | Sequence[float] = 0.89,
    ci_kind: str = "eti",
) -> CredibleBand:
    r"""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
    ----------
    points : jnp.ndarray, shape (n_points, 2)
        Stimulus locations, usually the reference points we report.
    n_directions : int, default=181
        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.
    ci_prob : float or sequence of float, default=0.89
        How much posterior mass the interval holds. At 0.89, 89% of the
        draws of the radius lie between ``lower`` and ``upper``, in each
        direction separately. 0.89 is ArviZ's default too, so a band and
        ``az.summary`` agree. Pass a sequence for nested bands, and each
        level gets its own interval stacked on a leading axis.
    ci_kind : {"eti", "hdi"}, default="eti"
        Which interval of that mass to take, since many of them hold it.
        ``"eti"`` is equal-tailed: it cuts the same probability off each
        end, so ``lower`` and ``upper`` are quantiles. ``"hdi"`` is
        highest-density: it takes the narrowest interval holding the mass.
        The two differ when the draws are skewed. Radii usually are,
        because a radius cannot go below zero.

    Returns
    -------
    CredibleBand

    Raises
    ------
    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:`from_params`. For a band, build it from an MCMC posterior.
        Also if ``ci_kind`` is unknown, or if any ``ci_prob`` is outside
        (0, 1).

    Examples
    --------
    >>> import jax.numpy as jnp
    >>> import jax.random as jr
    >>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceFieldSamples
    >>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
    >>> ref_points = jnp.array([[-0.5, -0.5], [0.5, 0.5]])  # (n_points, 2)
    >>> fields = WPPMCovarianceFieldSamples.from_prior(
    ...     model, n_samples=50, key=jr.PRNGKey(1)
    ... )
    >>> fields.credible_band(ref_points).lower.shape  # (n_points, n_directions)
    (2, 181)
    >>> nested = fields.credible_band(ref_points, ci_prob=[0.5, 0.8, 0.95])
    >>> nested.upper.shape  # (n_levels, n_points, n_directions)
    (3, 2, 181)
    """
    if self.n_samples == 1:
        raise ValueError(
            "1 parameter set has no spread, so it has no credible band. "
            "Build the field from an MCMC posterior: "
            "WPPMCovarianceFieldSamples(mcmc_posterior)."
        )
    if ci_kind not in _CI_KINDS:
        raise ValueError(
            f"ci_kind must be one of {sorted(_CI_KINDS)}, got {ci_kind!r}."
        )

    if isinstance(ci_prob, (int, float)):
        scalar_level = True
        probs: tuple[float, ...] = (float(ci_prob),)
    else:
        scalar_level = False
        probs = tuple(float(p) for p in ci_prob)
    if not probs:
        raise ValueError("ci_prob must hold at least one probability.")
    for p in probs:
        if not 0.0 < p < 1.0:
            raise ValueError(f"ci_prob must lie in (0, 1), got {p}.")

    if self.model.input_dim != 2:
        raise NotImplementedError(
            "credible_band supports 2-D stimulus spaces only, got "
            f"input_dim={self.model.input_dim}. contour_radii is "
            "d-dimensional, so call it with explicit directions instead."
        )

    # Closed grid, so the last angle repeats the first. n_directions is a magic
    # default (181 -> one direction every two degrees); nothing depends on it.
    phi = jnp.linspace(0.0, 2 * jnp.pi, n_directions)  # radians
    directions = jnp.stack([jnp.cos(phi), jnp.sin(phi)], axis=-1)  # (n_dir, 2)

    self._check_input_dim(points)
    # (n_samples, n_points, 2, 2)
    covs = self._eval_batch_impl(points)
    # (n_samples, n_points, n_directions)
    radii = jax.vmap(lambda c: contour_radii(c, directions))(covs)

    reduce = _CI_KINDS[ci_kind]
    bounds = [reduce(radii, p) for p in probs]
    lower = jnp.stack([lo for lo, _ in bounds])  # (n_levels, n_pts, n_dir)
    upper = jnp.stack([hi for _, hi in bounds])
    # One median whatever ci_prob holds, repeated per level so lower,
    # median and upper share a shape.
    median = jnp.median(radii, axis=0)  # (n_points, n_directions)
    median = jnp.broadcast_to(median, lower.shape)  # (n_levels, n_pts, n_dir)

    return CredibleBand(
        points=points,
        directions=directions,
        lower=lower[0] if scalar_level else lower,
        median=median[0] if scalar_level else median,
        upper=upper[0] if scalar_level else upper,
        ci_prob=probs[0] if scalar_level else probs,
        ci_kind=ci_kind,
    )

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: {"W": (degree+1, degree+1, d, m)}.

required

Returns:

Type Description
WPPMCovarianceFieldSamples

With n_samples == 1.

Raises:

Type Description
TypeError

If model is a dict or params is not one, as when the two arguments are swapped.

Examples:

>>> import jax.numpy as jnp
>>> import jax.random as jr
>>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceFieldSamples
>>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
>>> params = model.init_params(jr.PRNGKey(0))  # {"W": (3, 3, 2, 3)}
>>> fields = WPPMCovarianceFieldSamples.from_params(model, params)
>>> fields.n_samples
1
>>> fields(jnp.array([0.5, 0.5])).shape  # (n_samples, d, d)
(1, 2, 2)
Source code in src/psyphy/model/covariance_field.py
@classmethod
def from_params(cls, 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
    ----------
    model : WPPM
        Model that evaluates the parameters.
    params : dict
        1 parameter set, with no leading sample axis. For WPPM:
        ``{"W": (degree+1, degree+1, d, m)}``.

    Returns
    -------
    WPPMCovarianceFieldSamples
        With ``n_samples == 1``.

    Raises
    ------
    TypeError
        If ``model`` is a dict or ``params`` is not one, as when the two
        arguments are swapped.

    Examples
    --------
    >>> import jax.numpy as jnp
    >>> import jax.random as jr
    >>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceFieldSamples
    >>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
    >>> params = model.init_params(jr.PRNGKey(0))  # {"W": (3, 3, 2, 3)}
    >>> fields = WPPMCovarianceFieldSamples.from_params(model, params)
    >>> fields.n_samples
    1
    >>> fields(jnp.array([0.5, 0.5])).shape  # (n_samples, d, d)
    (1, 2, 2)
    """
    if isinstance(model, Mapping) or not isinstance(params, Mapping):
        raise TypeError(
            "from_params takes the model first: "
            "WPPMCovarianceFieldSamples.from_params(model, params)"
        )
    return cls(_OneSetSource(model, params))

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:

1
2
3
4
5
6
7
8
>>> import jax.random as jr
>>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceFieldSamples
>>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
>>> fields = WPPMCovarianceFieldSamples.from_prior(
...     model, n_samples=8, key=jr.PRNGKey(0)
... )
>>> fields.samples["W"].shape  # (n_samples, degree+1, degree+1, d, m)
(8, 3, 3, 2, 3)
Source code in src/psyphy/model/covariance_field.py
@classmethod
def from_prior(cls, 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
    ----------
    model : WPPM
        Model whose prior we draw from.
    n_samples : int
        Draws to take.
    key : jax.Array
        PRNG key, split n_samples ways.

    Returns
    -------
    WPPMCovarianceFieldSamples

    Examples
    --------
    >>> import jax.random as jr
    >>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceFieldSamples
    >>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
    >>> fields = WPPMCovarianceFieldSamples.from_prior(
    ...     model, n_samples=8, key=jr.PRNGKey(0)
    ... )
    >>> fields.samples["W"].shape  # (n_samples, degree+1, degree+1, d, m)
    (8, 3, 3, 2, 3)
    """
    return cls(_PriorSource(model), n_samples=n_samples, key=key)

mean

mean(x: ndarray) -> ndarray

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:

1
2
3
4
5
6
7
8
9
>>> import jax.numpy as jnp
>>> import jax.random as jr
>>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceFieldSamples
>>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
>>> fields = WPPMCovarianceFieldSamples.from_prior(
...     model, n_samples=16, key=jr.PRNGKey(0)
... )
>>> fields.mean(jnp.array([0.5, 0.3])).shape
(2, 2)
Source code in src/psyphy/model/covariance_field.py
def mean(self, x: jnp.ndarray) -> jnp.ndarray:
    r"""
    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
    ----------
    x : jnp.ndarray, shape (d,) or (..., d)
        One stimulus location, or any batch of them.

    Returns
    -------
    Sigma : jnp.ndarray, shape (d, d) or (..., d, d)
        The mean matrix per location, with no draws axis.

    Examples
    --------
    >>> import jax.numpy as jnp
    >>> import jax.random as jr
    >>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceFieldSamples
    >>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
    >>> fields = WPPMCovarianceFieldSamples.from_prior(
    ...     model, n_samples=16, key=jr.PRNGKey(0)
    ... )
    >>> fields.mean(jnp.array([0.5, 0.3])).shape
    (2, 2)
    """
    self._check_input_dim(x)
    if x.ndim == 1:
        return self._mean_single(x)
    return self._mean_batch_jitted(x)

sqrt_cov

sqrt_cov(x: ndarray) -> ndarray

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

required

Returns:

Name Type Description
U (ndarray, shape(n_samples, d, m) or (n_samples, ..., d, m))

One matrix per draw per location, m the embedding dimension. :math:U U^\top + \lambda I is the matching matrix of fields(x), with :math:\lambda the model's diag_term.

Examples:

1
2
3
4
5
6
7
8
9
>>> import jax.numpy as jnp
>>> import jax.random as jr
>>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceFieldSamples
>>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
>>> fields = WPPMCovarianceFieldSamples.from_prior(
...     model, n_samples=8, key=jr.PRNGKey(0)
... )
>>> fields.sqrt_cov(jnp.array([0.5, 0.3])).shape  # (n_samples, d, m)
(8, 2, 3)
Source code in src/psyphy/model/covariance_field.py
def sqrt_cov(self, x: jnp.ndarray) -> jnp.ndarray:
    r"""
    Evaluate the square root :math:`U(x)` for every draw.

    Parameters
    ----------
    x : jnp.ndarray, shape (d,) or (..., d)
        One stimulus location, or any batch of them. The last axis must
        have size ``input_dim``.

    Returns
    -------
    U : jnp.ndarray, shape (n_samples, d, m) or (n_samples, ..., d, m)
        One matrix per draw per location, ``m`` the embedding dimension.
        :math:`U U^\top + \lambda I` is the matching matrix of ``fields(x)``,
        with :math:`\lambda` the model's ``diag_term``.

    Examples
    --------
    >>> import jax.numpy as jnp
    >>> import jax.random as jr
    >>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceFieldSamples
    >>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
    >>> fields = WPPMCovarianceFieldSamples.from_prior(
    ...     model, n_samples=8, key=jr.PRNGKey(0)
    ... )
    >>> fields.sqrt_cov(jnp.array([0.5, 0.3])).shape  # (n_samples, d, m)
    (8, 2, 3)
    """
    self._check_input_dim(x)
    return jax.vmap(lambda params: _sqrt(self.model, params, x))(self.samples)

contour_radii

contour_radii(covs: ndarray, directions: ndarray) -> ndarray

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
def contour_radii(covs: jnp.ndarray, directions: jnp.ndarray) -> jnp.ndarray:
    r"""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
    ----------
    covs : jnp.ndarray, shape (..., d, d)
        One or more covariance matrices. Leading axes are broadcast over.
    directions : jnp.ndarray, shape (n_directions, d)
        Unit directions. We do not normalize them, and a non-unit direction
        rescales the radius.

    Returns
    -------
    jnp.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.
    """
    prec = jnp.linalg.inv(covs)
    quad = jnp.einsum("ki,...ij,kj->...k", directions, prec, directions)
    return 1.0 / jnp.sqrt(quad)

covariance_to_arviz

covariance_to_arviz(posterior, points)

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 Σ_ii
  • corr_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 to_arviz() (chain structure is needed for R-hat; sample() would pool the chains).

required
points (array_like, shape(n_points, input_dim))

Stimulus locations at which to evaluate Σ.

required

Returns:

Type Description
DataTree

posterior group with variable Sigma of dims (chain, draw, point, quantity), coordinates quantity (names as above) and location_0 ... location_{d-1} (the evaluation points, one coordinate per stimulus axis, along point). The posterior's sample_stats group (divergences, energy, ...) is carried over.

Raises:

Type Description
TypeError

If the posterior has no to_arviz() (e.g. a MAP posterior: no chains, nothing to diagnose).

ValueError

If points is not of shape (n_points, input_dim).

ImportError

If ArviZ is not installed (pip install 'psyphy[diagnostics]').

Examples:

>>> import jax.numpy as jnp
>>> import jax.random as jr
>>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceField
>>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
>>> from psyphy.posterior import MCMCPosterior
>>> # stand-in for NUTSSampler().fit(model, data): 2 chains of 50 prior samples
>>> keys = jr.split(jr.PRNGKey(1), 100)
>>> W = jnp.stack([model.init_params(k)["W"] for k in keys])  # (100, 3, 3, 2, 3)
>>> nuts_posterior = MCMCPosterior(model, {"W": W.reshape(2, 50, *W.shape[1:])})
>>> ref_points = jnp.array([[-0.5, -0.5], [0.5, 0.5]])  # (n_points, 2)
>>> import arviz as az
>>> from psyphy.model import covariance_to_arviz
>>> dt = covariance_to_arviz(nuts_posterior, ref_points)
>>> worst = az.rhat(dt)["Sigma"].max()  # worst point and quantity
>>> az.plot_trace(dt, var_names=["Sigma"], coords={"point": 0})
Source code in src/psyphy/model/covariance_field.py
def covariance_to_arviz(posterior, points):
    r"""
    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 Σ_ii
    - ``corr_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
    ----------
    posterior : MCMCPosterior
        A sample-based posterior with ``to_arviz()`` (chain structure is
        needed for R-hat; ``sample()`` would pool the chains).
    points : array_like, shape (n_points, input_dim)
        Stimulus locations at which to evaluate Σ.

    Returns
    -------
    xarray.DataTree
        ``posterior`` group with variable ``Sigma`` of dims
        ``(chain, draw, point, quantity)``, coordinates ``quantity`` (names as
        above) and ``location_0 ... location_{d-1}`` (the evaluation points, one
        coordinate per stimulus axis, along ``point``). The posterior's
        ``sample_stats`` group (divergences, energy, ...) is carried over.

    Raises
    ------
    TypeError
        If the posterior has no ``to_arviz()`` (e.g. a MAP posterior: no
        chains, nothing to diagnose).
    ValueError
        If ``points`` is not of shape ``(n_points, input_dim)``.
    ImportError
        If ArviZ is not installed (``pip install 'psyphy[diagnostics]'``).

    Examples
    --------
    >>> import jax.numpy as jnp
    >>> import jax.random as jr
    >>> from psyphy.model import WPPM, OddityTask, Prior, WPPMCovarianceField
    >>> model = WPPM(Prior(input_dim=2, basis_degree=2), OddityTask())
    >>> from psyphy.posterior import MCMCPosterior
    >>> # stand-in for NUTSSampler().fit(model, data): 2 chains of 50 prior samples
    >>> keys = jr.split(jr.PRNGKey(1), 100)
    >>> W = jnp.stack([model.init_params(k)["W"] for k in keys])  # (100, 3, 3, 2, 3)
    >>> nuts_posterior = MCMCPosterior(model, {"W": W.reshape(2, 50, *W.shape[1:])})
    >>> ref_points = jnp.array([[-0.5, -0.5], [0.5, 0.5]])  # (n_points, 2)
    >>> import arviz as az
    >>> from psyphy.model import covariance_to_arviz
    >>> dt = covariance_to_arviz(nuts_posterior, ref_points)
    >>> worst = az.rhat(dt)["Sigma"].max()  # worst point and quantity
    >>> az.plot_trace(dt, var_names=["Sigma"], coords={"point": 0})  # doctest: +SKIP
    """
    to_arviz = getattr(posterior, "to_arviz", None)
    if to_arviz is None:
        raise TypeError(
            f"{type(posterior).__name__} has no to_arviz(); convergence diagnostics "
            "need a sample-based posterior with chains (e.g. MCMCPosterior)."
        )

    model = posterior.model
    d = model.input_dim
    points = jnp.asarray(points)
    if points.ndim != 2:
        raise ValueError(
            f"points must have shape (n_points, input_dim), got {points.shape}. "
            "For a single location use points[None, :]."
        )
    if points.shape[-1] != d:
        raise ValueError(
            f"Last axis of points must be input_dim={d}, got {points.shape[-1]}"
        )

    # Chain-structured samples via the public API (raises ImportError without
    # ArviZ). Every posterior variable keeps its leading (chain, draw) axes,
    # e.g. {"W": (C, S, *W_shape)}.
    idata = to_arviz()
    import arviz as az
    import numpy as np

    params = {
        name: jnp.asarray(var.values)
        for name, var in idata["posterior"].data_vars.items()
    }

    def sigma_one_draw(p):
        # Σ at every point for ONE draw: (n_points, d, d)
        return jax.vmap(lambda x: model.local_covariance(p, x))(points)

    # vmap over samples, then chains: (C, S, n_points, d, d)
    Sig = jax.vmap(jax.vmap(sigma_one_draw))(params)

    # Identifiable summary of each Σ: log variances, then correlations (i < j).
    variances = jnp.diagonal(Sig, axis1=-2, axis2=-1)  # (C, S, P, d)
    columns = [jnp.log(variances[..., i]) for i in range(d)]
    names = [f"log_var_{i}" for i in range(d)]
    for i in range(d):
        for j in range(i + 1, d):
            columns.append(
                Sig[..., i, j] / jnp.sqrt(variances[..., i] * variances[..., j])
            )
            names.append(f"corr_{i}_{j}")
    feats = np.asarray(jnp.stack(columns, axis=-1))  # (C, S, P, n_quantities)

    data = {"posterior": {"Sigma": feats}}
    if "sample_stats" in idata.children:
        data["sample_stats"] = {
            k: v.values for k, v in idata["sample_stats"].data_vars.items()
        }
    dt = az.from_dict(
        data, dims={"Sigma": ["point", "quantity"]}, coords={"quantity": names}
    )
    # Record where Σ was evaluated, one 1-D coordinate per stimulus axis along
    # `point`. (A single (point, axis) coordinate would not attach to Sigma,
    # which has no `axis` dimension.)
    pts = np.asarray(points)
    dt["posterior"] = (
        dt["posterior"]
        .to_dataset()
        .assign_coords({f"location_{i}": ("point", pts[:, i]) for i in range(d)})
    )
    return dt

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

Params

Params = dict[str, jnp.ndarray]

Stimulus

Stimulus = tuple[jnp.ndarray, jnp.ndarray]

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 Model.__init__. Do not pass WPPM math knobs or task/likelihood knobs here.

{}

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
def __init__(
    self,
    prior: Prior,
    likelihood: TaskLikelihood,
    noise: Any | None = None,
    *,  # everything after here is keyword-only
    diag_term: float = 1e-6,
    **model_kwargs: Any,
) -> None:
    # Base-model configuration.
    #
    # `model_kwargs` is reserved for *future* base `Model.__init__` kwargs.
    # It should NOT be used for WPPM-specific math (e.g. alternative covariance
    # parameterizations) or for task-specific likelihood knobs.
    if model_kwargs:
        task_misuses = {"num_samples", "bandwidth", "online_config"}
        bad_task = sorted(task_misuses.intersection(model_kwargs.keys()))
        if bad_task:
            raise TypeError(
                "Do not pass task-specific kwargs via WPPM(..., **model_kwargs). "
                f"Move {bad_task} into the task config (e.g. OddityTaskConfig)."
            )
        prior_misuses = {
            "input_dim",
            "extra_dims",
            "extra_embedding_dims",
            "variance_scale",
            "decay_rate",
        }
        bad_prior = sorted(prior_misuses.intersection(model_kwargs.keys()))
        if bad_prior:
            raise TypeError(
                f"WPPM no longer takes {bad_prior}. Pass them to Prior; "
                "WPPM.input_dim, .embedding_dim, .variance_scale and "
                ".decay_rate read them from prior."
            )

    super().__init__(**model_kwargs)

    # --- core components ---
    self.prior = prior  # prior over parameter PyTree
    self.likelihood = likelihood  # task mapping and likelihood
    self.noise = noise  # noise model
    self.diag_term = float(diag_term)

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.

diag_term

diag_term = float(diag_term)

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.

likelihood

likelihood = likelihood

noise

noise = noise

prior

prior = prior

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, {"W": array of shape (degree+1, ..., input_dim, embedding_dim)}.

Source code in src/psyphy/model/wppm.py
def init_params(self, key: jax.Array) -> Params:
    """Sample initial parameters from the prior.

    Returns
    -------
    params : dict[str, jnp.ndarray], a parameter pytree
        For WPPM, ``{"W": array of shape (degree+1, ..., input_dim, embedding_dim)}``.
    """
    return self.prior.sample_params(key)

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
def local_covariance(self, params: Params, x: jnp.ndarray) -> jnp.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
    ----------
    params : dict
        Model parameters:
        - WPPM: {"W": (degree+1, ..., input_dim, embedding_dim)}
    x : jnp.ndarray, shape (input_dim,)
        Stimulus location

    Returns
    -------
    Σ : jnp.ndarray, shape (input_dim, input_dim)
        Covariance matrix in stimulus space.
    """
    # WPPM: spatially-varying covariance
    if "W" in params:
        U = self._compute_sqrt(params, x)  # (input_dim, embedding_dim)
        # Σ(x) = U(x) @ U(x)^T + diag_term * I
        # Result is (input_dim, input_dim)
        Sigma = U @ U.T + self.diag_term * jnp.eye(self.input_dim)
        return Sigma

    raise ValueError("params must contain 'W' (weights of WPPM)")

log_likelihood_from_data

log_likelihood_from_data(params: Params, data: Any, key: Array | None = None) -> ndarray

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 OddityTaskConfig.default_key_seed (useful for fixed evaluation and testing, but should not be used during gradient-based optimization).

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
def log_likelihood_from_data(
    self, params: Params, data: Any, key: jax.Array | None = None
) -> jnp.ndarray:
    """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
    ----------
    params : dict
        Model parameters.
    data : TrialData (or any object with refs/comparisons/responses arrays)
        Collected trial data.
    key : jax.Array | None, optional
        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 ``OddityTaskConfig.default_key_seed`` (useful for fixed evaluation
        and testing, but should not be used during gradient-based optimization).

    Returns
    -------
    loglik : jnp.ndarray, shape ()
        Scalar log-likelihood (task-only; add prior outside if needed).
    """
    return self.likelihood.loglik(params, data, self, key=key)

log_posterior_from_data

log_posterior_from_data(params: Params, data: Any, key: Array | None = None) -> ndarray

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 OddityTaskConfig.default_key_seed.

None

Returns:

Type Description
(ndarray, shape())

Scalar log posterior = loglik(params | data) + log_prior(params).

Source code in src/psyphy/model/wppm.py
def log_posterior_from_data(
    self, params: Params, data: Any, key: jax.Array | None = None
) -> jnp.ndarray:
    """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
    ----------
    params : dict
        Model parameters.
    data : TrialData
        Collected trial data.
    key : jax.Array | None, optional
        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 ``OddityTaskConfig.default_key_seed``.

    Returns
    -------
    jnp.ndarray, shape ()
        Scalar log posterior = loglik(params | data) + log_prior(params).
    """
    return self.log_likelihood_from_data(
        params, data, key=key
    ) + self.prior.log_prob(params)

predict_prob

predict_prob(params: Params, stimulus: Stimulus, **likelihood_kwargs: Any) -> ndarray

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
def predict_prob(
    self, params: Params, stimulus: Stimulus, **likelihood_kwargs: Any
) -> jnp.ndarray:
    """
    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
    ----------
    params : dict
    stimulus : tuple[jnp.ndarray, jnp.ndarray], each shape (input_dim,)
         (reference, comparison) pair in model space.

    Returns
    -------
    p_correct : jnp.ndarray, shape ()
        Scalar probability of a correct response.
    """
    # Strict task-owned configuration:
    # - MC control knobs (e.g. num_samples/bandwidth) live in the task config.
    # - WPPM.predict_prob therefore does not accept task-specific kwargs.
    if likelihood_kwargs:
        raise TypeError(
            f"WPPM.predict_prob got unexpected kwargs: {likelihood_kwargs}. "
            "Configure likelihood behavior via the TaskLikelihood object itself."
        )

    if not isinstance(self.likelihood, BernoulliTaskLikelihood):
        raise NotImplementedError(
            "WPPMP currently only supports "
            "BernoulliTaskLikelihood. Gaussian support requires "
            "updating to handle (mu, sigma) returns."
        )

    stimuli = jnp.stack(stimulus, axis=0)
    log_p, _ = self.likelihood.predict(params, stimuli, self)
    return jnp.exp(log_p)

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

Params

Params = dict[str, jnp.ndarray]

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

basis_degree

basis_degree: int = 4

decay_rate

decay_rate: float = 0.4

extra_embedding_dims

extra_embedding_dims: int = 1

input_dim

input_dim: int = 2

variance_scale

variance_scale: float = 0.004

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
def log_prob(self, params: Params) -> jnp.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
    ----------
    params : dict
        Parameter dictionary

    Returns
    -------
    log_prob : float
        Log prior probability (up to normalizing constant)
    """

    if "W" in params:
        W = params["W"]
        variances = self._compute_W_prior_variances()

        # Gaussian log probability for each entry
        # log N(x | 0, σ^2) = -0.5 * (x^2/σ^2 + log(2πσ^2))
        # Up to constant: -0.5 * x^2/σ^2

        if self.input_dim == 2:
            # Each W[i,j,:,:] ~ Normal(0, variance[i,j] * I)
            return -0.5 * jnp.sum((W**2) / (variances[:, :, None, None] + 1e-10))
        elif self.input_dim == 3:
            return -0.5 * jnp.sum((W**2) / (variances[:, :, :, None, None] + 1e-10))
        elif self.input_dim == 1:
            return -0.5 * jnp.sum((W**2) / (variances[:, None, None] + 1e-10))

    raise ValueError("params must contain weights 'W'")

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
def param_scales(self) -> 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
    -------
    scales : dict
        {"W": array with the same shape as sample_params()["W"]}
    """
    std = jnp.sqrt(self._compute_W_prior_variances())
    embedding_dim = self.input_dim + self.extra_embedding_dims
    # std.shape is the basis grid, e.g. (degree+1, degree+1) for 2D;
    # append the two trailing W axes and broadcast over them.
    W_shape = (*std.shape, self.input_dim, embedding_dim)
    return {"W": jnp.broadcast_to(std[..., None, None], W_shape)}

sample

sample(n: int, key: Any) -> Params

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:

1
2
3
4
5
>>> import jax.random as jr
>>> from psyphy.model import Prior
>>> prior = Prior(input_dim=2, basis_degree=2)
>>> prior.sample(5, key=jr.PRNGKey(0))["W"].shape
(5, 3, 3, 2, 3)
Source code in src/psyphy/model/prior.py
def sample(self, n: int, key: Any) -> Params:
    """
    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
    ----------
    n : int
        Number of draws.
    key : jax.Array
        PRNG key, split n ways.

    Returns
    -------
    params : dict
        Parameter dictionary with a leading axis of n, so for 2D
        {"W": (n, degree+1, degree+1, input_dim, embedding_dim)}

    Notes
    -----
    Satisfies :class:`psyphy.posterior.ParameterSource`.

    Examples
    --------
    >>> import jax.random as jr
    >>> from psyphy.model import Prior
    >>> prior = Prior(input_dim=2, basis_degree=2)
    >>> prior.sample(5, key=jr.PRNGKey(0))["W"].shape
    (5, 3, 3, 2, 3)
    """
    return jax.vmap(self.sample_params)(jr.split(key, n))

sample_params

sample_params(key: Any) -> 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
def sample_params(self, key: Any) -> 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
    ----------
    key : JAX random key

    Returns
    -------
    params : dict
        Parameter dictionary
    """
    # Basis function coefficients W
    variances = self._compute_W_prior_variances()
    embedding_dim = self.input_dim + self.extra_embedding_dims

    if self.input_dim == 2:
        # Sample W ~ Normal(0, variances) for each matrix entry
        # Shape: (degree+1, degree+1, input_dim, embedding_dim)
        # Note: degree+1 to match number of basis functions [T_0, ..., T_degree]
        W = jnp.sqrt(variances)[:, :, None, None] * jr.normal(
            key,
            shape=(
                self.basis_degree + 1,
                self.basis_degree + 1,
                self.input_dim,
                embedding_dim,
            ),
        )
    elif self.input_dim == 3:
        # Shape: (degree+1, degree+1, degree+1, input_dim, embedding_dim)
        W = jnp.sqrt(variances)[:, :, :, None, None] * jr.normal(
            key,
            shape=(
                self.basis_degree + 1,
                self.basis_degree + 1,
                self.basis_degree + 1,
                self.input_dim,
                embedding_dim,
            ),
        )
    elif self.input_dim == 1:
        # Shape: (degree+1, input_dim, embedding_dim)
        W = jnp.sqrt(variances)[:, None, None] * jr.normal(
            key,
            shape=(self.basis_degree + 1, self.input_dim, embedding_dim),
        )
    else:
        raise NotImplementedError(
            f"Wishart process only supports 1D, 2D and 3D. Got input_dim={self.input_dim}"
        )

    return {"W": W}

Noise


noise

Classes:

Name Description
GaussianNoise
StudentTNoise

GaussianNoise

GaussianNoise(sigma: float = 1.0)

Methods:

Name Description
log_prob
sample_standard

Sample from standard Gaussian (mean=0, var=1).

Attributes:

Name Type Description
sigma float

sigma

sigma: float = 1.0

log_prob

log_prob(residual: float) -> float
Source code in src/psyphy/model/noise.py
def log_prob(self, residual: float) -> float:
    _ = residual
    return -0.5

sample_standard

sample_standard(key: Array, shape: tuple[int, ...]) -> Array

Sample from standard Gaussian (mean=0, var=1).

Source code in src/psyphy/model/noise.py
def sample_standard(self, key: jax.Array, shape: tuple[int, ...]) -> jax.Array:
    """Sample from standard Gaussian (mean=0, var=1)."""
    return jr.normal(key, shape)

StudentTNoise

StudentTNoise(df: float = 3.0, scale: float = 1.0)

Methods:

Name Description
log_prob
sample_standard

Sample from standard Student-t (df=self.df).

Attributes:

Name Type Description
df float
scale float

df

df: float = 3.0

scale

scale: float = 1.0

log_prob

log_prob(residual: float) -> float
Source code in src/psyphy/model/noise.py
def log_prob(self, residual: float) -> float:
    _ = residual
    return -0.5

sample_standard

sample_standard(key: Array, shape: tuple[int, ...]) -> Array

Sample from standard Student-t (df=self.df).

Source code in src/psyphy/model/noise.py
def sample_standard(self, key: jax.Array, shape: tuple[int, ...]) -> jax.Array:
    """Sample from standard Student-t (df=self.df)."""
    return jr.t(key, self.df, shape)

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:OddityTask.

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:

>>> import jax.numpy as jnp
>>> from psyphy.model.likelihood import (
...     BernoulliTaskLikelihood,
...     log_probs_from_logit,
... )
>>> class DistanceTask(BernoulliTaskLikelihood):
...     def predict(self, params, stimuli, model, key=None):
...         z = 50.0 * (jnp.linalg.norm(stimuli[1] - stimuli[0]) - 0.1)
...         return log_probs_from_logit(z)
>>> log_p, log_1mp = DistanceTask().predict(
...     None, jnp.array([[0.0, 0.0], [0.1, 0.0]]), None
... )
>>> float(jnp.exp(log_p))
0.5

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

loglik(params: Any, data: Any, model: Any, key: Any = None) -> ndarray

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 .stimuli, .responses array attributes.

required
model Any

Model instance.

required
key Array

PRNG key. Passed as independent per-trial subkeys to predict. When None, falls back to key=jr.PRNGKey(0) (deterministic).

None

Returns:

Type Description
(ndarray, shape())

Scalar sum of Bernoulli log-likelihoods over all trials.

Source code in src/psyphy/model/likelihood/base.py
def loglik(
    self,
    params: Any,
    data: Any,
    model: Any,
    key: Any = None,
) -> jnp.ndarray:
    """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
    ----------
    params : Any
        Model parameters.
    data : Any
        Object with ``.stimuli``, ``.responses`` array attributes.
    model : Any
        Model instance.
    key : jax.Array, optional
        PRNG key. Passed as independent per-trial subkeys to ``predict``.
        When None, falls back to ``key=jr.PRNGKey(0)`` (deterministic).

    Returns
    -------
    jnp.ndarray, shape ()
        Scalar sum of Bernoulli log-likelihoods over all trials.
    """
    stimuli = jnp.asarray(data.stimuli)
    # TrialData stores responses as (N, R): R=1 for binary tasks.
    # Extract the single binary channel to get shape (N,).
    # Without this, jnp.where broadcasts (N, 1) against log_p (N,),
    # treating (N,) as (1, N) and producing an (N, N) result whose
    # sum scrambles the gradient: every p[j] receives signal from all
    # N responses instead of only response[j].

    responses = jnp.asarray(data.responses)
    if responses.ndim == 2:  # shape (N, R)
        responses = responses[:, 0]
    responses = responses.astype(int)
    n_trials = int(stimuli.shape[0])

    base_key = key if key is not None else jr.PRNGKey(0)
    trial_keys = jr.split(base_key, n_trials)

    log_p, log_1mp = jax.vmap(
        lambda stim, k: self.predict(params, stim, model, key=k)
    )(stimuli, trial_keys)  # each (N,)

    log_likelihoods = jnp.where(responses == 1, log_p, log_1mp)  # (N,)
    log_likelihoods = jnp.clip(log_likelihoods, jnp.log(_P_EPS), jnp.log1p(-_P_EPS))

    return jnp.sum(log_likelihoods)

predict

predict(params: Any, stimuli: ndarray, model: Any, key: Any = None) -> tuple[ndarray, ...]

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 model.noise).

required
key Array

PRNG key for stochastic tasks. When None, the task falls back to its config.default_key_seed.

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
@abstractmethod
def predict(
    self,
    params: Any,
    stimuli: jnp.ndarray,
    model: Any,
    key: Any = None,
) -> tuple[jnp.ndarray, ...]:
    """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
    ----------
    params : Any
        Model parameters.
    stimuli : jnp.ndarray, shape (stim_dim, K)
        stimuli for a given trial (stimulus dimensions, number of stimuli)
    model : Any
        Model instance (provides covariance structure and ``model.noise``).
    key : jax.Array, optional
        PRNG key for stochastic tasks. When None, the task falls back to
        its ``config.default_key_seed``.

    Returns
    -------
    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)
    """
    ...

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 (p_correct,). p_correct has shape (n_trials,) and holds the estimated P(correct) per trial used to draw the responses, as exp(log_p) of what predict returns.

Source code in src/psyphy/model/likelihood/base.py
def simulate(
    self,
    params: Any,
    stimuli: jnp.ndarray,
    model: Any,
    key: Any,
) -> tuple[jnp.ndarray, tuple[jnp.ndarray, ...]]:
    """Simulate observed binary responses for a batch of trials.

    Parameters
    ----------
    params : Any
        Model parameters.
    stimuli : jnp.ndarray, shape (n_trials, k_stim, input_dim)
        Stimuli.
    model : Any
        Model instance.
    key : jax.Array
        PRNG key (required; split internally for prediction and sampling).

    Returns
    -------
    responses : jnp.ndarray, shape (n_trials,), dtype int32
        Simulated binary responses (1 = correct, 0 = incorrect).
    probability parameters : tuple[jnp.ndarray]
        1-tuple ``(p_correct,)``. ``p_correct`` has shape (n_trials,) and holds
        the estimated P(correct) per trial used to draw the responses, as
        ``exp(log_p)`` of what ``predict`` returns.
    """
    stimuli = jnp.asarray(stimuli)
    n_trials = int(stimuli.shape[0])

    k_pred, k_bernoulli = jr.split(key)
    trial_keys = jr.split(k_pred, n_trials)

    log_p, _ = jax.vmap(lambda stim, k: self.predict(params, stim, model, key=k))(
        stimuli, trial_keys
    )
    p_correct = jnp.exp(log_p)  # (n_trials,)

    responses = jr.bernoulli(k_bernoulli, p_correct).astype(jnp.int32)
    return (responses, (p_correct,))

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

loglik(params: Any, data: Any, model: Any, key: Any = None) -> ndarray

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 .stimuli, .responses array attributes.

required
model Any

Model instance.

required
key Array

PRNG key. Passed as independent per-trial subkeys to predict. When None, falls back to key=jr.PRNGKey(0) (deterministic).

None

Returns:

Type Description
(ndarray, shape())

Scalar sum of Gaussian log-likelihoods over all trials.

Source code in src/psyphy/model/likelihood/base.py
def loglik(
    self,
    params: Any,
    data: Any,
    model: Any,
    key: Any = None,
) -> jnp.ndarray:
    """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
    ----------
    params : Any
        Model parameters.
    data : Any
        Object with ``.stimuli``, ``.responses`` array attributes.
    model : Any
        Model instance.
    key : jax.Array, optional
        PRNG key. Passed as independent per-trial subkeys to ``predict``.
        When None, falls back to ``key=jr.PRNGKey(0)`` (deterministic).

    Returns
    -------
    jnp.ndarray, shape ()
        Scalar sum of Gaussian log-likelihoods over all trials.
    """
    stimuli = jnp.asarray(data.stimuli)
    responses = jnp.asarray(data.responses)
    n_trials = int(stimuli.shape[0])

    base_key = key if key is not None else jr.PRNGKey(0)
    trial_keys = jr.split(base_key, n_trials)

    mu, sigma = jax.vmap(lambda stim, k: self.predict(params, stim, model, key=k))(
        stimuli, trial_keys
    )

    # ensure sigma is correct shape:
    sigma = jnp.squeeze(sigma)
    if n_trials == 1:
        sigma = jnp.expand_dims(sigma, axis=0)

    log_likelihoods = jax.vmap(
        lambda resp, m, s: jsp.multivariate_normal.logpdf(x=resp, mean=m, cov=s)
    )(responses, mu, sigma)

    def nan_loglik(logliks):
        if any(jnp.isnan(logliks)):
            import warnings

            warnings.warn(
                "GaussianTaskLikelihood: NaN log-likelihoods detected. "
                "This is likely caused by a non positive-definite covariance matrix",
                stacklevel=1,
            )

    jax.debug.callback(nan_loglik, log_likelihoods)

    return jnp.sum(log_likelihoods)

predict

predict(params: Any, stimuli: ndarray, model: Any, key: Any = None) -> tuple[ndarray, ...]

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 model.noise).

required
key Array

PRNG key for stochastic tasks. When None, the task falls back to its config.default_key_seed.

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
@abstractmethod
def predict(
    self,
    params: Any,
    stimuli: jnp.ndarray,
    model: Any,
    key: Any = None,
) -> tuple[jnp.ndarray, ...]:
    """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
    ----------
    params : Any
        Model parameters.
    stimuli : jnp.ndarray, shape (stim_dim, K)
        stimuli for a given trial (stimulus dimensions, number of stimuli)
    model : Any
        Model instance (provides covariance structure and ``model.noise``).
    key : jax.Array, optional
        PRNG key for stochastic tasks. When None, the task falls back to
        its ``config.default_key_seed``.

    Returns
    -------
    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)
    """
    ...

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
def simulate(
    self,
    params: Any,
    stimuli: jnp.ndarray,
    model: Any,
    key: Any,
) -> tuple[jnp.ndarray, tuple[jnp.ndarray, ...]]:
    """Simulate observed responses for a batch of trials.

    Parameters
    ----------
    params : Any
        Model parameters.
    stimuli : jnp.ndarray, shape (n_trials, k_stim, input_dim)
        Stimuli.
    model : Any
        Model instance.
    key : jax.Array
        PRNG key (required; split internally for prediction and sampling).

    Returns
    -------
    responses : jnp.ndarray, shape (n_trials, r_dims),
        Simulated responses.
    prob_params : jnp.ndarray, shape (n_trials, )
        Estimated (mu, sigma) per trial used to draw the responses.
    """
    raise NotImplementedError("Gaussian Task simulations not yet implemented")

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:

>>> from psyphy.model.likelihood import OddityTask
>>> from psyphy.model.likelihood import OddityTaskConfig
>>> from psyphy.model import WPPM, Prior
>>> from psyphy.model.noise import GaussianNoise
>>> import jax.numpy as jnp
>>> import jax.random as jr
>>>
>>> # Create task and model (task-owned MC controls)
>>> likelihood = OddityTask(
...     config=OddityTaskConfig(num_samples=1000, bandwidth=1e-2)
... )
>>> model = WPPM(
...     prior=Prior(input_dim=2),
...     likelihood=likelihood,
...     noise=GaussianNoise(),
... )
>>> params = model.init_params(jr.PRNGKey(0))
1
2
3
4
5
6
7
8
9
>>> # MC simulation, one trial
>>> from psyphy.data.dataset import ResponseData
>>> ref = jnp.array([0.0, 0.0])  # (2,)
>>> comparison = jnp.array([0.1, 0.0])  # (2,)
>>> data = ResponseData()
>>> data.add_trial((ref, comparison), resp=1)
>>> ll_mc = likelihood.loglik(params, data, model, key=jr.PRNGKey(42))
>>> ll_mc.shape
()

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
def __init__(self, config: OddityTaskConfig | None = None) -> None:
    # No analytical parameters in MC-only mode.
    self.config = config or OddityTaskConfig()

config

config = config or OddityTaskConfig()

loglik

loglik(params: Any, data: Any, model: Any, key: Any = None) -> ndarray

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 .stimuli, .responses array attributes.

required
model Any

Model instance.

required
key Array

PRNG key. Passed as independent per-trial subkeys to predict. When None, falls back to key=jr.PRNGKey(0) (deterministic).

None

Returns:

Type Description
(ndarray, shape())

Scalar sum of Bernoulli log-likelihoods over all trials.

Source code in src/psyphy/model/likelihood/base.py
def loglik(
    self,
    params: Any,
    data: Any,
    model: Any,
    key: Any = None,
) -> jnp.ndarray:
    """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
    ----------
    params : Any
        Model parameters.
    data : Any
        Object with ``.stimuli``, ``.responses`` array attributes.
    model : Any
        Model instance.
    key : jax.Array, optional
        PRNG key. Passed as independent per-trial subkeys to ``predict``.
        When None, falls back to ``key=jr.PRNGKey(0)`` (deterministic).

    Returns
    -------
    jnp.ndarray, shape ()
        Scalar sum of Bernoulli log-likelihoods over all trials.
    """
    stimuli = jnp.asarray(data.stimuli)
    # TrialData stores responses as (N, R): R=1 for binary tasks.
    # Extract the single binary channel to get shape (N,).
    # Without this, jnp.where broadcasts (N, 1) against log_p (N,),
    # treating (N,) as (1, N) and producing an (N, N) result whose
    # sum scrambles the gradient: every p[j] receives signal from all
    # N responses instead of only response[j].

    responses = jnp.asarray(data.responses)
    if responses.ndim == 2:  # shape (N, R)
        responses = responses[:, 0]
    responses = responses.astype(int)
    n_trials = int(stimuli.shape[0])

    base_key = key if key is not None else jr.PRNGKey(0)
    trial_keys = jr.split(base_key, n_trials)

    log_p, log_1mp = jax.vmap(
        lambda stim, k: self.predict(params, stim, model, key=k)
    )(stimuli, trial_keys)  # each (N,)

    log_likelihoods = jnp.where(responses == 1, log_p, log_1mp)  # (N,)
    log_likelihoods = jnp.clip(log_likelihoods, jnp.log(_P_EPS), jnp.log1p(-_P_EPS))

    return jnp.sum(log_likelihoods)

predict

predict(params: Any, stimuli: ndarray, model: Any, key: Any = None) -> tuple[ndarray, ...]

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
def predict(
    self,
    params: Any,
    stimuli: jnp.ndarray,  # (k_stimuli, dimensions)
    model: Any,
    key: Any = None,
) -> tuple[jnp.ndarray, ...]:
    """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.
    """
    num_samples = int(self.config.num_samples)
    bandwidth = float(self.config.bandwidth)
    if key is None:
        key = jr.PRNGKey(int(self.config.default_key_seed))

    ref = stimuli[0, :]
    comparison = stimuli[1, :]

    return self._simulate_trial_mc(
        params=params,
        ref=ref,
        comparison=comparison,
        model=model,
        num_samples=num_samples,
        bandwidth=bandwidth,
        key=key,
    )

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 (p_correct,). p_correct has shape (n_trials,) and holds the estimated P(correct) per trial used to draw the responses, as exp(log_p) of what predict returns.

Source code in src/psyphy/model/likelihood/base.py
def simulate(
    self,
    params: Any,
    stimuli: jnp.ndarray,
    model: Any,
    key: Any,
) -> tuple[jnp.ndarray, tuple[jnp.ndarray, ...]]:
    """Simulate observed binary responses for a batch of trials.

    Parameters
    ----------
    params : Any
        Model parameters.
    stimuli : jnp.ndarray, shape (n_trials, k_stim, input_dim)
        Stimuli.
    model : Any
        Model instance.
    key : jax.Array
        PRNG key (required; split internally for prediction and sampling).

    Returns
    -------
    responses : jnp.ndarray, shape (n_trials,), dtype int32
        Simulated binary responses (1 = correct, 0 = incorrect).
    probability parameters : tuple[jnp.ndarray]
        1-tuple ``(p_correct,)``. ``p_correct`` has shape (n_trials,) and holds
        the estimated P(correct) per trial used to draw the responses, as
        ``exp(log_p)`` of what ``predict`` returns.
    """
    stimuli = jnp.asarray(stimuli)
    n_trials = int(stimuli.shape[0])

    k_pred, k_bernoulli = jr.split(key)
    trial_keys = jr.split(k_pred, n_trials)

    log_p, _ = jax.vmap(lambda stim, k: self.predict(params, stim, model, key=k))(
        stimuli, trial_keys
    )
    p_correct = jnp.exp(log_p)  # (n_trials,)

    responses = jr.bernoulli(k_bernoulli, p_correct).astype(jnp.int32)
    return (responses, (p_correct,))

OddityTaskConfig

OddityTaskConfig(num_samples: int = 1000, bandwidth: float = 0.01, default_key_seed: int = 0)

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

bandwidth

bandwidth: float = 0.01

default_key_seed

default_key_seed: int = 0

num_samples

num_samples: int = 1000

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

loglik(params: Any, data: ndarray, model: Any, key: Any = None) -> ndarray

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 .stimuli, .responses array attributes.

required
model Any

Model instance (provides covariance structure and model.noise).

required
key Array

PRNG key for stochastic tasks. When None, the task falls back to its config.default_key_seed.

None

Returns:

Type Description
(ndarray, shape())

Scalar sum of log-likelihoods over all trials.

Source code in src/psyphy/model/likelihood/base.py
@abstractmethod
def loglik(
    self,
    params: Any,
    data: jnp.ndarray,
    model: Any,
    key: Any = None,
) -> jnp.ndarray:
    """
    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
    ----------
    params : Any
        Model parameters.
    data : Any
        Object with ``.stimuli``, ``.responses`` array attributes.
    model : Any
        Model instance (provides covariance structure and ``model.noise``).
    key : jax.Array, optional
        PRNG key for stochastic tasks. When None, the task falls back to
        its ``config.default_key_seed``.

    Returns
    -------
    jnp.ndarray, shape ()
        Scalar sum of log-likelihoods over all trials.
    """
    ...

predict

predict(params: Any, stimuli: ndarray, model: Any, key: Any = None) -> tuple[ndarray, ...]

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 model.noise).

required
key Array

PRNG key for stochastic tasks. When None, the task falls back to its config.default_key_seed.

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
@abstractmethod
def predict(
    self,
    params: Any,
    stimuli: jnp.ndarray,
    model: Any,
    key: Any = None,
) -> tuple[jnp.ndarray, ...]:
    """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
    ----------
    params : Any
        Model parameters.
    stimuli : jnp.ndarray, shape (stim_dim, K)
        stimuli for a given trial (stimulus dimensions, number of stimuli)
    model : Any
        Model instance (provides covariance structure and ``model.noise``).
    key : jax.Array, optional
        PRNG key for stochastic tasks. When None, the task falls back to
        its ``config.default_key_seed``.

    Returns
    -------
    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)
    """
    ...

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
@abstractmethod
def simulate(
    self,
    params: Any,
    stimuli: jnp.ndarray,
    model: Any,
    key: Any,
) -> tuple[jnp.ndarray, tuple[jnp.ndarray, ...]]:
    """Simulate responses for a batch of trials.

    Parameters
    ----------
    params : Any
        Model parameters.
    stimuli : jnp.ndarray, shape (n_trials, k_stimuli, input_dim)
        Stimuli.
    model : Any
        Model instance.
    key : jax.Array
        PRNG key (required; split internally for prediction and sampling).

    Returns
    -------
    responses : jnp.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
    """
    ...

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_sigmoid(z).

log_1mp jnp.ndarray, same shape as ``z``

log p(incorrect) = log_sigmoid(-z).

Examples:

1
2
3
4
5
>>> import jax.numpy as jnp
>>> from psyphy.model.likelihood import log_probs_from_logit
>>> log_p, log_1mp = log_probs_from_logit(jnp.array(0.0))
>>> float(jnp.exp(log_p)), float(jnp.exp(log_1mp))
(0.5, 0.5)
Source code in src/psyphy/model/likelihood/base.py
def log_probs_from_logit(z: jnp.ndarray) -> tuple[jnp.ndarray, jnp.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
    ----------
    z : jnp.ndarray, any shape
        Log-odds of a correct response.

    Returns
    -------
    log_p : jnp.ndarray, same shape as ``z``
        log p(correct) = ``log_sigmoid(z)``.
    log_1mp : jnp.ndarray, same shape as ``z``
        log p(incorrect) = ``log_sigmoid(-z)``.

    Examples
    --------
    >>> import jax.numpy as jnp
    >>> from psyphy.model.likelihood import log_probs_from_logit
    >>> log_p, log_1mp = log_probs_from_logit(jnp.array(0.0))
    >>> float(jnp.exp(log_p)), float(jnp.exp(log_1mp))
    (0.5, 0.5)
    """
    return jax.nn.log_sigmoid(z), jax.nn.log_sigmoid(-z)