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=NOTHING, bzero=None, gradients=None, eddy_xfms=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

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

eddy_xfms

List of transforms to correct for estimated eddy current distortions.

classmethod from_filename(filename: Path | str) → DWI[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

gradients

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

set_transform(index: int, affine: ndarray, order: int = 3) → None[source]

Set an affine transform for a particular index and update the data object.

The new affine is set as in set_transform, and, in addition, the corresponding gradient vector is rotated.

Parameters:

  • index (int) – The volume index to transform.

  • affine (numpy.ndarray) – The 4x4 affine matrix to be applied.

  • order (int, optional) – The order of the spline interpolation.

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, insert_b0: bool = False, bvals_dec_places: int = 2, bvecs_dec_places: int = 6) → None[source]

Write a NIfTI file to disk.

Parameters:

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

  • insert_b0 (bool, optional) – Insert a \(b=0\) at the front of the output NIfTI.

  • 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.load(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 and construct a DWI object.

This function can load data from either an HDF5 file (if the filename ends with .h5) or 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 or HDF5).

  • 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).