AbstractDDM <: SSM2D

An abstract type for the drift diffusion model.

AbstractLBA <: SSM2D

An abstract type for the linear ballistic accumulator model.

AbstractLCA <: SSM2D

An abstract type for the leaky competing accumulator model

AbstractLNR <: SSM2D

An abstract type for the lognormal race model

AbstractMDFT <: SSM2D

AbstractMLBA <: AbstractLBA

An abstract type for the multi-attribute linear ballistic accumulator

AbstractPoissonRace <: SSM2D

An abstract type for the Poisson race model.

AbstractRDM <: SSM2D

An abstract type for the racing diffusion model.

AbstractShiftedLogNormal <: SSM1D

An abstract type for the shifted lognormal model.

AbstractWald <: SSM1D

An abstract type for the Wald model.

AbstractaDDM <: SSM2D

An abstract type for the attentional drift diffusion model.

AbstractstDDM <: SSM2D

An abstract type for the starting-time diffusion decision model.

CDDM{T<:Real} <: AbstractCDDM

A circular drift diffusion model (CDDM) for continous responding. CCDM is typically applied to continous report of color in visual working memory tasks. Currently supports the 2D case.

Parameters

• ν::T: a vector drift rates. ν₁ is the mean drift rate along the x-axis; ν₂ is the mean drift rate along the y-axis. ν ∈ ℝⁿ.
• σ::T: intra-trial drift rate variability. σ ∈ ℝ.
• η::T: a vector across-trial standard deviations of drift rates. η₁ is the standard deviation of drift rate along the x-axis; η₂ is the standard deviation of drift rate along the y-axis. η ∈ ℝⁿ⁺.
• α::T: response boundary as measured by the radius of a circle. α ∈ ℝ⁺.
• τ::T: mean non-decision time. τ ∈ [0, min_rt].

Constructors

Two constructors are defined below. The first constructor uses positional arguments, and is therefore order dependent:

CDDM(ν, σ, η, α, τ)

The second constructor uses keywords with default values, and is not order dependent:

CDDM(; ν=[1,.5], η=[1,1], σ=1, α=1.5, τ=0.30)

Example

using SequentialSamplingModels
dist = CDDM(;ν=[1,.5], η=[1,1], σ=1, α=1.5, τ=0.30)
data = rand(dist, 10)
like = pdf(dist, data)
loglike = logpdf(dist, data)

References

Smith, P. L. (2016). Diffusion theory of decision making in continuous report. Psychological Review, 123(4), 425.

Smith, P. L., Garrett, P. M., & Zhou, J. (2023). Obtaining Stable Predicted Distributions of Response Times and Decision Outcomes for the Circular Diffusion Model. Computational Brain & Behavior, 1-13.

ClassicMDFT{T <: Real} <: AbstractMDFT

A model type for Multiattribute Decision Field Theory.

Parameters

• σ::T = 1.0: diffusion noise. σ ∈ ℝ⁺.
• α::T = 15.0: evidence threshold. α ∈ ℝ⁺.
• τ::T = .30: non-decision time. τ ∈ [0, min_rt].
• w::Vector{T}: attention weights vector where each element corresponds to the attention given to the corresponding dimension. wᵢ ∈ [0,1], ∑wᵢ = 1.
• S::Array{T, 2}: feedback matrix allowing self-connections and interconnections between alternatives. Self-connections range from zero to 1, where sij < 1 represents decay. Interconnections between options i and j where i ≠ j are inhibatory if sij < 0.
• C::Array{T, 2}: contrast weight matrix where c_ij is the contrast weight when comparing options i and j.

Constructors

ClassicMDFT(σ, α, τ, w, S, C)

ClassicMDFT(σ, α, τ, w, S, C = make_default_contrast(S))

Example

An example of the similarity effect. When choosing between options 1 and 2, the model predicts equal preference because the options fall along the diagonal of attribute space, signifying a 1 to 1 trade-off of equally weighted attributes. Option 3 is introduced to the choice set, which is similar to (and competitive with) option 1 and disimilar to option 2. In this case, the model predicts an increase the choice probability for option 2 relative to option 1.

# value matrix where rows correspond to alternatives, and columns correspond to attributes
M = [
    1.0 3.0
    3.0 1.0
    0.9 3.1
]

model = ClassicMDFT(;
    # non-decision time 
    τ = 0.300,
    # diffusion noise 
    σ = 1.0,
    # decision threshold
    α = 17.5,
    # attribute attention weights 
    w = [0.5, 0.5],
    # feedback matrix 
    S = [
        0.9500000 -0.0122316 -0.04999996
        -0.0122316 0.9500000 -0.00903030
        -0.0499996 -0.0090303 0.95000000
    ],
)
choices, rts = rand(model, 10_000, M; Δt = 1.0)
map(c -> mean(choices .== c), 1:3)

References

Roe, Robert M., Jermone R. Busemeyer, and James T. Townsend. "Multiattribute Decision Field Theory: A dynamic connectionst model of decision making." Psychological review 108.2 (2001): 370.

ContinuousMultivariateSSM <: ContinuousMultivariateDistribution

