Software

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.

We are starting to build virtual machines to distribute the full working environment.


Contents

VISTA REPOSITORIES

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

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 major sections:

Other directories are present, too.

There are some additional utilities written in C++/VTK. We run this software routinely on Linux and Apple computers. We used to run it routinely on Windows 7, but no longer .

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 please visit the Matlab page.

    Get VISTASOFT

    GIT
    Recommended for local users and those who want to contribute code or simply keep their software up to date. If you need help getting started using Git, have a look at the GIT page.

     # Repo URL: 
     http://github.com/vistalab
    # Linux Checkout Command: git clone http://github.com/vistalab/vistasoft.git

    DOWNLOAD ZIP

    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.

VISTATEST

To validate installs and generally test the reliability of our software, we use a unit testing framework. The unit testing scripts are installed in the VISTATEST repository on github.

To run the unit testing you must also installed the data used for testing. These are too large to install on github, so we keep them in the svn repository, VISTADATA. To download the data, please use

    Get VISTADATA

    SVN

     # Repo URL: 
     https://white.stanford.edu/repos/vistadata
    # Linux Checkout Command: svn checkout https://white.stanford.edu/repos/vistadata

    DOWNLOAD

    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.

    LOCAL USE
    Within the VISTA LAB there is no need to checkout a version because we maintain one checked-out copy of the vistadata in:

    /white/local/vistadata
    

There are some issues running the testing on Windows machine. In particular, running the vistatest code changes the repository. We know how to put it back into its original state on Linux and Mac, but not on Windows. So, if you run the test multiple times and you use a Windows machine, please reset the repository each time you run the unit test.

VISTAPROJ

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.

    Get VISTAPROJ

    NOTE: 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.
    SVN

     # 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 
    

VISTADISP

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.

    Get VISTADISP

    GIT

     # Repo URL: 
     http://github.com/vistalab/vistadisp
    # Linux Checkout Command: git clone https://github.com/vistalab/vistadisp.git

    DOWNLOAD

    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.


VISTASRC

VISTASRC is a repository containing the source code and compiled versions of mrMesh, related mex files (build mesh, smooth mesh and curvature), and an older version of QUENCH.

    Get VISTASRC

    SVN

     # Repo URL: 
      https://white.stanford.edu/repos/vistasrc 
    # Linux Checkout Command: svn co https://white.stanford.edu/repos/vistasrc

    DOWNLOAD

    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

VISTADWI (aka StanfordTools-DWI) is a repository containing only the source code for certain VISTA executables:

    Get VISTADWI

    SVN

     # Repo URL: 
      https://white.stanford.edu/repos/StanfordTools-DWI/ 
    # Linux checkout command: svn co https://white.stanford.edu/repos/StanfordTools-DWI/

    DOWNLOAD

    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

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.

    Get AFQ

    GIT

     # Repo URL: 
     https://github.com/jyeatman/AFQ
    # Linux Checkout Command: git clone https://github.com/jyeatman/AFQ.git

    DOWNLOAD

VISTADATA

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.

VISTASOFT

QUENCH



VISTA Executables

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

(The program CINCH has been superceded by QUENCH. They have similar features and some of the CINCH pages are still used to describe QUENCH.)

ITKGray

ITKGray Interface
Enlarge
ITKGray Interface

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.

DTIQUERY

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

CINCH Interface
Enlarge
CINCH Interface

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.

Download QUENCH from the Software page. You can download the QUENCH sample data set from that page. Or you can download the vistadata repository and use the data in the QUENCH folder.

QUENCH integrates CINCH and dtiQuery developed by Tony Sherbondy and David Akers' in collaboration with our team. Visit Dave Akers' site where you will find the official version of CINCH.

ConTrack

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.

A paper describing the probabilistic ConTrack algorithm: Sherbondy et al 2008. We have used the method in a number of our other publications - as have others. (Links here).

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).

MicroTrack

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.

NIMS

Neurobiological image management system

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.

External Software

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.

Matlab

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.

SPM

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 SPM8. Visit the SPM page for information regarding downloading SPM8 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.

Optional Packages

FSL

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.

FreeSurfer

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.

Numerical Fiber Generator (NFG)

Soon someone will describe external routine NFG and the Matlab hooks into it.

MRtrix

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.

Troubleshooting

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.

Computer Help

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

Code validation/testing

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.\

We use matlab_xunit as a unit testing framework. There are a number of individual validation functions. The simplest way to use them is to call them all via a single master script by issuing:

mrvTest

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.

How to write tests

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.

Examples

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:

assertEqual(storedTSeries.dim, size(tSeries));

should return true.

Advanced usage

Try writing the test for your code before you start writing the actual code.

Code Updates & Bug Reports

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
m2html('mfiles','yourCleanSVNDirectory', 'htmldir','theNewManualDirectory','recursive','on','source','off');

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

/u/websk/docs/manual

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.

Programming Practices

mrVista is open software, so we encourage users to modify the code if they see fit. However, you should first be familiar with all of the basics of using MATLAB.

We are starting to document some of the programming conventions we've used, including directory structure and data structures.

mrVista TODO

A list of mrVista cleaning projects that we are either doing or should be doing. Nothing interesting goes on this list - just housework.

Deprecated: VISTAPROJ

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.