Getting started

[See associated video]

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

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
 TrackVis displays and saves .trk files in LPS orientation. After import, this
 function attempts to reorient the fibers to match the orientation of the
 original volume data.
 
  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 structure array [1 x nTracks]
       nPoints - # of points in each streamline
       matrix  - XYZ coordinates (in mm) and associated scalars [nPoints x 3+nScalars]
       props   - Properties of the whole tract (ex: length)
 
  Example:
     exDir           = '/path/to/along-tract-stats/example';
     subDir          = fullfile(exDir, 'subject1');
     trkPath         = fullfile(subDir, 'CST_L.trk');
     [header tracks] = trk_read(trkPath);
 
  Other m-files required: none
  Subfunctions: get_header
  MAT-files required: none
 
  See also: http://www.trackvis.org/docs/?subsect=fileformat
            http://github.com/johncolby/along-tract-stats/wiki/orientation

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_labs                   - Match fiber vertices to vertices on a prototype fiber
trk_add_sc                     - Attaches 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 streamline data between matrix and structure array
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                - 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 or other

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