This repository contains a toolbox for model fitting and plotting of ideal observer models for the IBL task. For the moment, the code is only available in Matlab.
- Download or clone the repository on your local computer.
- Add the base folder of the repository (which contains the
ibl_changepoint_add2path.m
file) to your Matlab path. Warning: It is not recommended to permanently add the entire repository tree to your Matlab path, since this might cause function name clashes with other projects. - If you do not already have them, install Bayesian Adaptive Direct Search (BADS; an optimization toolbox) from here and Variational Bayesian Monte Carlo (VBMC; an approximate posterior inference toolbox) from here.
- Download the IBL data for the exemplar mice to CSV files in the
data
folder using this Python script (you will need IBL access credentials).
As a simple example, we are going to fit an "omniscient" Bayesian observer to a mouse stable-sessions data, assuming a biased lapse (see below for an explanation). The exemplar mice are CSHL_005
,CSHL_007
,IBL-T1
,IBL-T4
,ibl_witten_04
,ibl_witten_05
; we are going here to fit the first one:
ibl_changepoint_add2path; % Add the changepoint analysis toolbox to the Matlab path for this session
model_name = 'omniscient_contrastnoise_biasedlapse';
mouse_name = 'CSHL_005';
data = read_data_from_csv(mouse_name);
Nopts = 1; % Perform only one optimization (but you should use multiple starting points)
params = fit_model(model_name,data,Nopts);
plot_fit(data,params);
The available models are:
psychofun
: simple psychometric function fit (separately for each probability level).omniscient
: "omniscient" Bayesian observer that knows the true stimulus probability in each block.changepoint
: change-point Bayesian observer that tracks the stimulus probability from trial to trial.exponential
: observer that estimates side probability as an exponentially weighted-average of last trials, with Beta prior representing additional prior observations (pseudo-counts).
Specific features can be added to the base observer models, separated by subscripts:
_lapse
: adds a probabilitylapse_rate
of a random response with equal probability._biasedlapse
: as above, but lapses have alapse_bias
probability of responding "Left" (lapse_bias = 0.5
is unbiased lapse)._softmax
: adds a softmax probabilistic step to the decision rule._runlength
: adds flexibility to run-length related parameters (changepoint
observer only)._freesym
: adds flexibility to the a-priori block probabilities for biased blocks, assuming symmetry (changepoint
observer only)._nobias
: removes Beta prior over observations (exponential
model only).
Specific noise models are added as:
_contrastnoise
: a simple noise model based on a noisy measurement of the contrast level (recommended)._nakarusthon
: a noise model inspired by the Naka-Rushton model of contrast perception.
Multiple datasets and models can be fitted in batch by using the batch_model_fit.m
function.
If a dataset name is suffixed with _unbiased
, only unbiased (50/50) blocks are loaded.
If you are interested in estimating model parameters, you can find them in the params
struct returned by the fit_model
function. In particular:
params.names
contains the names of the fitted parameters.params.theta
stores a vector representing the maximum-likelihood estimate of the parameters. However, be aware that these parameters values are in a transformed space used for fitting (e.g., some parameters are transformed to log space, or to square-root space).params.(parameter_name)
, whereparameter_name
is one of the names of fitted parameters, contain the individual parameters used by the model (in the returnedparams
struct, at their maximum-likelihood value). These are the parameters you may want to take, since they use the standard parametrization.
The fit_all_unbiased.m
script contains the entire pipeline to fit psychometric functions and several "omniscient" models to the unbiased data only, in order to make predictions about the mice behavior in the full sessions that include change-point blocks.
The scripts
folder contains bash scripts to launch several jobs on a computer cluster (which uses the Slurm job manager).
Note that in addition to obtaining maximum-likelihood estimates of the parameters (via BADS), we also compute (approximate) Bayesian posteriors using VBMC.
The IBL change-point toolbox is work in progress, and I plan to extend the documentation where needed. In the meanwhile, for any question please drop me an email at luigi.acerbi@unige.ch.
The IBL change-point toolbox is released under the terms of the MIT license.