ModelResults class for race (or RL+race) models

There is one class to inspect model fits of race models (RDM, LBA, ARDM, and ALBA) or combinations of RL and race models (fitted on choices and response times): raceModelResults_2A.

The main functions of this class are:

To assess the model’s convergence and mcmc diagnostics, to make sure that the sampling was successful. This step is crucial and should be preferably done first.
To provide a measure of the model’s quantitative fit to the data (i.e., the Watanabe-Akaike information criterion). This is important when comparing the quantitative fit to the data of several, competing models.
To visualize and make interval-based (either Bayesian Credible Intervals or Higher Density Intervals) inferences on the posterior distributions of the model’s parameters. This is important when specific hypotheses were made about the parameters’ values.
To calculate and visualize posterior predictive distributions of the observed data. This step is important to assess the qualitative fit of the model to the data. Qualitative fit should be assessed not only when comparing different competing models, but also when a single candidate model is fitted. Different ways of calculating posterior predictive distributions are provided, together with different plotting options. In general, emphasis is given to calculating posterior predictive distributions across conditions. This allows us to assess whether a certain behavioral pattern observed in the data (e.g., due to experimental manipulations) can also be reproduced by the model. Finally, posterior predictives are available not only for mean choices and response times, but also for other summary statistics of the response times distributions (i.e., skewness and quantiles).

All models

class rlssm.fits_race.ModelResults(model_label, data_info, parameters_info, priors, rhat, waic, last_values, samples, trial_samples)

plot_posteriors(gridsize=100, clip=None, show_intervals='HDI', alpha_intervals=0.05, intervals_kws=None, **kwargs)

Plots posterior predictives of the model’s parameters.

If the model is hierarchical, then only the group parameters are plotted. In particular, group means are plotted in the first row and group standard deviations are plotted in the second row. By default, 95 percent HDI are shown. The kernel density estimation is calculated using scipy.stats.gaussian_kde.

Parameters

gridsize (int, default to 100) – Resolution of the kernel density estimation function, default to 100.
clip (tuple of (float, float), optional) – Range for the kernel density estimation function. Default is min and max values of the distribution.
show_intervals (str, default to "HDI") – Either “HDI”, “BCI”, or None. HDI is better when the distribution is not simmetrical. If None, then no intervals are shown.
alpha_intervals (float, default to .05) – Alpha level for the intervals. Default is 5 percent which gives 95 percent BCIs and HDIs.
intervals_kws (dict) – Additional arguments for matplotlib.axes.Axes.fill_between that shows shaded intervals. By default, they are 50 percent transparent.
**kwargs – Additional parameters for seaborn.FacetGrid.

Returns

g

Return type

seaborn.FacetGrid

to_pickle(filename=None)

Pickle the fitted model’s results object to file.

This can be used to store the model’s result and read them and inspect them at a later stage, without having to refit the model.

Parameters: filename (str, optional) – File path where the pickled object will be stored. If not specified, is set to

Race diffusion models (RDM, LBA, ARDM, and ALBA)

class rlssm.fits_race.raceModelResults_2A(model_label, data_info, parameters_info, priors, rhat, waic, last_values, samples, trial_samples, family)

show-inheritance

inherited-members

get_grouped_posterior_predictives_summary(grouping_vars, n_posterior_predictives=500, quantiles=None, **kwargs)

Calculates summary of posterior predictives of choices and response times, separately for a list of grouping variables.

The mean proportion of choices (in this case coded as accuracy) is calculated for each posterior sample across all trials in all conditions combination. Response times are summarized using mean, skewness, and quantiles.

For example, if grouping_vars=[‘reward’, ‘difficulty’], posterior predictives will be collapsed for all combinations of levels of the reward and difficulty variables.

Parameters

grouping_vars (list of strings) – They should be existing grouping variables in the data.
n_posterior_predictives (int) – Number of posterior samples to use for posterior predictives calculation. If n_posterior_predictives is bigger than the posterior samples, then calculation will continue with the total number of posterior samples.
quantiles (list of floats) – Quantiles to summarize response times distributions (separately for correct/incorrect) with.
noise_constant (float) – Scaling factor of the diffusion decision model. If changed, drift and threshold would be scaled accordingly. Not to be changed in most applications.
rt_max (float) – Controls the maximum rts that can be predicted. Making this higher might make the function a bit slower.
dt (float) – Controls the time resolution of the diffusion decision model. Default is 1 msec. Lower values of dt make the function more precise but much slower.

Returns

out – Pandas DataFrame. The columns contains the mean accuracy for each posterior sample, as well as mean response times, response times skewness and response times quantiles. The row index is a pandas.MultIndex, with the grouping variables as higher level and number of samples as lower level.

