Skip to content

Software overview

Jump to bottom Edit New page
Jonathan Winawer edited this page Aug 30, 2016 · 25 revisions

The Vistalab Software Tools described here involves the work of many people who came through the Wandell lab. We continue to work on revisions, improvements and 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.

We use git to manage the code, as hosted on the vistlab repository on github.

We distribute sample data sets using the Remote Data Toolbox by Ben Heasley. These are used in conjunction with the tutorial scripts in Tutorials and mrTest.

At this time, in collaboration with the Brainard lab, we are developing an Archiva system for downloading both MRI and Image Systems data from our server using Matlab scripts.

  1. VISTALAB Tools
The following sections describe the code repositories developed by the VISTA lab. All repositories are hosted on github.
    1. VISTASOFT
VISTASOFT is the main software repository for the VISTALAB tools. The repository includes methods for processing anatomical, functional, and diffusion tensor imaging data. The software is written mainly in Matlab. The VISTASOFT package contains a variety of tools. Tutorials for some of these tools can be found on these pages: We also maintain various additional repositories for experimental control and specialized 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).

Some of the repositories require external software to run (e.g., Matlab, SPM). Please see the section below for information about required software.

    1. VISTADISP
Vistadisp is a toolbox of experimental control and display software. 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.
    1. mrMesh
The github repository mrMesh contains the source code and compiled versions of MrMesh, related mex files (build mesh, smooth mesh and curvature), and an older version of QUENCH.
    1. 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.

    1. VISTASOFT
    1. QUENCH
    1. 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.)

    1. ITKGray
250px 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.

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

    1. QUENCH
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.

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

Table of Contents

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.

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

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

Configuring your software environment

There are many ways a user can configure their environment for Matlab and related programs and files. Here we make a recommendation for Mac users.

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





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 




 * [http://white.stanford.edu/manuals/mrDiffusion/mrDiffusion mrDiffusion]
 * [http://white.stanford.edu/manuals/mrLoadRet/mrLoadRet mrLoadRet]
 * [http://white.stanford.edu/manuals/synapse/synapse 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.

              


              

                
                   Add a custom footer
              

          



  
          

            

              

                

                  

                      
                        
                      
                    

                  

                

              


            
Clone this wiki locally