An abstract type for continuous multivariate sequential sampling models e.g., a circular drift diffusion model.

DDM{T<:Real} <: SSM2D

Model object for the standard Drift Diffusion Model.

Parameters

• ν::T: drift rate. Average slope of the information accumulation process. The drift gives information about the speed and direction of the accumulation of information. ν ∈ ℝ. Typical range: ν ∈ [-5,5].
• α::T: boundary threshold separation. The amount of information that is considered for a decision. α ∈ ℝ⁺. Typical range: α ∈ [.5, 2].
• z::T: starting point. Indicator of an an initial bias towards a decision. The z ∈ [0,1] parameter is relative to α.
• τ::T: non-decision time. The duration for a non-decisional processes (encoding and response execution). τ ∈ [0, min_rt]. Typical range: τ ∈ [.1,.5].

Constructors

Two constructors are defined below. The first constructor uses positional arguments, and is therefore order dependent:

DDM(ν, α, z, τ)

The second constructor uses keywords with default values, and is not order dependent:

DDM(; ν = 1.00, α = 0.80, τ = 0.30, z = 0.50)

Example

using SequentialSamplingModels
dist = DDM(ν = 1.0, α = 0.8, τ = 0.3, z = 0.25) 
choice,rt = rand(dist, 10)
like = pdf.(dist, choice, rt)
loglike = logpdf.(dist, choice, rt)

References

Ratcliff, R., & McKoon, G. (2008). The Diffusion Decision Model: Theory and Data for Two-Choice Decision Tasks. Neural Computation, 20(4), 873–922.

ExGaussian{T<:Real} <: SSM1D

The Ex-Gaussian is a convolution of the Gaussian and exponential distribution sometimes used to model reaction time distributions. Note that this is not technically a sequential sampling model.

Parameters

• μ::T: mean of Gaussian component. μ ∈ ℝ⁺.
• σ::T: standard deviation of Gaussian component. σ ∈ ℝ⁺
• τ::T: mean of exponential component. τ ∈ [0, min_rt]

Constructors

Two constructors are defined below. The first constructor uses positional arguments, and is therefore order dependent:

ExGaussian(μ, σ, τ)

The second constructor uses kewords, and is not order dependent:

ExGaussian(;μ=.5, σ=.20, τ=.20)

Example

using SequentialSamplingModels
dist = ExGaussian(;μ=.5, σ=.20, τ=.20) 
rt = rand(dist, 10)
like = pdf.(dist, rt)
loglike = logpdf.(dist, rt)

References

Matzke, D., & Wagenmakers, E. J. (2009). Psychological interpretation of the ex-Gaussian and shifted Wald parameters: A diffusion model analysis. Psychonomic Bulletin & Review, 16, 798-817.

LBA{T <: Real, T1 <: Union{<: T, Vector{<: T}}} <: AbstractLBA

A model object for the linear ballistic accumulator.

Parameters

• ν::Vector{T}: a vector of drift rates. α ∈ ℝ⁺.
• σ::T1: a scalar or vector of drift rate standard deviation. σ ∈ ℝ⁺.
• A::T: max start point. A ∈ ℝ⁺.
• k::T: A + k = b, where b is the decision threshold. k ∈ ℝ⁺.
• τ::T: an encoding-response offset. τ ∈ [0, min_rt].

Constructors

Two constructors are defined below. The first constructor uses positional arguments, and is therefore order dependent:

LBA(ν, σ, A, k, τ)

The second constructor uses keywords with default values, and is not order dependent:

LBA(;τ = .3, A = .8, k = .5, ν = [2.0,1.75], σ = 1)

Example

using SequentialSamplingModels
dist = LBA(ν=[3.0,2.0], A = .8, k = .2, τ = .3) 
choice,rt = rand(dist, 10)
like = pdf.(dist, choice, rt)
loglike = logpdf.(dist, choice, rt)

References

Brown, S. D., & Heathcote, A. (2008). The simplest complete model of choice response time: Linear ballistic accumulation. Cognitive psychology, 57(3), 153-178.

LCA{T<:Real} <: AbstractLCA

A model type for the Leaky Competing Accumulator.

Parameters

• ν::Vector{T}: drift rates
• σ::T: diffusion noise
• β::T: lateral inhabition
• λ::T: leak rate
• α::T: evidence threshold
• τ::T: non-decision time. τ ∈ [0, min_rt]

Constructors

Two constructors are defined below. The first constructor uses positional arguments, and is therefore order dependent:

LCA(ν, σ, β, λ, α, τ)

The second constructor uses keywords with default values, and is not order dependent:

LCA(; ν = [2.5, 2.0], σ = 1.0, β = 0.20, λ = 0.10, α = 1.5, τ = 0.30)

Example

using SequentialSamplingModels 
ν = [2.5,2.0]
α = 1.5
β = 0.20
λ = 0.10 
σ = 1.0
τ = 0.30

dist = LCA(; ν, α, β, λ, τ, σ)
choices,rts = rand(dist, 500)

References

