nifreeze.data.dmri package¶
dMRI data representation¶
This submodule implements data structures and I/O utilities for diffusion MRI data. Please, beware that NiFreeze is very opinionated about the gradients and diffusion data representation.
Gradient Table Representation.
The DWI class represents diffusion MRI data must
be provided a gradient table, which is a numpy.ndarray of shape (N, 4), where
N is the number of diffusion-weighted volumes.
The first three columns represent the gradient directions (b-vectors), and the fourth column
represents the b-values in s/mm².
NiFreeze expects that the gradient directions are normalized to unit length for non-zero
b-values, and that the \(b=0\) volumes have a gradient direction of \((0, 0, 0)\).
When non-unit b-vectors are detected, the corresponding b-value is automatically adjusted to
reflect the actual diffusion weighting.
If the input gradient table does not conform to these expectations, it will be automatically
corrected upon loading.
This means that, if you need to prepare the gradient table in a specific way (e.g., you don’t
want normalization of b-vectors to modify the b-values), you should do so before initializing
the DWI object.
Data Representation.
The DWI class requires a 4D dataobj with the volumes on the
first axis, (N, X, Y, Z), one volume per row of the gradient table (NIfTI files store volumes
on the last axis; from_nii() converts them).
The final step of the initialization process examines the data object and the gradient table,
and removes \(b=0\) volumes from the data AND the gradient table.
If a bzero parameter is provided, the bzero attribute
is set to its value. Note that a 3D volume is accepted.
If no bzero parameter is provided, a reference low-b volume is computed as the median of all
the low-b volumes (b < DEFAULT_LOWB_THRESHOLD s/mm²) and
inserted in the bzero attribute.
If \(b=0\) values are detected in the gradient table the dataobj
and gradients attributes will have their \(b=0\) indices
data removed.
If both a bzero value is provided and \(b=0\) values are detected in the gradient
table, the :math:`b=0 volumes will be discarded, and the corresponding
dataobj and gradients
indices data will be removed.
Therefore, *NiFreeze* WILL NOT be able to reconstruct the original data organization.
This design choice simplifies the internal representation and processing of diffusion MRI data.
If you want to calculate a \(b=0\) reference map in a more sophisticated way (e.g., after
realignment of all the low-b volumes), you should handle this separately and feed your own
reference through the bzero parameter.
- class nifreeze.data.dmri.DWI(self, dataobj: 'Any' = None, affine: 'np.ndarray' = None, brainmask: 'np.ndarray | None' = None, motion_affines: 'np.ndarray | None' = None, datahdr: 'nb.Nifti1Header | None' = None, filepath: 'Path' = NOTHING, gradients: 'npt.ArrayLike | None' = None, bzero: 'np.ndarray | None' = None, eddy_xfms: 'list' = None) None[source]¶
Bases:
BaseDataset[ndarray]Data representation structure for dMRI data.
Method generated by attrs for class DWI.
- property bvals¶
- property bvecs¶
- classmethod from_filename(filename: Path | str) Self[source]¶
Read an HDF5 file from disk and create a DWI object.
Files older than version 3 do not record the frame of their gradient table, which is read as RAS+B with a warning (see nfHDF5).
- Parameters:
filename (
os.pathlike) – The HDF5 file path to read.- Returns:
The constructed dataset with data loaded from the file.
- Return type:
- get_shells(num_bins: int = 15, multishell_nonempty_bin_count_thr: int = 7, bval_cap: int = 8000) list[source]¶
Get the shell data according to the b-value groups.
Bin the shell data according to the b-value groups found by
find_shelling_scheme.- Parameters:
- Returns:
Tuples of binned b-values and corresponding data/gradients indices.
- Return type:
- gradients: ndarray¶
a unit b-vector in world RAS+ coordinates (the frame the affine maps voxels into), then the b-value in s/mm².
- Type:
The gradient table,
(N, 4)
- realign_into(view: Self, index: int, order: int = 3) None[source]¶
Write volume
indexand its b-vector into a realigned view.Besides the volume (see
BaseDataset.realign_into), the original b-vector is turned into the reference’s frame by the estimate’s rotation, as at export (seerealign_bvecs()). The view’s whole gradient table is reassigned, so an integer table is never truncated.
- to_filename(filename: Path | str, compression: str | None = None, compression_opts: Any = None) None[source]¶
Write the dMRI dataset to an nfHDF5 file on disk.
- to_nifti(filename: Path | str | None = None, write_hmxfms: bool = False, order: int = 3, insert_b0: bool = False, bvals_dec_places: int = 2, bvecs_dec_places: int = 6) Nifti1Image[source]¶
Export the dMRI object to disk (NIfTI, b-vecs, & b-vals files).
- Parameters:
filename (
os.pathlike, optional) – The output NIfTI file path.write_hmxfms (
bool, optional) – IfTrue, the head motion affines will be written out to filesystem with BIDS’ X5 format.order (
int, optional) – The interpolation order to use when resampling the data. Defaults to 3 (cubic interpolation).insert_b0 (
bool, optional) – Insert a \(b=0\) at the front of the output NIfTI and add the corresponding null gradient value to the output bval/bvec files.bvals_dec_places (
int, optional) – Decimal places to use when serializing b-values.bvecs_dec_places (
int, optional) – Decimal places to use when serializing b-vectors.
- Returns:
NIfTI image written to disk.
- Return type:
- nifreeze.data.dmri.from_nii(filename: Path | str, brainmask_file: Path | str | None = None, gradients_file: Path | str | None = None, bvec_file: Path | str | None = None, bval_file: Path | str | None = None, b0_file: Path | str | None = None) DWI[source]¶
Load DWI data from NIfTI and construct a DWI object.
This function loads data from a NIfTI file, and its gradient table from either a RAS+B file or FSL’s
.bvecand.bvalfiles, which are converted into RAS+B with the image’s affine.- Parameters:
filename (
os.pathlike) – The main DWI data file (NIfTI).brainmask_file (
os.pathlike, optional) – A brainmask NIfTI file. If provided, will be loaded and stored in the returned dataset.gradients_file (
os.pathlike, optional) – A RAS+B gradient table (seeload_rasb()): MRtrix’s.b, NiPreps’.tsv, or any text file ofNrowsR A S B. A table with one column per volume (four rows) is transposed. If provided, it supersedes any .bvec / .bval combination.bvec_file (
os.pathlike, optional) – FSL’s b-vectors, shape (3, N) or (N, 3) (seeload_bvec_bval()).bval_file (
os.pathlike, optional) – FSL’s b-values, shape (N,).b0_file (
os.pathlike, optional) – A NIfTI file containing a b=0 volume (possibly averaged or reference). If not provided, and the data contains at least one b=0 volume, one will be computed.
- Returns:
dwi – A DWI object containing the loaded data, gradient table, and optional b-zero volume, and brainmask.
- Return type:
- Raises:
RuntimeError – If no gradient information is provided (neither
gradients_filenorbvec_file+bval_file).