API Reference

The GLAM class

class GLAM(data=None, name=None)

Bases: object

GLAM model instance that includes data, pymc3.model.Model instance, trace, parameter estimates, fit indices and predictions.

Parameters:
  • data (pandas.DataFrame) –

    DataFrame containing the experimental data. Each row corresponds to one trial. Must include the following columns:

    • subject (int, consecutive, starting with 0)
    • trial (int, starting with 0)
    • choice (int, items should be 0, 1, …, N)
    • rt (float, in seconds)
    • additional variables coding groups or conditions (str or int)

    For each item i in the choice set:

    • item_value_i: The item value (float, best on a scale between 1 and 10)
    • gaze_i: The fraction of total trial time the item was looked at in the trial (float, between 0 and 1)
  • name (str) – A name for the model. Useful if multiple models are fitted and compared.
compute_waic()

Compute WAIC for all appended PyMC3 models.

Returns:Adds WAIC to GLAM model object.
Return type:None
exchange_data(new_data, verbose=True)

Exchange GLAM model data. Useful for out-of-sample predictions using fitted parameters.

Parameters:
  • new_data (pandas.DataFrame) – new data to exchange old data with
  • verbose (bool, optional) – Toggle verbosity.
Returns:

new_data replaces data attribute of GLAM model object
Return type:

None
fit(method='MCMC', **kwargs)

Perform parameter estimation of the model.

Parameters:method (string ['MCMC', 'VI'], optional) – specifies fitting method to use, can be either ‘MCMC’ for MCMC-sampling or ‘VI’ for variational inference. Defaults to ‘MCMC’.
Returns:Adds trace and well as estimates to GLAM model object
Return type:None
make_model(kind='individual', depends_on={'gamma': None, 's': None, 't0': None, 'tau': None, 'v': None}, within_dependent=[], **kwargs)

Build the GLAM PyMC3 model, specifying model kind and dependencies.

Parameters:
  • kind (str, optional) – should be one of [‘individual’, ‘hierarchical’, ‘pooled’], defaults to ‘individual’
  • depends_on (dict, optional) – dictionary specifying for each GLAM model parameter whether the parameter is dependent on any levels of the data e.g. {‘v’: ‘speed’}, here one v parameter is created for each level of the ‘speed’ factor in the response data (factor must be encoded in data)
  • within_dependent (list, optional) – list of parameter names (‘v’, ‘gamma’, ‘s’, ‘tau’) each included parameter is modeled as dependent within a subject (i.e., as drawn from the same meta-distribution) only, if parameter dependency-structure specified in depends_on
Returns:

Adds PyMC3 model, depends_on, within_dependent and design to GLAM model object
Return type:

None
predict(n_repeats=1, boundary=1.0, error_weight=0.05, verbose=True)

Predict choices and RTs for included data

Parameters:
  • n_repeats (int, optional) – Number of repeats of each trial included in data during prediction Defaults to 1.
  • boundary (float, optional) – Magnitude of decision boundary. Defaults to 1.0
  • error_weight (float, optional) – float between [0, 1], defaults to 0.05 determining probability that choice and RT are drawn according to a unifrom error distribution (see manuscript)
  • verbose (bool, optional) – Toggle verbosity.
Returns:

Adds predictions to GLAM model object
Return type:

None
simulate_group(kind='hierarchical', n_individuals=10, n_trials=100, n_items=3, individual_idx=None, stimuli=None, parameters=None, error_weight=0.05, error_range=(0, 5), value_range=(0, 10), label=None, seed=None)

Simulate data from known parameters. Data is added to any existing attached dataframes, which allows blockwise simulation of multiple groups.

Parameters:
  • kind (str, optional) – Should be one of [‘individual’, ‘hierarchical’, ‘pooled’], defaults to ‘hierarchical’
  • n_individuals (int, optional) – number of individuals to be added for this condition
  • n_trials (int, optional) – number of trials per individual
  • n_items (int, optional) – number of items per trial
  • individual_idx (array of ints, optional) – individual indices to use (for within individual design simulation) defaults to continuous participant numbering across conditions
  • stimuli (DataFrame, optional) – instead of simulating item_value and gaze data for the given number of individuals and trials, a DataFrame containing item_values, gaze_data and participant indices can be supplied. This overrides n_individuals and n_trials arguments.
  • parameters (dict, optional) –

    dict with keys: ‘v’, ‘gamma’, ‘s’, ‘t0’, ‘tau’ if kind is individual:

    values: arrays of length n_individual
    if kind is hierarchical:
    values: dicts with keys: mu, sd, bounds
    values: floats for mu, sd, tuple for bounds
  • error_weight (float, optional) – range: [0, 1], probability of simulating error trial with random choice and uniform RT
  • error_range (int tuple of length 2, optional) – range of error RTs
  • value_range (tuple of length 2, optional) – range of item value ratings to be simulated
  • label (str, optional) – condition label. defaults “to condition_n”
  • seed (int, optional) – np.random.seed(argument)
Returns:

Adds data to GLAM model instance
Return type:

None

The analysis and plots submodules