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 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.
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. 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.
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.
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.
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.
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.
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.
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}
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.
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
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
The following list details the options pertaining to the input data, the tractography parameters, the output, and the PICo parameters.
raw - raw streamline data (default).
voxels - voxel lists.
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 one of the following formats: raw binary, voxels, or oogl. If neither -outputtracts nor -outputcp is specified, the default is to output raw tracts.
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.