Usher, M., & McClelland, J. L. (2001). The time course of perceptual choice: The leaky, competing accumulator model. Psychological Review, 108 3, 550–592. https://doi.org/10.1037/0033-295X.108.3.550

LNR{T <: Real, T1 <: Union{<:T, Vector{<:T}}} <: AbstractLNR{T, T1}

Parameters

• ν::Vector{T}: a vector of means in log-space. ν ∈ ℝⁿ.
• σ::T1: a scalar or vector of standard deviation parameter in log-space. σ ∈ ℝ⁺.
• τ::T: a encoding-response offset. τ ∈ [0, min_rt].

Constructors

Two constructors are defined below. The first constructor uses positional arguments, and is therefore order dependent:

LNR(ν, σ, τ)

The second constructor uses keywords with default values, and is not order dependent:

LNR(; ν = [-1, -2], σ = 1, τ = 0.20)

Example

using SequentialSamplingModels
dist = LNR(ν = [-2,-3], σ = 1, τ = .3)
choice,rt = rand(dist, 10)
like = pdf.(dist, choice, rt)
loglike = logpdf.(dist, choice, rt)

References

Rouder, J. N., Province, J. M., Morey, R. D., Gomez, P., & Heathcote, A. (2015). The lognormal race: A cognitive-process model of choice and latency with desirable psychometric properties. Psychometrika, 80(2), 491-513.

MDFT{T <: Real} <: AbstractMDFT

A model type for simulating Multi-attribute Decision Field Theory (MDFT) as an Stochastic Differential Equation (SDE).

Parameters

• σ::T = 1.0: diffusion noise. σ ∈ ℝ⁺.
• α::T = 15.0: evidence threshold. α ∈ ℝ⁺.
• τ::T = .30: non-decision time. τ ∈ [0, min_rt].
• γ::T: scales the valance, CMW, functioning like a drift rate. γ ∈ ℝ⁺.
• κ::Vector{T}: exponential rate parameters for switching attention between attributes. Currently, limited to two attributes. κ ∈ ℝ⁺.
• ϕ1::T: controls the sensitivity of lateral inhibition to distance in the distance function for creating the feedback matrix, S. ϕ1 ∈ ℝ⁺.
• ϕ2::T: controls evidence decay and maximum inhibition in the distance function for creating the feedback matrix, S. ϕ2 ∈ ℝ⁺.
• β::T: controls the weight of the dominance dimension in the feedback matrix distance function. If β < 0, the indifference dimension recieves more where. If β > 0, the dominance dimension recieves more weight
• S::Array{T, 2}: feedback matrix allowing self-connections and interconnections between alternatives. Self-connections range from zero to 1, where sij < 1 represents decay. Interconnections between options i and j where i ≠ j are inhibitory if sij < 0.
• C::Array{T, 2}: contrast weight matrix for comparing attended alternative to other alternatives. The element c_ij is the contrast weight when comparing options i and j.

Constructors

MDFT(σ, α, τ, γ, κ, ϕ1, ϕ2, β, C)

MDFT(;
    n_alternatives,
    σ,
    α,
    τ,
    γ,
    κ,
    ϕ1,
    ϕ2,
    β,
    C = make_default_contrast(n_alternatives)
)

Example

An example of the similarity effect. When choosing between options 1 and 2, the model predicts equal preference because the options fall along the diagonal of attribute space, signifying a 1 to 1 trade-off of equally weighted attributes. Option 3 is introduced to the choice set, which is similar to (and competitive with) option 1 and disimilar to option 2. In this case, the model predicts a reversal of preference between options 1 and 2.

using SequentialSamplingModels

model = MDFT(;
    n_alternatives = 3,
    σ = 0.1,
    α = .50,
    τ = 0.0,
    γ = 1.0,
    κ = [6.0, 5.0],
    ϕ1 = 0.01,
    ϕ2 = 0.10,
    β = 10.0
)
# value matrix where rows correspond to alternatives, and columns correspond to attributes
M = [
    1.0 3.0
    3.0 1.0
    0.9 3.1
]

choices, rts = rand(model, 10_000, M)
probs = map(c -> mean(choices .== c), 1:3)

References

Evans, N. J., Holmes, W. R., & Trueblood, J. S. (2019). Response-time data provide critical constraints on dynamic models of multi-alternative, multi-attribute choice. Psychonomic Bulletin & Review, 26, 901-933.

Hotaling, J. M., Busemeyer, J. R., & Li, J. (2010). Theoretical developments in decision field theory: Comment on tsetsos, usher, and chater (2010). Psychological Review, 117 , 1294-1298.

Roe, Robert M., Jermone R. Busemeyer, and James T. Townsend. "Multi-attribute Decision Field Theory: A dynamic connectionst model of decision making." Psychological review 108.2 (2001): 370.

MLBA{T <: Real, T1 <: Union{<: T, Vector{<: T}}} <: AbstractMLBA{T,T1}

Fields

