How to initialize a model

To initialize a model, you can use one of the following model classes:

1. For simple reinforcement learning models: RLModel_2A

2. For diffusion decision models: DDModel

3. For reinforcement learning diffusion decision models: RLDDModel

4. For race models: RDModel_2A, LBAModel_2A, ARDModel_2A, ALBAModel_2A

5. For reinforcement learning race models: RLRDModel_2A, RLLBAModel_2A, RLARDModel_2A, RLALBAModel_2A

All these classes have 1 non-default argument: hierarchical_levels. This should be set to 1 for model fits on individual data, and 2 for model fits on group data.

Additional arguments can be specified in order to “turn on and off” different model mechanisms that are implemented.

For example, let’s say I want to specify a RLDDM for 1 subject:

import rlssm

model = rlssm.RLDDModel(hierarchical_levels=1)

Using cached StanModel

After initialization, you can inspect the model’s default priors. You can change these when you fit the model.

model.priors

{'alpha_priors': {'mu': 0, 'sd': 1},
 'drift_scaling_priors': {'mu': 1, 'sd': 50},
 'threshold_priors': {'mu': 1, 'sd': 5},
 'ndt_priors': {'mu': 1, 'sd': 1}}

Note that, if this is the first time that you initialize this type of model, it’s going to take some time to compile it. Otherwise, the cashed model will be automatically loaded.

By default, all mechanisms are “off”, meaning that the simplest model is fit, so you need to set alternative mechanisms to True to have them included in your model:

model_complex = rlssm.DDModel(hierarchical_levels=1,
                              drift_variability = True,
                              starting_point_variability=True)

Using cached StanModel

model_complex.priors

{'threshold_priors': {'mu': 0, 'sd': 5},
 'ndt_priors': {'mu': 0, 'sd': 5},
 'drift_trialmu_priors': {'mu': 1, 'sd': 5},
 'drift_trialsd_priors': {'mu': 0, 'sd': 5},
 'rel_sp_trialmu_priors': {'mu': 0, 'sd': 0.8},
 'rel_sp_trialsd_priors': {'mu': 0, 'sd': 0.5}}

You can check what are the possible mechanisms for each class in the API reference guide, or by typing:

rlssm.DDModel?

Init signature:
rlssm.DDModel(
    hierarchical_levels,
    starting_point_bias=False,
    drift_variability=False,
    starting_point_variability=False,
    drift_starting_point_correlation=False,
    drift_starting_point_beta_correlation=False,
    drift_starting_point_regression=False,
)
Docstring:
DDModel allows to specify a diffusion decision model.

When initializing the model, you should specify whether the model is hierarchical or not.
Additionally, you can specify the mechanisms that you wish to include or exclude.

The underlying stan model will be compiled if no previously compiled model is found.
After initializing the model, it can be fitted to a particular dataset using pystan.
Init docstring:
Initialize a DDModel object.

Note
----
This model is restricted to two options per trial (coded as correct and incorrect).

Parameters
----------

hierarchical_levels : int
    Set to 1 for individual data and to 2 for grouped data.

starting_point_bias : bool, default False
    By default, there is no starting point bias.
    If set to True, the starting point bias is estimated.

drift_variability : bool, default False
    By default, there is no drift-rate variability across trials.
    If set to True, the standard deviation of the drift-rate across trials is estimated.

starting_point_variability : bool, default False
    By default, there is no starting point bias variability across trials.
    If set to True, the standard deviation of the starting point bias across trials
    is estimated.

drift_starting_point_correlation : bool, default False
    By default, the correlation between these 2 parameters is not estimated.
    If set to True, the 2 parameters are assumed to come
    from a multinormal distribution.
    Only relevant when drift_variability and starting_point_variability are True.

drift_starting_point_beta_correlation : bool, default False
    If True, trial-by-trial drift-rate, rel_sp and an external
    variable beta are assumed to come from a multinormal distribution.
         Only relevant when drift_variability and starting_point_variability are True.

drift_starting_point_regression : bool, default False
    If True, two regression coefficients are estimated, for trial drift
    and relative starting point, and an external variable beta.
    Only relevant when drift_variability and starting_point_variability are True.

Attributes
----------
model_label : str
    The label of the fully specified model.

n_parameters_individual : int
    The number of individual parameters of the fully specified model.

n_parameters_trial : int
    The number of parameters that are estimated at a trial level.

stan_model_path : str
    The location of the stan model code.

compiled_model : pystan.StanModel
    The compiled stan model.
File:           ~/git/rlssm/rlssm/models_DDM.py
Type:           type
Subclasses: