GLAMbox: A toolbox to fit the Gaze-weighted Linear Accumulator Model
GLAMbox is a Python toolbox for investigating the association between gaze allocation and decision behaviour, and applying the Gaze-weighted Linear Accumulator Model (Thomas, Molter et al., 2019).
See the BioRxiv preprint for detailed background, model description and example applications.
A full documentation page of the toolbox is available at https://glambox.readthedocs.io.
GLAMbox is written for Python 3.7 and requires a working Python environment running on your computer. We recommend to install the Anaconda Distribution (available for all major platforms). With the Python environment fully set up, the GLAMbox module can be installed from the command line using pip:
pip install glambox
This command also installs all of GLAMbox's dependencies, which are listed in the
Fitting the GLAM to a dataset can be done in just a few lines of code:
import glambox as gb import pandas as pd # load dataset (format must be GLAMbox compatible, of course) data = pd.read_csv('data.csv') # create the GLAM model object model = gb.GLAM(data) # build the PyMC3 model model.make_model(kind='individual') # perform MCMC sampling model.fit() # inspect parameter estimates print(model.estimates) # predict data using MAP estimates, save predictions model.predict() model.prediction.to_csv('prediction.csv')
A more detailed overview of the available functions can be found in the Basic usage section and the API Reference.
This repository includes Jupyter notebooks with full code for three usage examples outlined in the BioRxiv preprint. The notebook files for these examples can be found in the
examples folder of this repository. They can be downloaded and run interactively with Jupyter (also included in the Anaconda Python distribution). Fully rendered (non-interactive) html versions can be found on the documentation page.
Example 1: Individual gaze biases
In this example, we demonstrate individual model fitting, model comparisons between model variants, and out-of-sample prediction. (Jupyter, html)
Example 2: Hierarchical parameter estimation
In the second example, we demonstrate how to setup a hierarchical model with multiple groups, and compare parameter estimates between groups. (Jupyter, html)
Example 3: Parameter Recovery
In the last example, we demonstrate how to perform a basic parameter recovery analyis for a given dataset, using GLAMbox. (Jupyter, html)
Data format, the
The core functionality of the GLAMbox is implemented in the
GLAM model class. To apply the GLAM to data, an instance of the model class needs to be instantiated and supplied with the experimental data, first:
import glambox as gb glam = gb.GLAM(data=data)
The data must be a pandas (McKinney, 2010) DataFrame with one row per trial, containing the following variable entries:
subject: Subject index (
int, starting with 0)
trial: Trial index (
int, starting with 0)
choice: Chosen item (
int, items should be 0, 1, ..., N)
rt: Response time (
float, in seconds)
- for each item i in the choice set:
item_value_i: The item value (
gaze_i: The fraction of total time in this trial that the participant spent looking at this item (
float, between 0 and 1)
- additional variables coding groups or conditions (
For reference, the first two rows of a pandas DataFrame ready to be used with GLAMbox could look like this:
Next, the respective PyMC3 model, which will later be used to estimate the model's parameters, can be built using the
make_model method. Here, the researcher specifies the kind of the model:
'individual' if the parameters should be estimated for each subject individually,
'hierarchical' for hierarchical parameter estimation, or
'pooled' to estimate a single parameter set for all subjects. At this stage, the researcher can also specify experimental parameter dependencies: For example, a parameter could be expected to vary between groups or conditions. In line with existing modeling toolboxes (e.g., Voss & Voss, 2007; Wiecki, Sofer, Frank, 2013) dependencies are defined using the
depends_on expects a dictionary with parameters as keys and experimental factors as values (e.g.,
depends_on=dict(v='speed') for factor
'speed' with conditions
'slow' in the data). The toolbox internally handles within- and between subject designs and assigns parameters accordingly. If multiple conditions are given for a factor, one parameter will be designated for each condition. Finally, the
make_model method allows parameters to be fixed to a specific value using the
*_val arguments (e.g.,
gamma_val=1 for a model without gaze bias). If parameters should be fixed for individual subjects, a list of individual values needs to be passed.
model.make_model(kind='individual', depends_on=dict(v='speed'), gamma_val=1)
Once the PyMC3 model is built, parameters can be estimated using the
model.fit(method='MCMC', tune=5000, draws=5000)
fit method defaults to Metropolis Hastings Markov-Chain-Monte-Carlo (MCMC) sampling, but also allows for Variational Inference.
Accessing parameter estimates
After parameter estimation is completed, the resulting estimates can be accessed with the
estimates attribute of the GLAM model instance. This returns a table with one row for each set of parameter estimates for each individual and condition in the data. For each parameter, a maximum a posteriori (MAP) estimate is given, in addition to the 95% Highest-Posterior Density Interval (HPD). If the parameters were estimated hierarchically, the table also contains estimates of the group-level parameters.
Comparing parameters between groups or conditions
Parameter estimates can be compared between different experimental groups or conditions (specified with the
depends_on keyword when calling
make_model) using the
compare_parameters function from the
analysis module. It takes as input the fitted GLAM instance, a list of parameters (
'tau'), and a list of pairwise comparisons between groups or conditions. The comparison argument expects a list of tuples (e.g.,
[('group1', 'group2'), ('group1', 'group3')]). For example, given a fitted model instance (here
glam) a comparison of the $\gamma$ parameter between two groups (
group2) can be computed as:
from gb.analysis import compare_parameters comparison = compare_parameters(model=glam, parameters=['gamma'], comparisons=[('group1', 'group2')])
The function then returns a table with one row per specified comparison, and columns containing the mean posterior difference, percentage of the posterior above zero, and corresponding 95% HPD interval. If supplied with a hierarchical model, the function computes differences between group-level parameters. If an individual type model is given, it returns comparison statistics for each individual.
Comparisons can be visualized using the
compare_parameters function from the
plots module. It takes the same input as its analogue in the
analysis module. It plots posterior distributions of parameters and the posterior distributions of any differences specified using the
comparisons argument. For a usage example and plot see usage example 2 in the full documentation.
Comparing model variants
Model comparisons between multiple GLAM variants (e.g., full and restricted variants) can be performed using the
compare_models function, which wraps the function of the same name from the PyMC3 library. The
compare_models function takes as input a list of fitted model instances that are to be compared. Additional keyword arguments can be given and are passed on to the underlying PyMC3
compare function. This allows the user, for example, to specify the information criterion used for the comparison via the
ic argument (
'LOO' for Leave-One-Out cross validation). It returns a table containing an estimate of the specified information criterion, standard errors, difference to the best-fitting model, standard error of the difference, and other output variables from PyMC3 for each inputted model (and subject, if individually estimated models were given). We refer the reader to usage example 1 in the full documentation for the full code and exemplary output from the
Predicting choices and response times
Choices and RTs can be predicted with the GLAM by the use of the
For each trial of the dataset that is attached to the model instance, this method predicts a choice and RT using the previously determined MAP parameter estimates. To obtain a stable estimate of the GLAM's predictions, as well as the noise contained within them, it is recommended to repeat every trial multiple times during the prediction. The number of trial repeats can be specified with the
n_repeats argument. After the prediction is completed, the predicted data can be accessed with the
prediction attribute of the model.
- McKinney, W. (2010, June). Data structures for statistical computing in python. In Proceedings of the 9th Python in Science Conference (Vol. 445, pp. 51-56).
- Thomas, A. W., Molter, F., Krajbich, I., Heekeren, H. R., & Mohr, P. N. (2019). Gaze bias differences capture individual choice behaviour. Nature human behaviour, 3(6), 625.
- Voss, A., & Voss, J. (2007). Fast-dm: A free program for efficient diffusion model analysis. Behavior Research Methods, 39(4), 767-775.
- Wiecki, T. V., Sofer, I., & Frank, M. J. (2013). HDDM: Hierarchical Bayesian estimation of the drift-diffusion model in Python. Frontiers in neuroinformatics, 7, 14.
Release history Release notifications | RSS feed
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.