Return type

DataFrame

get_posterior_predictives_df(n_posterior_predictives=500, **kwargs)

Calculates posterior predictives of choices and response times.

Parameters

n_posterior_predictives (int) – Number of posterior samples to use for posterior predictives calculation. If n_posterior_predictives is bigger than the posterior samples, then calculation will continue with the total number of posterior samples.
noise_constant (float) – Scaling factor of the diffusion decision model. If changed, drift and threshold would be scaled accordingly. Not to be changed in most applications.
rt_max (float) – Controls the maximum rts that can be predicted. Making this higher might make the function a bit slower.
dt (float) – Controls the time resolution of the diffusion decision model. Default is 1 msec. Lower values of dt make the function more precise but much slower.

Returns

out – Data frame of shape (n_samples, n_trials*2). Response times and accuracy are provided as hierarchical column indeces.

Return type

DataFrame

get_posterior_predictives_summary(n_posterior_predictives=500, quantiles=None, **kwargs)

Calculates summary of posterior predictives of choices and response times.

The mean proportion of choices (in this case coded as accuracy) is calculated for each posterior sample across all trials. Response times are summarized using mean, skewness, and quantiles.

Parameters

n_posterior_predictives (int) – Number of posterior samples to use for posterior predictives calculation. If n_posterior_predictives is bigger than the posterior samples, then calculation will continue with the total number of posterior samples.
quantiles (list of floats) – Quantiles to summarize response times distributions (separately for correct/incorrect) with. Default to [.1, .3, .5, .7, .9].
noise_constant (float) – Scaling factor of the diffusion decision model. If changed, drift and threshold would be scaled accordingly. Not to be changed in most applications.
rt_max (float) – Controls the maximum rts that can be predicted. Making this higher might make the function a bit slower.
dt (float) – Controls the time resolution of the diffusion decision model. Default is 1 msec. Lower values of dt make the function more precise but much slower.

Returns

out – Pandas DataFrame, where every row corresponds to a posterior sample. The columns contains the mean accuracy for each posterior sample, as well as mean response times, response times skewness and response times quantiles.

Return type

DataFrame

plot_mean_grouped_posterior_predictives(grouping_vars, n_posterior_predictives, figsize=(20, 8), post_pred_kws=None, **kwargs)

Plots the mean posterior predictives of choices and response times, separately for either 1 or 2 grouping variables.

The first grouping variable will be plotted on the x-axis. The second grouping variable, if provided, will be showed with a different color per variable level.

Parameters

grouping_vars (list of strings) – They should be existing grouping variables in the data. The list should be of lenght 1 or 2.
n_posterior_predictives (int) – Number of posterior samples to use for posterior predictives calculation. If n_posterior_predictives is bigger than the posterior samples, then calculation will continue with the total number of posterior samples.
x_order (list of strings) – Order to plot the levels of the first grouping variable in, otherwise the levels are inferred from the data objects.
hue_order (lists of strings) – Order to plot the levels of the second grouping variable (when provided) in, otherwise the levels are inferred from the data objects.
hue_labels (list of strings) – Labels corresponding to hue_order in the legend. Advised to specify hue_order when using this to avoid confusion. Only makes sense when the second grouping variable is provided.
show_data (bool) – Whether to show a vertical line for the mean data. Set to False to not show it.
show_intervals (either "HDI", "BCI", or None) – HDI is better when the distribution is not simmetrical. If None, then no intervals are shown.
alpha_intervals (float) – Alpha level for the intervals. Default is 5 percent which gives 95 percent BCIs and HDIs.
palette (palette name, list, or dict) – Colors to use for the different levels of the second grouping variable (when provided). Should be something that can be interpreted by color_palette(), or a dictionary mapping hue levels to matplotlib colors.
color (matplotlib color) – Color for both the mean data and intervals. Only used when there is 1 grouping variable.
ax (matplotlib axis, optional) – If provided, plot on this axis. Default is set to current Axes.
intervals_kws (dictionary) –

Additional arguments for the matplotlib fill_between function
that shows shaded intervals. By default, they are 50 percent transparent.

post_pred_kwsdictionary
Additional parameters to get_grouped_posterior_predictives_summary.

Returns

fig

Return type

matplotlib.figure.Figure

plot_mean_posterior_predictives(n_posterior_predictives, figsize=(20, 8), post_pred_kws=None, **kwargs)

Plots the mean posterior predictives of choices and response times.

The mean proportion of choices (in this case coded as accuracy) is calculated for each posterior sample across all trials, and then it’s plotted as a distribution. The mean accuracy in the data is plotted as vertical line. This allows to compare the real mean with the BCI or HDI of the predictions. The same is done for response times, and are plotted one next to each other.

