Psychophysical Modeling and Adaptive Trial Placement

Installation | Documentation | Examples | Contributing

Install (editable)

git clone https://flatironinstitute.github.io/psyphy.git
cd psyphy
pip install -e .

Quickstart

• Go here for a light-weight tutorial that demonstrates how to instantiate, evaluate and fit a model quickly. You should be able to run the underlying script on your CPU.
• Go here for a more comprehensive example visualizing a spatially varying covariance field, also explaining the underlying math. The underlying script for this tutorial requires a GPU.

This package provides:

• Wishart Process Psychophysical Model (WPPM)
  • fit to subject's data
  • predict psychphysical thresholds
  • optional trial placement strategy leveraging model's posterior (e.g., information gain, place next batch of trials such that model's uncertainty is maximally reduced)
• Priors and noise models
  • supports cold and warm starts where warm means initialzing with parameters from previous subjects fitted parameters
  • Noise Model:
    • default: Gaussian
    • supports Student's T
• Task likelihoods
  • currently supports OddityTask, TwoAFC
• Inference engines (MAP, Langevin, Laplace)
• Posterior wrappers and diagnostics
• Trial placement strategies (grid, information gain)
  • supports online and batchwise trial placement
• Experiment session orchestration
  • reading session data and exporting next batch of trial placments

Background

This package implements methods described in:

• Hong et al. (2025). Comprehensive characterization of human color discrimination thresholds.

While the paper above used AEPsych (a Gaussian Process–based trial placer), psyphy integrates trial placement directly with the WPPM posterior (e.g. via InfoGain/EAVC), making the adaptive trial placement model-aware.

Docs

Build and preview the documentation locally:

# from repo root
source .venv/bin/activate
pip install mkdocs mkdocs-material 'mkdocstrings[python]'
mkdocs serve

Build the static site:

mkdocs build

Deploy to GitHub Pages (manual):

mkdocs gh-deploy --clean

For contributors, see CONTRIBUTING.md for full doc guidelines and NumPy-style docstrings.