def fit_dti(data_files, bval_files, bvec_files, mask=None,
out_dir=None, file_prefix=None, b0_threshold=0):
"""
Fit the DTI model using default settings, save files with derived maps
Parameters
----------
data_files : str or list
Files containing DWI data. If this is a str, that's the full path to a
single file. If it's a list, each entry is a full path.
bval_files : str or list
Equivalent to `data_files`.
bvec_files : str or list
Equivalent to `data_files`.
mask : ndarray, optional
Binary mask, set to True or 1 in voxels to be processed.
Default: Process all voxels.
out_dir : str, optional
A full path to a directory to store the maps that get computed.
Default: maps get stored in the same directory as the last DWI file
in `data_files`.
b0_threshold : float
Returns
-------
file_paths : a dict with the derived maps that were computed and full-paths
to the files containing these maps.
Note
----
Maps that are calculated: FA, MD, AD, RD
"""
img, data, gtab, mask = ut.prepare_data(data_files, bval_files,
bvec_files, mask=mask,
b0_threshold=b0_threshold)
# In this case, we dump the fit object
dtf = _fit(gtab, data, mask=None)
FA, MD, AD, RD, params = dtf.fa, dtf.md, dtf.ad, dtf.rd, dtf.model_params
maps = [FA, MD, AD, RD, params]
names = ['FA', 'MD', 'AD', 'RD', 'params']
if out_dir is None:
out_dir = op.join(op.split(data_files)[0], 'dti')
if file_prefix is None:
file_prefix = ''
if not op.exists(out_dir):
os.makedirs(out_dir)
aff = img.get_affine()
file_paths = {}
for m, n in zip(maps, names):
file_paths[n] = op.join(out_dir, file_prefix + 'dti_%s.nii.gz' % n)
nib.save(nib.Nifti1Image(m, aff), file_paths[n])
return file_paths
def fit_csd(data_files,
bval_files,
bvec_files,
mask=None,
response=None,
sh_order=8,
lambda_=1,
tau=0.1,
out_dir=None):
"""
Fit the CSD model and save file with SH coefficients.
Parameters
----------
data_files : str or list
Files containing DWI data. If this is a str, that's the full path to a
single file. If it's a list, each entry is a full path.
bval_files : str or list
Equivalent to `data_files`.
bvec_files : str or list
Equivalent to `data_files`.
mask : ndarray, optional
Binary mask, set to True or 1 in voxels to be processed.
Default: Process all voxels.
out_dir : str, optional
A full path to a directory to store the maps that get computed.
Default: file with coefficients gets stored in the same directory as
the first DWI file in `data_files`.
Returns
-------
fname : the full path to the file containing the SH coefficients.
"""
img, data, gtab, mask = ut.prepare_data(data_files, bval_files, bvec_files)
if response is None:
response, ratio = csd.auto_response(gtab,
data,
roi_radius=10,
fa_thr=0.7)
csdmodel = csd.ConstrainedSphericalDeconvModel(gtab,
response,
sh_order=sh_order)
csdfit = csdmodel.fit(data, mask=mask)
if out_dir is None:
out_dir = op.join(op.split(data_files)[0], 'dki')
if not op.exists(out_dir):
os.makedirs(out_dir)
aff = img.affine
fname = op.join(out_dir, 'csd_sh_coeff.nii.gz')
nib.save(nib.Nifti1Image(csdfit.shm_coeff, aff), fname)
return fname
def register_dwi(data_files, bval_files, bvec_files,
b0_ref=0,
pipeline=[c_of_mass, translation, rigid, affine],
out_dir=None):
"""
Register a DWI data-set
Parameters
----------
data_files : str or list
Files containing DWI data. If this is a str, that's the full path to a
single file. If it's a list, each entry is a full path.
bval_files : str or list
Equivalent to `data_files`.
bvec_files : str or list
Equivalent to `data_files`.
"""
img, data, gtab, mask = mut.prepare_data(data_files,
bval_files,
bvec_files)
if np.sum(gtab.b0s_mask) > 1:
# First, register the b0s into one image:
b0_img = nib.Nifti1Image(data[..., gtab.b0s_mask], img.affine)
trans_b0 = register_series(b0_img, ref=0, pipeline=pipeline)
ref_data = np.mean(trans_b0, -1)
else:
ref_data = data[..., gtab.b0s_mask]
# Construct a series out of the DWI and the registered mean B0:
series = nib.Nifti1Image(np.concatenate([ref_data,
data[...,
~gtab.b0s_mask]], -1),
img.affine)
transformed_list, affine_list = register_series(series, ref=0,
pipeline=pipeline)
reg_img = nib.Nifti1Image(np.array(transformed_list),
img.affine)
if out_dir is None:
out_dir = op.join(op.split(data_files)[0], 'registered')
if not op.exists(out_dir):
os.makedirs(out_dir)
path = op.join(out_dir, 'registered.nii.gz')
nib.save(reg_img, path)
return path
def prepare_img(self, fdata, fbval, fbvec):
"""
Prepare image data from DWI data.
Parameters
----------
fdata, fbval, fbvec : str
Full path to data, bvals, bvecs
"""
if self.img_affine is None:
self.img, _, _, _ = \
ut.prepare_data(fdata, fbval, fbvec,
b0_threshold=self.b0_threshold)
self.img_affine = self.img.affine
self.fdata = fdata
self.fbval = fbval
self.fbvec = fbvec
def prepare_map(self, mapping=None, reg_prealign=None, reg_template=None):
"""
Set mapping between DWI space and a template.
Parameters
----------
mapping : DiffeomorphicMap object, str or nib.Nifti1Image, optional.
A mapping between DWI space and a template.
If None, mapping will be registered from data used in prepare_img.
Default: None.
reg_template : str or nib.Nifti1Image, optional.
Template to use for registration (defaults to the MNI T2)
Default: None.
reg_prealign : array, optional.
The linear transformation to be applied to align input images to
the reference space before warping under the deformation field.
Default: None.
"""
if reg_template is None:
reg_template = afd.read_mni_template()
self.reg_template = reg_template
if mapping is None:
if self.seg_algo == "afq" or self.reg_algo == "syn":
gtab = dpg.gradient_table(self.fbval, self.fbvec)
self.mapping = reg.syn_register_dwi(self.fdata,
gtab,
template=reg_template)[1]
else:
self.mapping = None
elif isinstance(mapping, str) or isinstance(mapping, nib.Nifti1Image):
if reg_prealign is None:
reg_prealign = np.eye(4)
if self.img is None:
self.img, _, _, _ = \
ut.prepare_data(self.fdata,
self.fbval,
self.fbvec,
b0_threshold=self.b0_threshold)
self.mapping = reg.read_mapping(
mapping,
self.img,
reg_template,
prealign=np.linalg.inv(reg_prealign))
else:
self.mapping = mapping
def test_noise_from_b0():
out_shape = (5, 6, 7)
with nbtmp.InTemporaryDirectory() as tmpdir:
# make artificial dti data
fbval = op.join(tmpdir, 'dti.bval')
fbvec = op.join(tmpdir, 'dti.bvec')
fdata = op.join(tmpdir, 'dti.nii.gz')
make_dti_data(fbval, fbvec, fdata, out_shape=out_shape)
# make artifical mask
mask = np.ones(out_shape)
mask[0, 0, :] = 0
# load data and mask
bvals, bvecs = read_bvals_bvecs(fbval, fbvec)
img, data, gtab, mask = ut.prepare_data(fdata,
fbval,
fbvec,
mask=mask,
b0_threshold=50)
# test noise_from_b0
noise = dti.noise_from_b0(data, gtab, bvals, mask=mask)
npt.assert_almost_equal(noise, 0)
def fit_mdki(data_files,
bval_files,
bvec_files,
mask=None,
out_dir=None,
b0_threshold=0):
"""
Fit the DKI model, save files with derived maps
Parameters
----------
data_files : str or list
Files containing DWI data. If this is a str, that's the full path to a
single file. If it's a list, each entry is a full path.
bval_files : str or list
Equivalent to `data_files`.
bvec_files : str or list
Equivalent to `data_files`.
mask : ndarray, optional
Binary mask, set to True or 1 in voxels to be processed.
Default: Process all voxels.
min_kurtosis : float, optional
The minimal plausible value of kurtosis. Default: -1.
max_kurtosis : float, optional
The maximal plausible value of kurtosis. Default: 3.
out_dir : str, optional
A full path to a directory to store the maps that get computed.
Default: maps get stored in the same directory as the last DWI file
in `data_files`.
b0_threshold : float
Returns
-------
file_paths : a dict with the derived maps that were computed and full-paths
to the files containing these maps.
Note
----
Maps that are calculated: FA, MD, AD, RD, MK, AK, RK
"""
img, data, gtab, mask = ut.prepare_data(data_files,
bval_files,
bvec_files,
mask=mask,
b0_threshold=b0_threshold)
params = avs_dki_df(gtab, data, mask=mask)
MD = params[..., 0]
MK = params[..., 1]
S0 = params[..., 2]
maps = [MD, MK, S0]
names = ['MD', 'MK', 'S0']
if out_dir is None:
if isinstance(data_files, list):
out_dir = op.join(op.split(data_files[0])[0], 'dki')
else:
out_dir = op.join(op.split(data_files)[0], 'dki')
if not op.exists(out_dir):
os.makedirs(out_dir)
aff = img.affine
file_paths = {}
for m, n in zip(maps, names):
file_paths[n] = op.join(out_dir, 'mdki_%s.nii.gz' % n)
nib.save(nib.Nifti1Image(m, aff), file_paths[n])
return file_paths
def fit_dkimicro(data_files, bval_files, bvec_files, mask=None,
min_kurtosis=-1, max_kurtosis=3, out_dir=None,
b0_threshold=0):
"""
Fit the DKI model, save files with derived maps
Parameters
----------
data_files : str or list
Files containing DWI data. If this is a str, that's the full path to a
single file. If it's a list, each entry is a full path.
bval_files : str or list
Equivalent to `data_files`.
bvec_files : str or list
Equivalent to `data_files`.
mask : ndarray, optional
Binary mask, set to True or 1 in voxels to be processed.
Default: Process all voxels.
min_kurtosis : float, optional
The minimal plausible value of kurtosis. Default: -1.
max_kurtosis : float, optional
The maximal plausible value of kurtosis. Default: 3.
out_dir : str, optional
A full path to a directory to store the maps that get computed.
Default: maps get stored in the same directory as the last DWI file
in `data_files`.
b0_threshold : float
Returns
-------
file_paths : a dict with the derived maps that were computed and full-paths
to the files containing these maps.
Note
----
Maps that are calculated: FA, MD, AD, RD, MK, AK, RK
"""
img, data, gtab, mask = ut.prepare_data(data_files, bval_files,
bvec_files, mask=mask,
b0_threshold=b0_threshold)
dkimodel = dki_micro.KurtosisMicrostructureModel(gtab)
dkifit = dkimodel.fit(data, mask=mask)
AWF = dkifit.awf
T = dkifit.tortuosity
Da = dkifit.axonal_diffusivity
hRD = dkifit.hindered_rd
hAD = dkifit.hindered_ad
evals = dkifit.hindered_evals
hMD = (evals[..., 0] + evals[..., 1] + evals[..., 2]) / 3.0
params = dkifit.model_params
maps = [AWF, T, hAD, hRD, hMD, Da, params]
names = ['AWF', 'T', 'hAD', 'hRD', 'hMD', 'Da', 'params']
if out_dir is None:
out_dir = op.join(op.split(data_files)[0], 'dkimicro')
if not op.exists(out_dir):
os.makedirs(out_dir)
aff = img.get_affine()
file_paths = {}
for m, n in zip(maps, names):
file_paths[n] = op.join(out_dir, 'dkimicro_%s.nii.gz' % n)
nib.save(nib.Nifti1Image(m, aff), file_paths[n])
return file_paths
def fit_dki(data_files, bval_files, bvec_files, mask=None,
min_kurtosis=-1, max_kurtosis=3, out_dir=None, b0_threshold=0):
"""
Fit the DKI model, save files with derived maps
Parameters
----------
data_files : str or list
Files containing DWI data. If this is a str, that's the full path to a
single file. If it's a list, each entry is a full path.
bval_files : str or list
Equivalent to `data_files`.
bvec_files : str or list
Equivalent to `data_files`.
mask : ndarray, optional
Binary mask, set to True or 1 in voxels to be processed.
Default: Process all voxels.
min_kurtosis : float, optional
The minimal plausible value of kurtosis. Default: -1.
max_kurtosis : float, optional
The maximal plausible value of kurtosis. Default: 3.
out_dir : str, optional
A full path to a directory to store the maps that get computed.
Default: maps get stored in the same directory as the last DWI file
in `data_files`.
b0_threshold : float
Returns
-------
file_paths : a dict with the derived maps that were computed and full-paths
to the files containing these maps.
Note
----
Maps that are calculated: FA, MD, AD, RD, MK, AK, RK
"""
img, data, gtab, mask = ut.prepare_data(data_files, bval_files,
bvec_files, mask=mask,
b0_threshold=b0_threshold)
dkimodel = dki.DiffusionKurtosisModel(gtab)
dkifit = dkimodel.fit(data, mask=mask)
FA = dkifit.fa
MD = dkifit.md
AD = dkifit.ad
RD = dkifit.rd
MK = dkifit.mk(min_kurtosis, max_kurtosis)
AK = dkifit.ak(min_kurtosis, max_kurtosis)
RK = dkifit.rk(min_kurtosis, max_kurtosis)
params = dkifit.model_params
maps = [FA, MD, AD, RD, MK, AK, RK, params]
names = ['FA', 'MD', 'AD', 'RD', 'MK', 'AK', 'RK', 'params']
if out_dir is None:
out_dir = op.join(op.split(data_files)[0], 'dki')
if not op.exists(out_dir):
os.makedirs(out_dir)
aff = img.get_affine()
file_paths = {}
for m, n in zip(maps, names):
file_paths[n] = op.join(out_dir, 'dki_%s.nii.gz' % n)
nib.save(nib.Nifti1Image(m, aff), file_paths[n])
return file_paths
def fit_dti(data_files,
bval_files,
bvec_files,
mask=None,
out_dir=None,
file_prefix=None,
b0_threshold=0):
"""
Fit the DTI model using default settings, save files with derived maps
Parameters
----------
data_files : str or list
Files containing DWI data. If this is a str, that's the full path to a
single file. If it's a list, each entry is a full path.
bval_files : str or list
Equivalent to `data_files`.
bvec_files : str or list
Equivalent to `data_files`.
mask : ndarray, optional
Binary mask, set to True or 1 in voxels to be processed.
Default: Process all voxels.
out_dir : str, optional
A full path to a directory to store the maps that get computed.
Default: maps get stored in the same directory as the last DWI file
in `data_files`.
b0_threshold : float
Returns
-------
file_paths : a dict with the derived maps that were computed and full-paths
to the files containing these maps.
Note
----
Maps that are calculated: FA, MD, AD, RD
"""
img, data, gtab, mask = ut.prepare_data(data_files,
bval_files,
bvec_files,
mask=mask,
b0_threshold=b0_threshold)
# In this case, we dump the fit object
dtf = _fit(gtab, data, mask=None)
FA, MD, AD, RD, params = dtf.fa, dtf.md, dtf.ad, dtf.rd, dtf.model_params
maps = [FA, MD, AD, RD, params]
names = ['FA', 'MD', 'AD', 'RD', 'params']
if out_dir is None:
out_dir = op.join(op.split(data_files)[0], 'dti')
if file_prefix is None:
file_prefix = ''
if not op.exists(out_dir):
os.makedirs(out_dir)
aff = img.get_affine()
file_paths = {}
for m, n in zip(maps, names):
file_paths[n] = op.join(out_dir, file_prefix + 'dti_%s.nii.gz' % n)
nib.save(nib.Nifti1Image(m, aff), file_paths[n])
return file_paths
def segment(fdata, fbval, fbvec, streamlines, bundles,
reg_template=None, mapping=None, prob_threshold=0,
**reg_kwargs):
"""
Segment streamlines into bundles based on inclusion ROIs.
Parameters
----------
fdata, fbval, fbvec : str
Full path to data, bvals, bvecs
streamlines : list of 2D arrays
Each array is a streamline, shape (3, N).
bundles: dict
The format is something like::
{'name': {'ROIs':[img1, img2],
'rules':[True, True]},
'prob_map': img3,
'cross_midline': False}
reg_template : str or nib.Nifti1Image, optional.
Template to use for registration (defaults to the MNI T2)
mapping : DiffeomorphicMap object, str or nib.Nifti1Image, optional
A mapping between DWI space and a template. Defaults to generate
this.
prob_threshold : float.
Initial cleaning of fiber groups is done using probability maps from
[Hua2008]_. Here, we choose an average probability that needs to be
exceeded for an individual streamline to be retained. Default: 0.
References
----------
.. [Hua2008] Hua K, Zhang J, Wakana S, Jiang H, Li X, et al. (2008)
Tract probability maps in stereotaxic spaces: analyses of white
matter anatomy and tract-specific quantification. Neuroimage 39:
336-347
"""
img, _, gtab, _ = ut.prepare_data(fdata, fbval, fbvec)
tol = dts.dist_to_corner(img.affine)
xform_sl = dts.Streamlines(dtu.move_streamlines(streamlines,
np.linalg.inv(img.affine)))
if reg_template is None:
reg_template = dpd.read_mni_template()
if mapping is None:
mapping = reg.syn_register_dwi(fdata, gtab, template=reg_template,
**reg_kwargs)
if isinstance(mapping, str) or isinstance(mapping, nib.Nifti1Image):
mapping = reg.read_mapping(mapping, img, reg_template)
fiber_probabilities = np.zeros((len(xform_sl), len(bundles)))
# For expedience, we approximate each streamline as a 100 point curve:
fgarray = _resample_bundle(xform_sl, 100)
streamlines_in_bundles = np.zeros((len(xform_sl), len(bundles)))
min_dist_coords = np.zeros((len(xform_sl), len(bundles), 2))
fiber_groups = {}
for bundle_idx, bundle in enumerate(bundles):
# Get the ROI coordinates:
ROI0 = bundles[bundle]['ROIs'][0]
ROI1 = bundles[bundle]['ROIs'][1]
if not isinstance(ROI0, np.ndarray):
ROI0 = ROI0.get_data()
warped_ROI0 = patch_up_roi(
mapping.transform_inverse(
ROI0,
interpolation='nearest')).astype(bool)
if not isinstance(ROI1, np.ndarray):
ROI1 = ROI1.get_data()
warped_ROI1 = patch_up_roi(
mapping.transform_inverse(
ROI1,
interpolation='nearest')).astype(bool)
roi_coords0 = np.array(np.where(warped_ROI0)).T
roi_coords1 = np.array(np.where(warped_ROI1)).T
crosses_midline = bundles[bundle]['cross_midline']
# The probability map if doesn't exist is all ones with the same
# shape as the ROIs:
prob_map = bundles[bundle].get('prob_map', np.ones(ROI0.shape))
if not isinstance(prob_map, np.ndarray):
prob_map = prob_map.get_data()
warped_prob_map = mapping.transform_inverse(prob_map,
interpolation='nearest')
fiber_probabilities = dts.values_from_volume(warped_prob_map,
fgarray)
fiber_probabilities = np.mean(fiber_probabilities, -1)
for sl_idx, sl in enumerate(xform_sl):
if fiber_probabilities[sl_idx] > prob_threshold:
if crosses_midline is not None:
if (np.any(sl[:, 0] > img.shape[0] // 2) and
np.any(sl[:, 0] < img.shape[0] // 2)):
# This means that the streamline does
# cross the midline:
if crosses_midline:
# This is what we want, keep going
pass
else:
# This is not what we want, skip to next streamline
continue
dist0 = cdist(sl, roi_coords0, 'euclidean')
if np.min(dist0) <= tol:
dist1 = cdist(sl, roi_coords1, 'euclidean')
if np.min(dist1) <= tol:
min_dist_coords[sl_idx, bundle_idx, 0] =\
np.argmin(dist0, 0)[0]
min_dist_coords[sl_idx, bundle_idx, 1] =\
np.argmin(dist1, 0)[0]
streamlines_in_bundles[sl_idx, bundle_idx] =\
fiber_probabilities[sl_idx]
# Eliminate any fibers not selected using the plane ROIs:
possible_fibers = np.sum(streamlines_in_bundles, -1) > 0
xform_sl = xform_sl[possible_fibers]
streamlines_in_bundles = streamlines_in_bundles[possible_fibers]
min_dist_coords = min_dist_coords[possible_fibers]
bundle_choice = np.argmax(streamlines_in_bundles, -1)
for bundle_idx, bundle in enumerate(bundles):
print(bundle)
select_idx = np.where(bundle_choice == bundle_idx)
# Use a list here, because Streamlines don't support item assignment:
select_sl = list(xform_sl[select_idx])
# Sub-sample min_dist_coords:
min_dist_coords_bundle = min_dist_coords[select_idx]
if len(select_sl) == 0:
fiber_groups[bundle] = dts.Streamlines([])
# There's nothing here, move to the next bundle:
continue
for idx in range(len(select_sl)):
min0 = min_dist_coords_bundle[idx, bundle_idx, 0]
min1 = min_dist_coords_bundle[idx, bundle_idx, 1]
if min0 > min1:
select_sl[idx] = select_sl[idx][::-1]
# We'll set this to Streamlines object for the next steps (e.g.,
# cleaning) because these objects support indexing with arrays:
select_sl = dts.Streamlines(select_sl)
fiber_groups[bundle] = select_sl
return fiber_groups
def segment(fdata,
fbval,
fbvec,
streamlines,
bundles,
reg_template=None,
mapping=None,
as_generator=True,
clip_to_roi=True,
**reg_kwargs):
"""
Segment streamlines into bundles.
Parameters
----------
fdata, fbval, fbvec : str
Full path to data, bvals, bvecs
streamlines : list of 2D arrays
Each array is a streamline, shape (3, N).
bundles: dict
The format is something like::
{'name': {'ROIs':[img, img], 'rules':[True, True]}}
reg_template : str or nib.Nifti1Image, optional.
Template to use for registration (defaults to the MNI T2)
mapping : DiffeomorphicMap object, str or nib.Nifti1Image, optional
A mapping between DWI space and a template. Defaults to generate this.
as_generator : bool, optional
Whether to generate the streamlines here, or return generators.
Default: True.
clip_to_roi : bool, optional
Whether to clip the streamlines between the ROIs
"""
img, data, gtab, mask = ut.prepare_data(fdata, fbval, fbvec)
xform_sl = [
s for s in dtu.move_streamlines(streamlines, np.linalg.inv(img.affine))
]
if reg_template is None:
reg_template = dpd.read_mni_template()
if mapping is None:
mapping = reg.syn_register_dwi(fdata,
gtab,
template=reg_template,
**reg_kwargs)
if isinstance(mapping, str) or isinstance(mapping, nib.Nifti1Image):
mapping = reg.read_mapping(mapping, img, reg_template)
fiber_groups = {}
for bundle in bundles:
select_sl = xform_sl
for ROI, rule in zip(bundles[bundle]['ROIs'],
bundles[bundle]['rules']):
data = ROI.get_data()
warped_ROI = patch_up_roi(
mapping.transform_inverse(data, interpolation='nearest'))
# This function requires lists as inputs:
select_sl = dts.select_by_rois(select_sl,
[warped_ROI.astype(bool)], [rule])
# Next, we reorient each streamline according to an ARBITRARY, but
# CONSISTENT order. To do this, we use the first ROI for which the rule
# is True as the first one to pass through, and the last ROI for which
# the rule is True as the last one to pass through:
# Indices where the 'rule' is True:
idx = np.where(bundles[bundle]['rules'])
orient_ROIs = [
bundles[bundle]['ROIs'][idx[0][0]],
bundles[bundle]['ROIs'][idx[0][-1]]
]
select_sl = dts.orient_by_rois(select_sl,
orient_ROIs[0].get_data(),
orient_ROIs[1].get_data(),
as_generator=True)
# XXX Implement clipping to the ROIs
# if clip_to_roi:
# dts.clip()
if as_generator:
fiber_groups[bundle] = select_sl
else:
fiber_groups[bundle] = list(select_sl)
return fiber_groups
def fit_dki(data_files,
bval_files,
bvec_files,
mask=None,
min_kurtosis=-1,
max_kurtosis=3,
out_dir=None,
b0_threshold=0):
"""
Fit the DKI model, save files with derived maps
Parameters
----------
data_files : str or list
Files containing DWI data. If this is a str, that's the full path to a
single file. If it's a list, each entry is a full path.
bval_files : str or list
Equivalent to `data_files`.
bvec_files : str or list
Equivalent to `data_files`.
mask : ndarray, optional
Binary mask, set to True or 1 in voxels to be processed.
Default: Process all voxels.
min_kurtosis : float, optional
The minimal plausible value of kurtosis. Default: -1.
max_kurtosis : float, optional
The maximal plausible value of kurtosis. Default: 3.
out_dir : str, optional
A full path to a directory to store the maps that get computed.
Default: maps get stored in the same directory as the last DWI file
in `data_files`.
b0_threshold : float
Returns
-------
file_paths : a dict with the derived maps that were computed and full-paths
to the files containing these maps.
Note
----
Maps that are calculated: FA, MD, AD, RD, MK, AK, RK
"""
img, data, gtab, mask = ut.prepare_data(data_files,
bval_files,
bvec_files,
mask=mask,
b0_threshold=b0_threshold)
dkimodel = dki.DiffusionKurtosisModel(gtab)
dkifit = dkimodel.fit(data, mask=mask)
FA = dkifit.fa
MD = dkifit.md
AD = dkifit.ad
RD = dkifit.rd
MK = dkifit.mk(min_kurtosis, max_kurtosis)
AK = dkifit.ak(min_kurtosis, max_kurtosis)
RK = dkifit.rk(min_kurtosis, max_kurtosis)
params = dkifit.model_params
maps = [FA, MD, AD, RD, MK, AK, RK, params]
names = ['FA', 'MD', 'AD', 'RD', 'MK', 'AK', 'RK', 'params']
if out_dir is None:
out_dir = op.join(op.split(data_files)[0], 'dki')
if not op.exists(out_dir):
os.makedirs(out_dir)
aff = img.get_affine()
file_paths = {}
for m, n in zip(maps, names):
file_paths[n] = op.join(out_dir, 'dki_%s.nii.gz' % n)
nib.save(nib.Nifti1Image(m, aff), file_paths[n])
return file_paths
def segment(fdata, fbval, fbvec, streamlines, bundle_dict, mapping,
reg_prealign=None, b0_threshold=0, reg_template=None,
prob_threshold=0):
"""
Segment streamlines into bundles based on inclusion ROIs.
Parameters
----------
fdata, fbval, fbvec : str
Full path to data, bvals, bvecs
streamlines : list of 2D arrays
Each array is a streamline, shape (3, N).
bundle_dict: dict
The format is something like::
{'name': {'ROIs':[img1, img2],
'rules':[True, True]},
'prob_map': img3,
'cross_midline': False}
mapping : a DiffeomorphicMapping object
Used to align the ROIs to the data.
reg_template : str or nib.Nifti1Image, optional.
Template to use for registration (defaults to the MNI T2)
mapping : DiffeomorphicMap object, str or nib.Nifti1Image, optional
A mapping between DWI space and a template. Defaults to generate
this.
prob_threshold : float.
Initial cleaning of fiber groups is done using probability maps from
[Hua2008]_. Here, we choose an average probability that needs to be
exceeded for an individual streamline to be retained. Default: 0.
References
----------
.. [Hua2008] Hua K, Zhang J, Wakana S, Jiang H, Li X, et al. (2008)
Tract probability maps in stereotaxic spaces: analyses of white
matter anatomy and tract-specific quantification. Neuroimage 39:
336-347
"""
img, _, gtab, _ = ut.prepare_data(fdata, fbval, fbvec,
b0_threshold=b0_threshold)
tol = dts.dist_to_corner(img.affine)
if reg_template is None:
reg_template = dpd.read_mni_template()
# Classify the streamlines and split those that: 1) cross the
# midline, and 2) pass under 10 mm below the mid-point of their
# representation in the template space:
xform_sl, crosses = split_streamlines(streamlines, img)
if isinstance(mapping, str) or isinstance(mapping, nib.Nifti1Image):
if reg_prealign is None:
reg_prealign = np.eye(4)
mapping = reg.read_mapping(mapping, img, reg_template,
prealign=reg_prealign)
fiber_probabilities = np.zeros((len(xform_sl), len(bundle_dict)))
# For expedience, we approximate each streamline as a 100 point curve:
fgarray = _resample_bundle(xform_sl, 100)
streamlines_in_bundles = np.zeros((len(xform_sl), len(bundle_dict)))
min_dist_coords = np.zeros((len(xform_sl), len(bundle_dict), 2))
fiber_groups = {}
for bundle_idx, bundle in enumerate(bundle_dict):
rules = bundle_dict[bundle]['rules']
include_rois = []
exclude_rois = []
for rule_idx, rule in enumerate(rules):
roi = bundle_dict[bundle]['ROIs'][rule_idx]
if not isinstance(roi, np.ndarray):
roi = roi.get_data()
warped_roi = auv.patch_up_roi(
(mapping.transform_inverse(
roi,
interpolation='linear')) > 0)
if rule:
# include ROI:
include_rois.append(np.array(np.where(warped_roi)).T)
else:
# Exclude ROI:
exclude_rois.append(np.array(np.where(warped_roi)).T)
crosses_midline = bundle_dict[bundle]['cross_midline']
# The probability map if doesn't exist is all ones with the same
# shape as the ROIs:
prob_map = bundle_dict[bundle].get('prob_map', np.ones(roi.shape))
if not isinstance(prob_map, np.ndarray):
prob_map = prob_map.get_data()
warped_prob_map = mapping.transform_inverse(prob_map,
interpolation='nearest')
fiber_probabilities = dts.values_from_volume(warped_prob_map,
fgarray)
fiber_probabilities = np.mean(fiber_probabilities, -1)
for sl_idx, sl in enumerate(xform_sl):
if fiber_probabilities[sl_idx] > prob_threshold:
if crosses_midline is not None:
if crosses[sl_idx]:
# This means that the streamline does
# cross the midline:
if crosses_midline:
# This is what we want, keep going
pass
else:
# This is not what we want, skip to next streamline
continue
is_close, dist = _check_sl_with_inclusion(sl, include_rois,
tol)
if is_close:
is_far = _check_sl_with_exclusion(sl, exclude_rois,
tol)
if is_far:
min_dist_coords[sl_idx, bundle_idx, 0] =\
np.argmin(dist[0], 0)[0]
min_dist_coords[sl_idx, bundle_idx, 1] =\
np.argmin(dist[1], 0)[0]
streamlines_in_bundles[sl_idx, bundle_idx] =\
fiber_probabilities[sl_idx]
# Eliminate any fibers not selected using the plane ROIs:
possible_fibers = np.sum(streamlines_in_bundles, -1) > 0
xform_sl = xform_sl[possible_fibers]
streamlines_in_bundles = streamlines_in_bundles[possible_fibers]
min_dist_coords = min_dist_coords[possible_fibers]
bundle_choice = np.argmax(streamlines_in_bundles, -1)
# We do another round through, so that we can orient all the
# streamlines within a bundle in the same orientation with respect to
# the ROIs. This order is ARBITRARY but CONSISTENT (going from ROI0
# to ROI1).
for bundle_idx, bundle in enumerate(bundle_dict):
select_idx = np.where(bundle_choice == bundle_idx)
# Use a list here, because Streamlines don't support item assignment:
select_sl = list(xform_sl[select_idx])
if len(select_sl) == 0:
fiber_groups[bundle] = dts.Streamlines([])
# There's nothing here, move to the next bundle:
continue
# Sub-sample min_dist_coords:
min_dist_coords_bundle = min_dist_coords[select_idx]
for idx in range(len(select_sl)):
min0 = min_dist_coords_bundle[idx, bundle_idx, 0]
min1 = min_dist_coords_bundle[idx, bundle_idx, 1]
if min0 > min1:
select_sl[idx] = select_sl[idx][::-1]
# Set this to nibabel.Streamlines object for output:
select_sl = dts.Streamlines(select_sl)
fiber_groups[bundle] = select_sl
return fiber_groups
def segment(fdata, fbval, fbvec, streamlines, bundles,
reg_template=None, mapping=None, as_generator=True, **reg_kwargs):
"""
generate : bool
Whether to generate the streamlines here, or return generators.
reg_template : template to use for registration (defaults to the MNI T2)
bundles: dict
The format is something like::
{'name': {'ROIs':[img, img], 'rules':[True, True]}}
"""
img, data, gtab, mask = ut.prepare_data(fdata, fbval, fbvec)
xform_sl = [s for s in dtu.move_streamlines(streamlines,
np.linalg.inv(img.affine))]
if reg_template is None:
reg_template = dpd.read_mni_template()
if mapping is None:
mapping = reg.syn_register_dwi(fdata, gtab, template=reg_template,
**reg_kwargs)
if isinstance(mapping, str) or isinstance(mapping, nib.Nifti1Image):
mapping = reg.read_mapping(mapping, img, reg_template)
fiber_groups = {}
for bundle in bundles:
select_sl = xform_sl
for ROI, rule in zip(bundles[bundle]['ROIs'],
bundles[bundle]['rules']):
data = ROI.get_data()
warped_ROI = patch_up_roi(mapping.transform_inverse(
data,
interpolation='nearest'))
# This function requires lists as inputs:
select_sl = dts.select_by_rois(select_sl,
[warped_ROI.astype(bool)],
[rule])
# Next, we reorient each streamline according to an ARBITRARY, but
# CONSISTENT order. To do this, we use the first ROI for which the rule
# is True as the first one to pass through, and the last ROI for which
# the rule is True as the last one to pass through:
# Indices where the 'rule' is True:
idx = np.where(bundles[bundle]['rules'])
orient_ROIs = [bundles[bundle]['ROIs'][idx[0][0]],
bundles[bundle]['ROIs'][idx[0][-1]]]
select_sl = dts.orient_by_rois(select_sl,
orient_ROIs[0].get_data(),
orient_ROIs[1].get_data(),
in_place=True)
if as_generator:
fiber_groups[bundle] = select_sl
else:
fiber_groups[bundle] = list(select_sl)
return fiber_groups
def fit_dkimicro(data_files,
bval_files,
bvec_files,
mask=None,
min_kurtosis=-1,
max_kurtosis=3,
out_dir=None,
b0_threshold=0):
"""
Fit the DKI model, save files with derived maps
Parameters
----------
data_files : str or list
Files containing DWI data. If this is a str, that's the full path to a
single file. If it's a list, each entry is a full path.
bval_files : str or list
Equivalent to `data_files`.
bvec_files : str or list
Equivalent to `data_files`.
mask : ndarray, optional
Binary mask, set to True or 1 in voxels to be processed.
Default: Process all voxels.
min_kurtosis : float, optional
The minimal plausible value of kurtosis. Default: -1.
max_kurtosis : float, optional
The maximal plausible value of kurtosis. Default: 3.
out_dir : str, optional
A full path to a directory to store the maps that get computed.
Default: maps get stored in the same directory as the last DWI file
in `data_files`.
b0_threshold : float
Returns
-------
file_paths : a dict with the derived maps that were computed and full-paths
to the files containing these maps.
Note
----
Maps that are calculated: FA, MD, AD, RD, MK, AK, RK
"""
img, data, gtab, mask = ut.prepare_data(data_files,
bval_files,
bvec_files,
mask=mask,
b0_threshold=b0_threshold)
dkimodel = dki_micro.KurtosisMicrostructureModel(gtab)
dkifit = dkimodel.fit(data, mask=mask)
AWF = dkifit.awf
T = dkifit.tortuosity
Da = dkifit.axonal_diffusivity
hRD = dkifit.hindered_rd
hAD = dkifit.hindered_ad
evals = dkifit.hindered_evals
hMD = (evals[..., 0] + evals[..., 1] + evals[..., 2]) / 3.0
params = dkifit.model_params
maps = [AWF, T, hAD, hRD, hMD, Da, params]
names = ['AWF', 'T', 'hAD', 'hRD', 'hMD', 'Da', 'params']
if out_dir is None:
if isinstance(data_files, list):
out_dir = op.join(op.split(data_files[0])[0], 'dki')
else:
out_dir = op.join(op.split(data_files)[0], 'dki')
if not op.exists(out_dir):
os.makedirs(out_dir)
aff = img.affine
file_paths = {}
for m, n in zip(maps, names):
file_paths[n] = op.join(out_dir, 'dkimicro_%s.nii.gz' % n)
nib.save(nib.Nifti1Image(m, aff), file_paths[n])
return file_paths
def fit_fwdti(data_files,
bval_files,
bvec_files,
mask=None,
out_dir=None,
b0_threshold=50):
"""
Fit the free water DTI model [1]_, save files with derived maps
Parameters
----------
data_files : str or list
Files containing DWI data. If this is a str, that's the full path to a
single file. If it's a list, each entry is a full path.
bval_files : str or list
Equivalent to `data_files`.
bvec_files : str or list
Equivalent to `data_files`.
mask : ndarray, optional
Binary mask, set to True or 1 in voxels to be processed.
Default: Process all voxels.
out_dir : str, optional
A full path to a directory to store the maps that get computed.
Default: maps get stored in the same directory as the last DWI file
in `data_files`.
b0_threshold : float
Returns
-------
file_paths : a dict with the derived maps that were computed and full-paths
to the files containing these maps.
Note
----
..[1] R. Neto Henriques, A. Rokem, E. Garyfallidis, S. St-Jean, E.T.
Peterson, M. Correia (2017). [Re] Optimization of a free water
elimination two-compartment model for diffusion tensor imaging.
*ReScience*
"""
img, data, gtab, mask = ut.prepare_data(data_files,
bval_files,
bvec_files,
mask=mask,
b0_threshold=b0_threshold)
fwmodel = fwdti.FreeWaterTensorModel(gtab)
fwfit = fwmodel.fit(data, mask=mask)
FA = fwfit.fa
MD = fwfit.md
AD = fwfit.ad
RD = fwfit.rd
fwvf = fwfit.f
params = fwfit.model_params
maps = [FA, MD, AD, RD, fwvf, params]
names = ['FA', 'MD', 'AD', 'RD', 'FWVF', 'params']
if out_dir is None:
if isinstance(data_files, list):
out_dir = op.join(op.split(data_files[0])[0], 'fwdti')
else:
out_dir = op.join(op.split(data_files)[0], 'fwdti')
if not op.exists(out_dir):
os.makedirs(out_dir)
aff = img.affine
file_paths = {}
for m, n in zip(maps, names):
file_paths[n] = op.join(out_dir, 'fwdti_%s.nii.gz' % n)
nib.save(nib.Nifti1Image(m, aff), file_paths[n])
return file_paths
def fit_csd(data_files,
bval_files,
bvec_files,
mask=None,
response=None,
b0_threshold=50,
sh_order=None,
lambda_=1,
tau=0.1,
out_dir=None,
msmt=False):
"""
Fit the CSD model and save file with SH coefficients.
Parameters
----------
data_files : str or list.
Files containing DWI data. If this is a str, that's the full path to a
single file. If it's a list, each entry is a full path.
bval_files : str or list.
Equivalent to `data_files`.
bvec_files : str or list.
Equivalent to `data_files`.
mask : ndarray, optional.
Binary mask, set to True or 1 in voxels to be processed.
Default: Process all voxels.
response: tuple, optional.
The response function to be used by CSD, as a tuple with two elements.
The first is the eigen-values as an (3,) ndarray and the second is
the signal value for the response function without diffusion-weighting
(i.e. S0). If not provided, auto_response will be used to calculate
these values.
b0_threshold : float,optional.
The value of diffusion-weighting under which we consider it to be
equivalent to 0. Default:50
sh_order : int, optional.
default: infer the number of parameters from the number of data
volumes, but no larger than 8.
lambda_ : float, optional.
weight given to the constrained-positivity regularization part of
the deconvolution equation. Default: 1
tau : float, optional.
threshold controlling the amplitude below which the corresponding
fODF is assumed to be zero. Ideally, tau should be set to
zero. However, to improve the stability of the algorithm, tau is
set to tau*100 % of the mean fODF amplitude (here, 10% by default)
(see [1]_). Default: 0.1
out_dir : str, optional
A full path to a directory to store the maps that get computed.
Default: file with coefficients gets stored in the same directory as
the first DWI file in `data_files`.
msmt : bool, optional
If False, standard single-shell CSD will be used. Otherwise,
Returns
-------
fname : the full path to the file containing the SH coefficients.
"""
img, data, gtab, mask = ut.prepare_data(data_files,
bval_files,
bvec_files,
b0_threshold=b0_threshold)
csdfit = _fit(gtab,
data,
mask,
response=response,
sh_order=sh_order,
lambda_=lambda_,
tau=tau,
msmt=msmt)
if out_dir is None:
out_dir = op.join(op.split(data_files)[0], 'dki')
if not op.exists(out_dir):
os.makedirs(out_dir)
aff = img.affine
fname = op.join(out_dir, 'csd_sh_coeff.nii.gz')
nib.save(nib.Nifti1Image(csdfit.shm_coeff, aff), fname)
return fname
