-
Notifications
You must be signed in to change notification settings - Fork 142
Software overview
The Vistalab Software Tools are the work of many people who came through the Wandell lab. We continue to work on revisions, improvements and bug fixes.
In addition to using github to manage and share the code, we distribute sample data sets using the Remote Data Toolbox. These data are used in conjunction with the tutorial scripts Tutorials and validation scripts [mrTest].
Unless otherwise noted, our code is released under the GPL. The authors of the code (usually noted in the comments of each source file) retain all copyrights.
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:
- MrVista - fMRI tools
- Anatomical Methods|MrAnatomy - Anatomical
- MrDiffusion - DTI tools
- MrScripts - Matlab scripts that illustrate the use of VISTASOFT functions
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.
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.
We are using the Remote Data Toolbox to store and retrieve sample data as well as data used for software validation.
These are older links, which will be deprecated. We will also place the RDT links here:
- Example Data for GLM and Retinotopy Analyses
- mrDiffusion sample dataset
- Example Anatomical Segmentation and Mesh files
- Example PRF Session
- QUENCH sample dataset
In addition to the Matlab code for MrVista, we have a series of executables that help us to segment gray from white (ITKSnap), generate fiber tracks (ConTrack), and visualize and measure properties of fiber tracks (QUENCH).
The source code for these projects 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.)
ITKSnap is a segmentation tool which we sometimes use to clean up the output of FreeSurfer's autosegmentation algorithm. If you use ITKSnap please consider using 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.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.
- Jump to 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).
* Jump to the '''[[MicroTrack|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.
* Jump to '''[[Troubleshooting|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.
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](http://www.mathworks.com/matlabcentral/fileexchange/22846) as a [unit](http://en.wikipedia.org/wiki/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.
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
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.
Try writing the test for your code before you start writing the actual code.
If you are using mrVista and encounter a bug, please report it on the github Issues 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 Issues to see if this is an issue with a known fix.
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.
Examples of three online manuals generated with m2html (and how to link there) are
* [mrDiffusion](http://white.stanford.edu/manuals/mrDiffusion/mrDiffusion ) * [mrLoadRet](http://white.stanford.edu/manuals/mrLoadRet/mrLoadRet )
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](http://www.artefact.tk/software/matlab/m2html/).
- Vistasoft
- Getting Started
- mrVista Overview
- Anatomy
- Functional MRI
- mrVista
- Retinotopy tutorial
- Population RF methods also prf Model, prf_tutorial, prf tutorial
- Diffusion weighted MRI
- Visualization
- Tractography
- Tutorials
- Software overview