Precoded functions#

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

pybeam.precoded.simulate(model, N_sims, phi, dt=0.0001, seed=False)#

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:

  • model (class) – PyBEAM class object containing model information. See Precoded Tutorial 1 for usage.

  • N_sims (int) – Number of accumulators to simulate.

  • phi (dict) – Dictionary containing model parameter values. Keys are the model parameters, while values are the value associated with that parameter. If keys are unknown for your model, check model class attribute parameters (i.e. run model.parameters()). The output list provides the keys for this dictionary.

  • dt (float) – Sets the simulation time step. By default, dt = 1.0e-4.

  • seed (int, False) – Sets the random number seed. Defaults to False. If False, PyBEAM randomly chooses a seed.

Returns:

RT data simulated from your model.

Return type:

dict (values contain numpy arrays)

pybeam.precoded.likelihood(model, phi, rt_max, N_tnd=100, N_mu=10, x_res='default', t_res='default', dt_interp_scale=1.0, dt_interp_overide=0.0)#

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 (class) – PyBEAM class object containing model information. See Precoded Tutorial 1 for usage.

  • phi (dict) – Dictionary containing model parameter values. Keys are the model parameters, while values are the value associated with that parameter. If keys are unknown for your model, check model class attribute parameters (i.e. run model.parameters()). The output list provides the keys for this dictionary.

  • rt_max (float) – Sets the time to solve the likelihood function to.

  • 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’.

  • (DEPRECATED) (dt_interp_overide) – Sets the interpolation resolution. If 1.0, interpolation resolution equals the estimated time step. Otherwise, multiplies estimated time step by this value. Should be left at 1.0.

  • (DEPRECATED) – Allows user to automatically set interpolation resolution. If 0.0, interpolation step set by program. Should be left at 0.0.

Returns:

Model likelihood function.

Return type:

dict (values contain numpy arrays)

pybeam.precoded.loglikelihood(model, phi, rt, pointwise=False, N_tnd=100, N_mu=10, x_res='default', t_res='default', dt_interp_scale=1.0, dt_interp_overide=0.0)#

Calculates model loglikelihood function. If pointwise = False, outputs sum loglikelihood of all data. If pointwise = True, outputs loglikelihood of each individual data point.

Parameters:

  • model (class) – PyBEAM class object containing model information. See Precoded Tutorial 1 for usage.

  • phi (dict) – Dictionary containing model parameter values. Keys are the model parameters, while values are the value associated with that parameter. If keys are unknown for your model, check model class attribute parameters (i.e. run model.parameters()). The output list provides the keys for this dictionary.

  • 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’.

  • (DEPRECATED) (dt_interp_overide) – Sets the interpolation resolution. If 1.0, interpolation resolution equals the estimated time step. Otherwise, multiplies estimated time step by this value. Should be left at 1.0.

  • (DEPRECATED) – Allows user to automatically set interpolation resolution. If 0.0, interpolation step set by program. Should be left at 0.0.

Returns:

Loglikelihood of RT data.

Return type:

float (pointwise = False), dict (pointwise = True) with numpy arrays as values

pybeam.precoded.plot_rt(model, phi, rt_max, rt=False, bins=25, figsize=(6.4, 4), dpi=100, N_tnd=100, N_mu=10, x_res='default', t_res='default', dt_interp_scale=1.0, dt_interp_overide=0.0)#

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 (class) – PyBEAM class object containing model information. See Precoded Tutorial 1 for usage.

  • phi (dict) – Dictionary containing model parameter values. Keys are the model parameters, while values are the value associated with that parameter. If keys are unknown for your model, check model class attribute parameters (i.e. run model.parameters()). The output list provides the keys for this dictionary.

  • 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.

  • 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’.

  • (DEPRECATED) (dt_interp_overide) – Sets the interpolation resolution. If 1.0, interpolation resolution equals the estimated time step. Otherwise, multiplies estimated time step by this value. Should be left at 1.0.

  • (DEPRECATED) – Allows user to automatically set interpolation resolution. If 0.0, interpolation step set by program. Should be left at 0.0.

Returns:

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

Return type:

fig

pybeam.precoded.inference(model, priors, conditions, samples, chains, cores, file_name, dt_interp_scale=1.0, dt_interp_overide=0.0, N_tnd=100, N_mu=10, sampler='DEMetropolisZ', x_res='default', t_res='default', tune=0, save_loglikelihood=False)#

Run Bayesian inference on input RT data.

Parameters:

  • model (class) – PyBEAM class object containing model information. See Precoded Tutorial 1 for usage.

  • 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.

  • (DEPRECATED) (dt_interp_overide) – Sets the interpolation resolution. If 1.0, interpolation resolution equals the estimated time step. Otherwise, multiplies estimated time step by this value. Should be left at 1.0.

  • (DEPRECATED) – Allows user to automatically set interpolation resolution. If 0.0, interpolation step set by program. Should be left at 0.0.

  • 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.

  • 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.precoded.plot_idata(file_name, burnin, combined=False, compact=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.precoded.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.