rtdists (version 0.4-9)

Diffusion: The Ratcliff Diffusion Model

Description

Density, distribution function, quantile function, and random generation for the Ratcliff diffusion model with eight parameters: a (threshold separation), z (relative starting point), v (drift rate), t0 (non-decision time/response time constant), d (differences in speed of response execution), sv (inter-trial-variability of drift), st0 (inter-trial-variability of non-decisional components), and sz (inter-trial-variability of relative starting point).

Usage

ddiffusion(rt, boundary = "upper", a, v, t0, z = 0.5, d = 0, sz = 0,
  sv = 0, st0 = 0, precision = 3)
pdiffusion(rt, boundary = "upper", a, v, t0, z = 0.5, d = 0, sz = 0,
  sv = 0, st0 = 0, precision = 3, maxt = 10000)
qdiffusion(p, boundary = "upper", a, v, t0, z = 0.5, d = 0, sz = 0,
  sv = 0, st0 = 0, precision = 3, maxt = 10000, interval = c(0, 10))
rdiffusion(n, a, v, t0, z = 0.5, d = 0, sz = 0, sv = 0, st0 = 0,
  precision = 3)

Arguments

rt

a vector of RTs.

boundary

character vector. Which boundary should be tested? Possible values are c("upper", "lower"), possibly abbreviated and "upper" being the default. Alternatively, a numeric vector with values 1=lower and 2=upper. For convenience, /co

a

threshold separation. Amount of information that is considered for a decision. Large values indicate a conservative decisional style. Typical range: 0.5 < a < 2

v

drift rate. Average slope of the information accumulation process. The drift gives information about the speed and direction of the accumulation of information. Large (absolute) values of drift indicate a good performance. If received information supports

t0

non-decision time or response time constant (in seconds). Lower bound for the duration of all non-decisional processes (encoding and response execution). Typical range: 0.1 < t0 < 0.5

z

relative starting point. Indicator of an a priori bias in decision making. When the relative starting point z deviates from 0.5, the amount of information necessary for a decision differs between response alternatives. Typical range: 0.3 <

d

differences in speed of response execution (in seconds). Positive values indicate that response execution is faster for responses linked to the upper threshold than for responses linked to the lower threshold. Typical range: -0.1 < d < 0.1. D

sz

inter-trial-variability of (relative) starting point. Range of a uniform distribution with mean z describing the distribution of actual starting points from specific trials. Minimal impact on the RT distributions. Can be fixed to 0 in most ap

sv

inter-trial-variability of drift rate. Standard deviation of a normal distribution with mean v describing the distribution of actual drift rates from specific trials. Minimal impact on the RT distributions. Can be fixed to 0 in most appli

st0

inter-trial-variability of non-decisional components. Range of a uniform distribution with mean t0 + st0/2 describing the distribution of actual t0 values across trials. Accounts for response times below t0. Reduces

precision

numerical scalar value. Precision of calculation. Corresponds roughly to the number of decimals of the predicted CDFs that are calculated accurately. Default is 3.

maxt

maximum rt allowed, used to stop integration problems (prd only).

p

vector of probabilities.

interval

a vector containing the end-points of the interval to be searched for the desired quantiles (i.e., RTs) in qdiffusion. Default is c(0, 10).

n

is a desired number of observations.

Value

• ddiffusion gives the density, pdiffusion gives the distribution function, qdiffusion gives the quantile function (i.e., predicted RTs), and rdiffusion generates random response times and decisions (returning a data.frame with columns rts (numeric) and response (factor)).

  The length of the result is determined by n for rrd, and is equal to the length of rt for drd and prd.

  The distribution parameters (as well as boundary) are recycled to the length of the result. In other words, the functions are completely vectorized for all parameters and even the boundary.

Details

The Ratcliff diffusion model (Ratcliff, 1978) is a mathematical model for two-choice discrimination tasks. It is based on the assumption that information is accumulated continuously until one of two decision thresholds is hit. For more information, see Voss, Rothermund, and Voss (2004), Voss, Nagler, and Lerche (2013), or Wagenmakers (2009).

All functions are fully vectorized acros all parameters as well as the boundary. This allows for trialwise parameters for each parameter.