• ν::Vector{T}: a vector of drift rates, which is a function of β₀, λₚ, λₙ, γ. ν ∈ ℝⁿ.
• β₀::T: baseline input for drift rate. β₀ ∈ ℝ.
• λₚ::T: decay constant for attention weights of positive differences. λₚ ∈ ℝ⁺.
• λₙ::T: decay constant for attention weights of negative differences. λₙ ∈ ℝ⁺.
• γ::T: risk aversion exponent for subjective values. γ ∈ ℝ⁺.
• σ::T1: a scalar or vector of drift rate standard deviation. σ ∈ ℝ⁺.
• A::T: max start point. A ∈ ℝ⁺.
• k::T: A + k = b, where b is the decision threshold. k ∈ ℝ⁺.
• τ::T: an encoding-response offset. τ ∈ [0, min_rt].

Constructors

MLBA(ν, β₀, λₚ, λₙ, γ, σ, A, k, τ)

MLBA(;
    n_alternatives = 3,
    ν = fill(0.0, n_alternatives),
    β₀ = 5.0,
    λₚ = 0.20,
    λₙ = 0.40,
    γ = 5.0,
    τ = 0.3,
    A = 1.0,
    k = 1.0,
    σ = 1.0
)

Example

using SequentialSamplingModels

dist = MLBA(
    λₚ = 0.20,
    λₙ = 0.40,
    β₀ = 5,
    γ = 5,
    τ = 0.3,
    A = 0.8,
    k = 0.5
)

M = [
    1 4
    2 2
    4 1
]

choice, rt = rand(dist, 1000, M)
like = pdf.(dist, choice, rt, (M,))
loglike = logpdf.(dist, choice, rt, (M,))

References

Trueblood, J. S., Brown, S. D., & Heathcote, A. (2014). The multiattribute linear ballistic accumulator model of context effects in multialternative choice. Psychological Review, 121(2), 179.

PoissonRace{T<:Real} <: AbstractPoissonRace

Parameters

• ν::T: gamma scale parameter. ν ∈ ℝ⁺.
• α::T: threshold. α ∈ ℝ⁺
• τ::T: a encoding-response offset. τ ∈ [0, min_rt].

Constructors

Two constructors are defined below. The first constructor uses positional arguments, and is therefore order dependent:

PoissonRace(ν, α, τ)

The second constructor uses keywords with default values, and is not order dependent:

PoissonRace(;ν=[.05,.06], α=[5,5], τ=.3)

Example

using SequentialSamplingModels
dist = PoissonRace(ν=[.05,.06], α=[5,5], τ=.3)
choice,rt = rand(dist, 10)
like = pdf.(dist, choice, rt)
loglike = logpdf.(dist, choice, rt)

References

LaBerge, D. A. (1962). A recruitment model of simple behavior. Psychometrika, 27, 375-395.

RDM{T<:Real} <: AbstractRDM

An object for the racing diffusion model.

Constructors

Two constructors are defined below. The first constructor uses positional arguments, and is therefore order dependent:

RDM(ν, k, A, τ)

The second constructor uses keywords with default values, and is not order dependent:

RDM(;ν=[1,2], k=.3, A=.7, τ=.2)

Parameters

• ν::T: a vector of drift rates. ν ∈ ℝⁿ.
• A::T: the maximum starting point diffusion process, sampled from Uniform distribution. A ∈ ℝ⁺
• k::T: k = b - A where b is the decision threshold, and A is the maximum starting point. k ∈ ℝ⁺
• τ::T: a encoding-motor time offset. τ ∈ [0, min_rt].

Example

using SequentialSamplingModels
dist = RDM(;ν=[1,2], k=.3, A=.7, τ=.2)
choice,rt = rand(dist, 10)
like = pdf.(dist, choice, rt)
loglike = logpdf.(dist, choice, rt)

References

Tillman, G., Van Zandt, T., & Logan, G. D. (2020). Sequential sampling models without random between-trial variability: The racing diffusion model of speeded decision making. Psychonomic Bulletin & Review, 27, 911-936.

SSM1D <: ContinuousUnivariateDistribution

An abstract type for sequential sampling models characterized by a single choice reaction time distribution. Sub-types of SSM1D output a vector of reaction times.

SSM2D = Distribution{Multivariate, Mixed}

An abstract type for sequential sampling models characterized by a multivariate choice-reaction time distribution. Sub-types of SSM2D output a NamedTuple consisting of a vector of choices and reaction times.

ShiftedLogNormal{T <: Real} <: AbstractShiftedLogNormal

A special case of the lognormal race (LNR) model for a single response. The first passage time is lognormally distributed.

Parameters

• ν::T: mean finishing time in log-space. ν ∈ ℝ.
• σ::T: standard deviation parameter in log-space. σ ∈ ℝ⁺.
• τ::T: a encoding-response offset. τ ∈ [0, min_rt].

Constructors

Two constructors are defined below. The first constructor uses positional arguments, and is therefore order dependent:

ShiftedLogNormal(ν, σ, τ)

The second constructor uses keywords with default values, and is not order dependent:

ShiftedLogNormal(; ν = -1, σ=.5, τ = .20)

Example

using SequentialSamplingModels
dist = ShiftedLogNormal(ν = -1, σ=.5, τ = .20)
rts = rand(dist, 10)
like = pdf.(dist, rts)
loglike = logpdf.(dist, rts)

