Task function reference

mglEditScreenParams

availability: mgl 2.0
You can now use a GUI to set all of your screen parameters so that when you call initScreen everything is customized for your system. The settings will be stored across matlab sessions in a file called .mglScreenParams in your home directory. If you had been passing in a screenParams field to initScreen in your mgl program, you should convert to using mglEditScreenParams. To set the parameters you need to have mrTools installed (see Getting Started).

Start by setting your parameters:

mglEditScreenParams

This will bring up a dialog that looks like this:

This first dialog box allows you to manage all of the displays that you have for your computer. You can keep multiple different screen parameters if you have multiple displays on your computer for instance (one for each display). You may also want to keep different display settings for different uses, for example if you like to debug your code with a windowed context, then create another display parameter for the windowed context and set the displayName to say, debug. Then when you run initScreen you can select which display settings to use by passing in the displayName. For example, initScreen('debug').

In this dialog box you can add, delete or restore default settings for each display setting.

Next, you should edit the screen parameters for your desired display by selecting the display and clicking OK. You should see a dialog like this:

Here you can set all of your screen parameters (including the displayName which is how you access the settings with initScreen). You can test the settings using the “testSettings” button. The help button gives you information about all the settings. Here is a list of what the settings do:

Name Function
computerName The name of the computer for these screen parameters
displayName The display name for these settings. This can be left blank if there is only one display on this computer for which you will be using mgl. If instead there are multiple displays, then you will need screen parameters for each display, and you should name them appropriately. You then call initScreen(displayName) to get the settings for the correct display
useCustomScreenSettings If you leave this unchecked then mgl will open up with default screen settings (i.e. the display will be chosen as the last display in the list and the screenWidth and ScreenHeight will be whatever the current settings are). This is sometimes useful for when you are on a development computer – rather than the one you are running experiments on
screenNumber The screen number to use on this display. 0 is for a windowed contex. Less than 1 gives a transparent windowed context
screenWidth The width in pixels of the screen
screenHeight The height in pixels of the screen
framesPerSecond Refresh rate of monitor
displayDistance Distance in cm to the display from the eyes. This is used for figuring out how many pixels correspond to a degree of visual angle
displaySize Width and height of display in cm. This is used for figuring out how many pixels correspond to a degree of visual angle
displayPos This is only relevant if you are using a windowed context (e.g. screenNumber=0). It will set the position of the display in pixels where 0,0 is the bottom left corner of your display.
autoCloseScreen Check if you want endScreen to automatically do mglClose at the end of your experiment.
flipHorizontal Click if you want initScreen to set the coordinates so that the screen is horizontally flipped. This may be useful if you are viewing the screen through mirrors
flipVertical Click if you want initScreen to set the coordinates so that the screen is vertically flipped. This may be useful if you are viewing the screen through mirrors
hideCursor Click if you want initScreen to hide the mouse for this display.
backtickChar Set the keyboard character that is used a synch pulse from the scanner. At NYU this is the backtick character. If you use a different character enter it here. If you enter a number then this will be interpreted as a character code (see mglCharToKeycode).
responseKeys Sets which keys you want to use for response keys. This should be a space delimited string, for example: 1 2 3 4 5 6 7 8 9 is the default, which uses the number keys. If you want to use keycodes, for example to use the numberic key pad, you can do: k84 k85 k86 k87 k88 k89 k90 k92 k93
eatKeys Sets whether to eat keys. That is, any key that initScreen uses, for example the response keys and the backtickChar will not be sent to the terminal. See the function mglEatKeys for more details.
saveData Sets whether you want to save an stim file which stores all the parameters of your experiment. You will probably want to save this file for real experiments, but not when you are just testing your program. So on the desktop computer set it to 0. This can be 1 to always save a data file, 0 not to save data file,n>1 saves a data file only if greater than n number of volumes have been collected)
calibType Choose how you want to calibrate the monitor. This is for gamma correction of the monitor. Find latest calibration works with calibration files stored by moncalib, and will look for the latest calibration file in the directory task/displays that matches this computer and display name. If you want to specify a particular file then select that option and specify the calibration file in the field below. If you don''t have a calibration file created by moncalib then you might try to correct for a standard gamma value like 1.8 (mac computers) or 2.2 (PC computers). Or a gamma value of your choosing
calibFilename Specify the calibration filename. This field is only used if you use Specify particular calibration from above
diginPortNum Click this if you want to use the National Instruments cards digital io for detecting volume acquisitions and subject responses. If you use this, the keyboard will still work (i.e. you can still press backtick and response numbers. This uses the function mglDigIO – and you will need to make sure that you have compiled mgl/util/mglPrivateDigIO.c
diginAcqLine This is the line from which to read the acquisition pulse (i.e. the one that occurs every volume)
diginAcqType This is how to interpert the digial signals for the acquisition. If you want to trigger when the signal goes low then set this to 0. If you want trigger when the signal goes high, set this to 1. If you want to trigger when the signal changes state (i.e. either low or high), set to [0 1]
diginResponseLine This is the lines from which to read the subject responses. If you want to specify line 1 and line 3 for subject response 1 and 2, you would enter [1 3], for instance. You can have up to 7 different lines for subject responses.
diginResponseType This is how to interpert the digial signals for the responses. If you want to trigger when the signal goes low then set this to 0. If you want trigger when the signal goes high, set this to 1. If you want to trigger when the signal changes state (i.e. either low or high), set to [0 1]
testDigin Click to test the digin settings
testSettings Click to test the monitor settings

initScreen

purpose: initializes the screen
usage: myscreen = initScreen(<myscreen>,<randstate>)

argument value
myscreen Contains any desired initial parameters, can be left off if you are just using all defaults
randstate Sets the initial status of the random number generator. This can either be an integer value, or it can be the field myscreen.randstate to set the state back to what it was on a particular experiment.

This function initializes the screen by calling mglOpen, and also handles a number of different default initialization procedures such as setting up the gamma table with the correct linearization table. You should call this once at the beginning of the experiment. The variable myscreen will contain many fields associated with the status of the screen and records events like volume acquisitions and trial/segment times etc.

There are a number of parameters that will be specific to your computer/display that you can set by setting the screenParams field of myscreen to save information about your setup:

myscreen.screenParams{1} = {'yoyodyne.cns.nyu.edu',[],2,1280,1024,57,[31 23],60,1,1,[],[],[0 0]}; 
myscreen = initScreen(myscreen);

This will set parameters for your screen. The parameters in order are

  • computerName
  • displayName (optional–for computers with multiple displays like lcd and projector. You select which display you are working on by setting myscreen.displayname to the string stored here)
  • displayNumber
  • screenWidth (in pixels)
  • screenHeight (in pixels)
  • displayDistances (in cm)
  • displaySize (in cm)
  • framesPerSecond (in Hz)
  • autoCloseScreen (1 to close screen at end of experiment, 0 to leave it open)
  • saveData (1 to save data file, 0 not to save data file,n>1 saves a data file only if you exceed n number of volumes)
  • monitorGamma (The monitor gamma to correct for if you do not have a calibration file. Macs are supposed to have a gamma of 1.8)
  • calibFilename (the name of the calibration file–usually just the computer name–see below under moncalib)
  • flipHV (Whether to flip the screen horizontally and/or vertically–an array of length two 0=no flip, 1 = flip)

MGL 2.0: The initScreen program looks for a file called by default mgl/task/mglScreenParams.mat which contains a cell array of computer display information parameters like the above (as long as you don't set myscreen.screenParams before calling initScreen). This way you can save a file which contains information about all the computers in your lab and always load that up rather than having each stimulus program contain all the information. You can do this by changing the name of the file that initScreen loads by setting:

screenParams{1} = {'yoyodyne.cns.nyu.edu',[],2,1280,1024,57,[31 23],60,1,1,[],'yoyodyne',[0 0]};   
screenParams{2} = {'terranova.bnf.brain.riken.jp',[],0,800,600,57,[31 23],60,1,0,[],[],[0 0]};   
save ~/Desktop/myScreenParams.mat screenParams
mglSetParam('screenParamsFilename','~/Desktop/myScreenParams.mat');

initStimulus

purpose: initializes the global stimulus variable name
usage: myscreen = initScreen('stimulusName',myscreen);

argument value
stimulusName string that contains the name of the global variable that is used for your stimulus (i.e. if you had global stimulus, then this should be 'stimulus')
myscreen myscreen variable returned by initScreen

Note that this function, only needs to be called if you want to save the stimulus in your stim file. Since stimulus is a global variable, if you call this function, at the end of the experiment it will get the global variable with the name you specified here and save it in your stim file. If you do not need to save your stimulus variable, you do not need to call this function.

initTask

purpose: initializes a task variable
usage: [task myscreen] = initTask(task,myscreen,startSegmentCallback,screenUpdateCallback, trialResponseCallback, <startTrialCallback>, <endTrialCallback>, <startBlockCallback>)

argument value
task Parameters for the particular task (note this must be a struct not a cell array, for a cell array, call initTask fore each element of the cell array.
myscreen Variable returned by initScreen
startSegmentCallback Function pointer that will be called at start of a segment
screenUpdateCallback Function pointer that will be called every screen update (i.e. for a 60Hz buffer once every 1/60 of a second)
trialResponseCallback Function pointer that will be called when the subject responds and getResponse is set
startTrialCallback Function pointer that will be called at start of a trial
endTrialCallback Function pointer that will be called at end of a trial
startBlockCallback Function pointer that will be called at start of a block

The task variable gets set up as explained above. Here is a list of valid fields:

field value
verbose display verbose message when running tasks (probably shouldn't be set for real experiment since print statements can be slow)
parameter task parameters
seglen array of length of segments (used when not using segmin and segmax)
segmin array of minimum length of segment
segmax array of maximum length of segment
segdur a cell array (not all cells have to be set they can be empty) which specifies an array of values for the length of a segment for example segdur{2} = [1 3 5] would set segment 2 to have durations 1, 3 or 5 seconds long
segprob a cell array (not all cells have to be set they can be empty) which specifies an array of values for the probability of how often each segdur will happen, so if we have segdur{2} = [1 3 5] and segprob{2} = [0.4 0.5 0.1], then this would set segment 2 to have durations 1, 3 or 5 seconds long with probability 0.4 0.5 and 0.1 respectively. Note that if no segprob is set for a non-empty segdur than each of the durations in segdur will occur with equal probability.
synchToVol array where one means that the segment will synch to the next volume acquisiton once the segment is finished.
getResponse array where one means to get subject responses during that segment, set to zero means that subject responses will be ignored and the responseCallback will not be called
numBlocks number of blocks of trials to run before stopping
numTrials number of trials to run before stopping
waitForBacktick wait for a backtick before starting task phase
random randomize the order of parameters for each trial when set to 1, otherwise have the parameters go in order
timeInTicks when set to 1, segment legnths are in screen updates (not in seconds)
timeInVols when set to 1, segment lengths are in volumes (not in seconds)
segmentTrace internal variable that controls what trace this task will use to save out segment times (usually you will not set this)
responseTrace internal variable that controls what trace this task will use to save out subject responses (usually you will not set this)
phaseTrace internal variable that controls what trace this task will use to save out the phase number (usually you will not set this)
parameterCode For parameters that have groups
private A parameter that you can do whatever you want with
randVars random variables
fudgeLastVolume When you synchToVol or keep time in volumes, and want to have the experiment run for a set number of trials, the experiment won't usually end because in the last segment it is waiting for a volume to come in that never will. If you set this to 1, it will fudge that last one so that the experiment ends one TR after the last volume is aquired.

updateTask

purpose: updates the task
usage: [task myscreen phaseNum] = updateTask(task,myscreen,phaseNum)

argument value
task task variable, note task must be a cell array. If you only have one task phase, make phaseNum=1 and task a cell array of length one.
myscreen myscreen variable returned by initScreen
phaseNum The task phase you are currently updating. If you only have one phase, set to 1, for multiple phases, update Task will take care of switching from one phase to the next.


tickScreen

purpose: updates the screen
usage: [myscreen task] = tickScreen(myscreen,task);

argument value
myscreen myscreen variable returned by initScreen
task task variable

This function calls mglFlush to update the screen when it is needed and also checks for volumes and keys etc. Called with in main loop.

upDownStaircase

Implements a staircase for control of stimulus variable values. Type 'help upDownStaircase' for details. Also see taskTemplateStaircase.m for examples of using this function.

jumpSegment

Allows you to force a move to the next segment or the next trial:

task = jumpSegment(task) % this will end the segment and move to the next one
task = jumpSegment(task,inf) % this will end the trial and start a new trial