11.8. Visualising Estimated Spectra for 1D Phantom Data

11.8.1. Goal

This tutorial will guide you through the visualising process of the estimated spectra from the 1D Phantom data as generated in this tutorial. By the end of this tutorial you will be able to

  • Visualise spatially resolved spectra using plotSpectIm.

  • Plot averaged spectra across selected spatial regions using plotAvgspect.

  • Create spectral mask and plot component maps using the spectral mask using plotCompMaps.

  • Adjust figure appearance (e.g., axis scale, colorbar, axis limits, colormap etc).

  • Export the resulting figures in different file formats for documentation or further analysis.

11.8.2. Relevant downloads

This tutorial requires you to download the files Phantom1d_spectrum_mask.mat and four_color.mat from this link. The first file contains four spectral roi’s that we have already generated and stored in this format and the second file stores the information related to the color of each components and follows the format mentioned here.

11.8.3. Get started

Before going to the visualisation, lets check if we have the following file in our working directory (for this tutorial also we are assuming we are working in the ‘Documents’ folder)

/Documents/
├── Phantom1D/Phantom1D_data_ladmm_spect.mat (Generated from spectrum estimation tool)
├── Phantom1D/Phantom_data.mat (Generated from Phantom generation tool)
├── Phantom1D/Phantom_mask.mat (Generated from Phantom generation tool)
├── Phantom_spectrum_mask.mat (downloaded)
└── four_color.mat (downloaded)

11.8.4. Plot Spectroscopic image:

We will be using the function plotspectIm.sh/plotspectIm.m to plot the spectroscopic images. The detailed documentation is given here. Spectroscopic image is the visualisation of each individual spectrum spatially located at the source voxel location and the spectrum’s back ground is the MR data intensity of that voxel. The user can choose subset of region for which spectroscopic image will be plotted, select the color of each individual spectrum, zoom into to spectrum at all the selected voxels etc using this tool. In this tutorial we will be exploring the usage of the above function.

  1. First plot the spectroscopic image with the default setting and required inputs:

    plot_spect_im.sh -spect_imfile 'Phantom1D/Phantom1D_data_ladmm_spect.mat' -imgfile 'Phantom1D/Phantom_data.mat' -outprefix 'Phantom1D/Phantom1D_data_spectroscopic_Im' -spatmaskfile 'Phantom1D/Phantom_mask.mat'

    plot_spect_im('spect_imfile','Phantom1D/Phantom1D_data_ladmm_spect.mat','imgfile','Phantom1D/Phantom_data.mat','outprefix','Phantom1D/Phantom1D_data_spectroscopic_Im','spatmaskfile', 'Phantom1D/Phantom_mask.mat')

    The above program will generate the following spectroscopic image, ‘Phantom1D/Phantom1D_data_spectroscopic_Im_1.png’ for all the voxels indexed in the mask file ‘Phantom1D/Phantom_mask.mat’ by 1’s.

    specim1d1

    This plot is generated with the default setting in the tool. Now, let’s use the optional inputs to better explore the spectroscopic image.

  2. We can tune the figure appearance by changing the optional inputs. Let’s say we want to zoom into the region for \(10<T_2<100\). This is controlled by the named argument ax_lims. We set it to \([10 \; 100]\). Lets also change the color for each spectrum to the 'blue', plot the third contrast encoding of the multidimensional MR image as background for each slice, and save them in two types of format, ‘png’ and ‘eps’. The tool is run as follows with the above inputs,

    plot_spect_im.sh -spect_imfile 'Phantom1D/Phantom1D_data_ladmm_spect.mat' -imgfile 'Phantom1D/Phantom_data.mat' -outprefix 'Phantom1D/Phantom1D_data_spectroscopic_Im' -spatmaskfile 'Phantom1D/Phantom_mask.mat' -ax_lims '[10 100]' -color 'blue' -enc_idx 3 -file_types 'png' 'eps'

    plot_spect_im('spect_imfile', 'Phantom1D/Phantom1D_data_ladmm_spect.mat', 'imgfile','Phantom1D/Phantom_data.mat', 'outprefix', 'Phantom1D/Phantom1D_data_spectroscopic_Im', 'spatmaskfile', 'Phantom1D/Phantom_mask.mat','ax_lims',[0.03 2 10 100], 'color','blue', 'enc_idx', 3, 'file_types', {'png','eps'})

    Below we show the slice 3 generated from the above command.

    specim1d2

    All the images above shows the voxelwise spectra and their spatial distribution which is very important to analyse the estimated spectra and underlying tissue properties.