References

Heathcote, A., & Bohlscheid, E. Analysis and Modeling of Response Time using the Shifted Lognormal Distribution.

Wald{T<:Real} <: AbstractWald

A model object for the Wald model, also known as the inverse Gaussian model.

Parameters

• ν: drift rate. ν ∈ ℝ⁺.
• α: decision threshold. α ∈ ℝ⁺
• τ: a encoding-response offset. τ ∈ [0, min_rt]

Constructors

Two constructors are defined below. The first constructor uses positional arguments, and is therefore order dependent:

Wald(ν, α, τ)

The second constructor uses keywords with default values, and is not order dependent:

Wald(;ν=1.5, α=.50, τ=0.20)

Example

using SequentialSamplingModels
dist = Wald(ν=3.0, α=.5, τ=.130)
rt = rand(dist, 10)
like = pdf.(dist, rt)
loglike = logpdf.(dist, rt)

References

Anders, R., Alario, F., & Van Maanen, L. (2016). The shifted Wald distribution for response time data analysis. Psychological methods, 21(3), 309.

Folks, J. L., & Chhikara, R. S. (1978). The inverse Gaussian distribution and its statistical application—a review. Journal of the Royal Statistical Society Series B: Statistical Methodology, 40(3), 263-275.

WaldMixture{T<:Real} <: AbstractWald

Parameters

• υ: drift rate. ν ∈ ℝ⁺.
• η: standard deviation of drift rate. ν ∈ ℝ⁺.
• α: decision threshold. α ∈ ℝ⁺.
• τ: a encoding-response offset. τ ∈ [0, min_rt]

Constructors

Two constructors are defined below. The first constructor uses positional arguments, and is therefore order dependent:

WaldMixture(ν, η, α, τ)

The second constructor uses keywords with default values, and is not order dependent:

WaldMixture(;ν=3.0, η=.2, α=.5, τ=.130)

Example

using SequentialSamplingModels
dist = WaldMixture(;ν=3.0, η=.2, α=.5, τ=.130)
rt = rand(dist, 10)
like = pdf.(dist, rt)
loglike = logpdf.(dist, rt)

References

Steingroever, H., Wabersich, D., & Wagenmakers, E. J. (2020). Modeling across-trial variability in the Wald drift rate parameter. Behavior Research Methods, 1-17.

aDDM{T<:Real} <: AbstractaDDM

An object for the attentional diffusion model.

Parameters

• ν::Vector{T}: relative decision values (i.e., drift rates). ν ∈ ℝⁿ.
• σ::T: standard deviation of noise in evidence accumulation. σ ∈ ℝ.
• Δ::T: constant of evidence accumulation speed (evidence per ms). Δ ∈ ℝ.
• α::T: evidence threshold. α ∈ ℝ.
• z::T: initial evidence. z ∈ [0, α]
• θ::T: bias towards attended alternative (lower indicates more bias)
• τ::T: non-decision time. τ ∈ [0, min_rt]

Constructors

Two constructors are defined below. The first constructor uses positional arguments, and is therefore order dependent:

aDDM(ν, σ, Δ, θ, α, z, τ)

The second constructor uses keywords with default values, and is not order dependent:

aDDM(;ν=[5.0,4.0], α=1.0, z=α*.5, θ=.3, σ=.02, Δ=.0004, τ=0.0)

Example

using SequentialSamplingModels
using StatsBase

mutable struct Transition
    state::Int 
    n::Int
    mat::Array{Float64,2} 
 end

 function Transition(mat)
    n = size(mat,1)
    state = rand(1:n)
    return Transition(state, n, mat)
 end
 
 function fixate(transition)
     (;mat,n,state) = transition
     w = @view mat[state,:]
     next_state = sample(1:n, Weights(w))
     transition.state = next_state
     return next_state
 end

 model = aDDM()
 
 tmat = Transition([.98 .015 .005;
                    .015 .98 .005;
                    .45 .45 .1])

 choices,rts = rand(model, 100, tmat; fixate)

References

Krajbich, I., Armel, C., & Rangel, A. (2010). Visual fixations and the computation and comparison of value in simple choice. Nature neuroscience, 13(10), 1292-1298.

maaDDM{T<:Real} <: AbstractaDDM

An object for the multi-attribute attentional drift diffusion model.

Constructors

Two constructors are defined below. The first constructor uses positional arguments, and is therefore order dependent:

maaDDM(ν, σ, Δ, θ, ϕ, ω, α, z, τ)

The second constructor uses keywords with default values, and is not order dependent:

maaDDM(;
    ν = [4.0 5.0; 5.0 4.0],
    α = 1.0,
    z = 0.0,
    θ = 0.3,
    ϕ = 0.50,
    ω = 0.70,
    σ = 0.02,
    Δ = 0.0004,
    τ = 0.0,
)

In this version of the model, the non-attended attribute of the non-attended alternative is doubly discounted. For example, the mean drift rate for the attribute 1 of alternative 1 is given by:

    Δ * (ω * (ν[1,1] - θ * ν[2,1]) + (1 - ω) * ϕ * (ν[1,2] - θ * ν[2,2]))

