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

e = getTaskParameters(myscreen,task);

This will return a structure 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.

See also the section on setting subject IDs which will allow you to save in subject specific directories and provides a little more support for organizing stimfile locations.

Aborted stimfiles

If you have set your system not to save stimfiles or you answer n when prompted to save a stimfile, the task code will still save a stimfile but it will put in the ./Trash folder. Thus, you can always dig around in the Trash and look for a missing file if you messed up and didn't save it. Note that you may need to empty the Trash or remove these files if you don't need them and want to free up space. To delete them without emptying your whole trash folder:

comptuername:/Users/justin> cd ~/.Trash
computername:/Users/justin/.Trash> ls
mglAbortedStimfiles/
computername:/Users/justin/.Trash> rm -rf mglAbortedStimfiles

If you want to save these aborted stimfiles in a different directory then under the Trash, you can set the parameter 'abortedStimfilesDir':

mglSetParam('abortedStimfilesDir','/some/directory/where/you/want/them',1);

Set back to empty if you want the default location.

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.

See also here

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 trialNum] = 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. If you want to get the values of those variables instead of just the strings, see the function stimValsFromNames in mrTools
trialNum A cell array which contains which trial number each stimvol is associated with 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);

Or it can be _every_ which returns every combination of different parameters.

getStimvolFromVarname('_every_',myscreen,task);

For example, say you have the following variables, with the following values:

TrialNum = 1 2 3 4
    var1 = 1 2 1 2
    var2 = 1 1 2 2

Then _all_ would return:

{{[1 2 3 4]}}

and _every_ return would return:

{{1},{2},{3},{4}}

You can also specify every as a cross between the two variables:

getStimvolFromVarname('var1 _x_ var2',myscreen,task);

This syntax offers a bit of flexibility since you can specify which variables get crossed and even for what values, for instance you can specify a cross between var1 and var2 set to the value 1

getStimvolFromVarname('var1 _x_ var2=1',myscreen,task);

Which would return:

{{1},{2}}

You can specify arbitrary and conditions, by doing the following:

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

Which would return

{{[[1 3]},{[2]},{[4]}}

getTaskVarnames

usage:varnames = getTaskVarnames(task);
purpose: Gets a cell array of the variables names in your task. This function can also accept an MLR view instead of the task variable.

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