Content-type: text/html Manpage of track

track

Section: User Commands (1)
Index Return to Main Contents

 

NAME

procstreamlines - Process streamline data

 

SYNOPSIS

procstreamlines [options]

 

DESCRIPTION

This program does post-processing of streamline output from track. It can either output streamlines or connection probability maps.

 

SEEDS, WAYPOINTS, EXCLUSION ROIS, ENDPOINT ROIS AND TARGETS

The seed file, the waypoint file, the exclusion file, the endpoint file and the target file determine where streamlines start, where they may go, where they may not go, and how they are interpreted as connection probabilities.

All of these files are Analyze / NIFTI-1 / ITK images of the same dimension as the seed file. They may have any data type, but should be integer valued, and the maximum value in these files must not exceed 2^15 - 1 (the maximum representable by 16-bit signed short).

Voxels that share the same positive intensity are considered part of the same ROI, they do not have to be contiguous. Voxels that are zero or negative are considered background.

Each type of file is explained in more detail below.

 

SEED FILE

The seed file contains the regions of interest for tracking. Streamlines are seeded at the centre of all voxels with an intensity greater than zero.

 

WAYPOINT FILE

The waypoint file constrains streamlines to pass through certain volumes within the image. Waypoints are defined in the same way as ROIs, each intensity value (apart from zero) defines a different waypoint. Streamlines will be discarded unless they intersect one or more voxels in each waypoint.

 

EXCLUSION FILE

The exclusion file constrains streamlines to not pass through any volume marked with an intensity greater than zero. Streamlines that enter such regions will be discarded (default) or truncated (with -truncateinexclusion).

 

TARGET FILE

The target file is only used for PICo connection probability calculation. For PICo tracking without a target image, the output is the connection probability of each voxel to the seed, which is the fraction of streamlines that intersect the voxel. With targets, the connection probability to all voxels in the target is the fraction of streamlines that intersect any voxel in the target. For example, if the thalamus is segmented in the target image, then the connection probability to all voxels in the thalamus would be the fraction of streamlines that connect to anywhere in the thalamus. If we wanted to know the distribution of connections within the thalamus, we would pass the thalamus segmentation as a waypoint file but we would not use a target image. Then the output would be a connection probability to all voxels in the image, but only streamlines that connect to the thalamus would be used in the probability calculation.

 

ENDPOINT FILE

Endpoint ROIs have some properties of waypoints and some properties of exclusion ROIs. If an endpoint ROI image is supplied with the -endpointfile option, the program outputs only the streamlines that project from the seed point to two distinct endpoint ROIs. A streamline is discarded if it does not connect to two different endpoint ROIs, one on each side of the seed point. If the streamline does connect to two different endpoint ROIs, then it is truncated. The output is the shortest section of the streamline that connects two endpoint ROIs and includes the seed point.

The major differences between using end zones and a combination of exclusion / waypoints are:


  1. All waypoints must be intersected but only two endpoint ROIs must be intersected. 


  2. The section of streamline that intersects the endpoint ROIs must include the seed point. 
     With waypoints, any portion of the streamline may intersect the waypoint. 


  3. If the seed point is within an exclusion ROI, the streamline is truncated or excluded. If
     the seed point is within an endpoint ROI, the streamline is truncated only when it intersects
     another endpoint ROI.

 

ORDER OF PROCESSING

The program performs the various operations on each input streamline in the following order:


 * The streamline is truncated to the maximum length, if specified.
 * Exclusion ROIs are applied.
 * Waypoints are applied.
 * Endpoint ROIs are applied.

The streamline may be discarded if it does not connect end points, does not intersect waypoints, or enters an exclusion ROI. It may be truncated if it enters an exclusion ROI (with -discardinexclusion) or if it extends beyond the endpoint ROIs.

If the streamline is not discarded, then it is sent to the output or used to construct a PICo connectivity map.

Any operation that discards or truncates streamlines modify the PICo connection probabilities. Streamlines that are discarded do not figure in the calculation of connection probability. For example, if we seed 1000 streamlines and then discard 100 that do not enter all waypoints, the connection probability of each voxel to the seed is (number of streamlines entering voxel) / 900.

 

CONNECTIVITY BASED SEGMENTATION

With the -outputbs option and a target file, the program calculates the connection probability to each target region and labels the seed point with the target that has the highest connection probability.

 

OUTPUT

The output is either the streamlines themselves, or connection probability images (these images may be processed further with cpstats).

Streamline output is identical to that from track; see the options for streamline output in track(1). If a seed file and an outputroot are specified, output is segregated by region of interest. That is, streamlines from all seed points with the same label are grouped together. Otherwise, output is to a single file or to stdout.

 