Keywords

• ν::T: drift rates where rows are alternatives and columns are attributes. ν ∈ ℝⁿᵐ.
• σ::T: standard deviation of noise in evidence accumulation. σ ∈ ℝ.
• Δ::T: constant of evidence accumulation speed (evidence per ms). Δ ∈ ℝ.
• θ::T: bias away from unattended alternative (lower indicates more bias). θ ∈ [0,1].
• ϕ::T: bias away from unattended attribute. ϕ ∈ [0,1].
• ω::T: attribute weight. ω ∈ [0,1].
• α::T: evidence threshold. α ∈ ℝ⁺.
• z::T: initial evidence. z ∈ [0, α]
• τ::T: non-decision time. τ ∈ [0, min_rt].

Example

using SequentialSamplingModels
using StatsBase

mutable struct Transition
    state::Int 
    n::Int
    mat::Array{Float64,2} 
 end

 function Transition(mat)
    n = size(mat,1)
    state = rand(1:n)
    return Transition(state, n, mat)
 end
 
 function attend(transition)
     (;mat,n,state) = transition
     w = @view mat[state,:]
     next_state = sample(1:n, Weights(w))
     transition.state = next_state
     return next_state
 end

ν = [4.0 5.0; 5.0 4.0]
α = 1.0 
z = 0.0
θ = .3
ϕ = .50
ω = .70
σ = .02
Δ = .0004
τ = 0.0

dist = maaDDM(; ν, σ, Δ, θ, ϕ, ω, α, z, τ)

tmat = Transition([.98 .015 .0025 .0025;
                .015 .98 .0025 .0025;
                .0025 .0025 .98 .015;
                .0025 .0025 .015 .98])

 choices,rts = rand(dist, 100, attend, tmat)

References

Yang, X., & Krajbich, I. (2023). A dynamic computational model of gaze and choice in multi-attribute decisions. Psychological Review, 130(1), 52.

rand(dist::AbstractLCA, n_sim::Int; Δt = 0.001)

Generate n_sim random choice-rt pairs for the Leaky Competing Accumulator.

Arguments

• dist: model object for the Leaky Competing Accumulator.
• n_sim::Int: the number of simulated choice-rt pairs

Keywords

• Δt = 0.001: time step size

rand(dist::AbstractLCA; Δt = 0.001)

Generate a random choice-rt pair for the Leaky Competing Accumulator.

Arguments

• dist: model object for the Leaky Competing Accumulator.
• Δt = 0.001: time step size

rand(rng::AbstractRNG, d::AbstractMLBA, M::AbstractArray)

Generates a single choice-rt pair of simulated data from the Multi-attribute Linear Ballistic Accumulator.

Arguments

• dist::AbstractMLBA: an object for the multi-attribute linear ballistic accumulator
• M::AbstractArray: an alternative × attribute value matrix representing the value of the stimuli

rand(rng::AbstractRNG, d::AbstractMLBA, n_trials::Int, M::AbstractArray)

Generates n_trials choice-rt pair of simulated data from the Multi-attribute Linear Ballistic Accumulator.

Arguments

• dist::AbstractMLBA: an object for the multi-attribute linear ballistic accumulator
• n_trials::Int: the number of trials to simulate
• M::AbstractArray: an alternative × attribute value matrix representing the value of the stimuli

rand(
    rng::AbstractRNG,
    dist::AbstractaDDM,
    n_sim::Int,
    fixate::Function, 
    args...;
    rand_state! = _rand_state!,
    Δt = .001,
    kwargs...
)

Generate n_sim simulated trials from the attention diffusion model.

Arguments

• rng: a random number generator
• dist: an attentional diffusion model object
• n_sim::Int: the number of simulated trials
• fixate: a function of the visual fixation process which returns 1 for alternative and 2 for alternative 2
• args...: optional positional arguments for the fixate function

Keywords

rand_state! = _rand_state!: initialize first state with equal probability

• kwargs...: optional keyword arguments for the fixate function
• Δt = .001: time step

rand(
    rng::AbstractRNG, 
    dist::AbstractaDDM, 
    fixate::Function, args...; 
    rand_state! = _rand_state!, 
    Δt = .001,
    kwargs...
)

Generate a single simulated trial from the attentional diffusion model.

Arguments

• rng: a random number generator
• dist: an attentional diffusion model object
• fixate: a function of the visual fixation process which returns 1 for alternative and 2 for alternative 2
• args...: optional positional arguments for the fixate function

Keywords

• kwargs...: optional keyword arguments for the fixate function
• Δt = .001: time step

rand(dist::AbstractstDDM)

Generate a random choice-rt pair for starting-time diffusion decision model.

Arguments

• rng: a random number generator
• dist: model object for the starting-time diffusion decision model.
• Δt: time-step for simulation

rand(
    rng::AbstractRNG,
    dist::AbstractMDFT,
    n_sim::Int,
    M::AbstractArray;
    Δt = 0.001
)

Generate n_sim random choice-rt pairs for the Multiattribute Decision Field Theory (MDFT).

