Content-type: text/html
This program does post-processing of streamline output from track. It can either output streamlines or connection probability maps.
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 should be NIFTI-1 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^31 - 1 (the maximum representable by a signed 32-bit integer).
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.
The physical space of these images should be the same as the diffusion image from which the streamlines were generated.
These images should all share a consistent voxel space, but this shared space doesn't have to be the same as the underlying diffusion space. This means, for example, that you can use seed files of higher resolution than the diffusion data, and then produce results in the high-resolution space with this program.
Streamlines are tested against waypoints, targets etc pointwise, so it is important to ensure that the streamlines have sufficient spatial resolution for your needs. This is especially important for FACT tracking, where one point is placed in each voxel traversed by the streamline in the diffusion space, so the distance between points may be as large as the longest span across a voxel. If you perform further processing in a different voxel space, you should use the -resamplestepsize option to increase the streamline resolution.
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.
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.
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).
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 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. The seed point itself may count as one endpoint if it is inside a labeled region.
A streamline is retained if and only if:
1. It connects two different endpoint ROIs.
2. The segment connecting these two ROIs includes 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 connects 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.
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 -truncateinexclusion) 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.
The output is either the streamlines themselves, or connection probability images (these images may be processed further with imagestats).
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.
The -outputacm option takes all input streamlines and produces an image where each voxel contains the number of streamlines entering that voxel. If -outputcp is also specified, the values are divided by the total number of streamlines in the input. This output format is similar to that produced by FSL's probtrack.
The -outputacm option is named after the "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.
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.
If a target file is specified, the ACM is constructed as a target probability image, each target ROI is labeled by the number of streamlines entering the ROI.
Without -outputacm, or a target image, output is separately produced for each seed point.
The output is (using bash syntax):
${outputRoot}${region}_${seed point}_${pd}.{ext}
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.
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.
With a target image, output is
${outputRoot}_${region}_${seed point}_${pd}_0.{ext}
Either -outputcp or -outputsc may be specified with the target file. The default is -outputsc, which means results are not normalized by the total number of streamlines used to compose the image (which may vary from seed to seed due to filtering by waypoints etc).
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 -inputfile dt.nii.gz -inputmodel dt -outputroot cc_ -seedfile ccROI.nii.gz > cc.Bfloat
Apply an end point file cortex.nii.gz, which contains labeled cortical regions
procstreamlines -endpointfile cortex.nii.gz > corticalConnections.Bfloat
The output is now only tracts that connect two different cortical regions.
The tracts are read and written in physical space, the mapping between voxel and physical space is usually inferred from the input (eg a seed image), but if no input images are used, use -header to specify a reference image that has the same physical space as the diffusion data.
Streamlines that consist of fewer than minpoints will be discarded.
Streamlines are discarded if their length is less than minlength mm.
Streamlines that consist of more than maxpoints will be truncated to maxpoint in length. Specifying this option will automatically disable resampling of tracts.
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.
Output streamlines in raw binary format.
Although input and output of tracts is done in physical space, tracts are converted internally into voxel space for processing. This can introduce small deltas in the tract geometry. These precision errors are small but they might upset algorithms that look for exact pointwise correspondences.
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.