OUTPUT OF CONNECTION PROBABILITY IMAGES

With the option -outputcp or -outputsc and without target regions, the output is (using bash syntax):


   ${outputRoot}${region}_${seed point}_${pd}.{hdr, img}

Where the region is the numerical index of the ROI in the seed file, the seed points are numbered from 1 in the order in which they are processed by track, and the pd is the principal direction that the streamlines follow at the seed point. If there are P principal directions at each seed point, then a separate image is generated for pd 1 through P. The data type of the images is 32-bit float.

If -outputsc is specified, then the output contains raw streamline counts, ie the number of streamlines that enter each voxel. If -outputcp is specified, the streamline counts are normalized by the total number of streamlines. The data type of the images is 32-bit int.

                                                
 

OUTPUT OF TARGET CONNECTION PROBABILITY IMAGES

When a target file is present and -directional is not specified, the output is


   ${outputRoot}_${region}_${seed point}_${pd}_0.{hdr, img}

If -directional is specified, then two probability maps are created. Streamlines are divided into two at the seed point. The streamline segments that proceed from the seed point at an acute angle to the given direction are used to compute one set of connection probabilities (labelled 0) and the segments that proceed at an obtuse angle to the direction areused to connect the other set of connection probabilities (labelled 1, see EXAMPLES). The output is then


   ${outputRoot}_${region}_${seed point}_${pd}_{0,1}.{hdr, img}

Either -outputcp or -outputsc may be specified with the target file. The default is -outputsc.

 

OUTPUT OF CONNECTIVITY BASED SEGMENTATION

As with target probabilities, the output of connectivity based segmentation has twice as many components if -directional is specified. There is one output per ROI, rather than one per seed. If any seed point contains multiple principal directions, then one set of output is generated for each principal direction.

The image


   ${outputRoot}_labels_${region}_${pd}_0.{hdr, img}

is always produced, and is an Analyze image of data type short. Each voxel in the seed region is labelled with the target that has the highest connection probability to the seed. If -directional is specified, there are separate labels for each direction:


   ${outputRoot}_labels_${region}_${pd}_{0,1}.{hdr, img}

With the -outputcp option, the program also outputs


   ${outputRoot}_labelcp_${region}_${pd}_{0,1}.{hdr, img}

which contains the seed region labelled with the connection probabilities to the target region that the seed point is labelled with in the labels image. If -outputcp is not specified, or -outputsc is specified, then the program outputs


   ${outputRoot}_labelsc_${region}_${pd}_{0,1}.{hdr, img}

 

OUTPUT OF ANATOMICAL CONNECTIVITY MAPS

The -outputacm option may be used to create an "anatomical connectivity map" (ACM) (Embleton et al, Proc ISMRM 2007, 1548). To build an ACM, seed tractography at every voxel in brain gray / white matter, then run procstreamlines with this option.

The -outputacm option may be used with any ROI. It combines all streamlines in the input into a single connection probability image. The output is an Analyze image where each voxel contains the number of streamlines that enter the voxel. If -outputcp is also specified, the values are divided by the total number of streamlines in the input.

Because the ACM combines all streamlines into a single image, it is not necessary to specify the seed points or the number of iterations, and it is fine to process the input streamlines multiple times by calling procstreamlines with different options.

 

EXAMPLES

Track all fibres from an ROI drawn by hand on the mid-sagittal plane. The ROI contains corpus callosum fibres at the mid-sagittal plane.

track -inputmodel pico -outputroot cc_ -seedfile ccROI.Bshort -iterations 5000 -interpolate -outputtracts voxels < brain.bingham.Bdouble

This produces the output

cc_1.Bshort

We can then process these images to produce connection probability images for each seed point:

procstreamlines -outputroot cc_cp -seedfile ccROI.Bshort -iterations 5000 -inputmodel voxels
 -outputcp < cc_1.Bshort

This produces connection probability maps for each seed point.

Using the same streamlines, do connectivity based segmentation of the corpus callosum. Because we tracked from the midsagittal plane, the fibres proceed from the seed points to both the left and right hemispheres. By using the option -directional -1 0 0 we split the streamlines into two and produce separate results for connectivity to the left and right hemispheres:

procstreamlines -outputroot cc_cbs -outputcbs -seedfile ccROI.Bshort -targetfile targets
 -iterations 5000 -directional -1 0 0 -outputcp -inputmodel voxels < cc_1.Bshort