Arguments

• rng::AbstractRNG: a random number generator which is a subtype of AbstractRNG
• dist::AbstractMDFT: model object for the Multiattribute Decision Field Theory (MDFT).
• n_sim::Int: the number of simulated choice-rt pairs
• M::AbstractArray: an alternative × attribute value matrix representing the value of the stimuli

Keywords

• Δt = 0.001: time step size

rand(dist::DDM)

Generate a random rt for the Diffusion Decision Model (negative coding)

Arguments

• dist: model object for the Diffusion Decision Model.

rand(
    rng::AbstractRNG,
    dist::MDFT,
    n_sim::Int,
    M::AbstractArray;
    Δt = 0.001
)

Generate n_sim random choice-rt pairs for the Multi-attribute Decision Field Theory (MDFT).

Arguments

• rng::AbstractRNG: a random number generator which is a subtype of AbstractRNG
• dist::MDFT: model object for the Multi-attribute Decision Field Theory (MDFT).
• n_sim::Int: the number of simulated choice-rt pairs
• M::AbstractArray: an alternative × attribute value matrix representing the value of the stimuli

Keywords

• Δt = 0.001: time step size

rand(rng::AbstractRNG, d::SSM2D, N::Int; kwargs...)

Default method for Generating n_sim random choice-rt pairs from a sequential sampling model with more than one choice option.

Arguments

• d::SSM2D: a 2D sequential sampling model.
• n_trials::Int: the number of simulated choices and rts

Keywords

• kwargs...: optional keyword arguments

cdf(d::SSM2D, choice::Int, ub=10)

Computes the cumulative density for a given choice. The cumulative density is based on an analytic formula, a numeric integration of pdf, or Monte Carlo simulation, depending on which is available for a given model.

Arguments

• d::SSM2D: a 2D sequential sampling model.
• choice::Int: the number of simulated choices and rts
• ub::Real: upper bound of integration
• args...: optional arguments passed to rand

cdf(
    rng::AbstractRNG, 
    d::AbstractaDDM, 
    choice::Int, 
    fixate::Function, 
    ub, 
    args...; 
    n_sim=10_000, 
    kwargs...
)

Computes the approximate cumulative probability density of AbstractaDDM using Monte Carlo simulation.

Arguments

• dist: an attentional diffusion model object
• choice: the choice on which the cumulative density is computed
• fixate: a function of the visual fixation process which returns 1 for alternative and 2 for alternative 2
• ub::Int: the upper bound of the integral
• args...: optional positional arguments for the fixate function

Keywords

• n_sim::Int=10_000: the number of simulated trials

rand_state! = _rand_state!: initialize first state with equal probability

• kwargs...: optional keyword arguments for the fixate function

cdf(d::SSM1D, choice::Int, ub=10)

Computes the cumulative density for a given choice. The cumulative density is based on an analytic formula, a numeric integration of pdf, or Monte Carlo simulation, depending on which is available for a given model.

Arguments

• d::SSM1D: a 1D sequential sampling model.
• ub: upper bound of integration

logpdf(d::AbstractMLBA, c::Int, rt::Real,  M::AbstractArray)

Computes default log probability density for multi-alternative linear ballistic accumulator.

Arguments

• dist::AbstractMLBA: an object for the multi-attribute linear ballistic accumulator
• c::Int: choice index
• rt::Real: reaction time in seconds
• M::AbstractArray: an alternative × attribute value matrix representing the value of the stimuli

logpdf(d::SSM2D, data::NamedTuple)

Computes the likelihood for a 2D sequential sampling model.

Arguments

• d::SSM2D: an object for a 2D sequential sampling model
• data::NamedTuple: a NamedTuple of data containing choice and reaction time

pdf(d::AbstractMLBA, c::Int, rt::Real,  M::AbstractArray)

Computes default probability density for multi-alternative linear ballistic accumulator.

Arguments

• dist::AbstractMLBA: an object for the multi-attribute linear ballistic accumulator
• c::Int: choice index
• rt::Real: reaction time in seconds
• M::AbstractArray: an alternative × attribute value matrix representing the value of the stimuli

pdf(d::SSM2D, data::NamedTuple)

Computes the probability density for a 2D sequential sampling model.

Arguments

• d::SSM2D: an object for a 2D sequential sampling model
• data::NamedTuple: a NamedTuple of data containing choice and reaction time

compute_choice_probs(data::NamedTuple; choice_set=unique(data.choice))

Returns the choice probabilities for a 2D SSM.

Arguments

• data::NamedTuple: a data structure containing discrete choices in the key choice and corresponding

reaction times in key rt

Keywords

