Input/Output

The package provides a set of functions useful for input/output of data, both general and vendorspecific (currently limited to Philips given the interest of the authors):

General

  • Reading image and corresponding b-value etc from file (API)

  • Save data to image file (API)

  • Read image, preserving dimensionality in contrast to the functions above (API)

  • Read b-value and other parameter files (API)

  • Save image (API)

  • Save b-value and other parameters to file (API)

Philips

  • Generate dti_vectors_input file for arbitrary diffusion encoding schemes (API)

API

ivim.io.base.data_from_file(im_file: str, bval_file: str, bvec_file: str | None = None, cval_file: str | None = None, roi_file: str | None = None)

Load image data (optionally from an ROI/mask) into a 2D array along with b-values, b-vectors, c-values.

Parameters:

  • im_file – path to nifti image file

  • bval_file – path to .bval file

  • bvec_file – (optional) path to .bvec file

  • cval_file – (optional) path to .cval file

  • roi_file – (optional) path to nifti file defining a region-of-interest (ROI) from with data is extracted

Output:

Y: 2D array containing the image data [number of voxels x number of b-values] b: vector containing the b-values v: matrix containing the diffusion encoding directions c: vector containgin the c-values (flow encoding)

ivim.io.base.file_from_data(filename: str, data: ndarray[Any, dtype[float64]], roi: ndarray[Any, dtype[bool_]] | None = None, imref_file: str | None = None) → None

Save image data in Nifti format based on input 2D array originating from optional roi.

Parameters:

  • filename – path to Nifti file

  • data – image data in v x n array (v is number of voxels, n gives size of 4th dimension in final image)

  • roi – (optional) region-of-interest from which data is assumed to originate. The number of True elements must match first dimension of data

  • imref_file – (optional) path to nifti file from which header info is obtained

ivim.io.base.read_im(filename: str | None) → ndarray[Any, dtype[float64]] | None

Load image in Nifti format.

Parameters:

filename – path to image file

Output:

im: image (or None if filename is None)

ivim.io.base.read_bval(filename: str) → ndarray[Any, dtype[float64]]

Load b-values from file in FSL format.

Parameters:

filename – path to cval file

Output:

b: b-values

ivim.io.base.read_cval(filename: str) → ndarray[Any, dtype[float64]]

Load c-values from file in format similar to FSL bval format.

Parameters:

filename – path to cval file

Output:

c: c-values

ivim.io.base.read_time(filename: str) → ndarray[Any, dtype[float64]]

Load time parameter from file in format similar to FSL bval format.

Parameters:

filename – path to time parameter file

Output:

t: time parameter

ivim.io.base.read_k(filename: str) → ndarray[Any, dtype[float64]]

Load k (for intermediate regime) from file in format similar to FSL bval format.

Parameters:

filename – path to k file

Output:

k: k (+/- 1)

ivim.io.base.read_bvec(filename: str) → ndarray[Any, dtype[float64]]

Load encoding directions from file in FSL bvec format.

Parameters:

filename – path to bvec file

Output:

v: encoding directions

ivim.io.base.write_im(filename: str, im: ndarray[Any, dtype[float64]], imref_file: str | None = None) → None

Save image in Nifti format.

Parameters:

  • filename – path to nifti file

  • im – image to save

  • imref_file – (optional) path to nifti file from which header info is obtained

ivim.io.base.write_bval(filename: str, b: ndarray[Any, dtype[float64]]) → None

Save encoding directions to file in FSL bval format.

Parameters:

  • filename – path to file

  • b – b-values

ivim.io.base.write_cval(filename: str, c: ndarray[Any, dtype[float64]]) → None

Save encoding directions to file in format similar to FSL bval.

Parameters:

  • filename – path to file

  • c – c-values

ivim.io.base.write_time(filename: str, t: ndarray[Any, dtype[float64]]) → None

Save time parameter to file in format similar to FSL bval.

Parameters:

  • filename – path to file

  • t – time parameter

ivim.io.base.write_k(filename: str, k: ndarray[Any, dtype[float64]]) → None

Save k to file in format similar to FSL bval.

Parameters:

  • filename – path to file

  • k – k

ivim.io.base.write_bvec(filename: str, v: ndarray[Any, dtype[float64]]) → None

Save encoding directions to file in FSL bvec format.

Parameters:

  • filename – path to file

  • v – 3 x n array with diffusion encoding directions

ivim.io.philips.generate_dti_vectors_input(b: ndarray[Any, dtype[float64]], filename: str, dualpol: bool = False, header: str = 'IVIM acquistion scheme') → None

Generate a dti_vectors_input file b-values and encoding directions (x, y, z or +/- x, y, z) throughout the scan.

Parameters:

  • b – b-values [s/mm2]

  • filename – path to dti_vectors_input file

  • dualpol – (optional) if False, three encoding directions are used (x, y, z), if True six encoding directions are used (+/- x, y, z)

  • header – (optional) title written to the dti_vectors_input file

ivim.io.philips.write_dti_vectors_input(X: ndarray[Any, dtype[float64]], filename: str, header: str = '') → None

Save dti_vectors_input file in specified format.

Parameters:

  • X – 2D array were each row defines a 4-element tuple with the encoding direction in the first three elements and the b-value in the fourth.

  • filename – path to dti_vectors_input file

  • header – (optional) title written to the dti_vectors_input file

ivim.io.philips.read_dti_vectors_input(filename: str) → ndarray[Any, dtype[float64]]

Load dti_vectors_input file.

Parameters:

filename – path to dti_vectors_input file

Output:

X: 2D array were each row defines a 4-element tuple with the encoding direction in the first three elements and the b-value in the fourth.