vignettes/Tutorials/Model_definition.Rmd
Model_definition.RmdTo define a model, you must call the function DDModel(). There are at least four arguments that must be given to successfully define a model:
The parameter model is self-explanatory. Currently four models are supported in the package: DSTP, DMC, SSP and the classic DDM. Simply enter one of these abbreviations the mathematical basis for your model is already laid out:
library(DDModeling) #> Lade nötiges Paket: data.table DSTP <- DDModel(model="DSTP",task = "flanker",CDF_perc = c(0.1,0.3,0.5,0.7,0.9),CAF_perc = c(0.0,0.2,0.4,0.6,0.8,1.0)) DMC <- DDModel(model="DMC" ,task = "flanker",CDF_perc = c(0.1,0.3,0.5,0.7,0.9),CAF_perc = c(0.0,0.2,0.4,0.6,0.8,1.0)) SSP <- DDModel(model="SSP" ,task = "flanker",CDF_perc = c(0.1,0.3,0.5,0.7,0.9),CAF_perc = c(0.0,0.2,0.4,0.6,0.8,1.0)) DDM <- DDModel(model="DDM_classic",task = "RMT_LDT",CDF_perc = c(0.1,0.3,0.5,0.7,0.9),CAF_perc = c(0.0,0.2,0.4,0.6,0.8,1.0))
Note that you must give at least these four arguments, otherwise the function will return an error! The argument task specifies the experiment to be modelled. Currently, different tasks are supported depending on the predefined model, task = "flanker" (for a flanker task) and task = "RMT_LDT" (for a recognition memory or lexical decision task) are two examples. At the end of this tutorial we will have a look at the flag task = "custom", which makes the model definition quite complex. Next come CDF_perc and CAF_perc. Both take a numerical vector that specifies the representation of your data in the form of a cumulative distribution function (CDF) or a conditional accuracy function (CAF). Note, however, that the values of both parameters behave differently! While the CDF_perc values specify specific percentiles of the CDF, the CAF_perc values specify the limits of CAF quantiles. This means that in the examples above, the data is represented by five CDF percentiles (0.1, 0.3, 0.5, 0.7, 0.9) and five CAF quantiles (0.0<0.2, 0.2<0.4, 0.4<0.6, 0.6<0.8, 0.8<1.0) per condition.
Once you have specified your model, you can inspect it by simply calling the object:
DSTP #> DDModel Object: #> #> Model: DSTP #> #> ModelMatrix: #> $Cong #> Ter a c mu_t mu_f mu_RS2 mu_SS #> Ter 1 0 0 0 0 0 0 #> a 0 1 0 0 0 0 0 #> c 0 0 1 0 0 0 0 #> mu_RS1 0 0 0 1 1 0 0 #> mu_RS2_C 0 0 0 0 0 1 0 #> mu_RS2_D 0 0 0 0 0 1 0 #> mu_SS 0 0 0 0 0 0 1 #> z_RS 0 0 0 0 0 0 0 #> z_SS 0 0 0 0 0 0 0 #> s_Ter 0 0 0 0 0 0 0 #> s_mu_RS1 0 0 0 0 0 0 0 #> s_mu_RS2_C 0 0 0 0 0 0 0 #> s_mu_RS2_D 0 0 0 0 0 0 0 #> s_SS 0 0 0 0 0 0 0 #> s_z_RS 0 0 0 0 0 0 0 #> s_z_SS 0 0 0 0 0 0 0 #> #> $Incong #> Ter a c mu_t mu_f mu_RS2 mu_SS #> Ter 1 0 0 0 0 0 0 #> a 0 1 0 0 0 0 0 #> c 0 0 1 0 0 0 0 #> mu_RS1 0 0 0 1 -1 0 0 #> mu_RS2_C 0 0 0 0 0 1 0 #> mu_RS2_D 0 0 0 0 0 -1 0 #> mu_SS 0 0 0 0 0 0 1 #> z_RS 0 0 0 0 0 0 0 #> z_SS 0 0 0 0 0 0 0 #> s_Ter 0 0 0 0 0 0 0 #> s_mu_RS1 0 0 0 0 0 0 0 #> s_mu_RS2_C 0 0 0 0 0 0 0 #> s_mu_RS2_D 0 0 0 0 0 0 0 #> s_SS 0 0 0 0 0 0 0 #> s_z_RS 0 0 0 0 0 0 0 #> s_z_SS 0 0 0 0 0 0 0 #> #> Parameter Domain: #> Ter a c mu_t mu_f mu_RS2 mu_SS #> Upper_Limit 0.45 0.38 0.38 0.15 0.25 0.55 1.2 #> Lower_Limit 0.15 0.14 0.14 0.05 0.05 0.25 0.4 #> #> Simulation Parameter: #> dt sigma #> [1,] 0.001 0.1 #> #> Form of Representation: #> $CDF #> [1] 0.1 0.3 0.5 0.7 0.9 #> #> $CAF #> [1] 0.0 0.2 0.4 0.6 0.8 1.0
This gives you many insights into the model, such as its mapping matrix (ModelMatrix) for different conditions, parameter domains or parameters important for the simulation (simulation parameters). You might think: “Wait, where did I specify all this?”. Well, that’s the beauty of the task = "flanker" specification! It was created in accordance with the latest research results. So if you want to model a given flanker task, there is really nothing more you need to specify. However, if you want to model something else, have a look at the next section, otherwise jump to Simulation Tutorial.
Let us assume that we had conducted an experiment that involved pressing a button as quickly as possible after an indication, such as a flashing light bulb. We would argue that it is probable enough to model this task according to a simplified version of the DSTP in which there is no parallel attention process, since the test subject is not affected by any disturbances and attention is always directed to the indicator. To realize such a model, we first have to set task = "custom". Thus we need to specify four additional arguments in DDModel()": conditions, parameters, dt and sigma. conditions specifies the names of the conditions present in the model. Here we choose to name our singular condition hit. parameters refers to the names of the parameters we want to model with. In accordance with the above, we choose model after three parameters: Ter, a, mu. dt and sigma are simulation parameters for the model. The former quantifies the integration constant of the process and the latter the diffusion coefficient. These have quite a big influence on the model! For this reason these values should be chosen with caution! For the DSTP we choose dt = 0.001 and sigma = 0.1 as in the task = "flanker" preset. With all this we have a model as follows:
DSTP_simple <- DDModel(model="DSTP",task = "custom",conditions = "hit",parameter = c("Ter","a","mu"),dt = 0.001,sigma = 0.1,CDF_perc = c(0.1,0.3,0.5,0.7,0.9),CAF_perc = c(0.0,0.2,0.4,0.6,0.8,1.0)) DSTP_simple #> DDModel Object: #> #> Model: DSTP #> #> ModelMatrix: #> $hit #> Ter a mu #> Ter 0 0 0 #> a 0 0 0 #> c 0 0 0 #> mu_RS1 0 0 0 #> mu_RS2_C 0 0 0 #> mu_RS2_D 0 0 0 #> mu_SS 0 0 0 #> z_RS 0 0 0 #> z_SS 0 0 0 #> s_Ter 0 0 0 #> s_mu_RS1 0 0 0 #> s_mu_RS2_C 0 0 0 #> s_mu_RS2_D 0 0 0 #> s_SS 0 0 0 #> s_z_RS 0 0 0 #> s_z_SS 0 0 0 #> #> Parameter Domain: #> Ter a mu #> Upper_Limit NA NA NA #> Lower_Limit NA NA NA #> #> Simulation Parameter: #> dt sigma #> [1,] 0.001 0.1 #> #> Form of Representation: #> $CDF #> [1] 0.1 0.3 0.5 0.7 0.9 #> #> $CAF #> [1] 0.0 0.2 0.4 0.6 0.8 1.0
Seems to be good so far, but there is still a lot to do! For the beginning the ModelMatrix contains only zeros, such a model will not go anywhere! We have to map our parameters (columns) to the model parameters (rows). Here we have a simple 1:1 mapping (note that in the new version (DDModeling 0.0.2.0) I introduced intertrial variability into all models, which leads to a more spatial initialization!)
DSTP_simple@MM$hit[,"Ter"]<- c(1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0) DSTP_simple@MM$hit[,"a"] <- c(0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0) DSTP_simple@MM$hit[,"mu"] <- c(0,0,0,1,0,0,0,0,0,0,0,0,0,0,0,0)
Next, there are NAs in the Parameter Domain section! We need to specify an upper and lower limit for each of them:
DSTP_simple@DM[,"Ter"] <- c(0.45,0.2) DSTP_simple@DM[,"a"] <- c(0.15,0.005) DSTP_simple@DM[,"mu"] <- c(0.12,0.05)
Now let us take a look at the model again
DSTP_simple #> DDModel Object: #> #> Model: DSTP #> #> ModelMatrix: #> $hit #> Ter a mu #> Ter 1 0 0 #> a 0 1 0 #> c 0 0 0 #> mu_RS1 0 0 1 #> mu_RS2_C 0 0 0 #> mu_RS2_D 0 0 0 #> mu_SS 0 0 0 #> z_RS 0 0 0 #> z_SS 0 0 0 #> s_Ter 0 0 0 #> s_mu_RS1 0 0 0 #> s_mu_RS2_C 0 0 0 #> s_mu_RS2_D 0 0 0 #> s_SS 0 0 0 #> s_z_RS 0 0 0 #> s_z_SS 0 0 0 #> #> Parameter Domain: #> Ter a mu #> Upper_Limit 0.45 0.150 0.12 #> Lower_Limit 0.20 0.005 0.05 #> #> Simulation Parameter: #> dt sigma #> [1,] 0.001 0.1 #> #> Form of Representation: #> $CDF #> [1] 0.1 0.3 0.5 0.7 0.9 #> #> $CAF #> [1] 0.0 0.2 0.4 0.6 0.8 1.0
Everything looks fine! Time to do some simulations.