Quantile Function{ Due to the bivariate nature of the diffusion model, the diffusion processes reaching each boundary only return the defective CDF that does not reach 1. Only the sum of the CDF for both boundaries reaches 1. Therefore, qdiffusion can only return quantiles/RTs for any accumulator up to the maximal probability of that accumulator's CDF. This can be obtained by evaluating the CDF at a high value or Inf (the latter can be slow). See examples.

Also note that quantiles (i.e., predicted RTs) are obtained by numerically minimizing the absolute difference between desired probabiliy and the value returned from pdiffusion using optimize. If the difference between the desired probability and probability corresponding to the returned quantile is above a certain threshold (currently 0.0001) no quantile is returned but NA. This can be either because the desired quantile is above the maximal probability for this accumulator or because the limits for the numerical integration are too small (default is c(0, 10)). }

References

Ratcliff, R. (1978). A theory of memory retrieval. Psychological Review, 85(2), 59-108.

Voss, A., Rothermund, K., & Voss, J. (2004). Interpreting the parameters of the diffusion model: An empirical validation. Memory & Cognition. Vol 32(7), 32, 1206-1220.

Voss, A., Nagler, M., & Lerche, V. (2013). Diffusion Models in Experimental Psychology: A Practical Introduction. Experimental Psychology, 60(6), 385-402. doi:10.1027/1618-3169/a000218

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.

Examples

## identical calls (but different random values)
rt1 <- rdiffusion(500, a=1, v=2, t0=0.5)
head(rt1)
rt2 <- rdiffusion(500, a=1, v=2, t0=0.5, z=0.5, d=0, sz=0, sv=0, st0=0)
head(rt2)
  
# get density for random RTs:
sum(log(ddiffusion(rt1$rt, rt1$response, a=1, v=2, t0=0.5)))  # boundary is factor
sum(log(ddiffusion(rt1$rt, as.numeric(rt1$response), a=1, v=2, t0=0.5))) # boundary is numeric
sum(log(ddiffusion(rt1$rt, as.character(rt1$response), a=1, v=2, t0=0.5))) # boundary is character

sum(log(ddiffusion(rt2$rt, rt2$response, a=1, v=2, t0=0.5)))

# can we recover the parameters?
ll_diffusion <- function(pars, rt, boundary) 
{
  densities <- tryCatch(
    ddiffusion(rt, boundary=boundary, 
               a=pars[1], v=pars[2], t0=pars[3], 
               z=0.5, sz=pars[4], 
               st0=pars[5], sv=pars[6]), 
    error = function(e) 0)
  if (any(densities == 0)) return(1e6)
  return(-sum(log(densities)))
}

start <- c(runif(2, 0.5, 3), 0.1, runif(3, 0, 0.5))
names(start) <- c("a", "v", "t0", "sz", "st0", "sv")
recov <- nlminb(start, ll_diffusion, lower = 0, rt=rt1$rt, boundary=rt1$response)
round(recov$par, 3)
#     a     v    t0    sz   st0    sv 
# 1.017 2.186 0.505 0.345 0.000 0.000

# plot density:
curve(ddiffusion(x, a=1, v=2, t0=0.5, boundary = "upper"), 
      xlim=c(0,3), main="Density of upper responses", ylab="density", xlab="response time")
curve(ddiffusion(x, a=1, v=2, t0=0.5, st0=0.2, boundary = "upper"), 
      add=TRUE, lty = 2)
legend("topright", legend=c("no", "yes"), title = "Starting Point Variability?", lty = 1:2)

# plot cdf:
curve(pdiffusion(x, a=1, v=2, t0=0.5, st0=0.2, boundary="u"), 
     xlim = c(0, 3),ylim = c(0,1), 
     ylab = "cumulative probability", xlab = "response time",
     main = "CDF of diffusion model with start point variability")
curve(pdiffusion(x, a=1, v=2, t0=0.5, st0=0.2, boundary="l"), 
     add=TRUE, lty = 2)
legend("topleft", legend=c("upper", "lower"), title="boundary", lty=1:2)


### qLBA can only return values up to maximal predicted probability:
# maximum probability for a given set
pdiffusion(20, a=1, v=2, t0=0.5, st0=0.2, sz = 0.1, sv = 0.5, boundary="u")
# [1] 0.8705141

# equal but much slower:
# pdiffusion(Inf, a=1, v=2, t0=0.5, st0=0.2, sz = 0.1, sv = 0.5, boundary="u") 
# [1] 0.8705141

qdiffusion(0.87, a=1, v=2, t0=0.5, st0=0.2, sz = 0.1, sv = 0.5, boundary="u")
# [1] 1.769253

qdiffusion(0.88, a=1, v=2, t0=0.5, st0=0.2, sz = 0.1, sv = 0.5, boundary="u")
# NA