spectrIm-QMRS
Interactive MRS(I) Processing and Quantification

What is spectrIm-QMRS?

The feature rich desktop application spectrIm-QMRS is a tool for viewing, processing and quantifying clinical magnetic resonance spectroscopy data. The program name 'spectrIm-QMRS' consists of the words 'spectroscopy', 'imaging' and 'quantitative MRS(I)'.

The aim of the program is to offer the user a maximum of comfort in analyzing clinical- or research- MRS(I) dataset from clinical scanners.

This little website is intended to guide for interested persons to get a running spectrIm-QMRS version on their computer in a short time, and give detailed instructions of how to properly use the application.

Currently only Windows 10 and Windows 11 are supported. An Ubuntu Linux version will follow in the near future.

If you follow the steps below on this website you should be able to have a running version on your computer and made a prior knowledge model within one hour time.

Note: this is an alpha version of the program: although all features has been tested as good as possible, bugs cannot be excluded.

In case you find a bug sent us an email.

Where can I download spectrIm-QMRS?

If your web browser does not prevent you from downloading .zip files, you can here download the previous version of spectrIm-QMRS-64bit-v-2.0.9-alpha.zip here:

spectrIm-QMRS-64bit-v2.0.9-alpha.zip.
This is the previous version not supporting random fitting and ignoring sample points in the quentification.

Important note: If your browser pervents downloading of zip-files, than right-click the link to the zip-file link above and select the "Save link as .." item from the context menu.

Watch a video on where and how to download spectrIm-QMRS on your Windows 10 or Windows 11 computer.

The previous version of spectrIm-QMRS-64bit-v-2.0.10-alpha.zip here:

spectrIm-QMRS-64bit-v2.0.10-alpha.zip.
This is the latest version supporting random fitting and ignoring sample points in the quantification. Please note: At least two fit strategy steps are required. This is an implementation restriction, which will be solved in the next version of application.

The previous version is v2.0.11-alpha which is NOT backward compatible with previous versions (2.0.x; with x < 11). If you start using the spectrIm-QMRS you should start with downloading and using this version. If your web browser does not prevent you from downloading .zip files, you can here download the latest version of spectrIm-QMRS-64bit-v-2.0.11-alpha.zip here:
spectrIm-QMRS-64bit-v2.0.11-alpha.zip. This is the last version not supporting random fitting and ignoring sample points in the quantification.

The latest version is v2.0.12-alpha which is NOT backward compatible with previous versions (2.0.x; with x < 11). If you start using the spectrIm-QMRS you should start with downloading and using this version. If your web browser does not prevent you from downloading .zip files, you can here download the latest version of spectrIm-QMRS-64bit-v-2.0.12-alpha.zip here:
spectrIm-QMRS-64bit-v2.0.12-alpha.zip. This is the last version not supporting random fitting and ignoring sample points in the quantification. In this version the display bug in the TFDFitControlFrame: Gaussian lines were displayed with the wrong line width (computation was correct in all previous versions, though).

Last update of the software: September 20th 2024 :11:25 (new version 2.0.12-alpha not compatible with previous versions.).

Installing spectrIm-QMRS and system requirements

The application spectrIm-QMRS version 2.0.x [alpha] can be downloaded as zip-archive. It was developed in Netbeans 8.2 and runs on Windows 10 and Windows 11 computers and requires full HD-display for optimal display, as well as at least 4Gb RAM for smooth performance. Under Windows 10/11 tests have been performed. It is to be expected that it will also work under elder Windows versions, but cannot be guaranteed.

To run spectrIm-QMRS version 2.0.x alpha you need to have installed a 64 bits Java Runtime Environment (Version > 1.8). You can download the official Java RTE version via the following general download page of Oracle Java RTE 1.8 or newer. You need to select the Windows x64 version.

To run certain prepocessing steps you also need to have installed Python (>= Version 3.0 ) and the programming language R with spectrIm-QMRS together with the Random Forest package.

Watch a video on how to install the correct Python 3.10.13 version on your Windows 10 or Windows 11 computer. This step is very important, since it enables the use of a parallel running version of HLSVDpro on you Windows PC. Without HLSVDpro, accurate fitting of spectra is often hardly possible. In a later video we will show how to enable HLSVDpro, once it is installed.

How to get a quick overview of the functionality of spectrIm-QMRS

The desktop application spectrIm-QMRS was developed over a total period of 20 years. It is a graphical user interface based feature-rich application for processing and analysis of MRS(I) data. The application loads DICOM formatted MRI and several types of (proprietory) MRS(I) data. To get a quick overview over the gui, it is advisable to have a look at the description of the spectrIm-QMRS-menu.

This video shows how to download sample data from this website, and load this data into spectrIm-QMRS.

The following video example shows you how to: enable HLSVDpro in spectrIm-QMRS.

