wppmpy

Python code accompanying the Wishart Process Psychophysical Model (WPPM) — a Bayesian semi-parametric model that characterises how internal perceptual noise varies continuously across color space. This builds upon the public respository for the paper, providing additonal code. See installation instructions below.

Background on the model and related experimental data are described in:

Hong et al. Comprehensive characterization of human color discrimination using a Wishart process psychophysical model. eLife Reviewed Preprint (2025). https://elifesciences.org/reviewed-preprints/108943v1

This repository is being set up to provide:

• Illustrative examples of the statistical ideas underlying the WPPM
• Additional analysis code beyond that provided in the repository accompanying the paper
• Tools to help readers understand and use our results

These will be developed and added over time.

---

Installation

Basic install (toolbox only — no JAX required)

git clone https://github.com/BrainardLab/wppmpy.git
cd wppmpy
python -m venv .venv
source .venv/bin/activate      # macOS / Linux
# .venv\Scripts\activate       # Windows
pip install -e .

With notebooks

The notebooks in this repo require the paper repository and its dependencies (JAX, pandas, scipy, etc.). Run this instead of (or in place of) pip install -e . above:

pip install -e ".[notebooks]"

JAX (CPU build) is pulled in automatically. For GPU acceleration see the note below.

Then download the required data subset from OSF once (saved to data/hong_etal_2025/):

python src/hong_etal_2025/download_data.py

GPU acceleration (optional)

NVIDIA GPU (CUDA 12):

pip install "jax[cuda12]"

Run this after pip install -e ".[notebooks]" to replace the CPU JAX build.

Apple Silicon (M1/M2/M3/M4): GPU acceleration is not available for this codebase. The code requires 64-bit floating point (jax_enable_x64 = True), which the Apple Metal JAX plugin (jax-metal) does not support. CPU-only performance on Apple Silicon is still good.

Future sessions

Each time you open a new terminal, activate the environment before running code:

source .venv/bin/activate      # macOS / Linux
# .venv\Scripts\activate       # Windows

Using a local clone of ellipsoids_eLife2025

If you have a local clone and want to use it instead of the GitHub copy:

pip install -e /path/to/ellipsoids_eLife2025/ellipsoids

---

Examples

Bayesian inference with a finite sinusoidal basis

A key idea in the WPPM is that a smoothness prior is used to leverage data collected across the stimulus space. This notebook illustrates the idea of using such a prior together with Bayesian inference for a simple example. A finite sinusoidal basis is used to represent functions on $[0, 2\pi)$, an exponentially-decaying (with spatial frequency) Gaussian prior over weights on the basis function encodes a preference for smooth functions, and the closed-form Gaussian posterior is computed from a small number of noisy measurements. The example also illustrates the improvement you can get if you use a simple heuristic to drive adaptive measurement sampling.

Run interactively in your browser
View as a static page

Threshold ellipses from pre-computed tables (Hong et al. 2025, Figure 2C)

The WPPM was fit to color discrimination data from eight participants and used to read out threshold ellipses on a 7 × 7 grid of reference stimuli in the isoluminant plane of a 2-D model colour space. This notebook reproduces Figure 2C of Hong et al. (2025) by reading those pre-computed covariance matrices directly from the paper's OSF dataset — no model fitting or JAX computation required. It also shows how to construct the 95 % bootstrap confidence regions reported in the paper: for each of 120 bootstrap model fits, it ranks datasets by their summed Normalized Bures Similarity to the original fit, retains the top 95 % (114/120), and plots the resulting inner/outer radial envelopes as a coloured band around each black ellipse.

Data: download the required OSF data subset once after installation by running python src/hong_etal_2025/download_data.py.

Run interactively in your browser
View as a static page

---

More Hong et al. (2025) notebook examples

Additional notebooks — including ones best run locally from the cloned repository — are listed on the Hong et al. (2025) notebooks wiki page, along with static previews of each.

---

Repository layout

toolbox/                          # reusable Python modules
  basis_posterior/                # Bayesian posterior for finite basis models

src/
  example_finitebasis_gaussian/   # introductory Bayesian inference notebook
    example_finitebasis_gaussian.ipynb
  hong_etal_2025/                 # notebooks and data download for Hong et al. (2025)
    download_data.py              # fetch required OSF data subset
    ellipses_from_tables.ipynb    # reproduce Figure 2C from pre-computed CSV tables
    ellipses_from_fits.ipynb      # reproduce Figure 2C from pkl fit parameters

---

License

See LICENSE.