Skip to content

Posterior

Package

posterior

posterior

Posterior representations and diagnostics.

This subpackage provides: - Posterior : wrapper around model parameters, samples, and prediction APIs. - diagnostics : tools for checking posterior quality (ESS, R-hat, etc.).

MVP implementation
  • Posterior: stores MAP parameters and delegates predictions to WPPM.
  • Diagnostics: stubs and simple summaries.
Future extensions
  • Posterior: store MCMC samples, support predictive intervals.
  • Diagnostics: effective sample size, R-hat, posterior predictive checks.

Classes:

Name Description
Posterior

MVP Posterior (MAP only).

Functions:

Name Description
effective_sample_size

Estimate effective sample size (ESS) to calculate the number of independent

rhat

Compute R-hat convergence diagnostic.

Posterior 

Posterior(params, model)

Bases: BasePosterior

MVP Posterior (MAP only).

Parameters:

Name Type Description Default
params dict

MAP parameter dictionary.

 required
model WPPM

Model instance used for predictions.

 required
Notes
  • This is effectively a MAPPosterior.
  • Future subclasses (LaplacePosterior, MCMCPosterior) will extend BasePosterior with real sampling logic.

Methods:

Name Description
MAP_params

Return the MAP parameters.
predict_prob

Predict probability of correct response for a stimulus.
predict_thresholds

Predict discrimination threshold contour around a reference stimulus.
sample

Draw parameter samples from the posterior.

Attributes:

Name Type Description
model
params
Source code in src/psyphy/posterior/posterior.py 
43
44
45
def __init__(self, params, model):
    self.params = params
    self.model = model

model 

model = model

params 

params = params

MAP_params 

MAP_params()

Return the MAP parameters.

Returns:

Type Description
dict

Parameter dictionary.
Source code in src/psyphy/posterior/posterior.py 
50
51
52
53
54
55
56
57
58
59
def MAP_params(self):
    """
    Return the MAP parameters.

    Returns
    -------
    dict
        Parameter dictionary.
    """
    return self.params

predict_prob 

predict_prob(stimulus)

Predict probability of correct response for a stimulus.

Parameters:

Name Type Description Default
stimulus tuple

(reference, probe).

 required

Returns:

Type Description
ndarray

Probability of correct response.
Notes

Delegates to WPPM.predict_prob(). This is not recursion: Posterior calls WPPM’s method with stored params.

Source code in src/psyphy/posterior/posterior.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def predict_prob(self, stimulus):
    """
    Predict probability of correct response for a stimulus.

    Parameters
    ----------
    stimulus : tuple
        (reference, probe).

    Returns
    -------
    jnp.ndarray
        Probability of correct response.

    Notes
    -----
    Delegates to WPPM.predict_prob().
    This is not recursion: Posterior calls WPPM’s method with stored params.
    """
    return self.model.predict_prob(self.params, stimulus)

predict_thresholds 

predict_thresholds(
    reference,
    criterion: float = 0.667,
    directions: int = 16,
)

Predict discrimination threshold contour around a reference stimulus.

Parameters:

Name Type Description Default
reference ndarray

Reference point in model space.

 required
criterion float

Target performance (e.g., 2/3 for oddity).

 0.667
directions int

Number of directions to probe.

 16

Returns:

Type Description
ndarray

Contour points (MVP: unit circle).
MVP

Returns a placeholder unit circle.

Future
  • Search outward in each direction until performance crosses criterion.
  • Average over posterior samples (Laplace, MCMC) to get credible intervals.
Source code in src/psyphy/posterior/posterior.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
def predict_thresholds(self, reference, criterion: float = 0.667, directions: int = 16):
    """
    Predict discrimination threshold contour around a reference stimulus.

    Parameters
    ----------
    reference : jnp.ndarray
        Reference point in model space.
    criterion : float, default=0.667
        Target performance (e.g., 2/3 for oddity).
    directions : int, default=16
        Number of directions to probe.

    Returns
    -------
    jnp.ndarray
        Contour points (MVP: unit circle).

    MVP
    ---
    Returns a placeholder unit circle.

    Future
    ------
    - Search outward in each direction until performance crosses criterion.
    - Average over posterior samples (Laplace, MCMC) to get credible intervals.
    """
    angles = jnp.linspace(0, 2 * jnp.pi, directions, endpoint=False)
    contour = jnp.stack([reference + jnp.array([jnp.cos(a), jnp.sin(a)]) for a in angles])
    return contour

sample 

sample(num_samples: int = 1)

Draw parameter samples from the posterior.

Parameters:

Name Type Description Default
num_samples int

Number of samples.

 1

Returns:

Type Description
list of dict

Parameter sets.
MVP

Returns MAP params repeated n times.

Future
  • LaplacePosterior: draw from N(mean, cov).
  • MCMCPosterior: return stored samples.