11.8.5. Plot Average Spectra:

We will be using the function plotAvgSpectra.m/plotAvgSpectra.sh to plot the average spectra from all the voxels specified by the spatial mask. Detailed documentation is given here.

  1. Let’s run the tool using the following command and defaults inputs:

    plot_avg_spectra.sh -spect_imfile 'Phantom1D/Phantom1D_data_ladmm_spect.mat' -outprefix 'Phantom1D/Phantom1D_data_ladmm_avg_spectra' -spatmaskfile 'Phantom1D/Phantom_mask.mat'

    plot_avg_spectra('spect_imfile','Phantom1D/Phantom1D_data_ladmm_spect.mat','outprefix','Phantom1D/Phantom1D_data_ladmm_avg_spectra','spatmaskfile','Phantom1D/Phantom_mask.mat')

    This will generate the following contour plot showing the average spectra from all the voxels indicated by 1 in the spatial maskfile ‘Phantom1D/Phantom_mask.mat’.

    avg1

  2. We can also change appearance of the figure by modifying the optional inputs as done before while plotting the spectroscopic image. There are few common named arguments, which work the same way as in the previous tool. These are, ax_lims, color, file_types. However, here we can also change the axes scaling (using ax_scale), line width (using linewidth) of the plot. We have applied all these arguments to revisualize of the average spectra,

    plot_avg_spectra.sh -spect_imfile 'Phantom1D/Phantom1D_data_ladmm_spect.mat' -outprefix 'Phantom1D/Phantom1D_data_ladmm_avg_spectra' -spatmaskfile 'Phantom1D/Phantom_mask.mat' -ax_scale 'log' -ax_lims '[10 100]' -color 'b' -linewidth 3 -cbar 1 -file_types 'png'

    plot_avg_spectra('spect_imfile', 'Phantom1D/Phantom1D_data_ladmm_spect.mat', 'outprefix', 'Phantom1D/Phantom1D_data_ladmm_avg_spectra', 'spatmaskfile','Phantom1D/Phantom_mask.mat', 'ax_scale', 'log', 'ax_lims', [10 100],'color','b','linewidth',3,'file_types','png')

    The average spectrum obtained is as follows,

    avg3

11.8.6. Plot Component Maps:

One of the most crucial step to generate component maps is to create the spectral ROI (note that this is different from the spatial mask as described in the above examples). Component maps are constructed by the signal from specific spectral region. We generate the spectral ROI to define such specific spectral regions. This spectral ROI is a \(M_1 \times N_c\) (for 1D spectrum, where \(M_1\) is the spectral dimension and \(N_c\) is the user defined total number of components) binary mask where the locations in the mask equal to 1 are the spectral regions that we are interested in.

We know that the estimated spectra signifies the amplitude of the spectra at the spectral sampling points used while creating the dictionary. The Spectral ROI indexes these spectral sampling points. If we have only single location in the spectral ROI to be one, then we will get an image showing the spatial distribution of the amplitude values corresponding to that one specific spectral sampling point. If we have multiple points for which the spectral ROI is one, then we will get an image showing the spatial distribution of the sum of the amplitudes across all of the indicated spectral sampling points. These images are called component maps. Mathematically, for a voxel location \((x,y)\) the intensity of the t-th component map is calculated as follows,

