nifreeze.data.dmri.io module

Input/Output utilities for DWI objects.

nifreeze.data.dmri.io.GRADIENT_BVAL_BVEC_PRIORITY_WARN_MSG = 'Both a gradients table file and b-vec/val files are defined; ignoring b-vec/val files in favor of the gradients_file.'

“dMRI gradient file priority warning message.

nifreeze.data.dmri.io.GRADIENT_DATA_MISSING_ERROR = 'No gradient data provided.'

dMRI missing gradient data error message.

nifreeze.data.dmri.io.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, 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.

  • gradients_file (os.pathlike, optional) – A text file containing the gradients table, shape (N, C) where the last column stores the b-values. If provided following the column-major convention (C, N), it will be transposed automatically. If provided, it supersedes any .bvec / .bval combination.

  • bvec_file (os.pathlike, optional) – A text file containing b-vectors, shape (N, 3) or (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.

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.io.to_nifti(dwi, 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:

  • dwi (DWI) – A DWI object containing the diffusion data to be written, including the gradient table, and optional b-zero volume.

  • filename (os.pathlike, optional) – 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.

Returns:

nii – The main DWI data object.

Return type:

Nifti1Image