cc_cbs_labelcp_1_1_0.{hdr,img} contains connection probabilities to targets in the left hemisphere, and cc_cbs_labelcp_1_1_1.{hdr,img} contains connection probabilities to targets in the right hemisphere.

Streamline-to-streamline processing requires the fewest options.

procstreamlines -outputtracts voxels -waypointfile waypoints -outputroot cc_waypoints < cc_1.Bshort

 

PROCESSING MULTIPLE ROIS

By default, procstreamlines expects all ROIs in the seed file to be processed at once. Individual regions may be processed by specifying the -regionindex option. For example:

As in the example in track(1), let subA2ROI.img contain two ROIs, the first defined by voxels with intensity 1, the second by voxels with intensity 2.

track -inputmodel dt -seedfile subA2ROI -outputroot A_oneDT_ < A.picopdfs.Bdouble

We can process both ROIs together:

cat A_oneDT_1.Bfloat A_oneDT_2.Bfloat | procstreamlines -outputroot A_twoROI_ -outputtracts raw -waypointfile subA2ROI

or separately:

cat A_oneDT_1.Bfloat | procstreamlines -outputroot A_twoROI_ -outputtracts raw -waypointfile subA2ROI -regionindex 1

cat A_oneDT_2.Bfloat | procstreamlines -outputroot A_twoROI_ -outputtracts raw -waypointfile subA2ROI -regionindex 2

 

OPTIONS

The following list details the options pertaining to the input data, the tractography parameters, the output, and the PICo parameters.

 

DATA OPTIONS

-inputmodel <model>
One of the following:


  raw - raw streamline data (default).
  voxels - voxel lists.

-datadims <x> <y> <z>
The x, y, and z dimension of the data, in voxels. Not required if a seed, exclusion, waypoint or target file is given.

-voxeldims <x> <y> <z>
The x, y, and z dimension of each voxel, in millimetres. Not required if a seed, exclusion, waypoint or target file is given.

-mintractpoints <minpoints>

Streamlines that consist of fewer than minpoints will be discarded.

-mintractlength <minlength>

Streamlines are discarded if their length is less than minlength mm.

-maxtractpoints <maxpoints>

Streamlines that consist of more than maxpoints will be truncated to maxpoint in length. Specifying this option will automatically disable resampling of tracts.

-maxtractlength <maxlength>

Streamlines longer than maxlength mm will be truncated. This calculation is done before resampling, so the truncation is accurate to the original resolution of the tract.

 

SEED OPTIONS

-seedpointmm <x> <y> <z>
The coordinates of a single seed point for tractography, in mm.

-seedpointvox <x> <y> <z>
The voxel coordinates of a single seed point for tractography. Tracking will proceed from the centre of voxel (x,,y,x,z). This option overrides -seedpointmm. The voxel indices are numbered from 0 to (data dimension) - 1.

-seedfile <file.[hdr | nii | mha | mhd]>
Image containing seed points. If an output root is specified, the output is grouped according to the intensity of the seed in this image. This option overrides -seedpointvox and -seedpointmm.

-regionindex <index>
Process the specified region in the seed file.

 

OTHER OPTIONS

-iterations
Number of streamlines generated for each seed. Not required when outputting streamlines, but needed to create PICo images. The default is 1 if the output is streamlines, and 5000 if the output is connection probability images.

-targetfile <file>
Image containing target volumes. Targets are defined as regions of the image with the same intensity. If this option is given, the PICo maps will only localise connection probability to the volumes bounded by the targets. The connection probability to a target from a seed is the fraction of streamlines that pass anywhere within the target volume.

-allowmultitargets
Allows streamlines to connect to multiple target volumes. By default, the program only counts the first entry to a target volume.

-directional <X> <Y> <Z>
Splits the streamlines at the seed point and computes separate connection probabilities for each segment. Streamline segments are grouped according to their dot product with the vector (X, Y, Z). The ideal vector will be tangential to the streamline trajectory at the seed, such that the streamline projects from the seed along (X, Y, Z) and -(X, Y, Z). However, it is only necessary for the streamline trajectory to not be orthogonal to (X, Y, Z).

-waypointfile <file.[hdr | nii | mha | mhd]>
Image containing waypoints. Waypoints are defined as regions of the image with the same intensity, where 0 is background and any value > 0 is a waypoint. Streamlines are discarded if they do not pass through at least one voxel of each waypoint volume.

-truncateloops
This option allows streamlines to enter a waypoint exactly once. After the streamline leaves the waypoint, it is truncated upon a second entry to the waypoint. For the purposes of this operation, the streamline is divided into two segments at the seed point. Each segment is allowed to enter each waypoint once and the segment is truncated at a second entry.