Source code in src/psyphy/posterior/posterior.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def sample(self, num_samples: int = 1):
    """
    Draw parameter samples from the posterior.

    Parameters
    ----------
    num_samples : int, default=1
        Number of samples.

    Returns
    -------
    list of dict
        Parameter sets.

    MVP
    ---
    Returns MAP params repeated n times.

    Future
    ------
    - LaplacePosterior: draw from N(mean, cov).
    - MCMCPosterior: return stored samples.
    """
    return [self.params] * num_samples

effective_sample_size 

effective_sample_size(samples: ndarray) -> float

Estimate effective sample size (ESS) to calculate the number of independent samples that a correlated MCMC chain is equivalent to.

Parameters:

Name Type Description Default
samples ndarray

Posterior samples, shape (n_samples, ...).

 required

Returns:

Type Description
float

Effective sample size (stub).
Notes

MVP: Returns the number of samples. Full WPPM mode: Compute ESS using autocorrelation structure.

Source code in src/psyphy/posterior/diagnostics.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
def effective_sample_size(samples: jnp.ndarray) -> float:
    """
    Estimate effective sample size (ESS) to calculate the number of independent 
    samples that a correlated MCMC chain is equivalent to.

    Parameters
    ----------
    samples : jnp.ndarray
        Posterior samples, shape (n_samples, ...).

    Returns
    -------
    float
        Effective sample size (stub).

    Notes
    -----
    MVP:
        Returns the number of samples.
    Full WPPM mode:
        Compute ESS using autocorrelation structure.
    """
    return samples.shape[0]

rhat 

rhat(chains: ndarray) -> float

Compute R-hat convergence diagnostic.

Parameters:

Name Type Description Default
chains ndarray

Posterior samples across chains, shape (n_chains, n_samples, ...).

 required

Returns:

Type Description
float

R-hat statistic (stub).
Notes

MVP: Always returns 1.0. Full WPPM mode: Implement Gelman-Rubin diagnostic [1]

References: 
1
[1] https://bookdown.org/rdpeng/advstatcomp/monitoring-convergence.html
Source code in src/psyphy/posterior/diagnostics.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def rhat(chains: jnp.ndarray) -> float:
    """
    Compute R-hat convergence diagnostic.

    Parameters
    ----------
    chains : jnp.ndarray
        Posterior samples across chains, shape (n_chains, n_samples, ...).

    Returns
    -------
    float
        R-hat statistic (stub).

    Notes
    -----
    MVP:
        Always returns 1.0.
    Full WPPM mode:
        Implement Gelman-Rubin diagnostic [1]

    References:
    ----------
        [1] https://bookdown.org/rdpeng/advstatcomp/monitoring-convergence.html

    """
    return 1.0

Posterior Representation

posterior

posterior.py

Posterior representation for WPPM.

MVP implementation: - Posterior = MAPPosterior (point estimate only). - Stores one parameter set and delegates predictions to WPPM.

Design note
  • This class inherits from BasePosterior.
  • In the future, other subclasses (LaplacePosterior, MCMCPosterior) will also inherit from BasePosterior, each implementing the same interface.

Classes:

Name Description
Posterior

MVP Posterior (MAP only).

Posterior 

Posterior(params, model)

Bases: BasePosterior

MVP Posterior (MAP only).

Parameters:

Name Type Description Default
params dict

MAP parameter dictionary.

 required
model WPPM

Model instance used for predictions.

 required
Notes
  • This is effectively a MAPPosterior.
  • Future subclasses (LaplacePosterior, MCMCPosterior) will extend BasePosterior with real sampling logic.

Methods:

Name Description
MAP_params

Return the MAP parameters.
predict_prob

Predict probability of correct response for a stimulus.
predict_thresholds

Predict discrimination threshold contour around a reference stimulus.
sample

Draw parameter samples from the posterior.

Attributes:

Name Type Description
model
params
Source code in src/psyphy/posterior/posterior.py 
43
44
45
def __init__(self, params, model):
    self.params = params
    self.model = model

model 

model = model

params 

params = params

MAP_params 

MAP_params()

Return the MAP parameters.

Returns:

Type Description
dict

Parameter dictionary.
Source code in src/psyphy/posterior/posterior.py 
50
51
52
53
54
55
56
57
58
59
def MAP_params(self):
    """
    Return the MAP parameters.

    Returns
    -------
    dict
        Parameter dictionary.
    """
    return self.params

predict_prob 

predict_prob(stimulus)

Predict probability of correct response for a stimulus.

Parameters:

Name Type Description Default
stimulus tuple

(reference, probe).

 required

Returns:

Type Description
ndarray

Probability of correct response.
Notes

Delegates to WPPM.predict_prob(). This is not recursion: Posterior calls WPPM’s method with stored params.

Source code in src/psyphy/posterior/posterior.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def predict_prob(self, stimulus):
    """
    Predict probability of correct response for a stimulus.

    Parameters
    ----------
    stimulus : tuple
        (reference, probe).

    Returns
    -------
    jnp.ndarray
        Probability of correct response.

    Notes
    -----
    Delegates to WPPM.predict_prob().
    This is not recursion: Posterior calls WPPM’s method with stored params.
    """
    return self.model.predict_prob(self.params, stimulus)

predict_thresholds 

