Skip to contents

Censored-Shifted Wald Model

Source: R/model_cswald.R
cswald.Rd

Censored-Shifted Wald Model

Usage

cswald(rt, response, links = NULL, version = c("simple", "crisk"), ...)

Arguments

rt

The name of the variable in the dataset containing the response times. Response times should be coded in seconds (not milliseconds).

response

The name of the variable in the dataset containing the response/decision. Responses should be coded as 0 (lower boundary) or 1 (upper boundary). Alternatively, character values "lower" and "upper" or logical values (FALSE/TRUE) are accepted and will be converted automatically.

A named list of link functions for the model parameters. Available parameters depend on the version: "simple" has drift, bound, ndt, and s; "crisk" additionally has zr. Default links are "log" for bound, ndt and s, and "logit" for zr. drift has a "log" link in "simple", where it is positive, and an "identity" link in "crisk", where it can be negative, as in ddm() and ezdm(). For positive parameters, "softplus" is available as an alternative to "log" that grows linearly for large values and avoids the numerical blow-up of exp(). A name that is not a parameter of the model is an error, and a link that allows values the default link excludes (e.g. "identity" for a positive parameter) is a warning.

version

A character string specifying which version of the cswald model to use. Options are:

  • "simple" (default): The standard censored shifted Wald model, which treats error responses as censored correct responses. Best suited for tasks with few errors (<20%). Note: The bound parameter in the simple version represents the distance from the starting point to the correct boundary, which is half the total boundary separation in the diffusion model (assuming an unbiased starting point). To convert to the full boundary separation (as in DDM or crisk), multiply by 2.

  • "crisk": The competing risks version, which models both response types as arising from racing accumulators toward opposite boundaries. Better suited for tasks with substantial error rates. The bound parameter represents the total boundary separation, consistent with the diffusion model parameterization. zr is fixed at 0 on its logit scale (an unbiased zr = 0.5) unless you give it a formula.

For more details, see Miller et al. (2018).

...

Additional arguments passed internally (for testing purposes).

Value

An object of class bmmodel

Details

  • Domain: Decision making

  • Task: Choices and response times

  • Name: Censored-Shifted Wald Model

  • Citation:

    • Miller, R., Scherbaum, S., Heck, D. W., Goschke, T., & Enge, S. (2018). On the relation between the (censored) shifted Wald and the Wiener distribution as measurement models for choice response times. Applied Psychological Measurement, 42(2), 116-135. https://doi.org/10.1177/0146621617710465

  • Version: simple

  • Requirements:

    • Reaction times should be passed in seconds

  • The response variable should be passed numerically: 0 = lower response, 1 = upper response

  • Parameters:

    • drift: drift rate

    • bound: boundary (distance from starting point to correct boundary, half the boundary separation bound of version "crisk", ddm() and ezdm())

    • ndt: non-decision time

    • s: diffusion constant

  • Fixed parameters:

    • mu = 0

    • s = 0

  • Default parameter links:

    • drift = log; bound = log; ndt = log; s = log

  • Default priors:

    • drift:

      • main: normal(0,1)

      • effects: normal(0,0.3)

      • sd: exponential(2)

    • bound:

      • main: normal(0,0.3)

      • effects: normal(0,0.3)

      • sd: exponential(2)

    • ndt:

      • main: normal(-2,0.3)

      • effects: normal(0,0.3)

      • sd: exponential(2)

    • s:

      • main: normal(0,0.3)

      • effects: normal(0,0.2)

      • sd: exponential(2)

The prior for ndt and the fastest response

ndt has to stay below every response the model fits: all responses in version "crisk", the correct ones in "simple", which censors errors. bmm() and update() warn when more than half of the prior for ndt lies at or above the fastest of these responses. Sampling can then fail to start, and the data pull ndt down against the prior. With the default prior, normal(-2, 0.3) on the log scale, this happens when the fastest response is faster than 0.135 s. Set a prior with a lower location, as the warning suggests, or filter out anticipations. The check reads normal() and student_t() priors on the intercept of ndt, or on each cell of a formula without an intercept such as ndt ~ 0 + cond; other priors and designs are not checked, and neither are truncated priors or the links "inverse" and "logm1". In a formula with other fixed effects, such as ndt ~ 1 + cond, the prior on the intercept is the prior on the centred intercept (the grand mean), and the check compares it with the fastest response overall. update() with init or inits skips the check, while bmm() with init still runs it.

See also

dcswald() and rcswald() for the density and random generation functions.

Examples

if (FALSE) { # identical(Sys.getenv("BMM_EXAMPLES"), "true")
# generate simulated data from the diffusion model
dat <- rcswald(n = 500, drift = 2, bound = 1.5, ndt = 0.3, zr = 0.5, s = 1)

# specify the model
model <- cswald(rt = "rt", response = "response", version = "simple")

# specify the formula
formula <- bmf(
  drift ~ 1,
  bound ~ 1,
  ndt ~ 1
)

# fit the model
fit <- bmm(
  formula = formula,
  data = dat,
  model = model,
  cores = 4,
  backend = "cmdstanr"
)
}