11.1. Converting NIfTI / DICOM data to the imgfile format

Most MRI data are stored in either:

  • DICOM files exported from the scanner, or

  • NIfTI files (e.g. .nii or .nii.gz), often after basic preprocessing.

DRSuite does not read these formats directly. Instead, it expects a single MATLAB .mat file following the imgfile convention.

11.1.1. Goal

The goal of this tutorial is to show how to convert standard MRI data (e.g., NIfTI volumes exported from your scanner or preprocessing pipeline) into the DRSuite imgfile format. At the end of this tutorial, you will have a .mat file called imgfile that contains the four variables required by DRSuite:

  • data: multidimensional MR image array

  • resolution: voxel size along each spatial dimension

  • spatial_dim: spatial matrix size

  • transform: 4×4 voxel-to-world transform matrix

You can then use this imgfile directly in the DRSuite tools such as Spectrum Estimation, Plot Spectroscopic image and Registration.

11.1.2. Step 1: Understand your NIfTI layout

NIfTI files typically store the data in an array shaped like

  • 3D volume: \(N_x \times N_y \times N_z\)

  • 4D series: \(N_x \times N_y \times N_z \times N_t\)

Common examples of \(N_t\) include different:

  • diffusion directions,

  • b-values,

  • echo times (TE),

  • repetitions, or

  • combinations of the above.

DRSuite’s data uses the convention

\[\texttt{data} \in \mathbb{C}^{N_a \times N_1 \times N_2 \times N_3},\]

where:

  • \(N_a\) = number of acquisitions (e.g. all diffusion directions / TEs / repeats),

  • \(N_1, N_2, N_3\) = spatial dimensions.

Key decision: You must decide which NIfTI axis corresponds to \(N_a\) and which axes correspond to \(N_1, N_2, N_3\). In many cases:

  • \(N_x \to N_1\), \(N_y \to N_2\), \(N_z \to N_3\),

  • \(N_t \to N_a\) (the acquisition dimension).

Once this mapping is clear, you reshape / permute the NIfTI array so that the first dimension is \(N_a\) and the remaining dimensions are the three spatial axes expected by DRSuite.

Typical pitfalls

  • Treating a spatial axis as the acquisition axis by mistake (e.g. confusing \(N_z\) with \(N_a\)).

  • Having more than three spatial axes (e.g. multi-slab or multi-echo data) and not deciding clearly which dimensions should be treated as acquisitions.

  • Forgetting that DRSuite assumes each slice in \(N_3\) is processed sequentially, so \(N_3\) should remain a spatial dimension.

11.1.3. Step 2: Build the data variable

After you’ve decided the mapping, you need to reorder the array so that the dimensions match one of the supported shapes:

  • \(N_a \times N_1 \times N_2 \times N_3\) (3D volume)

  • \(N_a \times N_1 \times N_2\) (2D)

  • \(N_a \times N_1\) (1D)

Common operations at this step include:

  • Permuting axes so that acquisitions become the first dimension.

  • Reshaping if your acquisition dimension is spread across multiple axes (e.g. directions × echoes flattened into a single \(N_a\)).

  • Ensuring the data type is appropriate (e.g. magnitude vs. complex).

Typical pitfalls

  • Forgetting to permute the acquisition dimension to the first position.

  • Accidentally flattening spatial dimensions into the acquisition dimension.

  • Ignoring complex data (if your pipeline keeps real and imaginary parts separately, you will need to combine them before saving to data).

11.1.4. Step 3: Set resolution

The resolution variable is a 1×3 vector:

resolution = [vox_dim_1 vox_dim_2 vox_dim_3]

where:

  • vox_dim_i = voxel size along the \(i\)-th spatial dimension.

In NIfTI, these values usually come from the pixel dimensions (often called pixdim) and correspond to the physical size (e.g. in mm) along each spatial axis. You should match the ordering of resolution with the ordering of your spatial dimensions \(N_1, N_2, N_3\).

Typical pitfalls

  • Mixing up the order of voxel sizes (e.g. using [dy dx dz] instead of [dx dy dz]).

  • Using units incorrectly (e.g. cm instead of mm).

  • Forgetting to update resolution after resampling or interpolating the data.

11.1.5. Step 4: Set spatial_dim

The spatial_dim variable is a vector containing the spatial matrix size:

  • 3D data: [N1 N2 N3]

  • 2D data: [N1 N2]

These must correspond exactly to the spatial dimensions of your data variable after you’ve permuted it into DRSuite’s convention.

Important note: Spatial dimension cannot be purely 1D in DRSuite’s current implementation. Even if your problem is conceptually 1D, your data may still be stored as 2D/3D with singleton dimensions.

Typical pitfalls

  • Using the acquisition dimension \(N_a\) in spatial_dim by mistake.

  • Forgetting to update spatial_dim after subsetting the data (e.g. cropping FOV).

11.1.6. Step 5: Set the 4×4 transform matrix

The transform variable stores a 4×4 matrix that maps voxel coordinates to a chosen world / scanner coordinate system. For NIfTI, this information usually comes from the qform or sform affine matrix.

In most cases, you can simply:

  • Extract the NIfTI affine matrix, and

  • Store it directly as transform.

If you do not care about absolute spatial coordinates (for example, in some phantom or simulation experiments), you can set transform to the identity matrix and interpret voxel indices in a purely relative way.

Typical pitfalls

  • Ignoring qform/sform and always using the identity matrix, which can break registration and multi-modal alignment.

  • Permuting data axes but forgetting to adjust the transform accordingly (if you change the ordering of spatial dimensions, the corresponding affine should be permuted in a consistent way).

11.1.7. Step 6: Save the imgfile

After constructing:

  • data

  • resolution

  • spatial_dim

  • transform

you save them to a single MATLAB .mat file, e.g.:

imgfile = 'my_subject_imgfile.mat';

% MATLAB example
save(imgfile, 'data', 'resolution', 'spatial_dim', 'transform');

This imgfile can now be used throughout DRSuite wherever an imgfile is required.

11.1.8. What about DICOM input?

DRSuite does not provide a dedicated DICOM reader. Instead, we recommend the following workflow:

  1. Convert your DICOM series to NIfTI using your preferred tool (e.g., scanner-provided utilities or standard DICOM→NIfTI converters).

  2. Once you have the NIfTI files, follow exactly the same steps described in this tutorial to produce the imgfile:

    • Load the NIfTI volume(s),

    • Map the dimensions to DRSuite’s data format,

    • Set resolution, spatial_dim, and transform,

    • Save everything into a .mat file.