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
- data (pandas.DataFrame) –