estDstarM: Do a DM analysis
In vandenman/DstarM: Analyze Two Choice Reaction Time Data with the DM Method

Description Usage Arguments Details Value Examples

Do a D*M analysis

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
)

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

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.

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.

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