Scripting Overview

Everything can be scripted in MLR without any interaction with the GUI. Scripting can be as simple as writing a quick function to perform all the analysis steps that you typically run on a retinotopy experiment or your event-related experiment. In other cases, scripting may be the way that you run a much more complex analysis like fully analyzing an adaptation experiment or a classification experiment. The goal of MLR is to make these tasks easy by providing a Matlab interface to your data. MLR takes care of all the book-keeping and alignment of data, etc., and you simply write the parts of your analysis that are specific to your particular experiment. MLR also makes it easy to interface with the GUI once you have your analysis by giving you functions to display overlays and write your own interrogator functions which can display your voxel-by-voxel results in any way that makes sense for your particular experiment. The best way to get started with scripting is to look at some of the examples we have in this section.

Programming conventions

The following is a partial list of programming conventions. These are listed here to make your life easier. If you follow these conventions your programs will work better and work consistently with future releases of MLR. So, pay attention!

  1. “view” variables. A view variable is the starting place for almost all scripts. It encapsulates all the information about your session that is available when you have the GUI viewer going, but without having to bring up the GUI. Whenever you create a view with newView, you should remember to delete it when you are done (especially if it is inside a script/program). Otherwise you will build up a lot of useless view structures in memory.
     v = newView;
     ...
     do some stuff
     ...
     deleteView(v);

    Also, you might want to call the view variable v instead of view, since view is a built-in matlab function.

  2. Always use viewGet and viewSet for accessing fields. You should never directly access any of the MLR variables to get information about the scan. Why? Because we may have to change the implementation of how some variable is stored in a future version of MLR. If that happens, your code will be busted. If you use viewGet and viewSet, your code will work fine. Also, viewSet is designed to properly side-effect the global variable, not just the local copy. Note that viewGet and viewSet assume defaults (e.g., the current scan or current group) for some fields – these can usually be overridden in the call to viewGet/viewSet. You can get a full listing of what is possible to viewGet and viewSet by just typing viewGet or viewSet. You can get specific help for parameters, by doing (e.g.):
      viewGet([],'scan','help');

    Also, whenever you viewSet something, make sure to set the return argument:

      v = viewSet(v,'someParameter',newParameterSetting);
  3. Use mrMsgBox, mrErrorDlg, mrWarnDlg, mrWaitBar, and mrCloseDlg to give messages and errors to the user. These functions switch off of the 'mrLoadRet' 'verbose' preference. If the preference is off (not defined or defined to be 0) then the messages go to the matlab window instead of opening dialog boxes. Verbose preference also determines if user is queried about overwriting a file. Very useful for running scripts that are intended to be non-interactive.
  4. Avoid accessing scans or groups by number. Remember that if you delete a scan in a group, or delete a group the order of your scans and groups might be changed. It is always better to specify the name of the group you want, e.g. v = viewSet(v,'curGroup','MotionComp'), rather than the number. Virtually all of the viewGet commands accept a group name in lieu of a group number. Similarly, you should not count on the scan number of a scan staying the same. Instead, you might want to get the scan from the description string that you set. For example, if you want to get all the scans that have the string 'wedges' in their description:
      scanNums = viewGet(v,'scanNumFromDescription','wedges','Raw');

    Also keep in mind that if you are writing a true analysis function then you will have to provide (or use the default) reconcile functions which handle keeping track of which overlay goes with what scan by comparing the filenames of the scans. In MLR scan filenames should always be unique to each scan.