Metadata-Version: 2.4
Name: psihope
Version: 0.1.0
Summary: High-dimensional Online Particle Estimation (HOPE) for psychophysical experiments
Project-URL: Homepage, https://github.com/ag-perception-wallis-lab/hope
Project-URL: Issues, https://github.com/ag-perception-wallis-lab/hope/issues
Author-email: "Lars C. Reining" <lars.reining@tu-darmstadt.de>
License-Expression: MIT
License-File: LICENSE
Keywords: adaptive methods,bayesian,particle filter,psychophysics
Requires-Python: >=3.10
Requires-Dist: numpy>=2.2.6
Requires-Dist: scipy>=1.15.3
Requires-Dist: torch>=2.12.0
Description-Content-Type: text/markdown

# High-dimensional Online Particle Estimation (HOPE) for psychophysical experiments

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://badge.fury.io/py/psihope.svg)](https://badge.fury.io/py/psihope)

HOPE (High-dimensional Online Particle Estimation) is a Python package for adaptive psychophysics experiments. 

Given a parametric psychometric function and a discrete stimulus pool, it selects the next stimulus with maximum expected information gain. It uses a posterior approximation based on a combined particle filtering–MCMC approach. This is fast enough for real-time use within the inter-stimulus interval for feature spaces up to 50 dimensions, typically under one second on standard hardware and with a stimulus pool of 10,000 stimuli. The package includes a set of predefined psychometric functions, but users can also supply their own. It is designed to integrate with PsychoPy experiments.


## Installation

You can install HOPE using pip:

```bash
pip install psihope
```

## Usage

```python
from hope import HopeSampler
from hope.psychometric_functions import logistic_regression
from hope.psychometric_model import BinaryPsychometricModel

# 1. Define your priors
priors = {
    "bias": stats.norm(scale=1),
    "weights": stats.multivariate_normal(mean=np.zeros(2), cov=np.eye(2)),
}

# 2. Define your model
psychometric_model = BinaryPsychometricModel(
    psychometric_function=logistic_regression, # choose from our library of psychometric functions or define your own
    priors=priors,
)

# 3. Initialize the sampler
# define your stimulus pool here as a list of stimulus configurations
stimulus_pool = ... 
sampler = HopeSampler(
    psychometric_model=psychometric_model,
    stimulus_pool=stimulus_pool,
    seed=seed,
)

# 4. Run the experiment
for trial in range(num_trials):
    stimulus = sampler.get_next_stimulus()

    # Collect response from participant using e.g. PsychoPy
    response = ...

    sampler.update_posterior(stimulus, response)
```

For more advanced usage and more explanations refer to the [examples](examples/) directory.

## Citation

TODO