Skip to content

mrVista

Jump to bottom Edit New page
Nathan Witthoft edited this page Dec 14, 2016 · 14 revisions

The Matlab interface for analyzing functional and anatomical data is called mrVista. The mr (pronounced mister) throughout our code is appended to the acronym VISTA(vision, image science, and technology applications) that the Wandell lab has used for more than 20 years.

See the Software page to learn about setting up Matlab, and obtaining the other packages used in conjunction with mrVista.

For this section of the tutorial, we assume that you will start with an existing data set that contains functional measurements and that the data have already been initialized using mrInitRet. You can obtain an example data set from the tutorials page using the remote data toolbox.

Further information regarding mrVista can also be found on the mrVista conventions page.

Table of Contents

Starting MrVista

The current version of MrVista allows you to integrate and visualize data in several different "view types".

Screenshots from the different view types are shown below.

<gallery> Image:Inplane_GUI_Example.png|Example Inplane Window Image:Volume Window Example 3-View.png|Gray 3-View Image:FlatWindowVsPublishedFigure.png|Flat window and a publishFigure output. Image:MeshVisualize.jpg|Mesh colored by curvature </gallery>

You can start MrVista by changing MATLAB into the data directory and typing: 

  vw = mrVista();

This will start an inplane view type for the current data. If the data has been initialized, this will always work.

If the data have been processed to incorporate the other types of views, when you return for a new analysis you can begin with those visualizations by typing: 

 vw = mrVista('3view');&nbsp;% opens gray 3-view window
 vw = mrVista('flat'); &nbsp;% opens flat 3-view window
 vw = mrVista('gray'); &nbsp;% gray single-orientation window

(Type 'help mrVista' for more start options). The first letter of each option can be used as a shortcut as well.

mrVista functions

There are various tasks that we normally perform prior to analyzing the data in detail. These include

In addition, there are a wide variety of general purpose analyses you can apply, such as Most functions can be accessed via pull-down menus in the GUI window for the different views. These menus are mostly conserved across view types, though there are some exceptions in which a function is specific to a view (3D motion correction, for instance, is specific to the Inplane view, while the 2D visual field map atlas functionality is specific to the Flat view).

More general information about displaying data in mrVista:

  • Adjusting, saving and loading Color Maps for data overlays.
Descriptions for the functions associated with each menu are described on their own page:

mrVista view structures

Four different view structures exist in mrVista. Explanations of their fields, initialization, and uses exist on the following pages:

View Interaction Mechanisms

Regardless of the type of view being used, the view data structure can be accessed with calls to viewGet and viewSet. viewGet gets or calculates data based on the data structure, while viewSet sets or saves data to the underlying data structure. The signature of these two functions shows what is necessary to call them, as well as an example of calling them can be found here: 

 viewGet(View Structure,Parameter)<br />
 viewGet(vw,'Name');

 viewSet(View Structure,Parameter,Value To Save)<br />
 viewSet(vw,'Home Directory','~/matlab/session1');

The parameters can have any capitalization and spaces inside them. For example, 'homedir' and 'Home Dir' are treated exactly the same. As well, most parameters also have a translation field that treats all of the parameters the same. Thus, 'Home Dir' and 'Home Directory' are treated in the same way. This parameter field can be found in the function 'viewMapParameterField'. Some functionality will be added to allow a user to get the parameter fields from a specific parameter in the near future.

The viewGet/Set functions can now report all of the supported parameters, in alphabetical order. There are a few different ways of interacting with the viewGet/Set functions in a way that will get information about what parameters are supported, List, Help and Type can all be used in the method described below. Please note that once again capitalization and spacing is ignored (thus, 'type' and 'Ty Pe' will be treated in the same way).

  • List is used to list out all of the parameters that are supported by these functions.
  • Type lists the parameters that exist, in the same way as list, and appends the type which each of the parameters can be split into, e.g. 'ROI-related properties', 'Anatomy / Underlay-related properties', etc.
  • Help lists the parameters that exist, in the same way as list, and appends a quick help description describing what they mean.
To remove the requirement of having a view structure available when understanding the viewGet/Set functions, the new signature used for these cases is: 
 viewGet('List')<br />
 viewSet('Type')<br />
 viewGet('Help')<br />
 viewGet('Help',Parameter)

The difference between the 3rd and the 4th case is the number of results returned. Without a second parameter, as in the 3rd case, a call for 'Help' lists all of the parameters possible, in the same manner as list or type. However, with a second parameter, as in the 4th case, only that specific parameter is shown. This functionality can be used by either Type or Help. Both viewGet and viewSet can use these functions to retrieve this meta-data.

Please note that as there are calculated values in viewGet which do not map directly to a data point, the parameters that refer to these calculations do not have corresponding parameters implemented in viewSet. The upshot is that not all parameters that are listed will be usable in both viewGet and viewSet.

Adding a new parameter to viewGet/Set

When adding a new parameter, there are a few different locations that must be updated to ensure that this parameter will work smoothly. To enable the functionality listed above, each parameter must be added to the following files:

viewMapParameterField.m - Listing all of the aliases that this new parameter will have.

viewHelpParameter.m - A short description of the new parameter describing its use.

viewParameterType.m - The category type that this parameter is part of. This will also then define which viewGet/viewSet file to store its functionality into.

viewGet{Type}.m - The underlying file that stores the get functionality.

