SPM/Working with 4D data

Working with four-dimensional data

Recent versions of SPM (SPM5 or later) can handle 4D NIfTI data-sets, which are often used to represent fMRI time-series of 3D volumes, as well as more general collections of related image volumes (such as the different tissue classes in DARTEL Templates).

The key to working with 4D data in the graphical user interface (e.g. after clicking Display or Check Reg, or selecting images in the batch interface) is to realise that the 1 shown in the image selection dialogue (on the right, just above the list of selected files) refers to the first volume or frame of a 4D data-set. Note that 3D data can be viewed as a special case of 4D data with a single volume, so this first (only) frame is appropriate for normal 3D images too.

To select volumes other than the first, you simply need to change the frame specification. To choose a particular frame you can replace the number 1 with the desired number, e.g. 10 or 100, but more usefully, you can enter a MATLAB range, and you will then see any/all volumes up to the upper limit, so entering 1:999 will let you select all volumes in a time-series of less than 1000 volumes. The volumes are shown with their frame number after a comma at the end of the filename.

With fMRI data, it is often very helpful to change the filter expression from '.*' to a regular expression that shows only the set of images you are interested in selecting (e.g. change it to '^u' to see only the realigned and unwarped images starting with a 'u') and then to change the frame range from 1 to '1:999' (or some number large enough to show all of your volumes) and then to right click and choose 'Select All'. For more help on the filter (regular expressions), click the '?' on the left of the dialogue.

The reason the frame range doesn't just default to something like 1:9999999, is that if you entered a directory with a very large number of NIfTI files, the interface would be very slow, because all of the NIfTI headers would need to be read to find out how many volumes each one actually contained (even if most contained just 1). Again, note that setting the filter before expanding the frame range can help in this instance.

An example

In the example illustrated here, I have used Check Reg, navigated to my SPM directory (using the Prev pull-down menu), entered the toolbox directory and then the Seg directory, which contains the tissue probability maps (TPMs) for the New Segmentation Toolbox (see also SPM -> Tools -> New Segment). There are six TPM volumes in the 4D TPM.nii NIfTI file; by changing the frame number from '1' to '1:10', I was able to see all six volumes, and I selected the second and third frames (shown as TPM.nii,2 and TPM.nii,3), which correspond to the white-matter and CSF tissue classes.

Further details

For advanced users, the batch system lets you create batches which select files according to a pattern, using:

BasicIO -> File Selector (Batch Mode)

In this case, entire 4D NIfTI files will be selected (with no ',n' frame number(s)). You can then use another batch module:

SPM -> Util -> Expand image frames

to reference the individual 4D file and associate a specified list or range of frames with it. The resultant set of volumes is then available as a dependency for use in later modules of the batch.

Finally, even more advanced users can simply add the frame numbers to filenames in MATLAB scripts, which even lets one work with five-dimensional data (!) that is sometimes used for multivariate data-sets (see e.g. pages 3 and 4 of this NIfTI diagram), by adding two numbers after commas. For example, to view the three (x, y and z) components that are stored in the fifth dimension of a 5D DARTEL velocity field (or just to show off!) you can do:

>> ims = [repmat('u_rc1Blah_Template.nii', 3, 1) [',1,1';',1,2';',1,3']]
>> spm_check_registration(ims)

To automatically expand the volumes from a 4D nifti file path, you can use on SPM12:

>> ims = spm_select('expand', fullfile(SCAN_dir,'SCAN.nii'))

For SPM8 and below, you have to manually count the number of volumes and expand yourself, here is a code snippet:

function n = spm_select_get_nbframes(file)
% spm_select_get_nbframes(file) Get the number of volumes of a 4D nifti file, excerpt from SPM12 spm_select.m
    N   = nifti(file);
    dim = [N.dat.dim 1 1 1 1 1];
    n   = dim(4);
end

function out = expand_4d_vols(nifti)
% expand_4d_vols(nifti)  Given a path to a 4D nifti file, count the number of volumes and generate a list of all volumes
    nb_vols = spm_select_get_nbframes(nifti);
    out = strcat(repmat(nifti, nb_vols, 1), ',', num2str([1:nb_vols]'));
end

You can then use:

>> ims = expand_4d_vols(fullfile(SCAN_dir,'SCAN.nii'))

Note that any of the techniques above can be used to select only a subset of the 4D volumes (eg, to discard first x volumes to avoid MRI saturation effects):

>> ims = cellstr(ims(4:end,:));

Creating 4D NIfTI files in SPM

SPM lets you concatenate multiple 3D volumes into a 4D NIfTI using the batch system:

SPM -> Util -> 3D to 4D File Conversion

The images must have identical dimensions, otherwise it isn't meaningful to consider them as one 4D data-set.

Note that this interface also lets you create a new 4D file using volumes selected from within an existing 4D file, which means you can do things like dropping T1-equilibration scans from the start of one 4D file by creating a new 4D file containing just the volumes you want to keep.

Separating 4D NIfTI files into 3D volumes

This page should have demonstrated that you do not need to split 4D data-sets into their constituent 3D volumes for use in SPM, whether using the interactive interface, batching or scripting. Sometimes though, you might want to split data-sets to work on the images in other software packages that do not handle 4D NIfTIs. For this, SPM provides a simple command-line tool (not in the batch interface, sorry), that you can use by typing:

>> spm_file_split

and then selecting (the first frame of) a 4D NIfTI. If you select Blah.nii, this will then create images of the form Blah_00001.nii, Blah_00002.nii, etc. See help spm_file_split for more flexible usage.