Practical Introduction to Diffusion Modelling using the DMAT toolbox

Basics

DMAT is a Matlab toolbox for fitting the Ratcliff Drift Diffusion Model to behavioural data (see DMAT main page, incl. DMAT publication and "primer"). See the following page for a 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. (Currently this only works for matlab version 2009a not 2006b).

The format of the input for DMAT should be in a form like this:

data_ddm =
[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 as a row vector:

If you have more than one condition, you will get each row of these parameters for each condition.

Input Options, Fitting Multiple Models, Inspecting Output

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().

You can inspect the output of multiestv4 using the function "qtable". In order to compare different models, you can use the function "chi2test".

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

This example demonstrates how to run a DMAT analysis and change some of the default options, design matrices etc. For more information and further examples, look at the DMAT publication and "primer".

load Data4DDM.mat;  % load "data_ddm" for DDM model (see top of Wiki page)

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_ss) ); % starting point at half boundary separation
ddmoptions.Name = 'Example';    % give name to this model

DDM_output_ss = multiestv4(data_ddm, ddmoptions);   % estimate the model