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