viewSet{Type}.m - The underlying file that stores the set functionality.

Data directories

Prior to initializing your functional data you must organize key files and place them in the proper directories . The files and directories are described here.

We call the directory containing the MR measurements the session directory. The files and directories are normally named by the date and perhaps the subject code, (e.g. 20050810sc). (Use subject codes, not names, because of privacy). At first the only files in the session directory will be in the subdirectory called Raw/.

Raw/Pfiles -- contains functional data

Raw/Anatomy/Inplane -- contains coregistered anatomical data.

(If a data session doesn't have the Inplane anatomies, a temporal mean volume from one of the functional scans could be used instead; see below for more details.)

An optional, but useful, subdirectory is Raw/Anatomy/SS -- containing Screen Save files. (At the Lucas Center console, you can make a screen save by selecting the 'Browser' left-hand panel, choosing the exam, series, and one of the slices off which you prescribed the inplanes, then typing in the small prompt on the lower left-hand side, 'xr -s [#]', where [#] is the # of the Inplane series. Then press Save Screen, to save the image in series 99, for screen saves).

The script 'SetupRawDir' can be run from MATLAB to set up this directory. If you just have all of your raw data (with anatomical series in their own subdirectories, like 001/, 002/, etc), it will give you the option to rename the anatomical series, and move all P-files and headers into the Raw/Pfiles directory.

Linking to the subject's Volume Anatomy

An optional, but very useful, step in setting up a session directory is to make a link to the directory containing the subject's Volume Anatomy. In a linux, MacOSX terminal, or Cygwin terminal, you can change to the session directory, and use the following syntax: 

 ln -s /data/anatomy/subjectX/ 3DAnatomy

By default, if no anatomy path is specified, the code will look for a folder called 3DAnatomy. This can be useful, for instance, if you access the same session on multiple machines with different operating systems, since the path will then always be relative to the session directory, instead of an absolute path which changes.

Creating mrVista data structures from the Raw data

Once the Raw/ directory is set up, there are several tools to initialize a new mrVista session. We recommend that you go to that section of the manual.

'''mrInit''' provides a GUI for initializing the data.

Details on using the command line to initialize a session can be found here.

After initializing a session, in addition to the "Raw" directory, a session will have the following:

  • mrSESSION.mat: key MATLAB file containing information on what sets of data are in the current directory.
  • Inplane directory: contains all analyses performed on the data in the orientation in which they come from the scanner.
  • Inplane/Original: this is the 'data directory' for the "Original" data type, meaning the data before preprocessing. Any maps or data files which are computed for this set of data will be stored here. (Other data types, e.g. "Averages", "MotionComp" or "GLMs" can be made down the line.)
  • Inplane/anat.mat: This is a MATLAB file containing the inplane anatomy and information on other possible images to use as an "underlay" image in the display. This file is being removed as part of an update on 2013-04-01. More information can be found here.
  • Inplane/Original/TSeries: This directory contains the time series files for the original scans. Each scan has its own subdirectory, e.g. "Inplane/Original/TSeries/Scan1/" or "Inplane/Original/TSeries/Scan2/". Within each subfolder, time series are stored slice by slice: "Inplane/Original/TSeries/Scan1/tSeries4.mat" is the data for scan 1, slice 4, for instance. (There are accessor functions so you generally don't have to navigate down all these directories to get to the data.) The time series file contains a single variable, 'tSeries', which is a 2-D matrix of size [nTimePoints] rows by [nVoxels] columns. nVoxels is the product of the voxels along the X and Y dimensions of the slice.

Motion Correction and Anatomical Alignment

Methods for subject motion correction and alignment of the functional data to the anatomical coordinate frame are described on separate pages.

mrVista Functions

The many different mrVista functions are described on the separate pages that illustrate the Inplane, Volume, and Flat windows. In general, mrVista functions operate on 'view' structures, described here.

Each of the view types can be opened as either a GUI with a window, or as a "hidden" view which operates from the command line but does not open any windows. So, for instance, the command 

 '''mrVista inplane'''

will open an inplane window (in this case, omitting the 'inplane' argument also opens one since it's the default), while typing 

 '''ip = initHiddenInplane'''

will create a hidden structure.

In the first case (mrVista inplane), the data associated with the inplane window will be kept in the global variable INPLANE; this variable is a cell array which can contain information for many views. So, if you're opening an inplane for the first time, the data for that first window will be in INPLANE{1}, while if you open a second window, the data for that window will be in INPLANE{2}.

In the second case (ip = initHiddenInplane), the variable ip will be a struct variable containing all the same information that would be in INPLANE{1} -- except for a single field, ui, which is present in INPLANE, but not ip. The ui field contains information on the current state of the graphical user interface, including handles to the various graphical controls for the GUI.

Most mrVista functions take the view structure as the first input, which could be either the global variable (INPLANE{1}, VOLUME{1}, etc) or a hidden view (ip, hiddenGray, etc). So, for instance, to compute a map of the mean functional image of a scan or scans, you might call: 

 '''INPLANE{1} = computeMeanMap(INPLANE{1}); '''

Often these functions accept additional parameters for the function as subsequent input arguments. So, in this example, if you wanted to compute the mean functional image, but only for the first two scans, you would call: 

 '''INPLANE{1} = computeMeanMap(INPLANE{1}, [1 2]); '''
Add a custom footer
Clone this wiki locally