\[I_t(x,y)=\sum_{i\in \Lambda_t} f(i,x,y)\]

Where \(\Lambda_t\) is the region in the 1D spectral ROI with value \(1\) and \(f(i,x,y)\) is the 1D spectrum amplitudes for the 2D spatial slice as calculated from the spectrum estimation tool.

  1. First let’s create the spectral ROI. As the spectral_dim has value 300, we need to create binary vector of dimension 300x1 with zeros everywhere except the spectral region whose component maps we are interested to evaluate. In this tutorial we will look into the component maps corresponding to two spectral regions, so we created two binary masks to visualise the component maps corresponding to the spectral regions indicated by 1’s in the plots below,

    cmp1

  2. Lets name the vectors storing the above 300x1 masks as roi1 and roi2. Next we need to create the spectrum mask file with the format as given here. In this regard we need to create two variables named spec_mask and num_comp. The first variable stores all the spectral mask and the second variable stores the number of components. We have to concatenate these two 300x1 spectral masks to create spec_mask of dimension 300x2 and assign value 2 to the num_comp variable. Below is the MATLAB implementation to create such variable and store them to the file named ‘Phantom_spectrum_mask.mat’.

    num_comp=2;
spec_mask=cat(2,roi1,roi2);
save('Phantom_spectrum_mask.mat',"spec_mask","num_comp",'-v7.3')

    Note

    Although we have used two components here, you can create as many as 13 components if you are using default colors while plotting the component maps. If you have more than 13 component to visualise, please create a colorfile with the format mentioned here.

  3. Once we have the spectral mask, ‘Phantom_spectrum_mask.mat’ (either created following steps 1-2 above or by downloading the above zip file), we can use it to plot the the component maps. Detailed description is available here. We run the tool using the following required name value pairs,

    plot_comp_maps.sh -spect_imfile 'Phantom1D/Phantom1D_data_ladmm_spect.mat' -spectmaskfile 'Phantom_spectrum_mask.mat' -outprefix 'Phantom1D/Phantom1D_data_component_maps'

    plot_comp_maps('spect_imfile','Phantom1D/Phantom1D_data_ladmm_spect.mat','spectmaskfile','Phantom_spectrum_mask.mat','outprefix','Phantom1D/Phantom1D_data_component_maps')

    The above command will store one image named ‘Phantom1D/Phantom1D_data_component_maps_1.png’ corresponding to the component maps for the 2D slice and a .mat file named ‘’Phantom1D/Phantom1D_data_component_maps.mat’ storing the component map data in a similar format as in mentioned here. The component maps are shown below:

    cmp2

  4. The above program generates slicewise component maps corresponding to the two spectral regions chosen using the default colors. If you want to use a custom color, you can use the colorfile, 'four_colors.mat' provided in the above downloadable zip file. This input is controlled by the named argument, color (format can be found here). As you may see from the above image that component 2 looks darker, we can change its appearance using the argument weights. We have set it to [1 4] so that the brightness for component 2 increases four times, so does its intensity in the composite map. We can also add colorbar to each of these component maps using cbar and specify output image file format using file_types.

    plot_comp_maps.sh -spect_imfile 'Phantom1D/Phantom1D_data_ladmm_spect.mat' -spectmaskfile 'Phantom_spectrum_mask.mat' -outprefix 'Phantom1D/Phantom1D_data_component_maps'  -color 'four_color.mat' -weights [1 2 1 1] -cbar 1 -file_types 'jpg'

    plot_comp_maps('spect_imfile','Phantom1D/Phantom1D_data_ladmm_spect.mat','spectmaskfile','Phantom_spectrum_mask.mat','outprefix','Phantom1D/Phantom1D_data_component_maps','color','four_color.mat','weights',[1 2 1 1],'cbar',1,'file_types','jpg')

    Below is the component maps revisualised,

    cmp3