Diff for "DMATintro" - Meg Wiki
location: Diff for "DMATintro"
Differences between revisions 9 and 17 (spanning 8 versions)
Revision 9 as of 2011-09-20 10:32:38
Size: 7455
Editor: YaaraErez
Comment:
Revision 17 as of 2014-05-20 10:09:45
Size: 7560
Editor: OlafHauk
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
#acl GoodGroup:admin,read,write,delete,revert CambridgeGroup:read CbuGroup:read
Line 4: Line 2:
Line 6: Line 3:

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].
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]].
Line 11: Line 7:
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. 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).
Line 16: Line 12:
data =  data_ddm =
Line 24: Line 20:
Line 27: Line 22:
The second column codes whether a response was "correct" (1) or "incorrect" (0).  The second column codes whether a response was "correct" (1) or "incorrect" (0).
Line 36: Line 31:
Line 44: Line 38:

The output parameters appear in the following sequence:
The output parameters appear in the following sequence as a row vector:
Line 55: Line 48:
== Specifying Input Options, Fitting Multiple Models == If you have more than one condition, you will get each row of these parameters for each condition.
Line 57: Line 50:
== Input Options, Fitting Multiple Models, Inspecting Output ==
Line 62: Line 56:
Line 68: Line 61:
Line 73: Line 65:
See the appendices of the "primer to DMAT" for examples.  See the appendices of the "primer to DMAT" for examples.
Line 76: Line 68:

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 
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
Line 80: Line 71:
[1 
 1 
[1
 1
Line 84: Line 75:

This means that only one parameter is needed to fit this vector to the data - the drift rate which is common to all subjects. 
This means that only one parameter is needed to fit this vector to the data - the drift rate which is common to all subjects.
Line 94: Line 84:
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.
Line 95: Line 86:
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:
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:
Line 107: Line 96:
Line 111: Line 99:
[1 0 0 1 0 0  [1 0 0 1 0 0
Line 118: Line 106:

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 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.
Line 126: Line 113:

Line 129: Line 114:
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 [http://ppw.kuleuven.be/okp/software/dmat/ DMAT publication] and [http://ppw.kuleuven.be/okp/_pdf/Vandekerckhove2008DMAWM.pdf "primer"]. 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 [[http://ppw.kuleuven.be/okp/software/dmat/|DMAT publication]] and [[http://ppw.kuleuven.be/okp/_pdf/Vandekerckhove2008DMAWM.pdf|"primer"]].
Line 132: Line 117:
load Data4DDM.mat; % load "data_ddm" for DDM model load Data4DDM.mat; % load "data_ddm" for DDM model (see top of Wiki page)
Line 148: Line 133:
[ddmoptions.SpecificBias] = deal( repmat(0.5, 1, nr_cond) ); % starting point at half boundary separation [ddmoptions.SpecificBias] = deal( repmat(0.5, 1, nr_ss) ); % starting point at half boundary separation

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:

  • 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

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

CbuMeg: DMATintro (last edited 2014-05-20 10:09:45 by OlafHauk)