====== 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 [[:mgl:taskreferencesid#stimfile_location|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:

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

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 [[mgl:taskreference#gettaskparameters|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:overview|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:

<code>
TrialNum = 1 2 3 4
    var1 = 1 2 1 2
    var2 = 1 1 2 2
</code>

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