predict_thresholds(
    reference,
    criterion: float = 0.667,
    directions: int = 16,
)

Predict discrimination threshold contour around a reference stimulus.

Parameters:

Name Type Description Default
reference ndarray

Reference point in model space.

 required
criterion float

Target performance (e.g., 2/3 for oddity).

 0.667
directions int

Number of directions to probe.

 16

Returns:

Type Description
ndarray

Contour points (MVP: unit circle).
MVP

Returns a placeholder unit circle.

Future
  • Search outward in each direction until performance crosses criterion.
  • Average over posterior samples (Laplace, MCMC) to get credible intervals.
Source code in src/psyphy/posterior/posterior.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
def predict_thresholds(self, reference, criterion: float = 0.667, directions: int = 16):
    """
    Predict discrimination threshold contour around a reference stimulus.

    Parameters
    ----------
    reference : jnp.ndarray
        Reference point in model space.
    criterion : float, default=0.667
        Target performance (e.g., 2/3 for oddity).
    directions : int, default=16
        Number of directions to probe.

    Returns
    -------
    jnp.ndarray
        Contour points (MVP: unit circle).

    MVP
    ---
    Returns a placeholder unit circle.

    Future
    ------
    - Search outward in each direction until performance crosses criterion.
    - Average over posterior samples (Laplace, MCMC) to get credible intervals.
    """
    angles = jnp.linspace(0, 2 * jnp.pi, directions, endpoint=False)
    contour = jnp.stack([reference + jnp.array([jnp.cos(a), jnp.sin(a)]) for a in angles])
    return contour

sample 

sample(num_samples: int = 1)

Draw parameter samples from the posterior.

Parameters:

Name Type Description Default
num_samples int

Number of samples.

 1

Returns:

Type Description
list of dict

Parameter sets.
MVP

Returns MAP params repeated n times.

Future
  • LaplacePosterior: draw from N(mean, cov).
  • MCMCPosterior: return stored samples.
Source code in src/psyphy/posterior/posterior.py 
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def sample(self, num_samples: int = 1):
    """
    Draw parameter samples from the posterior.

    Parameters
    ----------
    num_samples : int, default=1
        Number of samples.

    Returns
    -------
    list of dict
        Parameter sets.

    MVP
    ---
    Returns MAP params repeated n times.

    Future
    ------
    - LaplacePosterior: draw from N(mean, cov).
    - MCMCPosterior: return stored samples.
    """
    return [self.params] * num_samples

Diagnostics

diagnostics

diagnostics.py

Posterior diagnostics.

Provides functions to check quality of posterior inference.

MVP implementation: - Stubs for effective sample size and R-hat.

Full WPPM mode: - Implement real diagnostics from posterior chains. - Include posterior predictive checks.

Functions:

Name Description
effective_sample_size

Estimate effective sample size (ESS) to calculate the number of independent

rhat

Compute R-hat convergence diagnostic.

effective_sample_size 

effective_sample_size(samples: ndarray) -> float

Estimate effective sample size (ESS) to calculate the number of independent samples that a correlated MCMC chain is equivalent to.

Parameters:

Name Type Description Default
samples ndarray

Posterior samples, shape (n_samples, ...).

 required

Returns:

Type Description
float

Effective sample size (stub).
Notes

MVP: Returns the number of samples. Full WPPM mode: Compute ESS using autocorrelation structure.

Source code in src/psyphy/posterior/diagnostics.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
def effective_sample_size(samples: jnp.ndarray) -> float:
    """
    Estimate effective sample size (ESS) to calculate the number of independent 
    samples that a correlated MCMC chain is equivalent to.

    Parameters
    ----------
    samples : jnp.ndarray
        Posterior samples, shape (n_samples, ...).

    Returns
    -------
    float
        Effective sample size (stub).

    Notes
    -----
    MVP:
        Returns the number of samples.
    Full WPPM mode:
        Compute ESS using autocorrelation structure.
    """
    return samples.shape[0]

rhat 

rhat(chains: ndarray) -> float

Compute R-hat convergence diagnostic.

Parameters:

Name Type Description Default
chains ndarray

Posterior samples across chains, shape (n_chains, n_samples, ...).

 required

Returns:

Type Description
float

R-hat statistic (stub).
Notes

MVP: Always returns 1.0. Full WPPM mode: Implement Gelman-Rubin diagnostic [1]

References: 
1
[1] https://bookdown.org/rdpeng/advstatcomp/monitoring-convergence.html
Source code in src/psyphy/posterior/diagnostics.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def rhat(chains: jnp.ndarray) -> float:
    """
    Compute R-hat convergence diagnostic.

    Parameters
    ----------
    chains : jnp.ndarray
        Posterior samples across chains, shape (n_chains, n_samples, ...).

    Returns
    -------
    float
        R-hat statistic (stub).

    Notes
    -----
    MVP:
        Always returns 1.0.
    Full WPPM mode:
        Implement Gelman-Rubin diagnostic [1]

    References:
    ----------
        [1] https://bookdown.org/rdpeng/advstatcomp/monitoring-convergence.html

    """
    return 1.0