Mesh

The code featured here involves the work of many people affiliated with 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 [http://www.gnu.org/copyleft/gpl.html 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 started using GIT, hosted on [http://github.com/vistalab the vistlab repository on github].

We distribute sample data sets (Vistadata). These are used in conjunction with the tutorial scripts in MrScripts. We store and distribute data for both MRI and Image Systems from our Stanford servers.

At this time, in collaboration with the Brainard lab, we are developing an [https://archiva.apache.org/index.cgi Archiva] system for downloading both MRI and Image Systems data from our server using Matlab scripts.

= VISTALAB Tools =

The following sections describe the code repositories developed by the VISTA lab. All repositories are hosted on [http://github.com/vistalab github].

== VISTASOFT ==

[https://github.com/vistalab/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:

*MrVista - fMRI tools *Anatomical Methods - Anatomical *MrDiffusion - DTI tools *MrScripts - Matlab scripts that illustrate the use of VISTASOFT functions

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 ([http://white.stanford.edu/newlm/index.php/Software#VISTASOFT_Required_Packages described below]).

Some of the repositories require external software to run (e.g., Matlab, SPM). Please see the [http://white.stanford.edu/newlm/index.php/Software#VISTASOFT_Required_Packages section below] for information about required software.

== VISTADISP ==

[https://github.com/vistalab/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 [http://www.psychtoolbox.org PsychToolbox].

== mrMesh ==

The github repository [https://github.com/vistalab/mrMesh 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.

== 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 [http://white.stanford.edu/trac/vistadata/browser ''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'''

*[http://white.stanford.edu/software/downloadsData/mrVistaGLMSession.zip Example Data set for GLM and Retinotopy Analyses] *[http://white.stanford.edu/software/downloadsData/mrDiffusion_sampleData.zip mrDiffusion sample dataset]

*[http://white.stanford.edu/software/downloadsData/mrMesh.zip Example Segmentation and Mesh files with Anatomy] *[http://white.stanford.edu/software/downloadsData/mrVistaPRFSession.zip Example PRF Session]

'''QUENCH'''

*[http://white.stanford.edu/software/downloadsData/CINCH_sampleData.zip QUENCH sample dataset]

= 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-Using), 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 [https://white.stanford.edu/repos/StanfordTools-DWI 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''' ==

Image:ITKGray.jpg

*ItkGray

ITKGray is a new segmentation tool developed by Bob Dougherty. ITKGray is a branch of the [http://www.itksnap.org/ ITKSnap] project. Bob added functionality from MrGray-Retired, including topology checking/fixing and a new flood-fill paintbrush that is similar to the MrGray-Retired 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. [http://www.itksnap.org/download/snap/files/py06nimg_bib.txt bibtex] | [http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?cmd=Retrieve&db=pubmed&dopt=Abstract&list_uids=16545965&query_hl=1&itool=pubmed_docsum pubmed] | [http://dx.doi.org/10.1016/j.neuroimage.2006.01.015 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''' == Image:Cinch-2.jpg

*'''QUENCH''' *'''QUENCH Tutorial'''

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 [http://white.stanford.edu/software 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 [http://graphics.stanford.edu/projects/dti/software/ dtiQuery] developed by [http://white.stanford.edu/Sherbondy.php Tony Sherbondy] and David Akers' in collaboration with our team. Visit [http://graphics.stanford.edu/projects/dti/software/ Dave Akers' site] where you will find the official version of CINCH.

== '''ConTrack''' ==

*Jump to the '''ConTrack'''

ConTrack is a probabilistic tracking algorithm developed by [http://white.stanford.edu/Sherbondy.php 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.

A paper describing the probabilistic ConTrack algorithm: Media:Sherbondy2008.pdf. 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''' ==

*Jump to the '''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.

= 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'''.

=== SPM ===

*Jump to SPM *[http://www.fil.ion.ucl.ac.uk/spm/software/spm5/ Download SPM5] (Non-VISTA Lab members)

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 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 [http://www.fil.ion.ucl.ac.uk/spm/doc/intro/ SPM's introduction page].

== Optional Packages ==

=== FSL ===

*Jump to '''FSL'''

For general info regarding FSL and FSL tools, including download and install instructions, you can visit the [http://www.fmrib.ox.ac.uk/fsl/ 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 for information on getting FSL to run via the command line on the white network.

=== FreeSurfer ===

*Jump to FreeSurfer *[http://surfer.nmr.mgh.harvard.edu/ FreeSurfer home page] (Non-VISTA Lab members)

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.

=== 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 =

*Jump to '''Troubleshooting'''

The Troubleshooting 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.

=== Computer Help ===

*Jump to the '''Computer Help'''

The Computer Help 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.

= VISTA Code Center =

== Code validation ==

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 [http://www.mathworks.com/matlabcentral/fileexchange/22846 matlab_xunit] as a [http://en.wikipedia.org/wiki/Unit_testing 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 [http://en.wikipedia.org/wiki/Regression_testing 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 ===

[http://www.agiledata.org/essays/tdd.html Try writing the test for your code before you start writing the actual code].

== Recent Changes & Bugs ==

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.

== Programming 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 [http://www.artefact.tk/software/matlab/m2html/ here.]

== MrVista 1 conventions ==

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 [http://tinyurl.com/h4lpm basics of using MATLAB].

We are starting to document MrVista 1 conventions.

== MrVista TODO ==

A MrVista TODO that we are either doing or should be doing. Nothing interesting goes on this list - just housework.