Handling and Inspecting Data from the Scanner

This mini practical covers two example boxes in Chapter 3: "Data Conversion to NifTI-MRS", and "Peek at the data". Both boxes appear on Page 76. As with all these mini-practicals, instructions on how to run FSL commands can be found on the Getting Started page.

This example will help you understand how you can:

Understand data that comes from the scanner
Convert it to a useful and standardised format
Inspect what the data shape, contents, and metadata are.

A particularly tricky part of MRS analysis is handling the disparate types of data that come from different vendor's scanners, or even the many possible types from the same scanner. You can't just rely on file type to know what data is in a file. This is why FSL-MRS uses the spec2nii tool to convert data to a standard format.

Please download the dataset for this practical using the button below. After download unzip the contents into a directory called data_ch3_conversion.

Data download

Example Box: Data Conversion to NIfTI-MRS

What files should I use?

In this practical we will follow the conversion of two sets of data in two different formats: DICOM and Siemens's proprietary TWIX/.dat format. We will then follow the processing of this data through the following SVS processing stages.

Conversion using spec2nii

spec2nii is a command line too that comes with FSL for converting SVS and reconstructed MRSI data to the standard NIfTI-MRS format. Once in NIfTI-MRS we can process and visualise our data using standard tools.

To get started cd into the appropriate data directory:

cd data_ch3_conversion

Siemens TWIX / .dat format

We'll start by converting the (unedited) single voxel data we will process and fit in the later practicals. This data was collected on a Siemens 7T scanner, and exported in one of Siemens proprietary, raw formats, .dat, sometimes known as TWIX after the name of the program used to export it (and presumably someone's favourite chocolate bar.)

This format can be quite complex, and will always contain fully unprocessed data. We therefore expect it to have many data dimensions and possibly integrated references or auxiliary scans. As such, spec2nii contains methods for inspecting .dat data before conversion. Let's look at the data from the water suppressed acquisition first, by using the --view / -v option.

spec2nii twix -v siemens_twix/meas_MID310_STEAM_metab_FID115673.dat

The output should be:

Software version: VB
Contents of file meas_MID310_STEAM_metab_FID115673.dat:                                                                                                                                                                      
The file contains these evalinfo flags with dimensions and sizes as follows:
image          :        Col, Cha, Set           [4096   32   64]
phasecor       :        Col, Cha                [4096   32]

From this we can see that there are two sets of data:

image, which by convention is the primary acquisition, and has dimensins of 4096 x 32 x 64, and
phasecor, which contains much less data, 4096 x 32.

The dimensions (Col, Cha, Set) correspond to the timepoints in the FID, the number of receive coils, and the number of temporal averages. Col and Cha are consistent in meaning between datasets, but the label applied to the temporal averages changes with version. If we know how the data was collected, then we can always use that knowledge to interpret this information: the RF coil has 32 elements, and we chose to use 64 averages.

In this case, phasecor is a single integrated unsuppressed water scan (water reference). Do not assume this will be present in every sequence, it is not.

Run the same command on the separate water reference data:

spec2nii twix -v siemens_twix/meas_MID311_STEAM_wref_FID115674.dat

This time we see a very similar output, but with a smaller data size, only two averages in the image class. This is because the water reference signal is much stronger than the metabolites, so we only need one or two averages. Note: the water reference has its own integrated reference, purely a left-over of the implementation.

Software version: VB
Contents of file meas_MID311_STEAM_wref_FID115674.dat:                                                                                                                                                                       
The file contains these evalinfo flags with dimensions and sizes as follows:
image          :        Col, Cha, Rep           [4096   32    2]
phasecor       :        Col, Cha                [4096   32]

Now let's actually convert the data. First, the water suppressed data, from which we want the image category. You can specify the output location and name of the file.

spec2nii twix -e image -o nifti -f steam_metab_raw siemens_twix/meas_MID310_STEAM_metab_FID115673.dat

We do the same with the dedicated water reference.

spec2nii twix -e image -o nifti -f steam_wref_raw siemens_twix/meas_MID311_STEAM_wref_FID115674.dat

The data is now converted. We will look at what's in it after we've explored the spec2nii tools a little more.

Siemens DICOM format

The DICOM file type is the standard medical imaging file format. Nearly all scanner vendors use it in some capacity to export MRS data, though the implementation is variable. Here we will convert single-voxel MEGA-edited data stored in the format.

To start with, we have downloaded three series of DICOM files, each series is contained in one folder. The series correspond to the main water-suppressed acquisition, and two water references (one with and one without eddy currents).

We can convert each in turn using spec2nii dicom:

spec2nii dicom siemens_dicom/mega_press_TR2000_V1__10_1 -o nifti_dicom -f mpress_metab_raw

For the water references, we know that only a single average was acquired, but two files are in each folder. These two files correspond to the two editing conditions. As such, we don't want to label the repeats as temporal averages, but as DIM_EDIT. We can specify this using the -t flag.

spec2nii dicom siemens_dicom/mega_press_wref1_V1_11_1 -o nifti_dicom -f wref_ecc -t DIM_EDIT
spec2nii dicom siemens_dicom/mega_press_wref3_V1_12_1 -o nifti_dicom -f wref_quant -t DIM_EDIT

A few other formats

spec2nii handles a number of other formats. These include:

Siemens .rda
United imaging DICOM
Philips SPAR/SDAT
Philips .data/.list
Philips DICOM
GE p-files
jMRUI formats
LCModel RAW format
Bruker "fid" format
Limited Varian support

The syntax for the most common of these are shown below as examples (no data provided).

Philips SPAR/SDAT

