WIP: Ratcliff Diffusion Model pdf and simulators

.gitignore

@@ -1,4 +1,3 @@
 Manifest.toml
 /temp
-/benchmark/*.json
-/benchmark/*.md
+/.vscode

docs/.gitignore

@@ -1,4 +1,5 @@
 build/
 site/
 docs/build/
-Manifest.toml
+Manifest.toml
+settings.json

docs/src/DDM.md

@@ -1,9 +1,13 @@
 # Diffusion Decision Model
 
-The Diffusion Decision Model (DDM; Ratcliff et al., 2016) is a model of speeded decision-making in two-choice tasks. The DDM assumes that evidence accumulates over time, starting from a certain position, until it crosses one of two boundaries and triggers the corresponding response (Ratcliff & McKoon, 2008; Ratcliff & Rouder, 1998; Ratcliff & Smith, 2004). Like other Sequential Sampling Models, the DDM comprises psychologically interpretable parameters that collectively form a generative model for reaction time distributions of both responses.
+The Diffusion Decision Model (DDM; Ratcliff et al., 2016) is a model of speeded decision-making in two-choice tasks. The DDM assumes that evidence accumulates over time, starting from a certain position, until it crosses one of two boundaries and triggers the corresponding response (Ratcliff & McKoon, 2008; Ratcliff & Rouder, 1998; Ratcliff & Smith, 2004). Like other Sequential Sampling Models, the DDM comprises psychologically interpretable parameters that collectively form a generative model for reaction time distributions of both responses. 
 
 The drift rate (ν) determines the rate at which the accumulation process approaches a decision boundary, representing the relative evidence for or against a specific response. The distance between the two decision boundaries (referred to as the evidence threshold, α) influences the amount of evidence required before executing a response. Non-decision-related components, including perceptual encoding, movement initiation, and execution, are accounted for in the DDM and reflected in the τ parameter. Lastly, the model incorporates a bias in the evidence accumulation process through the parameter z, affecting the starting point of the drift process in relation to the two boundaries. The z parameter in DDM is relative to a (i.e. it ranges from 0 to 1).
 
+However, in the Ratcliff Diffusion Decision Model, we also include across-trial variability parameters. These parameters were developed to explain specific discrepancies between the DDM and experimental data (Anderson, 1960; Laming, 1968; Blurton et al., 2017). The data exhibited a difference in mean RT between correct and error responses that could not be captured by the DDM. As a result, two parameters for across-trial variability were introduced to explain this difference: across-trial variability in the starting point (sz) to explain fast errors (Laming, 1968), and across-trial variability in drift rate (η) to explain slow errors (Ratcliff, 1978; Ratcliff and Rouder, 1998). Additionally, the DDM also showed a sharper rise in the leading edge of the response time distribution than observed in the data. To capture this leading edge effect, across-trial variability in non-decision time (st) was introduced. 
+
+Previous work has validated predictions of these across-trial variability parameters (Wagenmakers et al., 2009). When compared to the DDM, the Ratcliff DDM improves the fit to the data. Researchers now often assume that the core parameters of sequential sampling models, such as drift rates, non-decision times, and starting points vary between trials.
+
 One last parameter is the within-trial variability in drift rate (σ), or the diffusion coefficient. The diffusion coefficient is the standard deviation of the evidence accumulation process within one trial. It is a scaling parameter and by convention it is kept fixed. Following Navarro & Fuss, (2009), we use the σ = 1 version.
 
 # Example
@@ -33,8 +37,11 @@ In the code below, we will define parameters for the DDM and create a model obje
 
 The 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
 
+Across-trial-variability of drift rate. Standard deviation of a normal distribution with mean v describing the distribution of actual drift rates from specific trials. Values different from 0 can predict slow errors. Typical range: 0 < η < 2. Default is 0.
+
 ```@example DDM
 ν=1.0
+η = 0.16
 ```
 
 ### Boundary Separation
@@ -49,24 +56,30 @@ The amount of information that is considered for a decision. Large values indica
 
 The duration for a non-decisional processes (encoding and response execution). Typical range: 0.1 < τ < 0.5 
 
+Across-trial-variability of non-decisional components. Range of a uniform distribution with mean τ + st/2 describing the distribution of actual τ values across trials. Accounts for response times below t0. Reduces skew of predicted RT distributions. Typical range: 0 < τ < 0.2. Default is 0.
+
 ```@example DDM 
 τ = 0.30
+st = 0.10
 ```
 
 ### Starting Point
 
 An indicator of an an initial bias towards a decision. The z parameter is relative to a (i.e. it ranges from 0 to 1).
 
+Across-trial-variability of starting point. Range of a uniform distribution with mean z describing the distribution of actual starting points from specific trials. Values different from 0 can predict fast errors. Typical range: 0 < sz < 0.5. Default is 0.
+
 ```@example DDM 
 z = 0.50
+sz = 0.05
 ```
 
 ### DDM Constructor 
 
 Now that values have been assigned to the parameters, we will pass them to `DDM` to generate the model object.
 
 ```@example DDM 
-dist = DDM(ν, α, τ, z)
+dist = DDM(ν, α, τ, z, η, sz, st, σ)
 ```
 
 ## Simulate Model
@@ -108,6 +121,10 @@ plot!(dist; t_range=range(.301, 1, length=100))
 
 # References
 
+Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7–12. https://doi.org/10.1016/j.jmp.2016.11.003
+
+Laming, D. R. J. (1968). Information theory of choice-reaction times. Academic Press.
+
 Navarro, D., & Fuss, I. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. https://doi.org/10.1016/J.JMP.2009.02.003
 
 Ratcliff, R., & McKoon, G. (2008). The Diffusion Decision Model: Theory and Data for Two-Choice Decision Tasks. Neural Computation, 20(4), 873–922. https://doi.org/10.1162/neco.2008.12-06-420
@@ -117,3 +134,5 @@ Ratcliff, R., & Rouder, J. N. (1998). Modeling Response Times for Two-Choice Dec
 Ratcliff, R., & Smith, P. L. (2004). A comparison of sequential sampling models for two-choice reaction time. Psychological Review, 111 2, 333–367. https://doi.org/10.1037/0033-295X.111.2.333
 
 Ratcliff, R., Smith, P. L., Brown, S. D., & McKoon, G. (2016). Diffusion Decision Model: Current Issues and History. Trends in Cognitive Sciences, 20(4), 260–281. https://doi.org/10.1016/j.tics.2016.01.007
+
+Wagenmakers, E.-J. (2009). Methodological and empirical developments for the Ratcliff diffusion model of response times and accuracy. European Journal of Cognitive Psychology, 21(5), 641-671.