DstarM (version 0.1.0)

estDstarM: Do a D*M analysis

Description

Do a D*M analysis

Usage

estDstarM(data, tt, restr = NULL, fixed = list(), lower, upper, Optim = list(), DstarM = TRUE, SE = 0, oscPdf = TRUE, splits = rep.int(0, (ncondition)), forceRestriction = TRUE, mg = NULL, h = 1, pars, fun.density = Voss.density, args.density = list(), fun.dist = chisq, args.dist = list(tt = tt), verbose = TRUE)

Arguments

data

A dataframe 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).

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 oscilations.

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, usefull if a uniform kernel approximation does not suffice.

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

Logical, should intermediate output be printed? Defaults to TRUE. Estimation will speed up if set to FALSE. 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 FALSE and specify trace in Optim.

Value

Returns an object of class 'D*M', which is a named list.

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.

Examples

# 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)