====== Task function reference ======
===== mglEditScreenParams =====
**availability**: [[mgl:beta|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 [[mgl:gettingstarted#initial_setup|Getting Started]]).
Start by setting your parameters:
mglEditScreenParams
This will bring up a dialog that looks like this:
{{:mgl:mgleditscreenparams1.png|}}
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:
{{:mgl:mgleditscreenparams2.png?711x291|}}
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(,)
^ 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, , , )
^ 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