The following example shows you, once HLSVDpro runs, how to do a couple of post processing steps, and how to make simple spectroscopic images.

Finally in the following example shows you how to define a simple TDFDFit model and apply this model to a dataset, and make fitted spectroscopic maps.

What type of MRS(I) data can spectrIm-QMRS handle?

Therefore spectrIm-QRMS was designed for optimized workflow using clinical MRS(I) data, and therefore uses the DICOM file format as major source of input. It supports the following data formats, and has been tested for the following file format:

Standard DICOM Spectroscopy format
Siemens proprietary DICOM MRS data format
Siemens Standard Spectroscopy format
Siemens RDA file format
Enhanced Dicom Philips MRS data format

Also an import of preprocessed MIDAS EPSI data is possible. Other formats could be added upon request; criterium is that the spectroscopic data is shown together with MR-images, since there are many image viewers, many spectroscopy viewers but, apart from vendor solutions, a viewer that is able to show in vivo MR-spectra displayed in context of (anatomical) MR-images while offering easy to use state of the art quantification and analysis tools was still lacking.

Example Dicom test MRS(I) Data

To test and illustrate the features of spectrIm-QMRS, we added two anonymized MRSI examinations for download here:

Please note that the download can take a while due to the low bandwidth of the internet connection.
The first Siemens case is an in vivo case of a brain tumor (Siemens proprietory Dicom format):

The second case is post mortem case (Philips Enhanced Dicom format):

The data of both MR-examinations will be used to illistrate the workflow of spectrIm-QMRS throughout this website.

The graphical user interface of spectrIm-QMRS

The desktop application spectrIm-QMRS enables the user to load, view, model and analyze multidimensional in vivo datasets.

The GUI consist of following elements:

Top: The main spectrIm-QMRS-menu
Sub top: Toolbars.
Centre left: reference image with spectroscopic voxels projected into.
Centre right: Spectra related to selections on center left panel.
Centre right below: Processing pipeline related GUI.
Centre right lowest: Interal processing output.
Bottom left: The Study/Patient browser.
Bottom right: Dicom instances belonging to selection bottom left panel.

Functional Overview of spectrIm-QMRS

From a functional point of view, spectrIm-QMRS contains the following functionality:

spectrIm-QMRS main GUI

File I/O related
Loading of (individual) DICOM files via a file browser
Mounting of DICOM file containing directories
MR-examination explorer of multiple studies at a time
Export of spectral response data to .cvs, .mrui .mat files
Import of MIDAS created EPSI datasets
Import of .csv formatted result files (e.g. from external quantification software)
Viewing of spectroscopic data
Display of the spectral grids on top of arbitrary MR-image series
Single or multiple selected voxels and synchronized display of corresponding spectra in a spectrum viewer
Arbitrary shaped spectroscopic voxels of interest definition
Several display modes for selected spectroscopic voxels; Example below all individual spectra of the user selected voxels:

Several predefined color tables for use to display metabolic maps
Two predefined different selected spectroscopic volume groups, that is the "red" and the "blue" group. The two groups can de diplayed simultaneously to help clinician compare spectra originating from different locations in the dataset. Additionally, a difference spectrum can be diplayed between the red and the blue signal group.

Display of a 2D grid of selected spectra; example of a 4 x 4 selected subgrid:

MR Image display

The MR-image display can be manipulated via the spectrim_QMRS->Image menu:

Auto windowing (of gray values)
Set color scale
Print statistics of selected regions
Image segmentation (Single voxel only)

The functionality is described in more detail on the website: spectrim_QMRS->Image menu description.

Spectral processing, quantification and fitting

The spectrim_QMRS->Processing menu contains the most important functionality of spectrIm-QMRS. The following functionalty can be accessed via this menu:

spectrIm-QMRS: TDFDFitting Control

Loading/Saving of (individual) TDFDFit models
Creating new prior knowledge TDFDFit models
Set default models to be used in the main spectrIm-QMRS-window
Editing TDFDFit models

Add individual Voigt lines
Add spectrum responses from precalculated simulated basis sets:

jMUI format (binary)
TDFDFit format (binary)
Numeric pattern file format (spectrIm-QMRS format)

Add parametric patterns (not recommended)
Add metabolites (not recommended)
Removing spectral components

Easy definition of prior knowledge between spectral components
Definition of fitting strategy, for increasing the probability of reaching more acceptable fitting results

More details on making prior knowledge models you may find on TDFDFitting Control web pages.

Loading of Dicom data in spectrIm

