def track_ensemble(target_samples,
atlas_data_wm_gm_int,
parcels,
mod_fit,
tiss_classifier,
sphere,
directget,
curv_thr_list,
step_list,
track_type,
maxcrossing,
max_length,
n_seeds_per_iter=200,
pft_back_tracking_dist=2,
pft_front_tracking_dist=1,
particle_count=15,
roi_neighborhood_tol=8):
"""
Perform native-space ensemble tractography, restricted to a vector of ROI masks.
target_samples : int
Total number of streamline samples specified to generate streams.
atlas_data_wm_gm_int : array
3D int32 numpy array of atlas parcellation intensities from Nifti1Image in T1w-warped native diffusion space,
restricted to wm-gm interface.
parcels : list
List of 3D boolean numpy arrays of atlas parcellation ROI masks from a Nifti1Image in T1w-warped native
diffusion space.
mod : obj
Connectivity reconstruction model.
tiss_classifier : str
Tissue classification method.
sphere : obj
DiPy object for modeling diffusion directions on a sphere.
directget : str
The statistical approach to tracking. Options are: det (deterministic), closest (clos), boot (bootstrapped),
and prob (probabilistic).
curv_thr_list : list
List of integer curvature thresholds used to perform ensemble tracking.
step_list : list
List of float step-sizes used to perform ensemble tracking.
track_type : str
Tracking algorithm used (e.g. 'local' or 'particle').
maxcrossing : int
Maximum number if diffusion directions that can be assumed per voxel while tracking.
max_length : int
Maximum fiber length threshold in mm to restrict tracking.
n_seeds_per_iter : int
Number of seeds from which to initiate tracking for each unique ensemble combination.
By default this is set to 200.
particle_count
pft_back_tracking_dist : float
Distance in mm to back track before starting the particle filtering
tractography. The total particle filtering tractography distance is
equal to back_tracking_dist + front_tracking_dist. By default this is set to 2 mm.
pft_front_tracking_dist : float
Distance in mm to run the particle filtering tractography after the
the back track distance. The total particle filtering tractography
distance is equal to back_tracking_dist + front_tracking_dist. By
default this is set to 1 mm.
particle_count : int
Number of particles to use in the particle filter.
roi_neighborhood_tol : float
Distance (in the units of the streamlines, usually mm). If any
coordinate in the streamline is within this distance from the center
of any voxel in the ROI, the filtering criterion is set to True for
this streamline, otherwise False. Defaults to the distance between
the center of each voxel and the corner of the voxel.
Returns
-------
streamlines : ArraySequence
DiPy list/array-like object of streamline points from tractography.
"""
from colorama import Fore, Style
from dipy.tracking import utils
from dipy.tracking.streamline import Streamlines, select_by_rois
from dipy.tracking.local import LocalTracking, ParticleFilteringTracking
from dipy.direction import ProbabilisticDirectionGetter, BootDirectionGetter, ClosestPeakDirectionGetter, DeterministicMaximumDirectionGetter
# Commence Ensemble Tractography
parcel_vec = np.ones(len(parcels)).astype('bool')
streamlines = nib.streamlines.array_sequence.ArraySequence()
ix = 0
circuit_ix = 0
stream_counter = 0
while int(stream_counter) < int(target_samples):
for curv_thr in curv_thr_list:
print("%s%s" % ('Curvature: ', curv_thr))
# Instantiate DirectionGetter
if directget == 'prob':
dg = ProbabilisticDirectionGetter.from_shcoeff(
mod_fit, max_angle=float(curv_thr), sphere=sphere)
elif directget == 'boot':
dg = BootDirectionGetter.from_shcoeff(
mod_fit, max_angle=float(curv_thr), sphere=sphere)
elif directget == 'clos':
dg = ClosestPeakDirectionGetter.from_shcoeff(
mod_fit, max_angle=float(curv_thr), sphere=sphere)
elif directget == 'det':
dg = DeterministicMaximumDirectionGetter.from_shcoeff(
mod_fit, max_angle=float(curv_thr), sphere=sphere)
else:
raise ValueError(
'ERROR: No valid direction getter(s) specified.')
for step in step_list:
print("%s%s" % ('Step: ', step))
# Perform wm-gm interface seeding, using n_seeds at a time
seeds = utils.random_seeds_from_mask(
atlas_data_wm_gm_int > 0,
seeds_count=n_seeds_per_iter,
seed_count_per_voxel=False,
affine=np.eye(4))
if len(seeds) == 0:
raise RuntimeWarning(
'Warning: No valid seed points found in wm-gm interface...'
)
print(seeds)
# Perform tracking
if track_type == 'local':
streamline_generator = LocalTracking(
dg,
tiss_classifier,
seeds,
np.eye(4),
max_cross=int(maxcrossing),
maxlen=int(max_length),
step_size=float(step),
return_all=True)
elif track_type == 'particle':
streamline_generator = ParticleFilteringTracking(
dg,
tiss_classifier,
seeds,
np.eye(4),
max_cross=int(maxcrossing),
step_size=float(step),
maxlen=int(max_length),
pft_back_tracking_dist=pft_back_tracking_dist,
pft_front_tracking_dist=pft_front_tracking_dist,
particle_count=particle_count,
return_all=True)
else:
raise ValueError(
'ERROR: No valid tracking method(s) specified.')
# Filter resulting streamlines by roi-intersection characteristics
roi_proximal_streamlines = Streamlines(
select_by_rois(streamline_generator,
parcels,
parcel_vec,
mode='any',
affine=np.eye(4),
tol=roi_neighborhood_tol))
# Repeat process until target samples condition is met
ix = ix + 1
for s in roi_proximal_streamlines:
stream_counter = stream_counter + len(s)
streamlines.append(s)
if int(stream_counter) >= int(target_samples):
break
else:
continue
circuit_ix = circuit_ix + 1
print(
"%s%s%s%s%s" %
('Completed hyperparameter circuit: ', circuit_ix,
'...\nCumulative Streamline Count: ', Fore.CYAN, stream_counter))
print(Style.RESET_ALL)
print('\n')
return streamlines
def track_ensemble(target_samples, atlas_data_wm_gm_int, parcels, parcel_vec, mod_fit,
tiss_classifier, sphere, directget, curv_thr_list, step_list, track_type, maxcrossing, max_length,
n_seeds_per_iter=200):
from colorama import Fore, Style
from dipy.tracking import utils
from dipy.tracking.streamline import Streamlines, select_by_rois
from dipy.tracking.local import LocalTracking, ParticleFilteringTracking
from dipy.direction import ProbabilisticDirectionGetter, BootDirectionGetter, ClosestPeakDirectionGetter, DeterministicMaximumDirectionGetter
# Commence Ensemble Tractography
streamlines = nib.streamlines.array_sequence.ArraySequence()
ix = 0
circuit_ix = 0
stream_counter = 0
while int(stream_counter) < int(target_samples):
for curv_thr in curv_thr_list:
print("%s%s" % ('Curvature: ', curv_thr))
# Instantiate DirectionGetter
if directget == 'prob':
dg = ProbabilisticDirectionGetter.from_shcoeff(mod_fit, max_angle=float(curv_thr),
sphere=sphere)
elif directget == 'boot':
dg = BootDirectionGetter.from_shcoeff(mod_fit, max_angle=float(curv_thr),
sphere=sphere)
elif directget == 'closest':
dg = ClosestPeakDirectionGetter.from_shcoeff(mod_fit, max_angle=float(curv_thr),
sphere=sphere)
elif directget == 'det':
dg = DeterministicMaximumDirectionGetter.from_shcoeff(mod_fit, max_angle=float(curv_thr),
sphere=sphere)
else:
raise ValueError('ERROR: No valid direction getter(s) specified.')
for step in step_list:
print("%s%s" % ('Step: ', step))
# Perform wm-gm interface seeding, using n_seeds at a time
seeds = utils.random_seeds_from_mask(atlas_data_wm_gm_int > 0, seeds_count=n_seeds_per_iter,
seed_count_per_voxel=False, affine=np.eye(4))
if len(seeds) == 0:
raise RuntimeWarning('Warning: No valid seed points found in wm-gm interface...')
print(seeds)
# Perform tracking
if track_type == 'local':
streamline_generator = LocalTracking(dg, tiss_classifier, seeds, np.eye(4),
max_cross=int(maxcrossing), maxlen=int(max_length),
step_size=float(step), return_all=True)
elif track_type == 'particle':
streamline_generator = ParticleFilteringTracking(dg, tiss_classifier, seeds, np.eye(4),
max_cross=int(maxcrossing),
step_size=float(step),
maxlen=int(max_length),
pft_back_tracking_dist=2,
pft_front_tracking_dist=1,
particle_count=15, return_all=True)
else:
raise ValueError('ERROR: No valid tracking method(s) specified.')
# Filter resulting streamlines by roi-intersection characteristics
streamlines_more = Streamlines(select_by_rois(streamline_generator, parcels, parcel_vec.astype('bool'),
mode='any', affine=np.eye(4), tol=8))
# Repeat process until target samples condition is met
ix = ix + 1
for s in streamlines_more:
stream_counter = stream_counter + len(s)
streamlines.append(s)
if int(stream_counter) >= int(target_samples):
break
else:
continue
circuit_ix = circuit_ix + 1
print("%s%s%s%s%s" % ('Completed hyperparameter circuit: ', circuit_ix, '...\nCumulative Streamline Count: ',
Fore.CYAN, stream_counter))
print(Style.RESET_ALL)
print('\n')
return streamlines