Saving data into a stimfile

Stimfiles

After you have run an experiment, all three variables (myscreen, task and your stimulus variable) will get saved into a file called

yymmdd_stimnn.mat

Where yymmdd is the current date, and nn is a sequential number starting at 01. This file will be stored in the current directory or in the directory ~/data if you have one.

After these get saved, you can access all the variables for your experiment by using

getTaskParameters(myscreen,task);

This will return a strucutre that contains the starting volume of each trial, what each variable was set to, the response of the subject and reaction time, among other things. For most purposes this should contain all the information you need to reconstruct what was presented on what trial and what the subject's response was.

Note that there is a variable called myscreen.saveData which tells the task structure whether to save the stim file or not. The default on your computer is probably set not to save the stim file. When you run on the computer in the scanner room, it will save the file automatically. For debugging purposes this is usually what you want so that you don't save unnecessary stim files every time you test your program. However if you want to save the stim file on your test computer to look at, you can add the following to your code where you call initScreen:

myscreen.saveData = 1;
myscreen = initScreen(myscreen);

The variables stored in the stim file contain all the information you should need to recreate what happened in your experiment. In fact, it even contains a full listing of the file you used when running the experiment. This is useful since often you might make minor changes to the program and forget what version you were using when you ran an experiment. You can access a listing from the task variable:

task{1}{1}.taskFileListing===== Directory to save stimfiles in =====

By default, mgl will save the data in ~/data if that directory exists, and in the current directory if ~/data doesn't exist. To save data to a specific directory instead of to these defaults, set

myscreen.datadir = datadirname;

where datadirname is the full path of the desired directory.

Retrieving data from stimfiles

getTaskParameters

usage: e = getTaskParameters(myscreen,task);
purpose: Gets all the info about your task and its parameters

argument	value
myscreen	The myscreen variable saved in your stimfile
task	The task variable saved in your stimfile. This can be a cell array (task with multiple phases) or a cell array of cell arrays (multiple tasks with multiple phases) or a structure (single task, single phase).

return argument	value
e	A structure or cell array of structures that contains information about the task you run, including how each parameter and randVar was set on each trial, the stimvol for each trial, reaction times for each trial etc.

getStimvol

usage: [stimvol stimNames var] = getStimvol(v,'varname',<taskNum=?>,<phaseNum=?>,<segmentNum=?>);
purpose: Gets the stimvols for a variable. This function is available in mrTools. It will call getStimvolFromVarname on each stimfile for the scan and put all the stimvols together. This is useful for a concatenated scan that has multiple stimfiles since it will create the stimvols correctly for the concatenation – honoring junked frames for instance.