The main idea behind spectrIm-QMRS was to provide an easy to use graphical user interface for analyzing MR-spectroscopic (imaging) information which can also be used by (neuro-) radiologists amongst being able to view at the same time. This is essential for establishing MR-spectroscopy within (neuro-) radiological routine. The application therefore supports DICOM typed as main source of image and spectroscopy information, since this the data format in clinical environment.
In order to fit in a clinical workflow, spectrIm-QMRS works patient/examination based. In a clinical setting everything is patient-oriented. In this context one patient can have one or more MR-examination(s) associated to it. spectrIm-QMRS tries to respect aspect. Although it is possible to load individual spectroscopy data, this is not the standard use of spectrIm. To analyze data of a patient (examination) a directory can be "mounted" and this directory is automatically parsed, and a treeview structure is build up. Images and spectroscopic data is automatically detected. If double-clicked by the mouse the dicom data gets loaded. Spectroscopic grid data will be placed automatically on top of the references images which will also automatically be resolved if available. Different image series backgrounds can be loaded. The aim is to be able to analyse the spectra together with the images of the same examination.

Alternatively binary formatted MIDAS EPSI can imported after first having imported spectroscopic image created to import the dimensions of the dataset and the orientation in space. After the association is made, arbitrary image series of the same examination can loaded as well. Further information you find file menu description.

There is also a possibility to import .csv files from the file system with signals

Interactive preprocessing of MRS(I) data

Under construction!

Creating a fitting model in spectrIm-QMRS

The main window of spectrim-QMRS application enables easy access to the spectrum modelling tool. Via the spectrIm-QMRS -> Processing -> Create new TDFDFit model.. menu item an new model can be created,
or via spectrIm-QMRS -> Processing -> Edit selected TDFDFit model ..
can be an already exiting prior knowledge spectral model can be further edited. Prerequisite for both actions are a loaded spectrum in the main window of spectrIm-QMRS.
Also via the following toolbar buttons either a new method can be defined (assuming the loaded and selected spectra as prototype model):

For the above spectrum after selecting create new spectral model (file menu item or toolbar button) the TDFDFitControl window will be displayed. If the user presses the "Add numeric pattern from mrui file" the system file browser opens and one or multiple simulated metabolites from a simultation basisset can be selected as indicated in the figure below. Basissets can not be simulated within spectrIm-QMRS. However, this may not be a too big disadvatage since many very good packages are available (e.g. NMRScopeA/B of jMRUI, GAVA, etc.).

After the simulated metabolites (i.e. basisset elements) are selected TDFDFittingControl loads the basisset and displays them in the model treeview (left) as well as on the spectrum display control (right). Note that the default line broadening is assumed, and also the sum of all spectral components of the model (red curve) are shifted w.r.t. the measured prototype spectrum (black curve). The selected spectral component in the model tree view is displayed in blue in the spectrum view.

After the user presses the "Optimize Prototype Model"-button in the lower left corner, the prototype spectrum is fitted using TDFDFit respecting the defined prior-knowledge by the user. How to define this prior-knowledge is defined somewhere else.
After a few seconds the user defined model is optimized w.r.t. prototype spectrum. and gets displayed:

Note that fitting with the simulated basisset (obtained with NMRSCOPE (Graveron et al. 1993) gives very good result, but need and can further be optimized using the control. This will be described in more details somewhere else.

Creating processing pipelines in spectrIm-QMRS

Under construction!

Saving and exporting your processed data in spectrIm-QMRS

Under construction!

Using spectrIm-QMRS as Dicom listener

If you are working in a clinical or hospital environment, and you want to use MR-spectroscopy as a day to day clinical tool, you either have the choice to use vendor postprocessing tools, some of which some are extremely rudimentary or at best provide take it or leave it unflexible post processing pipeline, limiting the way the data can be evaluated.
If you use non certified processing packages, there are more sophisticated analysis possibilities, but most of them are "off line" tools, if not all, which require manual export of the spectroscopic data. In a clinical workflow, manual interactions with the data can not be afforded, and an MRS(I) processing package should therefore support DICOM-network protocol as far as is possible to guarantee quick and unproblematic DICOM network transfer of the MRS(I) datasets.
For this reason spectrIm-QMRS implements a DICOM-network listener. To make spectrIm-QMRS to a (temporary) DICOM-listener. After launching this listener within spectrIm-QMRS, it it possible to transfer DICOM spectroscopy and image data to the PC that runs spectrIm-QMRS.
Please refer to the section "How to setup and use "spectrIm-QMRS" as DICOM node" for more details on this feature.

How to reference spectrIm-QMRS

If you like spectrIm-QMRS and you found it usefull in processing data for a publication, you may cite following paper:
Nuno Pedrosa de Barros, et al.,
"Automatic quality control in clinical 1H MRSI of brain cancer",
NMR in Biomedicine, 2016, Volume 29, Issue 5 p. 563-575

In vivo MR-spectroscopy

In vivo MR-spectroscopy emerged from NMR spectroscopy at the beginning of the 80-tees of last century ..