[Camino-users] New tractography code in r1160

[Philip A Cook]

Hi,

I've committed some substantial changes to the track command in r 1160. 


NEW FEATURES

Some of the new features are truly new (such as Runge-Kutta stepping algorithm), others were available in some instances but can now be applied more flexibly. The choice of tracking algorithm and interpolation have been decoupled from each other and from the type of input data, giving you more choices in how to generate the streamlines.


    Tracking algorithms

You can now track with FACT, Euler, or RK4 stepping algorithms. The choice is controlled by the option -tracker. The default is fact, as before.


    Interpolation

Choose linear vector interpolation, nearest neighbour interpolation, probabilistic nearest neighbour, or TEND with -interpolator. You can also interpolate DWI data and fit diffusion tensors to the interpolated data as you track.

Nearest neighbour interpolation is new. Now you can evenly sample points along a path even if you don't want to deal with interpolation. It's also the default option.


    Curvature thresholds

Specify both the maximum allowed curvature (-curvethresh) and the distance over which you want to test (-curveinterval). The new default is to stop if there is curvature of more than 90 degrees over 5mm intervals. The old curvature checking can be closely approximated with -curvethresh 80 -curveinterval Z, where Z is the slice thickness of your data.


    Using different trackers and different interpolation with all available images

Use any combination of interpolators and trackers should work with any input model, within reason. Obviously TEND isn't going to work unless you have tensors data. But you have more choices than before. Probabilistic trackers no longer force use of probabilistic nearest neighbour, for example, you can use linear interpolation if you want.



BACKWARDS COMPATIBILITY

Backwards compatibility is mostly preserved, though scripts might need some updating. 

The one thing that is most different is FACT tracking. I've done internal refactoring to make the code more reliably consistent in how it generates tracks, so that the user's choice of stepping algorithm really only affects the size and orientation of each step, and nothing else. In doing this I had to accept some small diffs in FACT tracking. The results are similar, but not identical.

The difference arises from how we handle tracking close to a voxel boundary. Because FACT defines each step as the distance to the voxel boundary, it's possible to get almost stuck as the tracker goes back and forth. We resolve this by slightly increasing the step size when this happens. The basic idea is the same between the old and new code, but implemented slightly differently so results will not be identical.

Backwards compatibility for interpolated (Euler) tracking is more preserved. The following commands with old / new Camino should produce the same results:

  camino_new/bin/track -inputmodel pico -inputfile camino_new/test/tracking/torus/torus_06.bingham.Bdouble.gz -randomseed 1880 -iterations 1000 -seedfile camino_new/test/tracking/torus/rois/torus_single_seed.nii.gz -tracker euler -stepsize 0.5 -interpolator prob_nn -curvethresh 80 -curveinterval 2 | vtkstreamlines -outputfile new.vtk

  camino_old/bin/track -inputmodel pico -inputfile camino_new/test/tracking/torus/torus_06.bingham.Bdouble.gz -randomseed 1880 -iterations 1000 -seedfile camino_new/test/tracking/torus/rois/torus_single_seed.nii.gz -tracker euler -stepsize 0.5 -interpolated | vtkstreamlines -outputfile old.vtk

There might be some circumstances where the tracts will not be identical, because of changes in how we handle the curvature threshold, but the tracking and connectivity maps I've looked at appear to be the same for interpolated tracking.


    Converting existing command lines

A few things now need to be set explicitly

    -iterations (old default 1 or 5000, new default 1)

Both track and procstreamlines now default to 1 iteration. Previously, track tried to guess how many iterations you'd want by looking at the image type and seeing if it was deterministic. However, now any image can be used to produce non-deterministic streamlines by using probabilistic nearest-neighbour interpolation.


   -curvethresh (old default 80 degrees, new default 90 degrees)


   -curveinterval (old default slice thickness, new default 5 mm)

The interval at which we evaluate curvature used to be fixed to the slice (z) dimension, but is now user-defined.


    -stepsize (old default [slice thickness] / 10, new default 1 mm)

  
    -interpolate

This used to turn on Euler tracking with linear interpolation, or probabilistic nearest-neighbour interpolation, depending on whether the input data was probabilistic or not. 

DT data was previously interpolated at the tensor level by default, vector interpolation with that data was enabled with "-interpolate vectors". DT interpolation is gone for now, but may return with a log-Euclidean implementation in a future version.

With DT data, the following should be equivalent:

Old: -interpolate vectors -stepsize 1
New: -tracker euler -interpolator linear -stepsize 1

With pico, bayesdirac, or similar input:

Old: -interpolate -stepsize 1
New: -tracker euler -interpolator prob_nn -stepsize 1 




I have updated the track man page with some examples and more explanation of the new options. Please let me know if there are any questions or problems.

Thanks,


Phil