Getting started

Check your paths

Once you’ve downloaded along-tract-stats and set up your MATLAB path as described in the README, the first thing to do is to check that the path setup is actually working.

First check that MATLAB can find the FSL tool to load MRI volumes:

help read_avw

Output:

 [img, dims,scales,bpp,endian] = READ_AVW(fname)
 
   Read in an Analyze or nifti file into either a 3D or 4D
   array (depending on the header information)
   fname is the filename (must be inside single quotes)
   Note: automatically detects - unsigned char, short, long, float
          double and complex formats
   Extracts the 4 dimensions (dims), 
   4 scales (scales) and bytes per pixel (bpp) for voxels 
   contained in the Analyze or nifti header file (fname)
   Also returns endian = 'l' for little-endian or 'b' for big-endian
 
   See also: save_avw

If that fails, it probably means that the system environment your MATLAB session is running in can’t see the FSL tools. You’ll need to execute the following at the MATLAB prompt, or stick it in a startup.m file. (Adjust the path if your FSL got installed somewhere else)

setenv('FSLDIR', '/usr/local/fsl')

Now check that MATLAB can find the along-tract-stats tool to load in TrackVis tract groups:

help trk_read

Output:

 TRK_READ - Load TrackVis .trk files
 
  Syntax: [header,tracks] = trk_read(filePath)
 
  Inputs:
     filePath - Full path to .trk file [char]
 
  Outputs:
     header - Header information from .trk file [struc]
     tracks - Track data struc array [1 x nTracks]
       nPoints - # of points in each track
       matrix  - XYZ coordinates and associated scalars [nPoints x 3+nScalars]
       props   - Properties of the whole tract
 
  Other m-files required: none
  Subfunctions: get_header
  MAT-files required: none
 
  See also: http://www.trackvis.org/docs/?subsect=fileformat

Explore the included tools

Once your path is set up correctly, it is useful to do a bit of exploring to see what is included. The names of all of the included MATLAB functions will start with trk.... This makes it easy to get a quick function list:

lookfor trk

Output:

trk_add_sc                     - Adds a scalar value to each vertex in a .trk track group
trk_compile_data               - Compiles along-tract data for subjects/hemispheres/tracts
trk_flip                       - Flip the ordering of tracks
trk_interp                     - Interpolate tracks with cubic B-splines
trk_length                     - Calculate the lengths of tracks
trk_mean_sc                    - Calculate the mean scalar along a track
trk_plot                       - 3D plot of TrackVis .trk track group
trk_read                       - Load TrackVis .trk files
trk_restruc                    - Restrucutres track data between matrix and strucutre array forms
trk_stats                      - Compute intensity statistics about a volume within a track group
trk_stats_overlay              - Overlay stats on an example subject's mean tract geometry
trk_stats_quick                - TRK_STATS - Compute intensity statistics about a volume within a track group
trk_write                      - Write TrackVis .trk files
trk_write_ascii                - Save a tract group in an ascii format for use in R

If you’re using the matlab GUI, you can then click on the names of the individual tools to quickly get more information about them. Alternatively, you can use the standard help <command_name> syntax like we did before.

I try to use a consistent header format, so when you ask for help on a command, you can expect to see these things:

• An expanded description of the function
• Syntax description
• Inputs (with class and dimensions)
• Outputs
• Example usage