-discardloops
This option allows streamlines to enter a waypoint exactly once. After the streamline leaves the waypoint, the entire streamline is discarded upon a second entry to the waypoint. For the purposes of this operation, the streamline is divided into two segments at the seed point. Each segment is allowed to enter each waypoint once and the entire streamline is discarded if either segment enters a waypoint twice.

-exclusionfile <file.[hdr | nii | mha | mhd]>
Image containing exclusion ROIs. This should be an Analyze 7.5 header / image file.hdr and file.img. By default, exclusion ROIs are treated as anti-waypoints - streamlines that enter any exclusion ROI are discarded. if the -truncateinexclusion option is given, streamlines are truncated upon entry to an exclusion ROI, but not discarded.

-truncateinexclusion
Retain segments of a streamline before entry to an exclusion ROI. If this is not specified, streamlines that enter an exclusion ROI are discarded.

-endpointfile <file.[hdr | nii | mha | mhd]>
Image containing endpoint ROIs. This should be an Analyze 7.5 header / image file.hdr and file.img. Endpoint ROIs are defined as regions of the image with the same intensity, where 0 is background and any value > 0 is an endpoint ROI. Streamlines are discarded if they do not connect two different endpoint ROIs.

-resamplestepsize <size>
Each point on a streamline is tested for entry into target, exclusion or waypoint volumes. If the length between points on a tract is not much smaller than the voxel length, then streamlines may pass through part of a voxel without being counted. To avoid this, the program resamples streamlines such that the step size is one tenth of the smallest voxel dimension in the image. This increases the size of raw or oogl streamline output and incurs some performance penalty. The resample resolution can be controlled with this option or disabled altogether by passing a negative step size or by passing the -noresample option.

-noresample
Disables resampling of input streamlines. Resampling is automatically disabled if the input model is voxels.

 

OUTPUT OPTIONS

-gzip
Compress output using the gzip algorithm.

-outputtracts <format>

Output streamlines, in one of the following formats: raw binary, voxels, or oogl. If neither -outputtracts nor -outputcp is specified, the default is to output raw tracts.

-outputcp
Output the connection probability map for each seed. The map is an Analyze image with data type float. If targets are specified, then the image values in each target voxel are the fraction of streamlines that connect to that target. Without targets, the image is the fraction of streamlines that connect to each voxel.

-outputsc
Output the connection probability map for each seed. The output is the same as with -outputcp except that the values are not normalized, so the image contains the raw streamline counts. The map is an Analyze image with data type int.

-outputacm
Combine all tracts in the input into a single connection probability map. Outputs a single Analyze image where each voxel contains the number of streamlines that enter the voxel. If -outputcp is also specified, the values are divided by the total number of streamlines in the input.

-outputcbs
Perform connectivity based segmentation. This option produces outputs. The first is
 an image where each seed point in the ROI is labelled with the value of the target  to which the seed is most likely to connect. The second is an image where each seed point is labelled with the streamline count (default) or connection probability (if -outputcp is also specified) to the labelled target. A target file is required for this option.

-outputroot <string>
Prepended onto all output file names. If the output is streamlines, then using this option tells the program to separate streamlines by ROI. See track(1).

 

AUTHORS

Philip Cook <camino@cs.ucl.ac.uk>

 

SEE ALSO

track(1), cpstats(1), vtkstreamlines(1)

 

BUGS

Note that you cannot filter streamlines and output to the same file with a command like


  cat streamlines.Bfloat | procstreamlines [args] > streamlines.Bfloat

If you do this, the streamlines file will be lost.


 

Index

NAME
SYNOPSIS
DESCRIPTION
SEEDS, WAYPOINTS, EXCLUSION ROIS, ENDPOINT ROIS AND TARGETS
SEED FILE
WAYPOINT FILE
EXCLUSION FILE
TARGET FILE
ENDPOINT FILE
ORDER OF PROCESSING
CONNECTIVITY BASED SEGMENTATION
OUTPUT
OUTPUT OF CONNECTION PROBABILITY IMAGES
OUTPUT OF TARGET CONNECTION PROBABILITY IMAGES
OUTPUT OF CONNECTIVITY BASED SEGMENTATION
OUTPUT OF ANATOMICAL CONNECTIVITY MAPS
EXAMPLES
PROCESSING MULTIPLE ROIS
OPTIONS
DATA OPTIONS
SEED OPTIONS
OTHER OPTIONS
OUTPUT OPTIONS
AUTHORS
SEE ALSO
BUGS

This document was created by man2html, using the manual pages.
Time: 02:06:54 GMT, December 10, 2011