| Type: | Package |
| Title: | Fast Implementation of the Diffusion Decision Model |
| Version: | 1.0-2 |
| Description: | Provides the probability density function (PDF), cumulative distribution function (CDF), the first-order and second-order partial derivatives of the PDF, and a fitting function for the diffusion decision model (DDM; e.g., Ratcliff & McKoon, 2008, <doi:10.1162/neco.2008.12-06-420>) with across-trial variability in the drift rate. Because the PDF, its partial derivatives, and the CDF of the DDM both contain an infinite sum, they need to be approximated. 'fddm' implements all published approximations (Navarro & Fuss, 2009, <doi:10.1016/j.jmp.2009.02.003>; Gondan, Blurton, & Kesselmeier, 2014, <doi:10.1016/j.jmp.2014.05.002>; Blurton, Kesselmeier, & Gondan, 2017, <doi:10.1016/j.jmp.2016.11.003>; Hartmann & Klauer, 2021, <doi:10.1016/j.jmp.2021.102550>) plus new approximations. All approximations are implemented purely in 'C++' providing faster speed than existing packages. |
| License: | GPL-2 |GPL-3 [expanded from: GPL (≥ 2)] |
| Imports: | Rcpp (≥ 1.0.1), stats, methods, Formula |
| LinkingTo: | Rcpp, RcppEigen |
| Depends: | R (≥ 3.5.0) |
| Suggests: | rtdists, RWiener, ggplot2, reshape2, testthat, knitr,rmarkdown, microbenchmark, ggnewscale, ggforce, WienR, emmeans,estimability, lmtest, numDeriv |
| URL: | https://github.com/rtdists/fddm |
| BugReports: | https://github.com/rtdists/fddm/issues |
| RoxygenNote: | 7.3.1 |
| Encoding: | UTF-8 |
| VignetteBuilder: | knitr |
| NeedsCompilation: | yes |
| Packaged: | 2024-07-01 13:22:08 UTC; kendal |
| Author: | Kendal B. Foster [aut], Henrik Singmann [ctb, cre], Achim Zeileis [ctb] (methods partially taken from betareg) |
| Maintainer: | Henrik Singmann <singmann@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2024-07-02 16:00:07 UTC |
Second-Order Partial Derivative of 5-parameter DDM PDF with respect to a(threshold separation)
Description
Second-Order Partial Derivative of the density function for the 5-parametervariant of the Ratcliff diffusion decision model (DDM) with respect to a,the threshold separation. This variant contains the following parameters:v (drift rate),a (threshold separation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift),andsigma (diffusion coefficient of underlying Wiener process).
Usage
da2_dfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, sl_thresh = 0.5, err_tol = 1e-06)Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
sl_thresh | Threshold for deciding when to use the "small-time" variantor the "large-time" variant. If the "effective response time" is greaterthan |
err_tol | Allowed error tolerance of the overall calculation. Since thepartial derivative of the density function contains the sum of twoinfinite sums, each approximation of these two infinite sums will have anindividual error tolerance of |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR input wrapping will occur.
sv - Both the "small-time" and "large-time" variants of the densityfunction have two further variants: one with a constant drift ratev(i.e.,sv= 0), and one with a variable drift ratev(i.e.,sv> 0). The details of the differences between thesetwo density functions can be found in our associated paper. To use thedensity function with a constant drift rate, leave the parametersvto its default value ofsv = 0, as this will indicate no drift to thefunction. To use the density function with a variable drift rate, set theparametersv to some non-negative value, i.e.,sv> 0.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
Value
A vector containing the second-order partial derivatives of theDDM PDF with precisionerr_tol whose length matches that of thelongest input parameter (usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Hartmann, R., Klauer, K. C. (2021). Partial derivatives for thefirst-passage time distribution in Wiener diffusion models. Journal ofMathematical Psychology, 103, 102550.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
Examples
# derivative with respect to rt (response time)dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to t0 (non-decision time)dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to a (threshold separation)da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to v (drift rate)dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to w (relative starting point)dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to sv (inter-trial variability in the drift rate)dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)#-------- Log Versions --------## # derivative with respect to rt (response time)# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to t0 (non-decision time)# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to a (threshold separation)# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to v (drift rate)# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to w (relative starting point)# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to sv (inter-trial variability in the drift rate)# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)Partial Derivative of 5-parameter DDM PDF with respect to a (thresholdseparation)
Description
Partial Derivative of the density function for the 5-parameter variant ofthe Ratcliff diffusion decision model (DDM) with respect to a, thethreshold separation. This variant contains the following parameters:v (drift rate),a (threshold separation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift),andsigma (diffusion coefficient of underlying Wiener process).
Usage
da_dfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, sl_thresh = 0.5, err_tol = 1e-06)Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
sl_thresh | Threshold for deciding when to use the "small-time" variantor the "large-time" variant. If the "effective response time" is greaterthan |
err_tol | Allowed error tolerance of the overall calculation. Since thepartial derivative of the density function contains the sum of twoinfinite sums, each approximation of these two infinite sums will have anindividual error tolerance of |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR input wrapping will occur.
sv - Both the "small-time" and "large-time" variants of the densityfunction have two further variants: one with a constant drift ratev(i.e.,sv= 0), and one with a variable drift ratev(i.e.,sv> 0). The details of the differences between thesetwo density functions can be found in our associated paper. To use thedensity function with a constant drift rate, leave the parametersvto its default value ofsv = 0, as this will indicate no drift to thefunction. To use the density function with a variable drift rate, set theparametersv to some non-negative value, i.e.,sv> 0.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
Value
A vector containing the partial derivatives of the DDM PDF withprecisionerr_tol whose length matches that of the longest inputparameter (usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Hartmann, R., Klauer, K. C. (2021). Partial derivatives for thefirst-passage time distribution in Wiener diffusion models. Journal ofMathematical Psychology, 103, 102550.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
Examples
# derivative with respect to rt (response time)dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to t0 (non-decision time)dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to a (threshold separation)da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to v (drift rate)dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to w (relative starting point)dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to sv (inter-trial variability in the drift rate)dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)#-------- Log Versions --------## # derivative with respect to rt (response time)# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to t0 (non-decision time)# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to a (threshold separation)# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to v (drift rate)# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to w (relative starting point)# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to sv (inter-trial variability in the drift rate)# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)Estimation of 5-Parameter DDM
Description
Fit the 5-parameter DDM (Diffusion Decision Model) via maximum likelihoodestimation. The model for each DDM parameter can be specified symbolicallyusing R's formula interface. With the exception of the drift rate (which isalways estimated) all parameters can be either fixed or estimates.
Usage
ddm( drift, boundary = ~1, ndt = ~1, bias = 0.5, sv = 0, data, optim = "nlminb", args_optim = list(init = NULL, lo_bds = NULL, up_bds = NULL, control = list()), args_ddm = list(err_tol = 1e-06), use_gradient = TRUE, compiled_model = TRUE, model = TRUE, mmatrix = TRUE, response = TRUE, na.action, subset, contrasts = NULL)Arguments
drift | Two-sided formula. The left-hand side describes the response,the right-hand side provides a symbolic description of the regression modelunderlying the drift rate (v). The left-hand side needs to specify thecolumn in the data containing response time and corresponding binarydecision, concatenated by |
boundary,ndt,bias,sv | Either a one-sided formula providing a symbolicdescription of the regression model or a scalar number given the value thisparameter should be fixed to. Boundary separation (a), non-decision time(t0), relative initial bias (w), or inter-trial variability in the driftrate (sv) |
data,na.action,subset | arguments controlling formula processing via |
optim | character string or fitting function indicating which numericaloptimization method should be used. The default |
args_optim | named list of additional arguments for the optimizationfunction. The available options are:
|
args_ddm | named list of additional arguments passed to density functioncalculation. Currently, the only option for this is |
use_gradient | logical. Should gradient be used during numericaloptimization? Default is |
compiled_model,model,mmatrix,response | logicals. If |
contrasts | optional list. See the contrasts.arg of |
Details
ddm usesmodel.matrix for transforming thesymbolic description of the regression model underlying each parameter intoestimated coefficients. The following provides a few examples:
~ 1estimates a single coefficient, named(Intercept)~ conditionestimates the intercept plus k - 1 coefficientsfor a factor with k levels (e.g., intercept plus one coefficient ifcondition has two levels). The interpretation of the coefficientsdepend on the factor contrasts employed, which are usually based onthe contrasts specified inoptions("contrasts"). For thedefaulttreatmentcontrasts (contr.treatment),the intercept corresponds to the first factor level and theadditional coefficients correspond to the difference from theintercept (i.e., first factor level). When usingcontr.sumthe intercept corresponds to the grand mean and the additionalcoefficients correspond to the differences from the grand mean.~ 0 + conditionestimates no intercept but one coefficientper factor level. This specification can also be used to get onecoefficient per cell for a multi-factorial design, e.g.,~ 0 + condition1:condition2.~ 0 + condition1 + condition1:condition2estimates one"intercept" per level ofcondition1factor (which is notcalled intercept) plus k - 1 difference parameters from thecondition-specific intercept for the k-levels ofcondition2.The interpretation of the difference parameters again depends onthe contrasts used (e.g., treatment vs. sum-to-zero contrasts, seeexamples). This formula specification can often make sense for thedrift rate whencondition1is the factor (such as item type)mapped to upper and lower response boundary of the DDM andcondition2is another factor by which we want the drift rateto differ. This essentially gives one overall drift rate perresponse boundary plus the differences from this overall one (noteagain that with treatment contrasts this overall drift rate is thefirst factor level ofcondition2).
To get meaningful results it is necessary to estimate separate drift ratesfor the different condition/item-types that are mapped onto the upper andlower boundary of the diffusion model.
If a non-default fitting function is used, it needs to minimize thenegative log-likelihood, accept the following arguments,init, objective, gradient, lower, upper, control , and return a listwith the following argumentscoefficients, loglik, converged, optim(whereconverged is boolean andoptim can be an arbitrarylist with additional information).
Value
Object of classddm (i.e., a list with components as listedbelow) for which a number of common methods such asprint,coef, andlogLik are implemented, seeddm-methods.
coefficientsa named list whose elements are the values ofthe estimated model parametersdpara character vector containing the names of theestimated model parametersfixed_dpara named list whose elements are the values of thefixed model parametersloglikthe value of the log-likelihood function at theoptimized parameter valueshessiansa named list whose elements are the individualHessians for each of the model parametersvcova named list whose elements are the individualvariance-covariance matrices for each of the model parametersnobsthe number of observations in the data used for fittingnparthe number of parameters used to fit the model (i.e.,the estimated model parameters plus any hyperparameters)df.residualthe residual degrees of freedom (the number ofobservations - the number of parameters)callthe original function call toddmformulathe formulas used in the model (1indicatesthat the model parameter was estimated with a single coefficient;0indicates that the model parameter was fixed)dpar_formulasa named list whose elements are the formulasfor the model parameters (1indicates that the modelparameter was estimated with a single coefficient;0indicates that the model parameter was fixed)na.actionna.actiontermsa named list whose elements are the model parameters,except the last element is namedfulland shows thebreakdown of the model with all model parameterslevelsa named list whose elements are the levels associatedwith any parameters that are factors (the elements areNULLif the parameter is not a factor), and whose last element is namedFULLand shows all of the levels used in the modelcontrastsa named list whose elements are the type ofcontrasts used in the modelargs_ddma named list whose elements are the optionalarguments used in the calculation of the DDM log-likelihoodfunctionlinka named list whose elements show information about thelink function used for each model parameter (currently the onlylink function is the identity function)convergeda logical indicating whether the optimizationconverged (TRUE) or not (FALSE)optim_infoa named list whose elements are information aboutthe optimization process (e.g., the name of the algorithm used,the final value of the objective function, the number ofevaluations of the gradient function, etc.)modelthe data used in the model (might need to check this)responsethe response data used in the modelmmatrixa named list whose elements are the model matricesfor each of the estimated parameterscompiled_modelC++ object that contains the compiled model(see list below for more details)
The C++ object accessible via thecompiled_model component of theabove R object of classddm contains the following components:
rta numeric vector of the response time data used in themodelresponsean integer vector of the response data used in themodel (coded such that1corresponds to the "lower" boundaryand2corresponds to the "upper" boundary)err_tolthe error tolerance used in the calculations forfitting the DDMcoefficientsa numeric vector containing the current set ofcoefficients for the formulas provided to theddm()functioncall; the coefficients correspond to the DDM parameters in thefollowing order:v,a,t0,w,svlikelihooda double containing the log-likelihood for thecurrent set ofcoefficients(note this can be changed bycalling the functioncalculate_loglik()below)modmat_va numeric matrix containing the model matrix forv, the drift rate, determined by the formula input to theargumentdriftin theddm()function callmodmat_aa numeric matrix containing the model matrix fora, the boundary separation, determined by the formula inputto the argumentboundaryin theddm()function callmodmat_t0a numeric matrix containing the model matrix fort0, the non-decision time, determined by the formula inputto the argumentndtin theddm()function callmodmat_wa numeric matrix containing the model matrix forw, the inital bias, determined by the formula input to theargumentbiasin theddm()function callmodmat_sva numeric matrix containing the model matrix forsv, the inter-trial variability in the drift rate,determined by the formula input to the argumentsvin theddm()function callhess_va numeric matrix containing the Hessian forv,the drift rate, whose dimensions are determined by the formulainput to the argumentdriftin theddm()functioncallhess_aa numeric matrix containing the Hessian fora,the boundary separation, whose dimensions are determined by theformula input to the argumentdriftin theddm()function callhess_t0a numeric matrix containing the Hessian fort0, the non-decision time, whose dimensions are determinedby the formula input to the argumentdriftin theddm()function callhess_wa numeric matrix containing the Hessian forw,the initial bias, whose dimensions are determined by the formulainput to the argumentdriftin theddm()functioncallhess_sva numeric matrix containing the Hessian forsv, the inter-trial variability in the drift rate, whosedimensions are determined by the formula input to the argumentdriftin theddm()function callvcov_va numeric matrix containing the variance-covariancematrix forv, the drift rate, whose dimensions aredetermined by the formula input to the argumentdriftin theddm()function callvcov_aa numeric matrix containing the variance-covariancematrix fora, the boundary separation, whose dimensions aredetermined by the formula input to the argumentboundaryintheddm()function callvcov_t0a numeric matrix containing the variance-covariancematrix fort0, the non-decision time, whose dimensions aredetermined by the formula input to the argumentndtin theddm()function callvcov_wa numeric matrix containing the variance-covariancematrix forw, the inital bias, whose dimensions aredetermined by the formula input to the argumentbiasin theddm()function callvcov_sva numeric matrix containing the variance-covariancematrix forv, the inter-trial variability in the drift rate,whose dimensions are determined by the formula input to theargumentsvin theddm()function callcalculate_loglikcalculates and returns a double containingthe negated log-likelihood (note that this will overwrite thelikelihoodcomponent of the C++ object)calculate_gradientcalculates and returns a numeric vectorof the negated gradients for the provided coefficient values; thegradients are stored in the same manner as their correspondingcoefficents(note that this will overwrite thelikelihood) component of the C++ object)calculate_hessianscalculates and returns a named list ofthe negated Hessians for each model parameter for the providedcoefficient values (note that this will overwrite thelikelihood,hess_v,hess_a,hess_t0,hess_w, andhess_svcomponents of the C++ object)calculate_vcovcalculates and returns a named list of thevariance-covariance matrices for each model parameter for thestoredcoefficients(note that this will overwrite thelikelihood,hess_v,hess_a,hess_t0,hess_w,hess_sv,vcov_v,vcov_a,vcov_t0,vcov_w, andvcov_svcomponents of theC++ object)calculate_standard_errorcalculates and returns a numericvector of the standard errors of the storedcoefficients;the standard errors are stored in the same manner as theircorrespondingcoefficients(note that this will overwritethelikelihood,hess_v,hess_a,hess_t0,hess_w,hess_sv,vcov_v,vcov_a,vcov_t0,vcov_w, andvcov_svcomponents of the C++ object)
Examples
# prepare datadata(med_dec, package = "fddm")med_dec <- med_dec[which(med_dec[["rt"]] >= 0), ] ## only use valid RTs## select data from one participantp1 <- med_dec[med_dec[["id"]] == 2 & med_dec[["group"]] == "experienced", ]head(p1)##----------------------------------------------## Easiest: Fitting using emmeans -##----------------------------------------------## Because we use an ANOVA approach, we set orthogonal sum-to-zero contrastsop <- options(contrasts = c('contr.sum', 'contr.poly'))fit0 <- ddm(rt + response ~ classification*difficulty, data = p1)summary(fit0)## for more tests, we use emmeans:if (requireNamespace("emmeans")) {# for ANOVA table:emmeans::joint_tests(fit0)# get conditional main effects of difficulty (for each level of classification):emmeans::joint_tests(fit0, by = "classification")# get mean drift rates per condition:em1 <- emmeans::emmeans(fit0, "difficulty", by = "classification")em1# compare mean drift rates per conditionpairs(em1)update(pairs(em1), by = NULL, adjust = "holm")}options(op) # reset contrasts##----------------------------------------------------------------## Fitting with custom parametrisation -##----------------------------------------------------------------## one drift rate per classification by difficulty design cellfit1 <- ddm(rt + response ~ 0 + classification:difficulty, data = p1)summary(fit1)## set default contrasts (just in case contrasts have been changed)op <- options(contrasts = c('contr.treatment', 'contr.poly'))## one drift rate "intercept" per classification condition (blast vs. non-blast)## corresponding to first level of difficulty factor (easy)## plus one further coefficient per classification condition corresponding to## difference from "intercept" (hard - easy)fit1b <- ddm(rt + response ~ 0 + classification + classification:difficulty, data = p1, args_optim = list(control = list(iter.max = 1000, eval.max = 1000)))summary(fit1b)options(op) # reset contrasts## set orthogonal sum-to-zero contrastsop <- options(contrasts = c('contr.sum', 'contr.poly'))## one drift rate "intercept" per classification condition (blast vs. non-blast)## corresponding to mean drift rate for the classification condition## plus one further coefficient per classification condition corresponding to## difference from "intercept" (hard/easy - mean drift rate)fit1c <- ddm(rt + response ~ 0 + classification + classification:difficulty, data = p1)summary(fit1c)options(op) ## reset contrasts## all variants produce same fit, only meaning of parameters differslogLik(fit1)logLik(fit1b)logLik(fit1c)logLik(fit0) ## also model above## all models estimate same drift rates, but in different parametrisation:coef(fit1) ## drift rates per design cell## same drift rates based on fit1b:c(coef(fit1b)[1:2], coef(fit1b)[1] + coef(fit1b)[3], coef(fit1b)[2] + coef(fit1b)[4])## same drift rates based on fit1c:c(coef(fit1c)[1] + coef(fit1c)[3], coef(fit1c)[2] + coef(fit1c)[4], coef(fit1c)[1] - coef(fit1c)[3], coef(fit1c)[2] - coef(fit1c)[4])# we can estimate a model that freely estimates response bias# (instead of fixing it at 0.5)fit2 <- ddm(rt + response ~ 0 + classification:difficulty, bias = ~1, data = p1)summary(fit2)## Note: estimating bias only makes sense in situations like here where the## response boundaries do not correspond to correct/incorrect but to the## actual responses participants gave (here: blast vs. non-blast classification)## now let's perform a likelihood ratio test to check if estimating response## bias freely leads to a significant increase in model fit?if (requireNamespace("lmtest")) { ## requires package lmtest lmtest::lrtest(fit1, fit2) ## does not look like it (p = 0.1691)}# we can also make a DDM parameter, such as boundary, depend on a numeric# variable, such as block numberfit3 <- ddm(rt + response ~ 0 + classification:difficulty, boundary = ~ block, data = p1)summary(fit3)## does making boundary depend on block leads to a significant increase in model## fit?if (requireNamespace("lmtest")) { ## requires package lmtest lmtest::lrtest(fit1, fit3) ## does not look like it (p = 0.198)}##----------------------------------------------------------------## Fitting with optimization arguments -##----------------------------------------------------------------## example of how to use your own initial values and bounds for the optimization## of the coefficients (determined by the model matrices/formulas)options(op) # reset contrasts# this uses the default generated initial values and boundsfitex0 <- ddm(rt + response ~ 0 + classification:difficulty, data = p1)# we can see the number of coefficients (and thus the number of initial values# and bounds) required if we wish to use our ownfitex0$optim_info$args_optim$initfitex0$optim_info$args_optim$lo_bdsfitex0$optim_info$args_optim$up_bds# -1.9270279 2.5408864 -1.9270279 0.3181987 1.7907438 0.1264035# -Inf -Inf -Inf -Inf 0 0# Inf Inf Inf Inf Inf 0.461# the first four coefficients are for the drift rate (given by the formula we# provided), and the last two are for the boundary separation and non-decision# time, respectively (note that the default is to estimate these two model# parameters with a single coefficient).# to use our own initial values, we can include them in the `args_optim` list,# but note that they must be within the generated boundsfitex1 <- ddm(rt + response ~ 0 + classification:difficulty, data = p1, args_optim = list(init = c(-1.5, 1, -1, 1, 1.5, 0.3)))# to use our own bounds, we again can include them in the `args_optim` list,# but note that they must contain the generated initial valuesfitex2 <- ddm(rt + response ~ 0 + classification:difficulty, data = p1, args_optim = list(lo_bds = c(-20, -20, -20, -20, 0, 0), up_bds = c(20, 20, 20, 20, 10, 0.5)))# to use both our own initial values and bounds, we include them in the# `args_optim` list, and the bounds must contain the initial valuesfitex3 <- ddm(rt + response ~ 0 + classification:difficulty, data = p1, args_optim = list(init = c(-1.5, 1, -1, 1, 1.5, 0.3), lo_bds = c(-20, -20, -20, -20, 0, 0), up_bds = c(20, 20, 20, 20, 10, 0.5)))# the only other option in the `args_optim` list is the control parameters# directly used by the optimization function (e.g., the maximum number of# iterations); here we'll set the maximum number of iterations and function# evaluationsfitex4 <- ddm(rt + response ~ 0 + classification:difficulty, data = p1, args_optim = list(control = list(iter.max = 1000, eval.max = 1000)))Methods for ddm objects
Description
Implemented S3 methods for objects of classddm as returned byfunctionddm().
Usage
## S3 method for class 'ddm'print(x, digits = max(3, getOption("digits") - 3), ...)## S3 method for class 'ddm'summary(object, ...)## S3 method for class 'summary.ddm'print(x, digits = max(3, getOption("digits") - 3), ...)## S3 method for class 'ddm'coef(object, dpar = c("drift", "boundary", "ndt", "bias", "sv", "full"), ...)## S3 method for class 'ddm'vcov(object, dpar = c("drift", "boundary", "ndt", "bias", "sv"), ...)## S3 method for class 'ddm'model.frame(formula, ...)## S3 method for class 'ddm'model.matrix(object, dpar = c("drift", "boundary", "ndt", "bias", "sv"), ...)## S3 method for class 'ddm'terms(x, dpar = c("drift", "boundary", "ndt", "bias", "sv"), ...)## S3 method for class 'ddm'logLik(object, ...)## S3 method for class 'ddm'update(object, ...)recover_data.ddm(object, data, ...)emm_basis.ddm( object, trms, xlev, grid, dpar = c("drift", "boundary", "ndt", "bias", "sv"), ...)Arguments
digits | minimal number of significant digits, see |
... | further arguments passed to or from other methods. |
object,x | object of class |
dpar | which distributional parameter or DDM parameter to focus on. Inaddition to the five DDM parameters |
formula | see |
data,trms,xlev,grid | arguments needed foremmeans support. |
Details
The methods should fail with an informative error if adistributional parameter is selected indpar that is fixed and notestimated.
Density of Ratcliff Diffusion Decision Model
Description
Density function for the Ratcliff diffusion decision model (DDM) withfollowing parameters:v (drift rate),a (thresholdseparation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift), andsigma (diffusion coefficient of underlying Wiener process). If youare looking to fit the DDM, seeddm().
Usage
dfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, err_tol = 1e-06, log = FALSE, switch_mech = "eff_rt", switch_thresh = 0.8, n_terms_small = "SWSE", summation_small = "2017")Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
err_tol | Allowed error tolerance of the density function. The densityfunction contains an infinite sum that must be approximated; thisparameter is the upper bound of the total error incurred from thisapproximation (in absolute value). See Details for more information.Default is |
log | Logical; if |
switch_mech | Which switching mechanism to use in the choice of the"large-time" or "small-time" density function. Can be one of{ |
switch_thresh | Threshold for determining whether the effectiveresponse time ( |
n_terms_small | Which method to use for calculating the "small-time"approximation to the density function. Only applicable if |
summation_small | Which style of summation to use for the small-timeapproximation to the infinite sum. Can be one of { |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR recycling rules apply to ensure allinputs are of the same length.
The default settings ofswitch_mech = "eff_rt",switch_thresh = "0.8",n_terms_small = "SWSE",summation_small = "2017" produce the fastest and most accurateresults, as shown in our associated paper.
sv - Both the "small-time" and "large-time" variants of the densityfunction have two further variants: one with a constant drift ratev(i.e.,sv= 0), and one with a variable drift ratev(i.e.,sv> 0). The details of the differences between thesetwo density functions can be found in our associated paper. To use thedensity function with a constant drift rate, leave the parametersvto its default value ofsv = 0, as this will indicate no drift to thefunction. To use the density function with a variable drift rate, set theparametersv to some non-negative value, i.e.,sv> 0.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
err_tol - The density function is composed of an infinite sum (thatmust be approximated) and a multiplicative term outside the infinite sum,m. The total error of the approximation is the error incurred fromtruncating the infinite sum multiplied bym. Thus, to ensure that thetotal error is bounded by the user-provided error tolerance,err_tol,the approximation to the infinite sum uses a modified error tolerance(err_tol / m). If the error tolerance is small andm islarge, the modified error tolerance can underflow to0. To protectagainst this, we check that the modified error tolerance is at least1e-300 (near the smallest value that is representable by a floatingpoint number with double precision). If the modified error tolerance issmaller than this threshold, then we silently change it to1e-300.This case should only be encountered if extreme values of error toleranceare used (i.e., on the scale of1e-300).
switch_mech - The density function for the DDM has traditionally beenwritten in two forms: a "large-time" variant, and a "small-time" variant(Navarro and Fuss, 2009). These two forms are moreefficient at calculating the density for large and small response times,respectively. The parameterswitch_mech determines howdfddmdecides which of these two variants is used.switch_mech = "small" usesonly the "small-time" variant, andswitch_mech = "large" uses onlythe "large-time" variant. The "large-time" variant is unstable for smalleffective response times ((rt-t0)/(a*a) < 0.009) and may produce inaccuratedensities; thus, we do not recommend using theswitch_mech = "large"option if the inputs may contain such small effective response times. Tocircumvent this accuracy issue and resolve the differing efficiencies of the"large-time" and "small-time" variants, there are three switching mechanismsthat can be used to determine which of the two variants is more efficient.First,switch_mech = "terms" is the traditional approach andpre-calculates the number of terms required for the "large-time" and"small-time" sums, and then uses whichever variant requires fewer terms.This is the mechanism used in the Navarro and Fuss (2009) and Gondan,Blurton, and Kesselmeier (2014) papers.Second,switch_mech = "terms_large" pre-calculates the number ofterms only for the "large-time" variant, and compares that to the constantvalue ofceil(switch_thresh) (default value ofceil(0.8) = 1) to determine if the "large-time" variant issufficiently efficient.Third,switch_mech = "eff_rt" determines whether a given effectiveresponse time ((rt-t0)/(a*a)) is considered "large" or "small" bycomparing it to the value of the parameterswitch_thresh (defaultvalue of0.8); it then uses the corresponding variant.Bothswitch_mech = "terms_large" andswitch_mech = "eff_rt"only use the SWSE "small-time" approximation in the case that the"small-time" variant is more efficient.switch_mech = "eff_rt" is themost efficient method to determine which variant of the density functionshould be used.
switch_thresh - This parameter determines what effective responsetimes (rt/(a*a)) are "large" and"small". Thepaper_analysis folder in thefddm GitHubrepository contains plots showing the relative efficiencies of a range ofvalues for theswitch_thresh parameter when used withswitch_mech = "eff_rt" and alsoswitch_mech = "terms_large".Note that this parameter changed name and purpose with the release offddm version 0.5-0.
n_terms_small - The "small-time" variant has three different methodsfor how to truncate the infinite sum in the density function. Thesedifferent methods are discussed extensively in our associated paper, but thekey distinction is thatn_terms_small = "SWSE" uses a new method oftruncating the infinite sum. Then_terms_small = "SWSE" method iscurrently recommended (when possible) because it is the fastest and moststable algorithm when used withswitch_mech = "eff_rt".
summation_small - The "large-time" variant of the density functiondoes not have any further variants, but the "small-time" variant has moreoptions with respect to evaluating the infinite sum. There are twoequivalent styles of summation,summation_small = "2017" andsummation_small = "2014", of which the"2017" versionevaluates slightly faster and thus earns our recommendation. These differentstyles of summation are discussed in our associated paper.
Value
A vector containing the densities of the DDM with precisionerr_tol whose length matches that of the longest input parameter(usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
See Also
Examples
# minimal exampledfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3)# example with all function parameters set to default or a practical valuedfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = c("lower", "upper", "upper", "lower", "upper", "lower"), a = 1, v = -1, t0 = 0.2, w = 0.5, sv = 0, sigma = 1, err_tol = 1e-6, log = FALSE, switch_mech = "eff_rt", switch_thresh = 0.8, n_terms_small = "SWSE", summation_small = "2017")# example of mismatched input lengthsdfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = c("lower", "upper", "upper", "lower", "upper", "lower"), a = c(1, 3), v = c(-2, 2, 2, -2, 2, -2), t0 = 0.3, w = c(0.4, 0.5, 0.6), sv = 0.9, err_tol = 1e-10, log = FALSE, switch_mech = "large", summation_small = "2017")# example with Wiener diffusion coefficient (sigma) not equal to 1dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = c("lower", "upper", "upper", "lower", "upper", "lower"), a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0, sigma = 0.1, err_tol = 1e-10, log = TRUE, switch_mech = "terms_large", switch_thresh = 1, summation_small = "2017")### examples of different response inputs# integerresp_int <- as.integer(c(1, 2, 2, 1, 2, 1))dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_int, a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1, err_tol = 1e-10, log = FALSE, switch_mech = "eff_rt", summation_small = "2017")# doubleresp_dbl <- as.double(c(1, 2, 2, 1, 2, 1))dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_dbl, a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1, err_tol = 1e-10, log = FALSE, switch_mech = "eff_rt", summation_small = "2017")# factor (first level is mapped to "lower")days <- c("Monday", "Friday", "Friday", "Monday", "Friday", "Monday")resp_fac <- factor(days, levels = c("Monday", "Friday"))dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_fac, a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1, err_tol = 1e-10, log = FALSE, switch_mech = "eff_rt", summation_small = "2017")# stringresp_str <- c("lower", "upper", "upper", "lower", "upper", "lower")dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_str, a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1, err_tol = 1e-10, log = FALSE, switch_mech = "eff_rt", summation_small = "2017")# logicalresp_log <- c(FALSE, TRUE, TRUE, FALSE, TRUE, FALSE)dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_log, a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1, err_tol = 1e-10, log = FALSE, switch_mech = "eff_rt", summation_small = "2017")Second-Order Partial Derivative of 5-parameter DDM PDF with respect to sv(inter-trial variability in the drift rate)
Description
Second-Order Partial Derivative of the density function for the 5-parametervariant of the Ratcliff diffusion decision model (DDM) with respect to sv,the inter-trial variability in the drift rate. This variant contains thefollowing parameters:v (drift rate),a (threshold separation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift),andsigma (diffusion coefficient of underlying Wiener process).
Usage
dsv2_dfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, sl_thresh = 0.355, err_tol = 1e-06)Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
sl_thresh | Threshold for deciding when to use the "small-time" variantor the "large-time" variant. If the "effective response time" is greaterthan |
err_tol | Allowed error tolerance of the overall calculation. Since thepartial derivative of the density function contains one infinite sum, thisparameter defines the precision of the approximation to that infinite sum.If the provided error tolerance is less than |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR input wrapping will occur.
sv - Both the "small-time" and "large-time" variants of the densityfunction have two further variants: one with a constant drift ratev(i.e.,sv= 0), and one with a variable drift ratev(i.e.,sv> 0). The details of the differences between thesetwo density functions can be found in our associated paper. To use thedensity function with a constant drift rate, leave the parametersvto its default value ofsv = 0, as this will indicate no drift to thefunction. To use the density function with a variable drift rate, set theparametersv to some non-negative value, i.e.,sv> 0.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
Value
A vector containing the second-order partial derivatives of theDDM PDF with precisionerr_tol whose length matches that of thelongest input parameter (usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Hartmann, R., Klauer, K. C. (2021). Partial derivatives for thefirst-passage time distribution in Wiener diffusion models. Journal ofMathematical Psychology, 103, 102550.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
Examples
# derivative with respect to rt (response time)dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to t0 (non-decision time)dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to a (threshold separation)da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to v (drift rate)dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to w (relative starting point)dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to sv (inter-trial variability in the drift rate)dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)#-------- Log Versions --------## # derivative with respect to rt (response time)# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to t0 (non-decision time)# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to a (threshold separation)# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to v (drift rate)# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to w (relative starting point)# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to sv (inter-trial variability in the drift rate)# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)Partial Derivative of 5-parameter DDM PDF with respect to sv (inter-trialvariability in the drift rate)
Description
Partial Derivative of the density function for the 5-parameter variant ofthe Ratcliff diffusion decision model (DDM) with respect to w, theinter-trial variability in the drift rate. This variant contains thefollowing parameters:v (drift rate),a (threshold separation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift),andsigma (diffusion coefficient of underlying Wiener process).
Usage
dsv_dfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, sl_thresh = 0.355, err_tol = 1e-06)Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
sl_thresh | Threshold for deciding when to use the "small-time" variantor the "large-time" variant. If the "effective response time" is greaterthan |
err_tol | Allowed error tolerance of the overall calculation. Since thepartial derivative of the density function contains one infinite sum, thisparameter defines the precision of the approximation to that infinite sum.If the provided error tolerance is less than |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR input wrapping will occur.
sv - Both the "small-time" and "large-time" variants of the densityfunction have two further variants: one with a constant drift ratev(i.e.,sv= 0), and one with a variable drift ratev(i.e.,sv> 0). The details of the differences between thesetwo density functions can be found in our associated paper. To use thedensity function with a constant drift rate, leave the parametersvto its default value ofsv = 0, as this will indicate no drift to thefunction. To use the density function with a variable drift rate, set theparametersv to some non-negative value, i.e.,sv> 0.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
Value
A vector containing the partial derivatives of the DDM PDF withprecisionerr_tol whose length matches that of the longest inputparameter (usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Hartmann, R., Klauer, K. C. (2021). Partial derivatives for thefirst-passage time distribution in Wiener diffusion models. Journal ofMathematical Psychology, 103, 102550.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
Examples
# derivative with respect to rt (response time)dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to t0 (non-decision time)dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to a (threshold separation)da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to v (drift rate)dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to w (relative starting point)dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to sv (inter-trial variability in the drift rate)dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)#-------- Log Versions --------## # derivative with respect to rt (response time)# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to t0 (non-decision time)# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to a (threshold separation)# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to v (drift rate)# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to w (relative starting point)# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to sv (inter-trial variability in the drift rate)# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)Second-Order Partial Derivative of 5-parameter DDM PDF with respect to t0(non-decision time)
Description
Second-Order Partial Derivative of the density function for the 5-parametervariant of the Ratcliff diffusion decision model (DDM) with respect to t0,the non-decision time. This variant contains the following parameters:v (drift rate),a (threshold separation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift),andsigma (diffusion coefficient of underlying Wiener process).
Usage
dt02_dfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, sl_thresh = 0.44, err_tol = 1e-06)Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
sl_thresh | Threshold for deciding when to use the "small-time" variantor the "large-time" variant. If the "effective response time" is greaterthan |
err_tol | Allowed error tolerance of the overall calculation. Since thepartial derivative of the density function contains the sum of twoinfinite sums, each approximation of these two infinite sums will have anindividual error tolerance of |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR input wrapping will occur.
sv - Both the "small-time" and "large-time" variants of the densityfunction have two further variants: one with a constant drift ratev(i.e.,sv= 0), and one with a variable drift ratev(i.e.,sv> 0). The details of the differences between thesetwo density functions can be found in our associated paper. To use thedensity function with a constant drift rate, leave the parametersvto its default value ofsv = 0, as this will indicate no drift to thefunction. To use the density function with a variable drift rate, set theparametersv to some non-negative value, i.e.,sv> 0.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
Value
A vector containing the second-order partial derivatives of theDDM PDF with precisionerr_tol whose length matches that of thelongest input parameter (usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Hartmann, R., Klauer, K. C. (2021). Partial derivatives for thefirst-passage time distribution in Wiener diffusion models. Journal ofMathematical Psychology, 103, 102550.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
Examples
# derivative with respect to rt (response time)dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to t0 (non-decision time)dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to a (threshold separation)da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to v (drift rate)dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to w (relative starting point)dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to sv (inter-trial variability in the drift rate)dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)#-------- Log Versions --------## # derivative with respect to rt (response time)# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to t0 (non-decision time)# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to a (threshold separation)# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to v (drift rate)# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to w (relative starting point)# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to sv (inter-trial variability in the drift rate)# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)Partial Derivative of 5-parameter DDM PDF with respect to t0 (non-decisiontime)
Description
Partial Derivative of the density function for the 5-parameter variant ofthe Ratcliff diffusion decision model (DDM) with respect to t0, thenon-decision time. This variant contains the following parameters:v (drift rate),a (threshold separation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift),andsigma (diffusion coefficient of underlying Wiener process).
Usage
dt0_dfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, sl_thresh = 0.5, err_tol = 1e-06)Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
sl_thresh | Threshold for deciding when to use the "small-time" variantor the "large-time" variant. If the "effective response time" is greaterthan |
err_tol | Allowed error tolerance of the overall calculation. Since thepartial derivative of the density function contains the sum of twoinfinite sums, each approximation of these two infinite sums will have anindividual error tolerance of |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR input wrapping will occur.
sv - Both the "small-time" and "large-time" variants of the densityfunction have two further variants: one with a constant drift ratev(i.e.,sv= 0), and one with a variable drift ratev(i.e.,sv> 0). The details of the differences between thesetwo density functions can be found in our associated paper. To use thedensity function with a constant drift rate, leave the parametersvto its default value ofsv = 0, as this will indicate no drift to thefunction. To use the density function with a variable drift rate, set theparametersv to some non-negative value, i.e.,sv> 0.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
Value
A vector containing the partial derivatives of the DDM PDF withprecisionerr_tol whose length matches that of the longest inputparameter (usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Hartmann, R., Klauer, K. C. (2021). Partial derivatives for thefirst-passage time distribution in Wiener diffusion models. Journal ofMathematical Psychology, 103, 102550.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
Examples
# derivative with respect to rt (response time)dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to t0 (non-decision time)dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to a (threshold separation)da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to v (drift rate)dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to w (relative starting point)dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to sv (inter-trial variability in the drift rate)dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)#-------- Log Versions --------## # derivative with respect to rt (response time)# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to t0 (non-decision time)# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to a (threshold separation)# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to v (drift rate)# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to w (relative starting point)# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to sv (inter-trial variability in the drift rate)# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)Second-Order Partial Derivative of 5-parameter DDM PDF with respect to t(response time)
Description
Second-Order Partial Derivative of the density function for the 5-parametervariant of the Ratcliff diffusion decision model (DDM) with respect to t,the response time. This variant contains the following parameters:v (drift rate),a (threshold separation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift),andsigma (diffusion coefficient of underlying Wiener process).
Usage
dt2_dfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, sl_thresh = 0.5, err_tol = 1e-06)Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
sl_thresh | Threshold for deciding when to use the "small-time" variantor the "large-time" variant. If the "effective response time" is greaterthan |
err_tol | Allowed error tolerance of the overall calculation. Since thepartial derivative of the density function contains the sum of twoinfinite sums, each approximation of these two infinite sums will have anindividual error tolerance of |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR input wrapping will occur.
sv - Both the "small-time" and "large-time" variants of the densityfunction have two further variants: one with a constant drift ratev(i.e.,sv= 0), and one with a variable drift ratev(i.e.,sv> 0). The details of the differences between thesetwo density functions can be found in our associated paper. To use thedensity function with a constant drift rate, leave the parametersvto its default value ofsv = 0, as this will indicate no drift to thefunction. To use the density function with a variable drift rate, set theparametersv to some non-negative value, i.e.,sv> 0.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
Value
A vector containing the second-order partial derivatives of theDDM PDF with precisionerr_tol whose length matches that of thelongest input parameter (usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Hartmann, R., Klauer, K. C. (2021). Partial derivatives for thefirst-passage time distribution in Wiener diffusion models. Journal ofMathematical Psychology, 103, 102550.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
Examples
# derivative with respect to rt (response time)dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to t0 (non-decision time)dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to a (threshold separation)da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to v (drift rate)dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to w (relative starting point)dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to sv (inter-trial variability in the drift rate)dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)#-------- Log Versions --------## # derivative with respect to rt (response time)# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to t0 (non-decision time)# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to a (threshold separation)# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to v (drift rate)# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to w (relative starting point)# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to sv (inter-trial variability in the drift rate)# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)Partial Derivative of 5-parameter DDM PDF with respect to t (response time)
Description
Partial Derivative of the density function for the 5-parameter variant ofthe Ratcliff diffusion decision model (DDM) with respect to t, theresponse time. This variant contains the following parameters:v (drift rate),a (threshold separation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift),andsigma (diffusion coefficient of underlying Wiener process).
Usage
dt_dfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, sl_thresh = 0.5, err_tol = 1e-06)Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
sl_thresh | Threshold for deciding when to use the "small-time" variantor the "large-time" variant. If the "effective response time" is greaterthan |
err_tol | Allowed error tolerance of the overall calculation. Since thepartial derivative of the density function contains the sum of twoinfinite sums, each approximation of these two infinite sums will have anindividual error tolerance of |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR input wrapping will occur.
sv - Both the "small-time" and "large-time" variants of the densityfunction have two further variants: one with a constant drift ratev(i.e.,sv= 0), and one with a variable drift ratev(i.e.,sv> 0). The details of the differences between thesetwo density functions can be found in our associated paper. To use thedensity function with a constant drift rate, leave the parametersvto its default value ofsv = 0, as this will indicate no drift to thefunction. To use the density function with a variable drift rate, set theparametersv to some non-negative value, i.e.,sv> 0.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
Value
A vector containing the partial derivatives of the DDM PDF withprecisionerr_tol whose length matches that of the longest inputparameter (usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Hartmann, R., Klauer, K. C. (2021). Partial derivatives for thefirst-passage time distribution in Wiener diffusion models. Journal ofMathematical Psychology, 103, 102550.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
Examples
# derivative with respect to rt (response time)dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to t0 (non-decision time)dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to a (threshold separation)da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to v (drift rate)dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to w (relative starting point)dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to sv (inter-trial variability in the drift rate)dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)#-------- Log Versions --------## # derivative with respect to rt (response time)# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to t0 (non-decision time)# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to a (threshold separation)# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to v (drift rate)# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to w (relative starting point)# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to sv (inter-trial variability in the drift rate)# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)Second-Order Partial Derivative of 5-parameter DDM PDF with respect to v(drift rate)
Description
Second-Order Partial Derivative of the density function for the 5-parametervariant of the Ratcliff diffusion decision model (DDM) with respect to v,the drift rate. This variant contains the following parameters:v (drift rate),a (threshold separation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift),andsigma (diffusion coefficient of underlying Wiener process).
Usage
dv2_dfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, sl_thresh = 0.355, err_tol = 1e-06)Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
sl_thresh | Threshold for deciding when to use the "small-time" variantor the "large-time" variant. If the "effective response time" is greaterthan |
err_tol | Allowed error tolerance of the overall calculation. Since thepartial derivative of the density function contains one infinite sum, thisparameter defines the precision of the approximation to that infinite sum.If the provided error tolerance is less than |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR input wrapping will occur.
sv - Both the "small-time" and "large-time" variants of the densityfunction have two further variants: one with a constant drift ratev(i.e.,sv= 0), and one with a variable drift ratev(i.e.,sv> 0). The details of the differences between thesetwo density functions can be found in our associated paper. To use thedensity function with a constant drift rate, leave the parametersvto its default value ofsv = 0, as this will indicate no drift to thefunction. To use the density function with a variable drift rate, set theparametersv to some non-negative value, i.e.,sv> 0.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
Value
A vector containing the second-order partial derivatives of theDDM PDF with precisionerr_tol whose length matches that of thelongest input parameter (usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Hartmann, R., Klauer, K. C. (2021). Partial derivatives for thefirst-passage time distribution in Wiener diffusion models. Journal ofMathematical Psychology, 103, 102550.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
Examples
# derivative with respect to rt (response time)dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to t0 (non-decision time)dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to a (threshold separation)da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to v (drift rate)dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to w (relative starting point)dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to sv (inter-trial variability in the drift rate)dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)#-------- Log Versions --------## # derivative with respect to rt (response time)# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to t0 (non-decision time)# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to a (threshold separation)# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to v (drift rate)# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to w (relative starting point)# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to sv (inter-trial variability in the drift rate)# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)Partial Derivative of 5-parameter DDM PDF with respect to v (drift rate)
Description
Partial Derivative of the density function for the 5-parameter variant ofthe Ratcliff diffusion decision model (DDM) with respect to v, the driftrate. This variant contains the following parameters:v (drift rate),a (threshold separation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift),andsigma (diffusion coefficient of underlying Wiener process).
Usage
dv_dfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, sl_thresh = 0.355, err_tol = 1e-06)Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
sl_thresh | Threshold for deciding when to use the "small-time" variantor the "large-time" variant. If the "effective response time" is greaterthan |
err_tol | Allowed error tolerance of the overall calculation. Since thepartial derivative of the density function contains one infinite sum, thisparameter defines the precision of the approximation to that infinite sum.If the provided error tolerance is less than |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR input wrapping will occur.
sv - Both the "small-time" and "large-time" variants of the densityfunction have two further variants: one with a constant drift ratev(i.e.,sv= 0), and one with a variable drift ratev(i.e.,sv> 0). The details of the differences between thesetwo density functions can be found in our associated paper. To use thedensity function with a constant drift rate, leave the parametersvto its default value ofsv = 0, as this will indicate no drift to thefunction. To use the density function with a variable drift rate, set theparametersv to some non-negative value, i.e.,sv> 0.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
Value
A vector containing the partial derivatives of the DDM PDF withprecisionerr_tol whose length matches that of the longest inputparameter (usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Hartmann, R., Klauer, K. C. (2021). Partial derivatives for thefirst-passage time distribution in Wiener diffusion models. Journal ofMathematical Psychology, 103, 102550.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
Examples
# derivative with respect to rt (response time)dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to t0 (non-decision time)dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to a (threshold separation)da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to v (drift rate)dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to w (relative starting point)dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to sv (inter-trial variability in the drift rate)dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)#-------- Log Versions --------## # derivative with respect to rt (response time)# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to t0 (non-decision time)# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to a (threshold separation)# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to v (drift rate)# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to w (relative starting point)# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to sv (inter-trial variability in the drift rate)# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)Second-Order Partial Derivative of 5-parameter DDM PDF with respect to w(initial bias)
Description
Second-Order Partial Derivative of the density function for the 5-parametervariant of the Ratcliff diffusion decision model (DDM) with respect to w,the initial bias. This variant contains the following parameters:v (drift rate),a (threshold separation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift),andsigma (diffusion coefficient of underlying Wiener process).
Usage
dw2_dfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, sl_thresh = 0.5, err_tol = 1e-06)Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
sl_thresh | Threshold for deciding when to use the "small-time" variantor the "large-time" variant in one half of the calculation of the partialderivative of the density function. This acts in exactly the same way asthe parameter |
err_tol | Allowed error tolerance of the overall calculation. Since thepartial derivative of the density function contains the sum of twoinfinite sums, each approximation of these two infinite sums will have anindividual error tolerance of |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR input wrapping will occur.
sv - Both the "small-time" and "large-time" variants of the densityfunction have two further variants: one with a constant drift ratev(i.e.,sv= 0), and one with a variable drift ratev(i.e.,sv> 0). The details of the differences between thesetwo density functions can be found in our associated paper. To use thedensity function with a constant drift rate, leave the parametersvto its default value ofsv = 0, as this will indicate no drift to thefunction. To use the density function with a variable drift rate, set theparametersv to some non-negative value, i.e.,sv> 0.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
Value
A vector containing the second-order partial derivatives of theDDM PDF with precisionerr_tol whose length matches that of thelongest input parameter (usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Hartmann, R., Klauer, K. C. (2021). Partial derivatives for thefirst-passage time distribution in Wiener diffusion models. Journal ofMathematical Psychology, 103, 102550.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
Examples
# derivative with respect to rt (response time)dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to t0 (non-decision time)dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to a (threshold separation)da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to v (drift rate)dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to w (relative starting point)dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to sv (inter-trial variability in the drift rate)dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)#-------- Log Versions --------## # derivative with respect to rt (response time)# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to t0 (non-decision time)# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to a (threshold separation)# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to v (drift rate)# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to w (relative starting point)# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to sv (inter-trial variability in the drift rate)# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)Partial Derivative of 5-parameter DDM PDF with respect to w (initial bias)
Description
Partial Derivative of the density function for the 5-parameter variant ofthe Ratcliff diffusion decision model (DDM) with respect to w, the initialbias. This variant contains the following parameters:v (drift rate),a (threshold separation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift),andsigma (diffusion coefficient of underlying Wiener process).
Usage
dw_dfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, sl_thresh = 1, err_tol = 1e-06)Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
sl_thresh | Threshold for deciding when to use the "small-time" variantor the "large-time" variant in one half of the calculation of the partialderivative of the density function. This acts in exactly the same way asthe parameter |
err_tol | Allowed error tolerance of the overall calculation. Since thepartial derivative of the density function contains the sum of twoinfinite sums, each approximation of these two infinite sums will have anindividual error tolerance of |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR input wrapping will occur.
sv - Both the "small-time" and "large-time" variants of the densityfunction have two further variants: one with a constant drift ratev(i.e.,sv= 0), and one with a variable drift ratev(i.e.,sv> 0). The details of the differences between thesetwo density functions can be found in our associated paper. To use thedensity function with a constant drift rate, leave the parametersvto its default value ofsv = 0, as this will indicate no drift to thefunction. To use the density function with a variable drift rate, set theparametersv to some non-negative value, i.e.,sv> 0.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
Value
A vector containing the partial derivatives of the DDM PDF withprecisionerr_tol whose length matches that of the longest inputparameter (usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Hartmann, R., Klauer, K. C. (2021). Partial derivatives for thefirst-passage time distribution in Wiener diffusion models. Journal ofMathematical Psychology, 103, 102550.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
Examples
# derivative with respect to rt (response time)dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to t0 (non-decision time)dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to a (threshold separation)da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to v (drift rate)dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to w (relative starting point)dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)# derivative with respect to sv (inter-trial variability in the drift rate)dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0.4, err_tol = 1e-6)#-------- Log Versions --------## # derivative with respect to rt (response time)# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to t0 (non-decision time)# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to a (threshold separation)# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to v (drift rate)# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to w (relative starting point)# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)# # derivative with respect to sv (inter-trial variability in the drift rate)# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,# sv = 0.4, err_tol = 1e-6)Medicial decision data
Description
Part of the accuracy and response time data presented in Trueblood et al.(2017) investigating medical decision making among medical professionals(pathologists) and novices (i.e., undergraduate students). The task ofparticipants was to judge whether pictures of blood cells show cancerouscells (i.e., blast cells) or non-cancerous cells (i.e., non-blast cells). Thecurrent data set contains 200 decisions per participant (the "accuracy"condition from Trueblood et al.).
Usage
data(med_dec)Format
A data frame with 11000 rows and 9 variables:
- id
identification number of the participant
- group
expertise of participant; "experienced", "inexperienced", or "novice". The first two levels refer to different type of medical professional (i.e., experts).
- block
block number
- trial
index of trial for each participant
- classification
true classification of the pictured cell; i.e. the correct response
- difficulty
adjudged difficulty of the task for the particular image
- response
response given by the participant; either "blast" or "non-blast"
- rt
the response time associated with the response, in seconds
- stimulus
the image file used for the specific trial
Details
At the beginning of the experiment, both novices and medical expertscompleted a training to familiarize themselves with blast cells. After that,each participant performed the main task in which they judged whether or notpresented images were blast cells or non-blast cells. Among them, some of thecells were judged as easy and some as difficult trials by an additional groupof experts. The current data set only contains the data from the "accuracy"condition (i.e., Trueblood et al. considered additional conditions that arenot part of the current data set).
The relevant part of the method section for the accuracy condition from theoriginal paper is as follows:
"The main task consisted of six blocks with 100 trials in each block. Themain task was the same as the practice block, where participants were askedto identify single images. However, participants did not receivetrial-by-trial feedback about their choices. They received feedback abouttheir performance at the end of each block. The 100 trials in each block werecomposed of equal numbers of easy blast images, hard blast images, easynon-blast images, and hard non-blast images, fully randomized.
There were three manipulations across blocks: accuracy, speed, and bias. Inthe accuracy blocks, participants were instructed to respond as accurately aspossible and were given 5 s to respond. [...] If they responded after thedeadline, they received the message "Too Slow!" The 5-s [...] responsewindows for the accuracy [...] [condition was] based on the response timedata from the three expert raters. The 0.975 quantile of the expert raters'response times was 4.96 s; thus, we set the accuracy response window to 5 s.
The order of the first three blocks was randomized but with the constraintthat there was one block for each type of manipulation (i.e., accuracy,speed, and bias). The order of the last three blocks was identical to theorder of the first three blocks."
Note that this dataset contains some negative response times that indicate amissing response (i.e., the response value for that trial isNA). Take carein removing these values before using this dataset. See our Validity vignettefor an example of use in an optimization setting.
Source
Trueblood, J.S., Holmes, W.R., Seegmiller, A.C. et al. The impact ofspeed and bias on the cognitive processes of experts and novices in medicalimage decision-making. Cogn. Research 3, 28 (2018).https://doi.org/10.1186/s41235-018-0119-2
Examples
data("med_dec", package = "fddm")str(med_dec)## number of participants per expertise condition:aggregate(id ~ group, med_dec, function(x) length(unique(x)))## number of trials per participantaggregate(rt ~ group + id, med_dec, length)Distribution of Ratcliff Diffusion Decision Model
Description
Density function for the Ratcliff diffusion decision model (DDM) withfollowing parameters:v (drift rate),a (thresholdseparation),t0 (non-decision time/response time constant),w(relative starting point),sv (inter-trial variability of drift), andsigma (diffusion coefficient of underlying Wiener process).
Usage
pfddm( rt, response, v, a, t0, w = 0.5, sv = 0, sigma = 1, err_tol = 1e-06, log = FALSE, method = "Mills")Arguments
rt | A vector of response times (in seconds). If a response time isnon-positve, then its density will evaluate to |
response | Binary response(s) that correspond(s) to either the "lower"or "upper" threshold. This model parameter can either be a singular valueor a vector. The value(s) in 'response' can be of the following datatypes:
|
v | Drift rate. Average slope of the information accumulation process.The drift gives information about the speed and direction of theaccumulation of information. Large (absolute) values of drift indicate agood performance. If received information supports the response linked tothe upper threshold, then the sign will be positive; similarly a negativevalue indicates that the received information supports the response linkedto the lower threshold. Allowed range: |
a | Threshold separation. Amount of information that is considered fora decision. Large values indicate a conservative decisional style. Allowedrange: |
t0 | Non-decision time or response time constant (in seconds). Lowerbound for the duration of all non-decisional processes (encoding andresponse execution). If this value is greater than |
w | Relative starting point. Indicator of an a priori bias in decisionmaking. When the relative starting point |
sv | Inter-trial-variability of drift rate. Standard deviation of anormal distribution with mean |
sigma | Diffusion coefficient of the underlying Wiener process. Allowedrange:
. |
err_tol | Allowed error tolerance of the density function. Since thedensity function contains an infinite sum, this parameter defines theprecision of the approximation to that infinite sum. If the providederror tolerance is less than |
log | Logical; if |
method | Which method of calculating the CDF to use. Can be one of{ |
Details
All of the model inputs and parameters (rt,response,v,a,t0,w,sv,sigma) can beinput as a single value or as a vector of values. If input as a vector ofvalues, then the standardR input wrapping will occur.
sigma - The default value of this parameter is1 because itonly scales the parametersv,a, andsv, as shownabove. However, other formulations of the DDM may setsigma = 0.1(see Ratcliff (1978), the fourth reference), so care must be taken whencomparing the results of different formulations.
Value
A vector containing the distribution of the DDM with precisionerr_tol whose length matches that of the longest input parameter(usuallyrt).
References
Navarro, D. J., & Fuss, I. G. (2009). Fast and accuratecalculations for first-passage times in Wiener diffusion models. Journalof Mathematical Psychology, 53(4), 222-230.
Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and evenmore accurate first-passage time densities and distributions for theWiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.
Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passagetime distribution for the diffusion model with variable drift. Journal ofMathematical Psychology, 76, 7-12.
Ratcliff, R. (1978). A theory of memory retrieval. Psychological review,85(2), 59.
Examples
# minimal examplepfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3)# example with all function parameters set to default or a practical valuepfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = c("lower", "upper", "upper", "lower", "upper", "lower"), a = 1, v = -1, t0 = 0.2, w = 0.5, sv = 0, sigma = 1, err_tol = 1e-6, log = FALSE, method = "Mills")# example of mismatched input lengthspfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = c("lower", "upper", "upper", "lower", "upper", "lower"), a = c(1, 3), v = c(-2, 2, 2, -2, 2, -2), t0 = 0.3, w = c(0.4, 0.5, 0.6), sv = 0.9, err_tol = 1e-10, log = FALSE, method = "NCDF")# example with Wiener diffusion coefficient (sigma) not equal to 1pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = c("lower", "upper", "upper", "lower", "upper", "lower"), a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0, sigma = 0.1, err_tol = 1e-10, log = TRUE, method = "Mills")### examples of different response inputs# integerresp_int <- as.integer(c(1, 2, 2, 1, 2, 1))pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_int, a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1, err_tol = 1e-10, log = FALSE, method = "Mills")# doubleresp_dbl <- as.double(c(1, 2, 2, 1, 2, 1))pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_dbl, a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1, err_tol = 1e-10, log = FALSE, method = "Mills")# factor (first level is mapped to "lower")days <- c("Monday", "Friday", "Friday", "Monday", "Friday", "Monday")resp_fac <- factor(days, levels = c("Monday", "Friday"))pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_fac, a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1, err_tol = 1e-10, log = FALSE, method = "Mills")# stringresp_str <- c("lower", "upper", "upper", "lower", "upper", "lower")pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_str, a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1, err_tol = 1e-10, log = FALSE, method = "Mills")# logicalresp_log <- c(FALSE, TRUE, TRUE, FALSE, TRUE, FALSE)pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_log, a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1, err_tol = 1e-10, log = FALSE, method = "Mills")