argument	value
v	A view variable returned by newView in mrTools. Make sure to set its curGroup and curScan to the group and scan that you want to get the stimvols for.
varname	The name of the variable you want to get stimvols for (see getStimvolFromVarname for all the options that you can use to select subsets of values of the variable
taskNum	This is an optional argument for when you have multiple tasks, select which task you want by passing in an argument 'taskNum=2' for instance.
phaseNum	This is an optional argument for when you have multiple phases within a task, select which phase you want by passing in an argument 'phaseNum=3' for instance.
segmentNum	This is an optional argument for when you have want to get volumes relative to a specific segment of a trial rather than from the beginning of the trial. Select which segment you want by passing in an argument 'segmentNum=2' for instance.

return argument	value
stimvol	A cell array of arrays. The cell array has one array for each setting of the variable. Each array contains the volume numbers for the times at which the variable in question was set to that particular value.
stimNames	A cell array of strings that contains a description of what that particular stimulus setting is.
var	A structure that contains the varname, taskNum etc. that you used to get the stimvols

An example:

v = newView;
v = viewSet(v,'curGroup',3);
v = viewSet(v,'curScan',1);
[stimvol stimNames var] = getStimvol(v,'varname','taskNum=2','phaseNum=2');

getStimvolFromVarname

usage:[stimvol stimNames] = getStimvolFromVarname(varnameIn,myscreen,task,taskNum,phaseNum,segmentNum);
purpose: Gets a cell array that contains the stimulus volumes for a particuar variable name

argument	value
varnameIn	The variable name that you want to get stimvols for. See below for more information on how this value can be set.
myscreen	The myscreen variable saved in your stimfile
task	The task variable from your stimfile
taskNum	This is an optional argument for when you have multiple tasks. Set to the number of the task you want.
phaseNum	This is an optional argument for when you have multiple phases within a task. Set to the number of the phase you want.
segmentNum	This is an optional argument for when you have want to get volumes relative to a specific segment of a trial rather than from the beginning of the trial. Set to the number of the segment you want.

return argument	value
stimvol	A cell array of arrays. The cell array has one array for each setting of the variable. Each array contains the volume numbers for the times at which the variable in question was set to that particular value.
stimNames	A cell array of strings that contains a description of what that particular stimulus setting is.

varnameIn can be the name of a parameter or randVar. e.g.:

getStimvolFromVarname('dir',myscreen,task,2,2);

It can also be of the form varname(indexVar). For when you have used a parameterCode and an index variable. e.g.:

getStimvolFromVarname('localDir(dirIndex)',myscreen,task);

Or it can be _all_ which returns all trial numbers regardless of stimulus type:

getStimvolFromVarname('_all_',myscreen,task);

If varnameIn is a cell array, then you can specify a set of matching conditions. For example, the following would return the stimvols for when var1 = 1 *and* var2 = either 2 or 3:

{'var1=[1]','var2=[2 3]'}

If you want to return multiple sets of stimvols with matching conditions, you can make a cell array of cell arrays of the type form above. For example:

{{'var1=[1]','var2=[2 3]'},{'var1=[2]','var2=[1]'}}

getTaskVarnames

usage:varnames = getTaskVarnames(task);
purpose: Gets a cell array of the variables names in your task

argument	value
task	The task variable from your stimfile

return argument	value
varnames	A cell array of strings containing the names of parameters and randVars from your task

getParameterTrace

usage: trace = getParameterTrace(myscreen,task,'varname');
purpose: Gets a trace of the variable called for. The time base for the trace is in screen refreshes. e.g.: plot(getParameterTrace(myscreen,task,'dirnum'));

argument	value
myscreen	The myscreen variable saved in your stimfile
task	The task variable from your stimfile
varname	The variable that you want to create a trace for

return argument	value
trace	A vector containing the value of the variable as a function of time in screen refreshes

getVarFromParameters

usage: [varval taskNum phaseNum] = getVarFromParameters('varname',e);
purpose: Gets the variable settings for each trial

argument	value
varname	The name of the variable of interest
e	A structure retruned from getTaskParameters

return argument	value
varval	An array of what the particular variable was set to on each trial
taskNum	The number of the task in which the variable was defined. If defined in multiple tasks will return the last task that it was defined in. To get another task, useg getTaskParameters to select which task to get information from.
phaseNum	The number of the phase in which the variable was defined

makeTraces

For most people, using getTaskParameters is the easiest way to get what happened on each trial. But there is another mechanism that allows you to see the specific timing of events as traces. This is saved in the traces field of the myscreen variable. This field stores when each volume was collected and what stimulus was presented. Using this information you can reconstruct the volume when each stimulus occurred. It is set up so the first row contains an array which has a one every time a volume was acquired (i.e. whenever a backtick was received) and zeros elsewhere. The timebase for the array is in monitor refreshes, so every 60 elements shouls be one second. Take a look at what this trace has by doing:

myscreen = makeTraces(myscreen);
plot(myscreen.traces(1,:));

You can also plot in seconds, relative to the beginning of the experiment:

plot(myscreen.time,myscreen.traces(1,:));

The other important trace is the one corresponding to myscreen.stimtrace:

plot(myscreen.traces(myscreen.stimtrace,:));

This will contain the information about which trial was presented as long as you have set the writeTrace variable correctly (see next section).