nifreeze.data.dmri module

dMRI data representation.

nifreeze.data.dmri.DEFAULT_CLIP_PERCENTILE = 75

Upper percentile threshold for intensity clipping.

nifreeze.data.dmri.DEFAULT_HIGHB_THRESHOLD = 8000

A b-value cap for DWI data.

nifreeze.data.dmri.DEFAULT_LOWB_THRESHOLD = 50

The lower bound for the b-value so that the orientation is considered a DW volume.

nifreeze.data.dmri.DEFAULT_MAX_S0 = 1.0

Maximum value when considering the \(S_{0}\) DWI signal.

nifreeze.data.dmri.DEFAULT_MIN_S0 = 1e-05

Minimum value when considering the \(S_{0}\) DWI signal.

nifreeze.data.dmri.DEFAULT_MULTISHELL_BIN_COUNT_THR = 7

Default bin count to consider a multishell scheme.

nifreeze.data.dmri.DEFAULT_NUM_BINS = 15

Number of bins to classify b-values.

nifreeze.data.dmri.DTI_MIN_ORIENTATIONS = 6

Minimum number of nonzero b-values in a DWI dataset.

class nifreeze.data.dmri.DWI(self, dataobj: 'np.ndarray' = None, affine: 'np.ndarray' = None, brainmask: 'np.ndarray' = None, motion_affines: 'np.ndarray' = None, datahdr: 'SpatialHeader' = None, filepath: 'Path' = NOTHING, bzero: 'np.ndarray' = None, gradients: 'np.ndarray' = None, eddy_xfms: 'list' = None) → None[source]

Bases: BaseDataset[ndarray | None]

Data representation structure for dMRI data.

Method generated by attrs for class DWI.

property bvals
property bvecs
bzero: np.ndarray

A b=0 reference map, preferably obtained by some smart averaging.

eddy_xfms: list

List of transforms to correct for estimated eddy current distortions.

classmethod from_filename(filename: Path | str) → Self[source]

Read an HDF5 file from disk and create a DWI object.

Parameters:

filename (os.pathlike) – The HDF5 file path to read.

Returns:

The constructed dataset with data loaded from the file.

Return type:

DWI

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:

  • num_bins (int, optional) – Number of bins.

  • multishell_nonempty_bin_count_thr (int, optional) – Bin count to consider a multi-shell scheme.

  • bval_cap (int, optional) – Maximum b-value to be considered in a multi-shell scheme.

Returns:

Tuples of binned b-values and corresponding data/gradients indices.

Return type:

list

gradients: np.ndarray

A 2D numpy array of the gradient table (4xN).

to_filename(filename: Path | str, compression: str | None = None, compression_opts: Any = None) → None[source]

Write the dMRI dataset to an HDF5 file on disk.

Parameters:

  • filename (os.pathlike) – The HDF5 file path to write to.

  • compression (str, optional) – Compression strategy. See create_dataset documentation.

  • compression_opts (typing.Any, optional) – Parameters for compression filters.

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) → nibabel.Nifti1Image[source]

Export the dMRI object to disk (NIfTI, b-vecs, & b-vals files).

Parameters:

  • filename (os.pathlike) – The output NIfTI file path.

  • write_hmxfms (bool, optional) – If True, 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.

nifreeze.data.dmri.find_shelling_scheme(bvals: ndarray, num_bins: int = 15, multishell_nonempty_bin_count_thr: int = 7, bval_cap: float = 8000) → tuple[str, list[ndarray[Any, dtype[floating]]], list[floating]][source]

Find the shelling scheme on the given b-values.

Computes the histogram of the b-values according to num_bins and depending on the nonempty bin count, classify the shelling scheme as single-shell if they are 2 (low-b and a shell); multi-shell if they are below the multishell_nonempty_bin_count_thr value; and DSI otherwise.

Parameters:

  • bvals (list or ndarray) – List or array of b-values.

  • num_bins (int, optional) – Number of bins.

  • multishell_nonempty_bin_count_thr (int, optional) – Bin count to consider a multi-shell scheme.

  • bval_cap (float, optional) – Maximum b-value to be considered in a multi-shell scheme.

Returns:

  • scheme (str) – Shelling scheme.

  • bval_groups (list) – List of grouped b-values.

  • bval_estimated (list) – List of ‘estimated’ b-values as the median value of each b-value group.

nifreeze.data.dmri.from_nii(filename: Path | str, brainmask_file: Path | str | None = None, motion_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, b0_thres: float = 50) → DWI[source]

Load DWI data from NIfTI and construct a DWI object.

This function loads data from a NIfTI file, optionally loading a gradient table from either a separate gradients file or from .bvec / .bval files.

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.

  • motion_file (os.pathlike) – A file containing head motion affine matrices (linear)

  • gradients_file (os.pathlike, optional) – A text file containing the gradients table, shape (4, N) or (N, 4). If provided, it supersedes any .bvec / .bval combination.

  • bvec_file (os.pathlike, optional) – A text file containing b-vectors, shape (3, N).

  • bval_file (os.pathlike, optional) – A text file containing 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.

  • b0_thres (float, optional) – Threshold for determining which volumes are considered DWI vs. b=0 if you combine them in the same file.

Returns:

dwi – A DWI object containing the loaded data, gradient table, and optional b-zero volume, and brainmask.

Return type:

DWI

Raises:

RuntimeError – If no gradient information is provided (neither gradients_file nor bvec_file + bval_file).

nifreeze.data.dmri.transform_fsl_bvec(b_ijk: ndarray, xfm: ndarray, imaffine: ndarray, invert: bool = False) → ndarray[source]

Transform a b-vector from the original space to the new space defined by the affine.

Parameters:

  • b_ijk (ndarray) – The b-vector in FSL/DIPY conventions (i.e., voxel coordinates).

  • xfm (ndarray) – The affine transformation to apply. Please note that this is the inverse of the head-motion-correction affine, which maps coordinates from the realigned space to the moved (scan) space. In this case, we want to move the b-vector from the moved (scan) space into the realigned space.

  • imaffine (ndarray) – The image’s affine, to convert.

  • invert (bool, optional) – If True, the transformation will be inverted.

Returns:

The transformed b-vector in voxel coordinates (FSL/DIPY).

Return type:

ndarray