spec2nii philips .SDAT .SPAR

Philips DICOM

spec2nii philips_dcm .DCM

GE p-files / .7

spec2nii ge .7

Automatic conversion

spec2nii can attempt to automatically figure out the correct conversion routine from the data using the auto option. Note not all options and formats are exposed through this option.

spec2nii auto file.extension

Special conversion tools: spec2nii dump and anon

We can use spec2nii dump to inspect the detailed meta-data contents of a converted NIfTI-MRS file. Do this now for the unedited data we converted from twix format.

spec2nii dump nifti/steam_metab_raw.nii.gz

The first part of the output lists the NIfTI header, which contains lots of infomration about the data size and the encoded orientation (the latter is held in the various sform and qform fields). The second part of the output contains MRS-specific key:value pairs.

You might note that there are some (made up) patient identifying fields in the second part (PatientDoB, PatientName, etc), let's try removing these using spec2nii.

spec2nii anon nifti/steam_metab_raw.nii.gz -o nifti -f anon
spec2nii dump nifti/anon.nii.gz

If you need to manually edit the content of the NIfTI-MRS header spec2nii has two sub-commands that allow you to extract the header as an editable JSON file, before insert(ing) the modified header bac into the file.

Now a preconfigured list of potentially sensitive fields have been removed.

Example Box: Peek at the data

After converting the data, we can check its structure and any available metadata using the tools above. However, to validate that we have a) converted the right file, b) make decisions about the processing, or c) even find out what is in the file we might need to have a look at the spectroscopic data itself. There is a chance that even after conversion we might need to reorganise, split or combine bits of data before processing.

There is an MRS-specific command line tool for this in FSL-MRS: mrs_tools. This commandline tool can interrogate, visualise and manipulate NIfTI-MRS data. Note: we will see more advanced visualisation tools in the next practical.

mrs_tools info

Let's use mrs_tools to look at the edited data we converted from DICOM.

mrs_tools info nifti_dicom/metab_raw.nii.gz

This produces a short summary of the data shape and some key, identifying meta-data

File metab_raw.nii.gz (.../nifti_dicom)
NIfTI-MRS version 0.9
Data shape (1, 1, 1, 2048, 256)
Dimension tags: ['DIM_DYN', None, None]
Spectrometer Frequency: 123.255795 MHz
Dwelltime (Spectral bandwidth): 2.500E-04 s (4000 Hz)
Nucleus: 1H
Field Strength: 2.89 T

We see some expected values, 1H, 2.89 T (a Siemens 3T), but we can also see that there is only a single dimension of data, 256 elements long, labelled as temporal averages (DIM_DYN). We know this is MEGA-edited data, so we expect a 2-element long DIM_EDIT dimension as well.

mrs_tools reshape

Let's use another of the mrs_tools commands to reshape this data into one that has an editing dimension. mrs_tools reshape uses Numpy-like reshaping to form new or remove unwanted dimensions.

mrs_tools reshape \
    --file nifti_dicom/metab_raw.nii.gz \
    --shape 2 -1 \
    --d5 DIM_EDIT \
    --d6 DIM_DYN \
    --output nifti_dicom \
    --filename metab_reshaped

We can check that this has worked by using a visualisation command explained in the next practical.

mrs_tools vis nifti_dicom/metab_reshaped.nii.gz --display_dim DIM_EDIT --no_mean

The output, showing two spectra, one with NAA suppressed, indicates that we have successfully reshaped the data. We will see more of mrs_tools vis in later practicals

If all we want to achieve is a reordering or relabelling of the dimensions (preserving size), then one can use the mrs_tools reorder command to achieve this.

mrs_tools split and merge

Sometimes we collect data that we want to analyse together in several separate acquisitions, perhaps so we can issue instructions or check shim adjustments. In this case the tools mrs_tools split/merge are useful.

Try splitting the data using mrs_tools split along the temporal averages dimension DIM_DYN, before recombining it using mrs_tools merge

mrs_tools split \
--file nifti_dicom/metab_reshaped.nii.gz \
--dim DIM_DYN \
--index 63 \
--output nifti_dicom \
--filename split

Check the file shapes using mrs_tools info

mrs_tools info nifti_dicom/split_low.nii.gz
mrs_tools info nifti_dicom/split_high.nii.gz

Finally try recombining the files with an additional dimension. This can be achieved by using the --newaxis flag combined with the (generic) tag of the new dimension DIM_USER_0.

mrs_tools merge \
--files nifti_dicom/split_high.nii.gz nifti_dicom/split_low.nii.gz \
--dim DIM_USER_0 \
--newaxis \
--output nifti_dicom \
--filename merged

Inspect the output

mrs_tools info nifti_dicom/merged.nii.gz

to see a 2 (edit) x 64 (temporal averages) x 2 (new) piece of data ...

...
Data shape (1, 1, 1, 2048, 2, 64, 2)
Dimension tags: ['DIM_EDIT', 'DIM_DYN', 'DIM_USER_0']
...

More about spec2nii and NIfTI-MRS

spec2nii is developed by the authors of the FSL-MRS toolbox, but it is also contributed to by the wider MRS development community. If you find that your specific data format is not handled by the tool, or it handles something incorrectly, then reach out to the developers on the spec2nii development page.

The NIfTI-MRS format was created by the ISMRM MRS study group, and the standard is both published online and has its own documentation. The NIfTI-MRS software tools (like mrs_tools) are published separately of FSL and can be found in their own Github repository.

A discussion of all the relevant tools and formats can be found in the paper NIfTI-MRS: A standard data format for magnetic resonance spectroscopy .