Merge pull request #73 from itsdfish/mdft2

Add MDFT (WIP)

Project.toml

@@ -1,7 +1,7 @@
 name = "SequentialSamplingModels"
 uuid = "0e71a2a6-2b30-4447-8742-d083a85e82d1"
 authors = ["itsdfish"]
-version = "0.10.2"
+version = "0.11.0"
 
 [deps]
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"

README.md

@@ -21,6 +21,7 @@ The following SSMs are supported :
 - [Linear Ballistic Accumulator](https://itsdfish.github.io/SequentialSamplingModels.jl/dev/lba/) 
 - [Log Normal Race](https://itsdfish.github.io/SequentialSamplingModels.jl/dev/lnr/) 
 - [Multi-attribute Attentional Drift Diffusion](https://itsdfish.github.io/SequentialSamplingModels.jl/dev/maaDDM/)
+- [Multi-attribute Decision Field Theory](https://itsdfish.github.io/SequentialSamplingModels.jl/dev/mdft/)
 - [Poisson Race](https://itsdfish.github.io/SequentialSamplingModels.jl/dev/poisson_race)
 - [Racing Diffusion](https://itsdfish.github.io/SequentialSamplingModels.jl/dev/rdm/) 
 - [Wald](https://itsdfish.github.io/SequentialSamplingModels.jl/dev/wald/) 

benchmark/benchmarks.jl

@@ -61,3 +61,24 @@ for dist ∈ dists
     SUITE[:simulate][dist_name] =
         @benchmarkable(simulate($dist()), evals = 10, samples = 1000,)
 end
+
+parms = (
+    σ = 0.1,
+    α = 0.50,
+    τ = 0.0,
+    γ = 1.0,
+    ϕ1 = 0.01,
+    ϕ2 = 0.1,
+    β = 10,
+    κ = [5, 5]
+)
+
+mdft = MDFT(; n_alternatives = 3, parms...)
+
+M = [
+    1.0 3.0
+    3.0 1.0
+    0.9 3.1
+]
+
+SUITE[:simulate][:mdft] = @benchmarkable(simulate(mdft, M), evals = 10, samples = 1000,)

docs/make.jl

@@ -30,7 +30,8 @@ makedocs(
             "Leaky Competing Accumulator (LCA)" => "lca.md",
             "Linear Ballistic Accumulator (LBA)" => "lba.md",
             "Lognormal Race Model (LNR)" => "lnr.md",
-            "Muti-attribute attentional drift diffusion Model" => "maaDDM.md",
+            "Muti-attribute Attentional Drift Diffusion Model" => "maaDDM.md",
+            "Multi-attribute Decision Field Theory" => "mdft.md",
             "Poisson Race" => "poisson_race.md",
             "Racing Diffusion Model (RDM)" => "rdm.md",
             "Starting-time Drift Diffusion Model (stDDM)" => "stDDM.md",

docs/src/DDM.md

@@ -91,12 +91,10 @@ logpdf.(dist, choices, rts)
 ```
 
 ## Compute Choice Probability
-The choice probability $\Pr(C=c)$ is computed by passing the model and choice index to `cdf`.
-
+The choice probability $\Pr(C=c)$ is computed by passing the model and choice index to `cdf` along with a large value for time as the second argument.
  ```@example DDM 
-cdf(dist, 1)
+cdf(dist, 1, 10)
 ```
-To compute the joint probability of choosing $c$ within $t$ seconds, i.e., $\Pr(T \leq t \wedge C=c)$, pass a third argument for $t$.
 
 ## Plot Simulation
 The code below overlays the PDF on reaction time histograms for each option.

docs/src/cddm.md

@@ -11,7 +11,8 @@ model = CDDM(;
     η = [.50,.50],
     σ = 1.0,
     α = 4.0,
-    τ = .30)
+    τ = .30
+)
 
 Random.seed!(5874)
 
@@ -90,7 +91,7 @@ Non-decision time is an additive constant representing encoding and motor respon
 Now that values have been asigned to the parameters, we will pass them to `CDDM` to generate the model object.
 
 ```@example CDDM 
-dist = CDDM(ν, η, σ, α, τ)
+dist = CDDM(; ν, η, σ, α, τ)
 ```
 ## Simulate Model
 

docs/src/index.md

@@ -19,13 +19,14 @@ using SequentialSamplingModels
 using SequentialSamplingModels: increment!
 Random.seed!(8437)
 
-parms = (α = 1.5,
-            β=0.20,
-             λ=0.10,
-             ν=[2.5,2.0],
-             Δt=.001,
-             τ=.30,
-             σ=1.0)
+parms = (
+    α = 1.5,
+    β=0.20,
+    λ=0.10,
+    ν=[2.5,2.0],
+    τ=.30,
+    σ=1.0
+)
 model = LCA(; parms...)
 time_steps,evidence = simulate(model)
 lca_plot = plot(time_steps, evidence, xlabel="Time (seconds)", ylabel="Evidence",

docs/src/lba.md

@@ -86,12 +86,10 @@ logpdf.(dist, choices, rts)
 ```
 
 ## Compute Choice Probability
-The choice probability $\Pr(C=c)$ is computed by passing the model and choice index to `cdf`.
-
+The choice probability $\Pr(C=c)$ is computed by passing the model and choice index to `cdf` along with a large value for time as the second argument.
  ```@example lba 
-cdf(dist, 1)
+cdf(dist, 1, Inf)
 ```
-To compute the joint probability of choosing $c$ within $t$ seconds, i.e., $\Pr(T \leq t \wedge C=c)$, pass a third argument for $t$.
 
 ## Plot Simulation
 The code below overlays the PDF on reaction time histograms for each option.

docs/src/lca.md

@@ -51,12 +51,6 @@ Diffusion noise is the amount of within trial noise in the evidence accumulation
 ```@example lca 
 σ = 1.0
 ```
-### Time Step
-The time step parameter $\Delta t$ is the precision of the discrete time approxmation. 
-
-```@example lca 
-Δt = .001
-```
 
 ### Non-Decision Time
 
@@ -69,7 +63,7 @@ Non-decision time is an additive constant representing encoding and motor respon
 Now that values have been asigned to the parameters, we will pass them to `LCA` to generate the model object.
 
 ```@example lca 
-dist = LCA(; ν, α, β, λ, τ, σ, Δt)
+dist = LCA(; ν, α, β, λ, τ, σ)
 ```
 ## Simulate Model
 
@@ -78,13 +72,13 @@ Now that the model is defined, we will generate $10,000$ choices and reaction ti
  ```@example lca 
  choices,rts = rand(dist, 10_000)
 ```
-## Compute Choice Probability
-The choice probability $\Pr(C=c)$ is computed by passing the model and choice index to `cdf`.
+In the code block above, `rand` has a keyword argument `Δt` which controls the precision of the discrete approximation. The default value is `Δt = .001`.
 
+## Compute Choice Probability
+The choice probability $\Pr(C=c)$ is computed by passing the model and choice index to `cdf` along with a large value for time as the second argument.
  ```@example lca 
-cdf(dist, 1)
+cdf(dist, 1, Inf)
 ```
-To compute the joint probability of choosing $c$ within $t$ seconds, i.e., $\Pr(T \leq t \wedge C=c)$, pass a third argument for $t$.
 
 ## Plot Simulation
 The code below plots a histogram for each option.

docs/src/lnr.md

@@ -74,7 +74,7 @@ logpdf.(dist, choices, rts)
 The choice probability $\Pr(C=c)$ is computed by passing the model and choice index to `cdf`.
 
  ```@example lnr 
-cdf(dist, 1)
+cdf(dist, 1, Inf)
 ```
 To compute the joint probability of choosing $c$ within $t$ seconds, i.e., $\Pr(T \leq t \wedge C=c)$, pass a third argument for $t$.
 

docs/src/mdft.md

@@ -0,0 +1,204 @@
+```@setup MDFT
+using SequentialSamplingModels
+using Plots 
+using Random
+M = [
+    1.0 3.0 # A 
+    3.0 1.0 # B
+    0.9 3.1 # S
+]
+```
+
+# Multi-attribute Decision Field Theory
+
+Multi-attribute Decision Field Theory (MDFT; Roe, Busemeyer, & Townsend, 2001) models how people choose between alternatives with multiple dimensions, such as cars, phones, or jobs. As an example, jobs may differ in terms of benefits, salary, flexibility, and work-life balance. As with other sequential sampling models, MDFT assumes that evidence (or preference) accumulates dynamically until the evidence for one alternative reaches a threshold, and triggers the selection of the winning alternative. MDFT incorporates three additional core assumptions:
+
+1. Attention switches between attributes, and alternatives are compared on the currently attended attribute
+2. As two alternatives become closer to each other in attribute space, their mutual inhibition increases
+3. Evidence for each alternative gradually decays across time
+
+One of MDFT's strong suits is accounting for context effects in preferential decision making. A context effect occurs when the preference relationship between two alternatives changes when a third alternative is included in the choice set. In such cases, the preferences may reverse or the decision maker may violate rational choice principles.  
+
+Note that this version of MDFT uses stochastic differential equations (see Evans et al., 2019). For the random walk version, see `ClassicMDFT`. 
+
+# Similarity Effect
+
+In what follows, we will illustrate the use of MDFT with a demonstration of the similarity effect. 
+Consider the choice between two jobs, `A` and `B`. The main criteria for evaluating the two jobs are salary and flexibility. Job `A` is high on salary but low on flexibility, whereas job `B` is low on salary. In the plot below, jobs `A` and `B` are located on the line of indifference, $y = 3 - x$. However, because salary recieves more attention, job `A` is slightly prefered over job `B`.
+
+```@example MDFT
+scatter(
+    M[:, 1],
+    M[:, 2],
+    grid = false,
+    leg = false,
+    lims = (0, 4),
+    xlabel = "Flexibility",
+    ylabel = "Salary",
+    markersize = 6,
+    markerstrokewidth = 2
+)
+annotate!(M[1, 1] + 0.10, M[1, 2] + 0.25, "A")
+annotate!(M[2, 1] + 0.10, M[2, 2] + 0.25, "B")
+annotate!(M[3, 1] + 0.10, M[3, 2] + 0.25, "S")
+plot!(0:0.1:4, 4:-0.1:0, color = :black, linestyle = :dash)
+```
+Suppose an job `S`, which is similar to A is added to the set of alternatives. Job `S` inhibits job `A` more than job `B` because `S` and `A` are close in attribute space. As a result, the preference for job `A` over job `B` is reversed. Formally, this is stated as:  
+
+```math
+\Pr(A \mid \{A,B\}) > \Pr(B \mid \{A,B\})
+```
+
+```math
+\Pr(A \mid \{A,B,S\}) < \Pr(B \mid \{A,B,S\})
+```
+
+## Load Packages
+The first step is to load the required packages.
+
+```@example MDFT
+using SequentialSamplingModels
+using Plots 
+using Random
+
+Random.seed!(8741)
+```
+## Create Model Object
+In the code below, we will define parameters for the MDFT and create a model object to store the parameter values. 
+
+### Drift Rate Scalar
+In MDFT, the drift rate is determined by the contrast between alternatives along the attended attribute. These evaluations are scaled by the parameter $\gamma$:
+
+```@example MDFT
+γ = 1.0
+```
+### Threshold
+The threshold $\alpha$ represents the amount of evidence required to make a decision.
+```@example MDFT 
+α = .50
+```
+
+### Dominance Weight
+In MDFT, alternatives are compared along the dominance dimension (diagonal) and indifference dimension (off-diagonal) in attribute space. The relative weight of the dominance dimension is controlled by parameter $\beta$
+```@example MDFT 
+β = 10
+```
+
+### Lateral Inhibition
+
+In MDFT, alternatives inhibit each other as an inverse function of thier distance in attribute space: the closer they are, the more inhibititory the relationship. Lateral inhibition is controled via a
+alternative $\times$ alternative feedback matrix in which the diagonal elements (e.g., self-inhibition) represents decay or leakage, and the non-diagonal elements represent lateral inhibition between different alternatives. The values of the feedback matrix are controled by a Gaussian distance function with two parameters: $\phi_1$ and $\phi_2$. 
+
+#### Inhibition Strength
+
+The distance gradient parameter $\phi_1$ controls the strength of lateral inhibition between alternatives:
+
+```@example MDFT
+ϕ1 = .01
+```
+
+#### Maximum Inhibition
+
+Maximimum inhibition and decay is controlled by parameter $\phi_2$:
+
+```@example MDFT
+ϕ2 = .10
+```
+
+### Diffusion Noise
+Diffusion noise is the amount of within trial noise in the evidence accumulation process. 
+```@example MDFT 
+σ = .10
+```
+
+### Non-Decision Time
+
+Non-decision time is an additive constant representing encoding and motor response time. 
+```@example MDFT 
+τ = 0.30
+```
+### Attention Switching Rates
+The rate at which attention shifts from one attribute to the other is controlled by the following rate parameters:
+```@example MDFT 
+κ = [6, 5]
+```
+The second rate is lower than the first rate to reflect more attention to the second dimension (i.e., salary).
+
+### MDFT Constructor 
+
+Now that values have been asigned to the parameters, we will pass them to `MDFT` to generate the model object. We will begin with the choice between job `A` and job `B`.
+
+```@example MDFT 
+dist = MDFT(;
+    n_alternatives = 2,
+    σ,
+    α,
+    τ,
+    γ,
+    κ,
+    ϕ1,
+    ϕ2,
+    β,
+)
+```
+## Simulate Model
+
+Now that the model is defined, we will generate 10,000 choices and reaction times using `rand`. 
+
+ ```@example MDFT
+M₂ = [
+    1.0 3.0 # A 
+    3.0 1.0 # B
+]
+    
+choices,rts = rand(dist, 10_000, M₂; Δt = .001)
+probs2 = map(c -> mean(choices .== c), 1:2)
+```
+Here, we see that job `A` is prefered over job `B`. Also note, in the code block above, `rand` has a keyword argument `Δt` which controls the precision of the discrete approximation. The default value is `Δt = .001`.
+
+Next, we will simulate the choice between jobs `A`, `B`, and `S`.
+
+ ```@example MDFT
+dist = MDFT(;
+    n_alternatives = 3,
+    σ,
+    α,
+    τ,
+    γ,
+    κ,
+    ϕ1,
+    ϕ2,
+    β,
+)
+
+M₃ = [
+    1.0 3.0 # A 
+    3.0 1.0 # B
+    0.9 3.1 # S
+]
+
+choices,rts = rand(dist, 10_000, M₃)
+probs3 = map(c -> mean(choices .== c), 1:3)
+```
+In this case, the preferences have reversed: job `B` is now preferred over job `A`. 
+
+## Compute Choice Probability
+The choice probability $\Pr(C=c)$ is computed by passing the model and choice index to `cdf` along with a large value for time as the second argument.
+
+ ```@example MDFT 
+cdf(dist, 1, Inf, M₃)
+```
+
+## Plot Simulation
+The code below plots a histogram for each alternative.
+ ```@example MDFT 
+histogram(dist; model_args = (M₃,))
+```
+# 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.

docs/src/poisson_race.md

@@ -71,12 +71,10 @@ logpdf.(dist, choices, rts)
 ```
 
 ## Compute Choice Probability
-The choice probability $\Pr(C=c)$ is computed by passing the model and choice index to `cdf`.
-
+The choice probability $\Pr(C=c)$ is computed by passing the model and choice index to `cdf` along with a large value for time as the second argument.
  ```@example poisson_race 
-cdf(dist, 1)
+cdf(dist, 1, Inf)
 ```
-To compute the joint probability of choosing $c$ within $t$ seconds, i.e., $\Pr(T \leq t \wedge C=c)$, pass a third argument for $t$.
 
 ## Plot Simulation
 The code below overlays the PDF on reaction time histograms for each option.