Preprocessing

The package provides a set of functions useful for preprocessing of data, both general and some specific (currently limited to signal drift):

General

  • Averaging across diffusion encoding direction (API)

  • Combining imaging volume from separate files (API)

  • Extracting a subset of frames from an imaging volume (API)

Signal drift

  • Correcting for signal drift with a global correction (API)[1]

  • Correcting for signal drift with a spatiotemporal correction (API)[2]

Both algorithms for signal drift correction relies on acquisition of multiple b=0 imaging volumes distributed throughout the protocol.

References

API

ivim.preproc.base.average(im_file: str, bval_file: str, outbase: str, cval_file: str | None = None, avg_type: str = 'geo') → None

Average signal across encoding directions.

Parameters:

  • im_file – path to nifti image file

  • bval_file – path to .bval file

  • outbase – basis for output filenames, i.e. filename without file extension to which .nii.gz, .bval, etc. is added

  • cval_file – (optional) path to .cval file

  • avg_type – (optional) kind of averaging: ‘geo’ for geometric mean or ‘arith’ for arithmetic mean

ivim.preproc.base.combine(dwi_files: list, bval_files: list, outbase: str, bvec_files: list | None = None, cval_files: list | None = None, normb: float | None = None, roi_file: str | None = None) → None

Combine a set of dwi nifti files and the corresponding .bval, .bvec and .cval files to single files.

Parameters:

  • dwi_files – list of paths to nifti image file

  • bval_files – list of paths to .bval files

  • outbase – basis for output filenames, i.e. filename without file extension to which .nii.gz, .bval, etc. is added

  • bvec_files – (optional) list of paths to .bvec files

  • cval_files – (optional) list of paths to .cval files

  • normb – (optional) if set to a value in the data set, each data set is normalized towards the data at this b-value (typically normb = 0)

  • roi_file – (optional) path to nifti file defining a region-of-interest (ROI) used for normalization

ivim.preproc.base.extract(im_file: str, bval_file: str, outbase: str, bvec_file: str | None = None, b_ex: float = 0, cval_file: str | None = None, c_ex: float | None = None)

Extract data and b-values (optionally also c-values) equal to specific b-value (and optionally c-value).

Parameters:

  • im_file – path to nifti image file

  • bval_file – path to .bval file

  • outbase – basis for output filenames, i.e. filename without file extension to which .nii.gz, .bval, etc. is added

  • bvec_file – (optional) path to .bvec file

  • b_ex – (optional) b-value to extract, i.e. b_ex = 0 will extract data from all frames with b == 0

  • cval_file – (optional) path to .cval file

  • c_ex – (optional) c-value to extract in addition to condition given by b_ex, i.e. both b == b_ex and c == c_ex must be fulfilled for extraction

ivim.preproc.signal_drift.temporal(im_file: str, bval_file: str, outbase: str, roi_file: str | None = None, order: int = 2, ctm: str = 'mean', voxelwise: bool = False) → None

Correct for temporal signal drift by fitting a polynomial in time.

Parameters:

  • im_file – path to nifti image file

  • bval_file – path to .bval file

  • outbase – basis for output filenames, i.e. filename without file extension to which .nii.gz, .bval, etc. is added

  • roi_file – (optional) path to nifti file defining a region-of-interest (ROI) in which the correction is calculated and applied

  • order – (optional) order of estimated polynomial (1 or 2)

  • ctm – (optional) central tendency measure used to summarize the signal in the ROI, ‘mean’ or ‘median’

  • voxelwise – (optional) if True, one polynomial is fitted for each voxel, else one polynomial for the mean/median signal in the ROI

The correction follows the algorithm described by Vos et al. “The Importance of Correcting for Signal Drift in Diffusion MRI” https://doi.org/10.1002/mrm.26124

ivim.preproc.signal_drift.spatiotemporal(im_file: str, bval_file: str, outbase: str, roi_file: str | None = None, order: int = 2) → None

Correct for spatiotemporal signal drift by fitting a polynomial in space and time.

Parameters:

  • im_file – path to nifti image file

  • bval_file – path to .bval file

  • outbase – basis for output filenames, i.e. filename without file extension to which .nii.gz, .bval, etc. is added

  • roi_file – (optional) path to nifti file defining a region-of-interest (ROI) in which the correction is calculated and applied

  • order – (optional) order of estimated polynomial (1 or 2)

The correction follows the algorithm described by Hansen et al. in “Characterization and Correlation of Signal Drift in Diffusion Weighted MRI” https://doi.org/10.1016/j.mri.2018.11.009