From Vista Lab Manual
The code featured here involves the work of many people from the Wandell lab. We are constantly working on revisions and improvements as well as bug fixes. Note that the source code is always included in our downloads. Unless otherwise noted, all our code is released under the GPL. The authors of the code (usually noted in the comments of each source file) retain all copyrights. By downloading our code, you implicitly agree to be bound by the terms of the GPL.
Starting in winter of 2013, we changed version control sytems from from subversion SVN hosted on our own severs to GIT hosted on github. Vistalab software should not be downloaded from the vistlab repository on github. For example, you can download a zip-file of the vistasoft code from the vistasoft repository.
We also distribute a sample data set (vistadata). These are used in conjunction with the tutorial scripts in mrScripts. These scripts expect certain data sets to be in the vistadata repository. The sample data set is large enough that we felt we shouldn't abuse our relationship with the free github system, hence we manage that from our Stanford servers.
The following sections describe the code repositories developed by the VISTA lab. Most repositories are hosted on GitHub. Other repositories are locally hosted and can be "checked out" using SVN. GitHub repositories can be browsed on GitHub, while local repositories can be browsed using Trac (click the title to browse with trac). Each repository section contains a "Get" section with details of how you can obtain the code. Importantly, some of the VISTA code packages (e.g., VISTASOFT) require external software to run (e.g., Matlab, SPM). Please see the section below for information about required software.
VISTASOFT is the MAIN software repository for the tools used in the VISTA Lab. The repository includes methods for processing anatomical, functional, and diffusion tensor imaging data. The software is written mainly in Matlab. The VISTASOFT package contains:
- MrVista - fMRI tools
- MrAnatomy - Anatomical
- MrDiffusion - DTI tools
- MrScripts - Matlab scripts that illustrate the use of VISTASOFT functions
There are some additional utilities written in C++/VTK. All of the software runs on Windows/XP and on Linux. Most of the software runs on Apple computers. To run VISTASOFT you will need Matlab and tools from FSL and SPM (described below).
- For information regarding setting up your environment to run VISTASOFT pelase visit the Matlab page.
# Repo URL: http://github.com/vistalab
# Linux Checkout Command: git clone http://github.com/vistalab/vistasoft.git
For those users who would like to quickly download a current version of the software. Clicking HERE will download a zip-file containing a current snapshot of the entire VISTASOFT repository.
Experimental control and display toolbox. A set of Matlab routines for controlling the experiment, particular for calibrating displays for vision experiments and managing the interface with the MR scanner. But also useful for straight psychophysics. This code relies on parts of the PsychToolBox.
# Repo URL: http://github.com/vistalab/vistadisp
# Linux Checkout Command: git clone https://github.com/vistalab/vistadisp.git
For those users who would like to quickly download a current version of the software. Clicking HERE will download a zip-file containing a current (hourly) snapshot of the entire VISTADISP repository.
The vistadata repository includes data sets that are used in conjunction with the tutorial scripts in mrScripts. These scripts run on multiple platforms and the tutorial scripts expect certain data sets to be in the vistadata repository.
# Repo URL: https://white.stanford.edu/repos/vistadata
# Linux Checkout Command: svn checkout https://white.stanford.edu/repos/vistadata
- VISTADATA_daily.zip (~2.5 GB)
Those users who would like to quickly download a current version of the repo can do so using the link above. This will download a zip-file containing a current (daily) snapshot of the entire VISTADATA repository.
Within the VISTA LAB there is no need to checkout a version because we maintain one checked-out copy of the vistadata in:
We are working on a number of local projects that have software, experiments and analyses under development. These projects are not ready for sharing. It is convenient, however, to maintain a repository version of the project code. The vistaproj repository contains the code for these development projects VISTASOFT projects. Vistaproj is intended to be a working repository for local projects, unlike the relatively stable VISTASOFT repository.
VISTAPROJ is a private/secure repository - which means only members of the lab have access this repo. For this reason we did not set up the VISTAPROJ repository for trac browsing.
# Repo URL: https://white.stanford.edu/srepos/vistaproj
# Linux Checkout Command: svn co https://white.stanford.edu/srepos/vistaproj
You can just check out a portion of the repository, as well, by specifying the subdirectory. The way to do this is to create a directory, vistaproj, and then to use:
svn co https://white.stanford.edu/srepos/vistaproj/YOURPROJECT
# Repo URL: https://white.stanford.edu/repos/vistasrc
# Linux Checkout Command: svn co https://white.stanford.edu/repos/vistasrc
For those users who would like to quickly download a current version of the software. Clicking HERE will download a zip-file containing a current (hourly) snapshot of the entire VISTASRC repository.
VISTADWI (aka StanfordTools-DWI) is a repository containing only the source code for certain VISTA executables:
# Repo URL: https://white.stanford.edu/repos/StanfordTools-DWI/
# Linux checkout command: svn co https://white.stanford.edu/repos/StanfordTools-DWI/
For those users who would like to quickly download a current version of the code. CLicking the above link will download a zip-file containing a current (hourly) snapshot of the entire VISTADWI repository.
AFQ is designed to automatically identify major fiber tracts and quantify tissue properties along their trajectories. The result is a "Tract Profile" of MRI parameters that can be used to study white matter tissue properties in healthy brains or quantify abnormalities in diseased brains. In the future we hope to be able to automatically identify abnormalities in an individual and quantify that individual's risk for various functional consequences. AFQ is based on the main mrDiffusion software package but hopefully at some point will be written as a standalone routine. The main contributors to this project are Jason Yeatman, Bob Dougherty and Brian Wandell, however many others have contributed along the way.
# Repo URL: https://github.com/jyeatman/AFQ
# Linux Checkout Command: git clone https://github.com/jyeatman/AFQ.git
The vistadata repository includes data sets that are used in conjunction with the tutorial and validation scripts in mrScripts. These scripts run on multiple platforms and the tutorial scripts expect certain data sets to be in the vistadata repository.
NOTE: We recommend that you use the Vistadata repository to get sample data. The Vistadata repository contains an array of sample data, which you can browse HERE and download the data you require. These data are selected to work with the scripts in mrScripts. This is a work in progress. We still provide links to some older data sets here.
In addition to the Matlab code for mrVista, we have a series of executables that help us to segment gray from white ( ITKGray), generate fiber tracks (ConTrack), and visualize and measure properties of fiber tracks (QUENCH).
If you need the source code for these projects, they are stored in the SVN StanfordTools-DWI repository. This is a fairly large repository that contains sections for QUENCH, RAPID, and Contrack. The checkout command is simply
svn co https://white.stanford.edu/repos/StanfordTools-DWI
ITKGray is a new segmentation tool developed by Bob Dougherty. ITKGray is a branch of the ITKSnap project. Bob added functionality from mrGray, including topology checking/fixing and a new flood-fill paintbrush that is similar to the mrGray auto-segmentation methods, but is run on small sections of an image rather than the entire image at once.
If you use ITKGray in published work, please consider citing the ITKSnap folks with the following citation: Paul A. Yushkevich, Joseph Piven, Heather Cody Hazlett, Rachel Gimpel Smith, Sean Ho, James C. Gee, and Guido Gerig. User-guided 3D active contour segmentation of anatomical structures: Significantly improved efficiency and reliability. Neuroimage. 2006 Jul 1; 31(3):1116-28. bibtex | pubmed | doi:10.1016/j.neuroimage.2006.01.015.
The new version of DTIQUERY is compiled for Ubuntu only (static library inclusion).
sudo apt-get gifti # is necessary for running on Ubuntu.
We are starting to prepare scripts documenting its usage with Matlab, loading pdb-version 3 fiber data, and modes of operation. The main DTIQUERY page only has a few comments for mouse and key commands, and some version history. More will be placed there.
QUENCH is a DTI software visualization tool. It enables the user to visualize fiber tracts, edit them, group them, draw volumes of interest, and show measures of tract properties along the length of the tract.
- Jump to the ConTrack Page
ConTrack is a probabilistic tracking algorithm developed by Anthony Sherbondy. This software package is included in mrVISTA and is run primarily through Matlab. The actual executable is run through a bash shell. For info regarding ConTrack and directions on how to generate fibers please visit the ConTrack Page.
The ConTrack executable (included with VISTASOFT) is implemented only for 64-bit linux machines. If you need to build the executables for your system see the Build QUENCH page and follow the directions there (ConTrack and QUENCH are part of the same package).
- Jump to the MicroTrackPage
MicroTrack is a method that inverts tractography. It begins with an estimate of fascicles and predicts the diffusion data. Similar calculations are performed by NFG (link to go here). The MicroTrack algorithm differs in several ways as we explain on the main page.
Early papers describing the MicroTrack principles: PUT THEM HERE. MICCAI papers here.
This is a Postgres database backend with Python accessibility that we are creating for archiving and validating neuroimaging data and analyses at the CNI. Our lab is taking the lead, however, so that the development code and testing is in our world.
Some external software is used regularly in the VISTA lab. Some are required to run the VISTASOFT code (e.g., Matlab and SPM), while others are optional packages that lab members often rely upon for various things (e.g., Freesurfer for auto-segmetation of anatomical images).
VISTASOFT Required Packages
The following software packages are required to use VISTASOFT.
You will need a copy of MATLAB to run VISTASOFT. The Matlab page is intended to be a resource for new users to get Matlab installed and working with VISTASOFT.
While the VISTASOFT code has been used in conjunction with many versions of MATLAB, the version which is being used for development and testing is version Matlab R2010b. Therefore R2010B is the best starting point for those installing Matlab.
For more information regarding which version of MATLAB to use, platform-specific questions, and information regarding setting up Matlab to run VISTASOFT please visit the Matlab Page.
Some of the code included in mrVista depends upon certain routines from SPM. Thus, anyone who plans on doing analysis with mrVista should have a copy of SPM in their Matlab path to ensure that those functions can be found. The version of SPM used by the mrVista code is SPM5. Visit the SPM page for information regarding downloading SPM5 and adding the directory to your matlab path.
SPM is an academic software toolkit for the analysis of functional imaging data, for users familiar with the underlying statistical, mathematical and image processing concepts. For a more detailed introduction to SPM (by Friston) you can check out SPM's introduction page.
- Jump to FSL Page
For general info regarding FSL and FSL tools, including download and install instructions, you can visit the FSL website. Here we will just mention, for those who don't know, that FSL is a comprehensive library of analysis tools for FMRI, MRI and DTI brain imaging data. FSL is written mainly by members of the Analysis Group, FMRIB, Oxford, UK. FSL runs on Apple, PCs (Linux and Windows) and Sun, and is very easy to install. Most of the tools can be run both from the command line and as GUIs ("point-and-click" graphical user interfaces).
Our lab uses a variety of FSL tools to view files and process data. You can jump to the FSL page for information on getting FSL to run via the command line on the white network.
Some of the code included in mrVista can use certain processing algorithms from FreeSurfer. For example, we use FreeSurfer for aligning multiple subjects to the MNI template using the spherical methods advocated by Harvard, Wash. U. and BrainVoyager. We used this method for identifying common ROIs across the children in the DTI data set.
See the FreeSurfer page for installation instructions and examples of how we use their code.
Soon someone will describe external routine NFG and the Matlab hooks into it.
MRtrix provides a set of tools to perform diffusion-weighted MR white-matter tractography in a manner robust to crossing fibres, using constrained spherical deconvolution (CSD) and probabilistic streamlines. The MRtrix page describes how to install and use this package on lab machines using data in the VISTA laboratory.
- Jump to Troubleshooting Page
The Troubleshooting Page contains helpful information regarding compiling/mex issues, SPM, and dealing with software versions. Please visit the page if you're experiencing problems. If you've solved a problem, or have found a solution elsewhere please tap into your altruistic side and post it in the Troubleshooting Page.
- Jump to the Computer Help Page
The Computer Help Page provides more general computer advice about accessing linux boxes from other machines and other various tasks that make working with your computer a joy. This page is more specific to the Stanford setup. If you have some tips or have found something that has helped you setup your computer in such a way that you think would bring joy to others please post it on the Computer Help Page.
VISTA Code Center
Vistasoft validation functions exist to ensure that the integrity of the code base. There are three main reasons to use validation functions. First, if you have made changes to the code base and would like to commit your changes to the repository, we ask that you first run all validation functions. This will reduce the likelihood of introducing bugs in the code. Second, if you upgrade your computer environment (OS, Matlab version, etc), you may want to ensure that vistasoft code runs properly. Third, by periodically running the validation code, we hope to root out as many past bugs that slipped into the system as possible.\
This calls all the individual validation functions and generates a log file (optional input), which reports how the tests returned. We encourage programmers to add new validation scripts. The more code we validate the better.
The tests are all concentrated in the '/trunk/mrvTest/tests/' directory. To write tests for this framework, write an m-file, with a file-name that starts with `test`. A validation script should run in a few seconds (or 10s of seconds at most). This file will contain some calls to the function you are interested in testing. In addition to running through the code and making sure that it is syntactically sound, you can verify that the results make sense. This can be done by comparing the current run of the function with some kind of "ground truth" against which you would like to test. This can be data analyzed in a previous version, or on a different platform (sometimes referred to as regression testing). This can also take the form of a simple calculation, which is known to yield a particular result. To compare two results, you can use the various assert* functions. These functions return a failure, unless the assertion they are preforming is true.
A simple example is provided in `tests/test_Stats_fisherz.m`. This function tests the implementation of the Fisher Z transform, in mrLoadRet/Analysis/Stats/fisherz.m The first lines generate a set of random test data:
r = rand(1000);
The following lines use the function to calculate the Z transform in two different ways. One uses this implementation of the transform, while the other uses the Matlab built-in `atanh`:
z = fisherz(r); z_another_way = atanh(r);
These two should yield identical results, up to floating-point errors. Therefore, we assert their equality, with a tolerance for fp error:
assertAlmostEqual(z, z_another_way, 1e-10)
If the difference is smaller than 1e-10, this assertion will return true and the test will pass.
Another kind of test will rely on previous data from the vistadata repository. For example, look at tests/test_tSeries4D.m. This example changes the pwd to a directory in which there is data, so that the calls
vw = viewSet(vw, 'CurrentDataType', dataType); % Data type
%% Get time series from ROI: % Format returned is rows x cols x slices x time tSeries = tSeries4D(vw, scan, , 'usedefaults', ~isRawTSeries);
create a struct with some properties. These can then be compared to a previous calculation:
vFile = fullfile(mrvDataRootPath,'validate','tSeries4D'); storedTSeries = load(vFile);
Such that for example:
should return true.
For more details on specific bug fixes and updates to the code, check out the Recent Changes page.
If you are using mrVista and encounter a bug, please report it on the Bugs page. We keep track of this page, and will do our best to respond in a reasonable amount of time. We do ask that you check the Troubleshooting page to see if this is an issue with a known fix; and that you please follow the instructions on the Bugs page to report the bug.
Code Documentation (Using m2html)
We use m2html to create web-pages describing the Matlab functions.
m2html copies the comments at the top of each m-file and formats them nicely for HTML display. It also creates HTML files in a nice directory tree, with many links.
To create a manual, for any major directory branch you can follow these steps:
- Export the versioned SVN files into a separate directory.
- Clean this directory
- Run the m2html command
In this case the theNewManualDirectory directory will contain HTML files describing the yourCleanSVNDirectory directory.
Once the directory of HTML pages is created, we suggest you place it in
You may need sudo permission to do this.
Examples of three online manuals generated with m2html (and how to link there) are
* mrDiffusion * mrLoadRet * synapse
The m2html command is kept in the ISET-admin directory. It should probably be somewhere in the VISTASOFT area, too. You can download the package (which is not very large) from here.
We are starting to document some of the programming conventions we've used, including directory structure and data structures.
A list of mrVista cleaning projects that we are either doing or should be doing. Nothing interesting goes on this list - just housework.
This repository will be deprecated and replaced by individual repositories on github.
We are working on a number of local projects that have software, experiments and analyses under development. These projects are not ready for sharing. It is convenient, however, to maintain a repository version of the project code. The vistaproj repository used to contain the most recent code for these development projects. We are now trying to keep these on github. Because they are under active development, some of these are still kept as secure repositories.
Deprecated: VISTA Code Repositories (SVN)
For several years we used SVN rather than GIT. Starting in February, 2013 we shifted. We archive the Vistasoft SVN descriptions here, but these are no longer being updated.