• `choice_set: a vector of possible choices.

compute_quantiles(data::Array{<:Real,2}; percentiles=.1:.1:.90)

Returns the marginal quantiles for a continous multivariate SSM.

• data::Array{<:Real,2}: an array of continous observations

Keywords

• percentiles=.1:.1:.90: percentiles at which to evaluate the quantiles

compute_quantiles(data::NamedTuple; choice_set=unique(data.choice), percentiles=.1:.1:.90)

Returns the quantiles for each choice of a 2D SSM. Note there is a chance that a given choice will have no observations, and thus no quantiles. Such cases will need to be removed or handled in post processing.

Arguments

• data::NamedTuple: a data structure containing discrete choices in the key choice and corresponding

reaction times in key rt

Keywords

• percentiles=.1:.1:.90: percentiles at which to evaluate the quantiles
• choice_set=unique(choice): a vector of possible choices.

compute_quantiles(data::Vector{<:Real}; percentiles=.1:.1:.90)

Returns the quantiles associated with a vector of reaction times for a single choice SSM.

• data::Vector{<:Real}: a vector of reaction times

Keywords

• percentiles=.1:.1:.90: percentiles at which to evaluate the quantiles

n_options(dist::DDM)

Returns 2 for the number of choice options

Arguments

• d::DDM: a model object for the drift diffusion model

n_options(dist::SSM2D)

Returns the number of choice options based on the length of the drift rate vector ν.

Arguments

• d::SSM2D: a sub-type of SSM2D

n_options(dist::SSM1D)

Returns 1 for the number of choice options

Arguments

• d::SSM1D: a sub-type of SSM1D

simulate(model::AbstractCDDM; Δt=.001)

Returns a matrix containing evidence samples of the racing diffusion model decision process. In the matrix, rows represent samples of evidence per time step and columns represent different accumulators.

Arguments

• model::AbstractCDDM;: a circular drift diffusion model object

Keywords

• Δt=.001: size of time step of decision process in seconds

simulate(model::MDFT, M::AbstractArray; Δt = 0.001, _...)

Returns a matrix containing evidence samples of the MDFT decision process. In the matrix, rows represent samples of evidence per time step and columns represent different accumulators.

Arguments

• model::MDFT: an MDFT model object
• M::AbstractArray: an alternative × attribute value matrix representing the value of the stimuli

simulate(model::SSM2D, args...; Δt = .001, kwargs...)

Returns a matrix containing evidence samples from a 2D SSM. In the matrix, rows represent samples of evidence per time step and columns represent different accumulators.

Arguments

• model::SSM2D: a subtype of a 2D SSM
• args...: optional positional arguments

Keywords

• Δt = .001: size of time step of decision process in seconds
• kwargs...: optional keyword arguments

simulate(model::AbstractLBA; n_steps=100, _...)

Returns a matrix containing evidence samples of the LBA decision process. In the matrix, rows represent samples of evidence per time step and columns represent different accumulators.

Arguments

• model::AbstractLBA: a subtype of AbstractLBA

Keywords

• n_steps=100: number of time steps at which evidence is recorded

simulate(rng::AbstractRNG, model::AbstractMLBA, M::AbstractArray; n_steps = 100)

Returns a matrix containing evidence samples of the MLBA decision process. In the matrix, rows represent samples of evidence per time step and columns represent different accumulators.

Arguments

• model::AbstractMLBA: a subtype of AbstractMLBA

Keywords

• n_steps=100: number of time steps at which evidence is recorded

simulate(
    rng::AbstractRNG, 
    model::AbstractaDDM; 
    fixate, 
    args=(), 
    kwargs=(), 
    Δt = .001,
    rand_state! = _rand_state!
)

Returns a matrix containing evidence samples from a subtype of an attentional drift diffusion model decision process. In the matrix, rows represent samples of evidence per time step and columns represent different accumulators.

Arguments

• rng::AbstractRNG: random number generator
• model::AbstractaDDM: an drift diffusion model object

Keywords

• fixate: a function of the visual fixation process which returns 1 for alternative and 2 for alternative 2
• args=(): a set of optional positional arguments for the attend function
• kwargs=(): a set of optional keyword arguments for the attend function
• Δt = .001: time step

rand_state! = _rand_state!: initialize first state with equal probability

simulate(rng::AbstractRNG, model::AbstractstDDM; Δt)

Returns a matrix containing evidence samples of the stDDM decision process. In the matrix, rows represent samples of evidence per time step and columns represent different accumulators.

Arguments

• rng: a random number generator
• model::AbstractstDDM: a starting-time diffusion decision model diffusion model object
• Δt: time-step for simulation

simulate(model::SSM1D, args...; Δt = .001, kwargs...)

Returns a matrix containing evidence samples from a 2D SSM. In the matrix, rows represent samples of evidence per time step and columns represent different accumulators.

Arguments

• model::SSM1D: a subtype of a 2D SSM
• args...: optional positional arguments

Keywords

• Δt = .001: size of time step of decision process in seconds
• kwargs...: optional keyword arguments

loglikelihood(d::SSM2D, data::NamedTuple)

Computes the summed log likelihood for a 2D sequential sampling model.

Arguments

• d::SSM2D: an object for a 2D sequential sampling model
• data::NamedTuple: a NamedTuple of data containing choice and reaction time

loglikelihood(d::SSM1D, data::AbstractArray{T, 1})

Computes the summed log likelihood for a 1D sequential sampling model.

Arguments

• d::SSM2D: an object for a 2D sequential sampling model
• data::AbstractVector{<:Real}: a vector of reaction times