Parameters

n_posterior_predictives (int) – Number of posterior samples to use for posterior predictives calculation. If n_posterior_predictives is bigger than the posterior samples, then calculation will continue with the total number of posterior samples.
figsize (tuple) – figure size of the matplotlib figure
show_data (bool) – Whether to show a vertical line for the mean data. Set to False to not show it.
color (matplotlib color) – Color for both the mean data and intervals.
ax (matplotlib axis, optional) – If provided, plot on this axis. Default is set to current Axes.
gridsize (int) – Resolution of the kernel density estimation function, default to 100.
clip (tuple) – Range for the kernel density estimation function. Default is min and max values of the distribution.
show_intervals (either "HDI", "BCI", or None) – HDI is better when the distribution is not simmetrical. If None, then no intervals are shown.
alpha_intervals (float) – Alpha level for the intervals. Default is 5 percent which gives 95 percent BCIs and HDIs.
intervals_kws (dictionary) – Additional arguments for the matplotlib fill_between function that shows shaded intervals. By default, they are 50 percent transparent.
post_pred_kws (dictionary) – Additional parameters to get_posterior_predictives_summary.

Returns

fig

Return type

matplotlib.figure.Figure

plot_quantiles_grouped_posterior_predictives(n_posterior_predictives, grouping_var, quantiles=None, figsize=(20, 8), post_pred_kws=None, **kwargs)

Plots the quantiles of the posterior predictives of response times, separately for correct/incorrect responses, and 1 grouping variable.

Parameters

n_posterior_predictives (int) – Number of posterior samples to use for posterior predictives calculation. If n_posterior_predictives is bigger than the posterior samples, then calculation will continue with the total number of posterior samples.
grouping_vars (string) – Should be an existing grouping variable in the data.
quantiles (list of floats) – Quantiles to summarize response times distributions (separately for correct/incorrect) with.
figsize (tuple) – figure size of the matplotlib figure
show_data (bool) – Whether to show the quantiles of the data. Set to False to not show it.
show_intervals (either "HDI", "BCI", or None) – HDI is better when the distribution is not simmetrical. If None, then no intervals are shown.
alpha_intervals (float) – Alpha level for the intervals. Default is 5 percent which gives 95 percent BCIs and HDIs.
kind (either 'lines' or 'shades') – Two different styles to plot quantile distributions.
palette (palette name, list, or dict) – Colors to use for the different levels of the second grouping variable (when provided). Should be something that can be interpreted by color_palette(), or a dictionary mapping hue levels to matplotlib colors.
hue_order (lists of strings) – Order to plot the levels of the grouping variable in, otherwise the levels are inferred from the data objects.
hue_labels (list of strings) – Labels corresponding to hue_order in the legend. Advised to specify hue_order when using this to avoid confusion.
jitter (float) – Amount to jitter the grouping variable’s levels for better visualization.
scatter_kws (dictionary) – Additional plotting parameters to change how the data points are shown.
intervals_kws (dictionary) – Additional plotting parameters to change how the quantile distributions are shown.
post_pred_kws (dictionary) – Additional parameters to get_grouped_posterior_predictives_summary.

Returns

fig

Return type

matplotlib.figure.Figure

plot_quantiles_posterior_predictives(n_posterior_predictives, quantiles=None, figsize=(20, 8), post_pred_kws=None, **kwargs)

Plots the quantiles of the posterior predictives of response times, separately for correct/incorrect responses.

Parameters

n_posterior_predictives (int) – Number of posterior samples to use for posterior predictives calculation. If n_posterior_predictives is bigger than the posterior samples, then calculation will continue with the total number of posterior samples.
quantiles (list of floats) – Quantiles to summarize response times distributions (separately for correct/incorrect) with.
figsize (tuple) – figure size of the matplotlib figure
show_data (bool) – Whether to show the quantiles of the data. Set to False to not show it.
show_intervals (either "HDI", "BCI", or None) – HDI is better when the distribution is not simmetrical. If None, then no intervals are shown.
alpha_intervals (float) – Alpha level for the intervals. Default is 5 percent which gives 95 percent BCIs and HDIs.
kind (either 'lines' or 'shades') – Two different styles to plot quantile distributions.
color (matplotlib color) – Color for both the data and intervals.
scatter_kws (dictionary) – Additional plotting parameters to change how the data points are shown.
intervals_kws (dictionary) – Additional plotting parameters to change how the quantile distributions are shown.
post_pred_kws (dictionary) – Additional parameters to get_posterior_predictives_summary.

Returns

fig

Return type

matplotlib.figure.Figure

Reinforcement learning race diffusion models (RLRDM, RLLBA, RLARDM, and RLALBA)

See raceModelResults_2A.