Custom functions#

Listed below are all functions available in PyBEAM’s custom submodule.

pybeam.custom.functions_test(model_dir, phi, x, t)#

Tests user defined model functions to make sure they are operating as expected.

Parameters:

model_dir (str) – String indicating the directory your model files are located in.
phi (dict) – Dictionary containing model parameter values. Keys are the model parameters, while values are the value associated with that parameter.
x (float) – Sets accumulator state to evaluate functions at.
t (float) – Sets time sot evaluate functions at.

Returns:

Value of each user defined model function at set x and t.

Return type:

list

pybeam.custom.simulate(N_sims, model_dir, phi, seed=False, dt=0.0001)#

Simulates model N_sims times. Outputs dictionary containing two keys, ‘rt_upper’ and ‘rt_lower’, wich contain the reaction times for the upper and lower threshold crossing, respectively.

Parameters:

N_sims (int) – Number of accumulators to simulate.
model_dir (str) – String indicating the directory your model files are located in.
phi (dict) – Dictionary containing model parameter values. Keys are the model parameters, while values are the value associated with that parameter.
seed (int, False) – Sets the random number seed. Defaults to False. If False, PyBEAM randomly chooses a seed.
dt (float) – Sets the simulation time step. By default, dt = 1.0e-4.

Returns:

RT data simulated from your model.

Return type:

dict (values contain numpy arrays)

pybeam.custom.likelihood(model_dir, phi, rt_max, x_res='default', t_res='default')#

Calculates model likelihood function. Outputs dictionary containing the likelihood function for input models and parameter set. Contains three keys: ‘time’, ‘lh_upper’, and ‘lh_lower’. Value for key ‘time’ corresponds to the time array. Values for keys ‘lh_upper’ and ‘lh_lower’ provide the probability of crossing the upper and lower thresholds, respectively, at time t provided in the ‘time’ list.

Parameters:

model_dir (str) – String indicating the directory your model files are located in.
phi (dict) – Dictionary containing model parameter values. Keys are the model parameters, while values are the value associated with that parameter.
rt_max (float) – Sets the time to solve the likelihood function to.
x_res (str, float) – Sets the number of spatial mesh points for the PDE solution. Can be set to integer between 101-501, or resolutions ‘default’ (151), ‘fast’ (101), ‘high’ (251), or ‘max’ (501).
t_res (str) – Sets the time resolution for the PDE solution. Can be set to ‘default’, ‘fast’, ‘high’, or ‘max’. Should be left at ‘default’.

Returns:

Model likelihood function.

Return type:

dict (values contain numpy arrays)

pybeam.custom.loglikelihood(model_dir, phi, rt, x_res='default', t_res='default')#

Calculates model loglikelihood.

Parameters:

model_dir (str) – String indicating the directory your model files are located in.
phi (dict) – Dictionary containing model parameter values. Keys are the model parameters, while values are the value associated with that parameter.
rt (float) – Dictionary containing reaction time data. Must contain two keys, ‘rt_upper’ and ‘rt_lower’, with values of numpy arrays/lists containing the upper and lower threshold crossing data.
N_tnd (int) – Sets the number of integration points for the non-decision time distribution. Ignored if model uses constant non-decision time.
N_mu (int) – Sets the number of integration points for the drift distribution. Ignored if model uses constant drift rate.
x_res (str, float) – Sets the number of spatial mesh points for the PDE solution. Can be set to integer between 101-501, or resolutions ‘default’ (151), ‘fast’ (101), ‘high’ (251), or ‘max’ (501).
t_res (str) – Sets the time resolution for the PDE solution. Can be set to ‘default’, ‘fast’, ‘high’, or ‘max’. Should be left at ‘default’.

Returns:

Loglikelihood of RT data.

Return type:

float

pybeam.custom.plot_rt(model_dir, phi, rt_max, x_res='default', t_res='default', rt=False, bins=False)#

Plots the model likelihood function. If input rt is provided a dictionary containing RT data, a histogram of that data is also plotted.

Parameters:

model_dir (str) – String indicating the directory your model files are located in.
phi (dict) – Dictionary containing model parameter values. Keys are the model parameters, while values are the value associated with that parameter.
rt_max (float) – Sets the time to solve the likelihood function to.
rt (float, False) – Dictionary containing reaction time data. Must contain two keys, ‘rt_upper’ and ‘rt_lower’, with values of numpy arrays/lists containing the upper and lower threshold crossing data. If False, will not plot any RT data.
x_res (str, float) – Sets the number of spatial mesh points for the PDE solution. Can be set to integer between 101-501, or resolutions ‘default’ (151), ‘fast’ (101), ‘high’ (251), or ‘max’ (501).
t_res (str) – Sets the time resolution for the PDE solution. Can be set to ‘default’, ‘fast’, ‘high’, or ‘max’. Should be left at ‘default’.

Returns:

Figure containing model likelihood and histogram of data (if rt is given a dictionary).

Return type:

fig

pybeam.custom.inference(model_dir, priors, conditions, samples, chains, cores, file_name, solver='DEMetropolisZ', x_res='default', t_res='default', tune=0, save_loglike=False)#

Run Bayesian inference on input RT data.

Parameters:

model_dir (str) – String indicating the directory your model files are located in.
priors (dict) – Dictionary containing parameter priors. Key names are arbitrary. The values for each key are strings written in PyMC’s syntax for priors. They can also be constants if you want a parameter to remain fixed at all times.
conditions (dict) – Dictionary containing dictionaries for each model condition. See examples for use.
samples (int) – Sets the number of MCMC samples to run. Recommend at least 25000 samples.
chains (int) – Sets the number of MCMC chains to run. Recomend at least 3 chains.
cores (int) – Sets the number of cpu cores to run the chains on.
file_name (str) – Sets the name of the .nc file output by the solver containing the posteriors. Automatically adds the .nc extension to the string.
sampler (str) – Sets the sampler. Defaults to ‘DEMetropolisZ’, but can also be set to ‘DEMetropolis’.
x_res (str, float) – Sets the number of spatial mesh points for the PDE solution. Can be set to integer between 101-501, or resolutions ‘default’ (151), ‘fast’ (101), ‘high’ (251), or ‘max’ (501).
t_res (str) – Sets the time resolution for the PDE solution. Can be set to ‘default’, ‘fast’, ‘high’, or ‘max’. Should be left at ‘default’.
tune (int) – Sets the amount of MCMC tuning steps. Defaults to zero (recommended for DEMetropolisZ and DEMetropolis, but can sometimes be useful. Test on data if need be).
save_loglikelihood (False, True) – If True, saves the loglikelihood of every MCMC sample. Incurs a 2x speed cost.

Returns:

ArViz idata dataframe containing inference information and .nc file which stores it.

pybeam.custom.plot_idata(file_name, burnin, combined=False)#

Plot Bayesian posteriors output by inference function.

Parameters:

file_name (str) – File name to plot. Input as string omitting .nc extension (automatically added by function).
burnin (int) – Number of samples to throw out from the posterior when plotting.
combined (False, True) – If False, plots each chain posterior independently. If True, combines the posteriors into one curve.

Returns:

Figure containing Bayesian posteriors.

Return type:

fig

pybeam.custom.summary(file_name, burnin)#

Give summary statistics for Bayesian posteriors given by .nc file.

Parameters:

file_name (str) – File name to plot. Input as string omitting .nc extension (automatically added by function).
burnin (int) – Number of samples to throw out from the posterior when plotting.

Returns:

Dataframe containing summary statistics for the input Bayesian posteriors.