jMRUI2XML has a graphical user interface (GUI) developed in Java on the jMRUI plug-in platform, and adheres to the Model View Controller design pattern. It is aimed at two goals, firstly, automating MRS processing, and secondly, serving as a platform for outputting exchangeable data for use in pattern recognition. jMRUI’s current architecture allows for easy development of four categories of plugins (conversion, preprocessing, quantitation, and custom) via interface implementation [12].
The jMRUI2XML GUI is aimed at being a user-friendly and straightforward tool; resembling a form, where the users select only the steps they are interested in. It consists of three tabs: Preprocessing, Meta Data and LabelsMV (see Fig. 1). The first tab contains all the Preprocessing steps along with some additional information that can be added to the output. The second tab contains a text-editor-like interface that is also added to the output, and the last tab will be used in case the user wants to provide labels for the individual voxels of a MV acquisition. jMRUI2XML saves the processed spectra along with preprocessing details in an XML file.
jMRUI2XML functionality and interface description
Pre-processing tab
Fig. 1 shows the interface with the Preprocessing tab in foreground. This tab entails ten steps labelled with a roman number and a descriptive name. The first eight steps (I through VIII) are purely preprocessing steps and the last two (IX and X) serve as meta-data input. It must be said that the preprocessing steps are performed in increasing order of their roman numbering – the lower numbers are performed first.
The first three steps, i.e. Set Reference, Apodize, and Water filtering, were already available algorithms in jMRUI. Step I, Set Reference, takes as input a value in ppm that will represent the new reference. For example, one may set the reference to 4.75 ppm for unsuppressed water in proton spectra. Step II, Apodize, is used for line broadening with either a Gaussian or a Lorentzian function of a certain line-width (input given in Hz). Step III, Water Filtering, uses the HLSVD algorithm [17, 18] to commonly filter the water signal in case of proton spectra. The interface requires as input the number of Lorentzians to be used and can filter simultaneously up to three regions (units for filtered range in ppm). By allowing multiple filtering regions the users can filter any signal they need, not only water. We emphasize this because our plugin should not be seen as being limited to proton spectra. Step II and III are carried out in the time-domain.
In step IV, Baseline Correction, users may choose up to three regions (units for range to correct in ppm) to use in performing baseline correction. The means of the data points heights in the given ranges are summed up and their mean is taken; this value is then subtracted from each data point height of the spectral vector. The algorithm can only perform appropriate correction to a baseline that is not sloped.
Step V, Change number of points in specified range, allows the user to enforce a strict number of points in a certain ppm range. If the spectra have more points in the specified range then the algorithm will undersample the frequency vector by skipping values; if there are less points than desired then the algorithm does zero filling (in the time domain), as required. This is the step that allows the user to homogenize the spectral range and number of points, for example two spectra, one with spectral width of 2500 Hz and 2048 points and the other with 1000 Hz and 512 points.
Set to zero, the VI-th step, can set to 0 the spectral points in up to two intervals (in ppm). This step can be useful, for example in 1H-MRS, when water suppression was poorly performed yet the user needs that residual contribution, for example to vector normalization, to be negligible.
Step VII – Normalization will perform l2 normalization [19], also named Unit Length, on the spectra. Currently only this type of normalization is defined in the plugin. The definition of an l2 norm of is shown in Eq. 1:
$$ \left|x\right| = \sqrt{{\displaystyle \sum_{k=1}^n}\left|{x}_k\right|{}^2} $$
(1)
where n is the number of spectral points in the spectral vector x. An l2 normalized spectrum will have each value from k = 1 to n divided by the l2 norm, |x|.
It is recommended to perform this step because the amplitude of the spectrum is expressed as arbitrary units and may vary from scanner to scanner. The l2 normalization brings all spectra within the same relative range on the y axis. Again, if the purpose is to unify the number of points and the sweep widths that step (referring to step V) must be performed before Step VII.
Finally, the last procedure that can be applied is Step VIII, Alignment Correction. This eighth step will correct for slight misalignments of the spectrum according to a theoretical value of some preset reference peak(s) (±10 points in the frequency vector – in the frequency domain, note that this means a smaller ppm range for higher resolution data). If one chooses this step, the first thing is to let the system know if the spectra to be aligned are brain proton spectra. If they are and the isBrainH checkbox is ticked then all relevant fields are automatically filled in and the alignment algorithm for 1.5 T SV spectra described in [11] is used. The second option is to input manually the theoretical values for the peaks that will be used for alignment. Then, the algorithm aligns according to the peak with the highest signal-to-noise ratio (SNR) amongst the previously defined ones. The SNR is computed using Eq. 2:
$$ SNR = \frac{Max\ Peak}{2STD(noise)} $$
(2)
where Max Peak represents the highest amplitude in the spectral vector, STD stands for standard deviation and in this particular case we consider the noise from a range chosen by the user.
The above preprocessing steps (from V onwards) were not available beforehand in jMRUI and they have been adapted from the INTERPRET data manipulation software [10, 11]. With the exception of zero filling, the new steps act in the frequency domain in contrast to the way jMRUI works (in the time domain).
Steps IX and X do not directly affect the spectrum or spectra present in jMRUI. On the contrary, they deal with exporting details - for example, even though the user may choose in the fifth (Change number of points in specified range) step to have a specific number of points in a given ppm interval it does not mean that the plugin will output only that range (unless otherwise instructed the plugin will output the full initial ppm range, while ensuring the desired number of points in the selected ppm range). This step, IX, is used when the user only needs a specific ppm range to be present in the output. This is useful when dealing with data from multiple machines which have different ppm ranges before the processing.
For example, when dealing with two raw spectra that have the same number of points but slightly different ppm ranges this step is needed because otherwise outputting the full ppm range/spectra will result in spectral vectors with different number of points.
Moving forward to the Additional Information step (X), it is compulsory to complete the User’s Name and Place fields if one wants to be able to export the processed spectrum as an XML file. This was done because it ensures a minimum traceability on who (and where) has performed the preprocessing. The date of the processing is automatically assigned by the plugin when exporting to XML.
Other information that can be written to the XML is: the SNR for each voxel (which uses Eq. (2), with the highest peak in the whole spectrum as Max Peak), the class label in case of single voxel. By default, the ‘***’ value will be given to the label tag; otherwise the user can label the spectrum as “tumour”, “normal”, etc.
Keywords can also be added with a maximum of 45 characters. This is relevant when the user wants to retain pin-pointed details about the spectra, for example “treated with substance X” or “acquired X minutes after substance injection”.
Finally the four control buttons serve as follows: Save config. saves the parameters that are present in the interface at button-press time to an XML file that can later be loaded back using Load config. Preview/Original can be toggled to see how spectra will look like by tuning parameters and once the user is satisfied the spectra can be saved as an XML file by using the Export button. Such a processed spectrum can be seen in Fig. 2.
It is useful to note that the jMRUI2XML plugin uses the data that is available when it is loaded; if the spectrum has been processed before loading it, then the plugin will see that spectrum and not the unprocessed one. The same is valid if the users apply other processing steps after they have clicked Preview but before Export, for example if they apply additional zero or first order phasing manually using the jMRUI main menu.
Meta Data tab
The second tab- Meta Data (Fig. 3) serves as an observation notebook. For instance, as in the previous example when manual phasing or any extra procedure available in jMRUI but not in the plugin has been applied through its main menu, this is where it can be manually recorded using this tab. Although it might seem trivial, this tab can accommodate details that are crucial for later data-analysis, such as voxel position, clinical trial code, comments about spectral quality or even a description of the spectrum in report terms.
Labels MV tab
The last tab of jMRUI2XML is called LabelsMV and it is used for labelling each individual voxel of an MV grid. Fig. 4 depicts this tab - each cell in the grid represents a voxel; each of them has a label assigned with the default value of “***”. The labels can be viewed and edited by clicking on a cell. The grid follows matrix notation, meaning the top left corner corresponds to position [1, 1] and the bottom right corner corresponds to position [m,n], where m is the number of rows and n is the number of columns.