estDstarM: Do a D*M analysis

Description Usage Arguments Details Value Examples

View source: R/estDstarM.R

Description

Do a D*M analysis

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
estDstarM(
  formula = NULL,
  data,
  tt,
  restr = NULL,
  fixed = list(),
  lower,
  upper,
  Optim = list(),
  DstarM = TRUE,
  SE = 0,
  oscPdf = TRUE,
  splits = rep(0L, (ncondition)),
  forceRestriction = TRUE,
  mg = NULL,
  h = 1,
  pars,
  fun.density = Voss.density,
  args.density = list(),
  fun.dist = chisq,
  args.dist = list(tt = tt),
  verbose = 1L,
  useRcpp = TRUE
)

Arguments

formula

A formula object of the form: binary response ~ reaction time + condition1 * condition2 * ... conditionN.

data

A dataframe for looking up data specified in formula. For backwards compatibility this can also be with: a column named rt containing response times in ms, a column named response containing at most 2 response options, and an optional column named condition containing a numeric index as to which conditions observations belong.

tt

A time grid on which the density function will be evaluated. Should be larger than the highest observed reaction time.

restr

A restriction matrix where each column depicts one condition. The number of rows should match the number of parameters (and be equal to the length of lower). The contents of restr should be numbers, identical numbers means that these parameters (either within or between condition) will be constrained. Different numbers means parameters will not be constrained.

fixed

A matrix that allows for fixing parameters to certain values.

lower

Should be a vector containing lower bounds for each parameter. Has a default if fun.density == Voss.density.

upper

Should be a vector containing upper bounds for each parameter. Has a default if fun.density == Voss.density.

Optim

a named list with identical arguments to DEoptim.control. In addition, if verbose == TRUE Optim$steptol can be a vector, i.e. c(200, 50, 10) means: Do 200 iterations then check for convergence, do 50 iterations then check for convergence, check every 10 iterations for convergence until itermax is reached. Defaults to Optim = list(reltol = 1e-6, itermax = 1e3, steptol = 50, CR = .9, trace = 0, parallelType = 0).

DstarM

If TRUE a D*M analysis is done, otherwise the Chi square distance between data and model is minimized.

SE

positive value, how many standard error to add to the variance to relax the variance restriction a bit.

oscPdf

Logical, if TRUE check for oscillations in calculated densities and remove densities with oscillations.

splits

Numeric vector determining which conditions have an equal nondecision density. Identical values in two positions indicate that the conditions corresponding to the indices of those values have an identical nondecision distribution.

forceRestriction

if TRUE the variance restriction is enforced.

mg

Supply a data density, useful if a uniform kernel approximation does not suffice. Take care that densities of response categories within conditions are degenerate and therefore integrate to the proportion a category was observed (and not to 1).

h

bandwidth of a uniform kernel used to generate data based densities.

pars

Optional parameter vector to supply if one wishes to evaluate the objective function in a given parameter vector. Only used if itermax equal zero.

fun.density

Function used to calculate densities. See details.

args.density

A names list containing additional arguments to be send to fun.density.

fun.dist

Function used to calculate distances between densities. Defaults to a chi-square distance.

args.dist

A named list containing additional arguments to be send to fun.dist.

verbose

Numeric, should intermediate output be printed? Defaults to 1, higher values result in more progress output. Estimation will speed up if set to 0. If set to TRUE, Optim$trace will be forced to 0, hereby disabling the build in printing of DEoptim. To enable the printing of DEoptim, set verbose to 0 and specify Optim$trace. Optim. If set to 1, ETA refers to the expected maximum time until completion (when the iterations limit is reached).

useRcpp

Logical, setting this to true will make the objective function use an Rcpp implementation of Voss.density with the distance function chisq. This gains speed at the cost of flexibility.

Details

Response options will be alphabetically sorted and the first response option will be treated as the 'lower' option. This means that if the observed proportion of the first response options is higher, the drift speed will most likely be negative.

fun.density allows a user to specify a custom density function. This function must (at least) take the following arguments: t: a vector specifying at which time points to calculate the density pars: a parameter vector boundary: character 'upper' or 'lower' specifying for which response option the density will be calculated. DstarM: Logical, if TRUE the density should not describe the nondecision density, if FALSE it should describe the nondecision density. Any additional arguments can be passed to fun.density via the argument args.density. If one intends to use a custom density function it is recommended to test the function first with testFun. When specifying a custom density function it is probably also necessary to change the lower and upper bounds of the parameter space.

For purposes of speed, the function can be run in parallel by providing the argument Optim = list(parallelType = 1). See DEoptim.control for details. Also, for Ratcliff models the objective function has been rewritten in Rcpp. This limits some functionality but does result in a faster estimation. Usage of Rcpp can be enabled via useRcpp = TRUE.

When verbose is set to 1, the ETA is an estimated of the time it takes to execute ALL iterations. Convergence can (and is usually) reached before then.

Value

Returns a list of class DstarM.fitD that contains:

Bestvals

Named numeric vector. Contains the best parameter estimates.

fixed

Numeric vector. Contains the best parameter estimates.

GlobalOptimizer

List. All output from the call to DEoptim

Debug

List. contains the number of DEoptim iterations, the number of function evaluation of the objective function, and the maximum number of iterations.

note

String. A possible note that is used for summary purposes

tt

Numeric vector. Contains the time grid used.

g.hat

Numeric matrix. Named columns represent the (possibly smoothed) densities of the data distribution of each condition-response pair.

modelDist

Numeric matrix. Named columns represent the densities of the model evaluated at grid tt with parameters Bestvals.

ncondition

Numeric scalar. The number of conditions

var.data

Numeric vector. The variance of each condition-response pair. There are as many values as hypothesized nondecision densities.

var.m

Numeric vector. The variance of the model distributions. There are as many values as hypothesized nondecision densities.

restr.mat

Numeric matrix. Contains the restrictions used.

splits

Numeric vector. Equal to the input argument with the same name.

n

Numeric scalar. The total number of observations.

DstarM

Logical. Equal to the input argument with the same name.

fun.density

Function. Equal to the input argument with the same name.

fun.dist

Function. Equal to the input argument with the same name.

h

Scalar. Equal to the input argument with the same name.

args.density

Named list. Equal to the input argument with the same name.

args.dist

Named list. Equal to the input argument with the same name.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
# simulate data with three stimuli of different difficulty.
# this implies different drift rates across conditions.
# define a time grid. A more reasonable stepsize is .01; this is just for speed.
tt = seq(0, 5, .1)
pars = c(.8, 2, .5, .5, .5, # condition 1
        .8, 3, .5, .5, .5,  # condition 2
        .8, 4, .5, .5, .5)  # condition 3
pdfND = dbeta(tt, 10, 30)
# simulate data
data = simData(n = 3e3, pars = pars, tt = tt, pdfND = pdfND)
# define restriction matrix
restr = matrix(1:5, 5, 3)
restr[2, 2:3] = 6:7 # allow drift rates to differ
# fix variance parameters
fixed = matrix(c('sz1', .5, 'sv1', .5), 2, 2)
## Not run: 
# Run D*M analysis
res = estDstarM(data = data, tt = tt, restr = restr, fixed = fixed)
coef(res)
summary(res)

## End(Not run)

DstarM documentation built on Aug. 29, 2020, 1:06 a.m.