#acl GoodGroup:admin,read,write,delete,revert CambridgeGroup:read CbuGroup:read
= Practical Introduction to Diffusion Modelling using the DMAT toolbox =
== Basics ==
DMAT is a Matlab toolbox for fitting the [http://140.254.101.126/coglab/ Ratcliff Drift Diffusion Model] to behavioural data (see [http://ppw.kuleuven.be/okp/software/dmat/ DMAT main page], incl. [http://ppw.kuleuven.be/okp/software/dmat/ DMAT publication] and [http://ppw.kuleuven.be/okp/_pdf/Vandekerckhove2008DMAWM.pdf "primer"]). See the following page for a [http://toolsandtutorials.pbworks.com/w/page/37703696/Commonly-Used-DMAT-Commands#multiestv4 list of DMAT commands].
The following will show you how to get started with the DMAT toolbox.
First things first: In order to use the Matlab toolbox on our linux system, start Matlab and type "dmat" in the command window - this will set the necessary paths etc.
The format of the input for DMAT should be in a form like this:
{{{
data = [ ...
1 1 0.5223
1 0 0.6661
2 1 0.9812
2 0 0.4932
3 1 0.4112
3 0 0.8342
...]
}}}
The first column codes your "conditions", i.e. subsets of your data that may be allowed to differ from the rest in some way in the later analysis. This could be separate subjects, or both different experimental conditions and subjects. You can later specify (by means of "design matrices") what you want to keep constant across subjects, across conditions, within subjects etc. (please be patient...).
The second column codes whether a response was "correct" (1) or "incorrect" (0).
The third column contains the response times - make sure they are in seconds (not milliseconds)!
You could already fit the diffusion model using default parameters on these data with the function "multiestv4":
{{{
ddmoutput = multiestv4( data );
}}}
In this case, you will get one set of fitted parameters for the whole data set, i.e. not for individual condtions.
The result will be in
{{{
ddmoutput.Minimum
}}}
The output parameters appear in the following sequence:
* 1: Boundary Separation, a
* 2: non-decision time (t_er)
* 3: intertrial standard deviation of drift rate
* 4: starting point, z
* 5: range of z, (s_z, uniform)
* 6: range of t_er (s_t, uniform)
* 7: accumulation/drift rate
== Specifying Input Options, Fitting Multiple Models ==
You can specify a range of different input options, or "models", for DMAT. In order to get the default options, type
{{{
ddmoptions = multiestv4();
}}}
ddmoptions is a Matlab structure containing input parameters for DMAT. You can change them and then run the model
{{{
ddmoutput = multiestv4(data, ddmoptions);
}}}
You can specify multiple models ddmoptions(1), ddmoptions(2), etc. These will then be fitted one-by-one, and the outputs will appear in the output structure as ddmoutput(1), ddmoutput(2), etc. Unfortunately, multiestv4 applied to several model invokes the programme "runqueue", which will use the fitted model parameters for one model as starting points for the fit of the next - this may not be what you want. If you want to be sure that models are fitted independently of each other (and the results don't depend on the sequence of your models), then you should fit each model with a separate call to multiestv4().
See the appendices of the "primer to DMAT" for examples.
== Using Design Matrices ==
Assume you want to get different drift rates for each of your subjects, but all other parameters should be kept constant across subjects. By default, all parameters will be kept constant. You can deal with this type of problem very flexibly specifying design matrices for each parameter. Let's assume we only have 3 subjects. In the case where drift rate is constant across subjects (the default), the design matrix is just a vector
{{{
[1
1
1]
}}}
This means that only one parameter is needed to fit this vector to the data - the drift rate which is common to all subjects.
Letting drift rate vary across subjects means that we will obtain 3 separate drift rates, one for each subject. We are therefore fitting a model to the data which consists of three vectors, each representing a single subject. These vectors are the columns of the design matrix
{{{
[1 0 0
0 1 0
0 0 1]
}}}
which is the identity matrix. You can think of this as a linear regression model '''y'''='''Db''', where '''y''' are the data (3 subjects), '''D''' is the design matrix (3-by-3 identity matrix above), and '''b''' contains the 3 drift rates for each subject that we want to fit.
Now assume a slightly more complex example. We still have 3 subjects, but each of them participated in two tasks. We simply vertically concatenate the data matrices (like at the top of this page), so we have 6 conditions - the top 3 belong to task A, and the bottom 3 to task B. Now we want to fit a model where the drift rate varies across subjects, but is the same for conditions A and B within each subject. We now have 6 conditions, i.e. the design matrix should have 6 rows. We want 3 drift rates (one per subject), i.e. the design matrix should have 3 columns. The corresponding design matrix looks like this:
{{{
[1 0 0
0 1 0
0 0 1
1 0 0
0 1 0
0 0 1]
}}}
If you want to allow for variation of drift rate between conditions A and B within subjects, you can use the following design matrix:
{{{
[1 0 0 1 0 0
0 1 0 0 1 0
0 0 1 0 0 1
1 0 0 0 0 0
0 1 0 0 0 0
0 0 1 0 0 0]
}}}
This will produce 6 drift rates, one per subject that is the same for A and B, and one per subject that represents the difference in drift rate between conditions A and B. This logic is analogous to the General Linear Model in multiple regression, for example.
This is how you specify design matrices in the DMAT options structure:
{{{
ddmoptions.DesignMatrix{7} = eye(3); % design matrix drift rate
}}}
== Example Script ==
{{{
load Data4DDM.mat; % load "data_ddm" for DDM model
nr_ss = 10; % number of subjects/conditions in DDM model
ddmoptions = multiestv4; % get default options for DDM model
% specify design matrices; vary drift/boundary/dead-time across subjects, keep everything else constant
Dv = [ eye(nr_ss) ]; % for drift rate
Db = [ eye(nr_ss) ]; % for boundary separation
Dt = [ eye(nr_ss) ]; % for dead time
Ds = []; % starting point will be at half boundary separation (see also below)
ddmoptions.DesignMatrix = {Db, Dt, '1', Ds, '1', '1', Dv}; % '1' if fixed across conditions/subjects (default)
[ddmoptions.EstimationMethodScalar] = deal(3); % option 3: Chi^2 user-supplied percentiles
[ddmoptions.Percentiles] = deal( [10 30 50 70 90; 10 30 50 70 90] ); % percentiles
[ddmoptions.SpecificBias] = deal( repmat(0.5, 1, nr_cond) ); % starting point at half boundary separation
ddmoptions.Name = 'Example'; % give name to this model
DDM_output_ss = multiestv4(data_ddm, ddmoptions); % estimate the model
}}}