{% include breadcrumbs.html %}
This tutorial introduces the CaTSper (Cambridge Terahertz Spectrum Analyser) tool and how to use it to calculate the transmittance, frequency dependent absorption cofficient, refractive index and dielectric constant spectra from a set of sample and reference time-domain waveforms that were previously converted into the '.thz' file format using the CaTx tool. Please also refer to the CaTSper Processing Steps documentation where the mathematical steps CaTSper uses are outlined.
- TOC {:toc}
Please follow the instructions in the CaTx tutorial documentation to generate a '.thz' file before using CaTSper.
Please ensure the 'Name' row in the 'Tcell' array - the central table in CaTx - has been correctly assigned with distinguishable values for each waveform recorded, otherwise nothing will be displayed in the 'Measurement' list box in the CaTSper user interface. This can be done by loading the '.thz' file back into CaTx.
This documentation uses the sample '.thz' File 'varyRBV_terapulse_240809.thz' generated by CaTx. The file can be found in the CaTSper sample files folder.
Click the 'Import THz Files' button at the top of the CaTSper user interface and select the '.thz' file created by CaTx. The name of the file imported will be displayed, without the '.thz' suffix, to the right of the button. If the measurements (or terahertz waveforms recorded) are assigned with certain names, they will all appear in the 'Measurement' list box. Otherwise, please check the .thz file properties.
This documentation uses the sample data in .thz format generated by CaTx. Click 'Deploy' at the top. The user will then see the following UI if the data have been successfully imported into CaTSper, with all available data stored in the .thz file listed in the 'Measurement' box:
Click the 'Clear Memory' button at the top of the CaTSper user interface. A dialogue box will pop up to confirm this action: 'Do you want to clear memory?'
A 'Yes' answer will remove all entries and items from the 'Measurement' and 'Selection' list boxes and reset the MATLAB workspace. A 'No' or 'Cancel' answer will keep the existing data and take the user back to the CaTSper user interface.
The default tab at the top left corner selected is the 'Time Domain (TD)' tab. If another tab is selected, the user can click the 'Time Domain (TD)' tab to open the TD analysis page. The user will find the data processing steps under the TD tab in the following sections.
Stage 1: Once all measurements are listed, the user can pick those of interest by clicking the target item; the selected item will be shaded. Information on the selected item will appear in the 'General Information', 'Metadata Information' and 'Dataset Information' sections, and in the 'Metadata Information' box the user can select which metadata field houses the thickness and reference thickness for each item.
Stage 2: To add this measurement to the 'Selection' list box, the user can click the 'ADD' button and the measurement will then appear in the 'Selection' list box. Please note that only one measurement can be selected each time, so if you want to include all measurements, simply click the 'ALL' button and all measurements will be added. If you want to remove some measurements already in the 'Selection' list box, choose the target item in the 'Selection' list box and click the 'DEL' button. This item will then disappear from the 'Selection' list box, however it can still be found in the 'Measurement' list box.
Stage 3: The plot can only be made once the data are selected and displayed in the 'Selection' list box. Clicking the 'Plot 1' button will generate the waveform plot on the 'PLOT 1' axes whilst such plot will appear on the 'PLOT 2' axes if the 'Plot 2' button is pushed in. The user can plot the same measurement on both sets of axes.
The measurement contains waveforms for both the reference and the sample. The default setting (where the 'Both' radio button is chosen) will plot both the reference and the sample waveforms. The user can choose the 'Reference' or 'Sample' radio button to plot only the reference or sample waveform respectively. This allows the user to visualise the waveforms recorded and select those of interest for fast Fourier transformation (FFT) into the frequency domain (FD).
In the example shown above, the chosen 'Sample' data are plotted in 'Plot 1' while the 'Reference' data are plotted in 'Plot 2'. 'Legend' is displayed to show the names of the measurements.
Stage 4: Please check if the correct row of metadata is assigned to the 'Sample' and/or the 'Reference'. In this example, 'md3' and 'md4' are assigned to the 'Sample' and 'Reference' thicknesses respectively.
Stage 5: The 'FFT Settings' field is designated for FFT into the FD (see next section). The values assigned in the 'FFT Settings' field serve globally for all items in the 'Selection' list box.
The mathematical steps for the Fourier transform used in CaTSper can be found here.
'Frequency range (THz)' sets the range of frequencies for the FFT. The default values are 0.2 THz for the minimum frequency and 3.0 THz for the maximum frequency. The user can change these values in the corresponding edit fields.
'FFT Upsampling' has a default value of zero filling and power of 2. The user can alter this power value by operating the spinner. Upsampling is the process to pad zeros at the high frequency component end on each side of the signal.
'Unwrapping' - [insert description]
'Extrapolation Range (THz)' - [insert description]
'Window function' can either 'Auto Window' before the first internal reflection (if this button is pushed in) or the user can specify the minimum time and the maximum time. The default values are -10.00 ps and 20.00 ps respectively.
'Function' allows the user to select an apodisation function from a drop-down list. The default value is 'rectwin'. An apodisation function helps smoothly reduce the edge signal to zero at the boundaries between which the frequencies are chosen for the FFT. Descriptions of the various functions can be found here. The 'Plot Window Function' button allows the user to visualise the effect of windowing on the time-domain signal on the 'PLOT 2' axes.
Checking the 'Full list naming' box gives more detail in the names of the transformed items, which appear in a list box in the 'Frequency Domain (FD)' tab. If unchecked, the names include window boundaries and window function. When checked, there is additionally the frequency range and upsampling power.
Once the settings are adjusted, clicking the 'Transform' button will enable the app to compute the FFT, and the transformed items will appear in the 'FD List' box in the 'Frequency Domain (FD) tab'.
This functionality allows the user to pause the analysis and return at a later stage. Once the time-domain data have been selected and appeared in the 'Selection' list box, the user can click the 'Save TD_DATA'. A message box will pop up to ask: 'Do you want to save all data?'. If the user returns 'Yes', then all list items in the 'Measurement' list box will be saved in a '.mat' file, whereas 'No, only the selected data' will only save those in the 'Selection' list box.
This only works when runnning CaTSper in MATLAB. Click 'Load TD_DATA' and choose the '.mat' file created by the 'Save TD_DATA' functionality. The measurements saved in this file will then be imported to the 'Measurement' and 'Selection' list boxes.
'ALL': add all data sets from the 'Measurement' list box to the 'Selection' list box
'ADD': add chosen data set from the 'Measurement' list box to the 'Selection' list box
'DEL': remove chosen data set from the 'Selection' list box
'Grid Off': turn off the grid lines on the plots
'Plot 1': reveal the plot in the 'PLOT 1' area
'Plot 2': reveal the plot in the 'PLOT 2' area
'Plot For Customisation': open the plot in the 'PLOT 1' area in a new window to allow for further customisation. The resulting plot is more customisable when running CaTSper in MATLAB than when running the compiled version.
'Check Dynamic Range': opens a window in which the dynamic range of each measurement - the range of frequencies detected without excessive interference by noise - can be examined
'Transform': evaluate the fast Fourier transform for data sets in the 'Selection' list box and transfer the data to 'FD List' list box under the 'Frequency Domain (FD)' tab
'Legend': turn on the legend for the data sets
'Jet Colormap': change the colour scheme for the curve to jet colourmap
'Load TD_DATA': import saved TD data from a '.mat' file
'Save TD_DATA': save all TD data from the 'Measurement' or 'Selection' list box, depending on the user response, to a '.mat' file
'Assign TD_DATA in Workspace': assign all TD data from the 'Measurement' list box to the MATLAB workspace. Only works when running CaTSper in MATLAB.
Note: Please carry out the TD analysis before commencing the following steps, otherwise nothing will be displayed in the 'FD List' box.
To perform the FD analysis, the user needs to select the 'Frequency Domain (FD)' tab at the top left corner of the CaTSper user interface to open the FD analysis page. The user will find the data processing steps under the TD tab in the following sections.
Once the FFT is done by clicking the 'Transform' button under the 'Time Domain (TD)' tab (see above), the measurements in the 'Selection' list box of the 'Time Domain (TD)' tab will appear in the 'FD List' box of the 'Frequency Domain (FD)' tab with a naming structure dependent on whether the 'Full list naming' box in the 'Time Domain (TD)' tab had been checked (see above):
If unchecked:
'[Measurement Name] ([Min.Time]-[Max.Time]ps/[Apodization Function])'
For example:
'1:5mgRBV_1 (-5-25ps,hamming)'
If checked:
'[Measurement Name] ([Min.Time]-[Max.Time]ps/([Min.Freq.]-[Max.Freq.]THz/[Apodization Function]/[power of upsampling]upscale)'
For example:
'1:5mgRBV_1 (-5-25ps,0.2-3THz,hamming,2upscale)'
Stage 1: This process is quite similar to the TD analysis. The user can pick those of interest by click the target item; the selected item will be shaded. The user can click the 'ADD' button and the measurement will appear in the 'FD Selection' list box. Please note that only one measurement can be selected each time, so to include all measurements, click the 'ALL' button. To remove selected items, choose the target item in the 'FD Selection' list box and click the 'DEL' button. This item will then disappear from the 'FD Selection' list box, however it can still be found in the 'FD List' list box.
The operations are similar to those described in the 'Plot the TD data' section. Similarly, the plot can only be done once the data are selected and displayed in the 'FD Selection' list box. Similar options to those available in the 'Time Domain (TD)' tab (see above) allow the user to visualise the FD waveforms before processing.
Stage 2: Clicking the 'Plot 1' button will generate the waveform plot on the 'PLOT 1' axes whilst such plot will appear on the 'PLOT 2' axes if the 'Plot 2' button is pushed. The user can plot the same measurement on both axes. These operations will generate the plots for all FD data in the 'FD Selection' list box. If the user wishes to remove certain FD data from the plot, click the unwanted data in the 'FD Selection' list box and press 'DEL'. Then click either the 'Plot 1' or 'Plot 2' button, and the new plot will override the previous plot.
The default setting for the plot is to plot 'Sample' waveforms under the 'log' scale with 'Amplitude' on the vertical axis. The user can customise the following changes by choosing a different radio button to the right-hand side of the 'FD selection' list box:
'Reference': plot the reference waveforms only;
'Sample': plot the sample waveforms only;
'Both': plot both the reference and sample waveforms on the same plot;
'log': use a log scale;
'linear': use a linear scale;
'Amplitude': plot the electric field amplitude against frequency (THz).
'Phase': plot the phase (in degree form) against frequency (THz).
This example uses plots with 'Both' in the 'log' scale:
The user needs to click either the 'Plot 1' or 'Plot 2' button to update the plot or axes.
The default settings will generate the grid on the plot. If the user wants to turn off the grid line, press the 'Grid Off' button (and it will turn grey) and click either the 'Plot 1' or 'Plot 2' button to update the plot.
In the 'FD Data Analysis' field, the user can extract and plot the 'Transmittance', 'Absorption', 'Refractive Index' and 'Dielectric Constant' from the measurements.
Stage 3: The user needs to select the FD data for analysis from the 'FD List' box and press the 'ADD' button in the 'FD Data Analysis' field to import them into the lower 'FD Selection' list box. Note that this procedure is done separately to that outlined in the 'Plot the FD Data' section. The 'ALL' button loads all data from the 'FD List' box to the 'FD Selection' list box whilst the 'DEL' button removes the selected item from the 'FD Selection' list box.
The user can select an item from the 'FD Selection' list box to check that the correct values appear in the 'Description', 'Thickness (mm)' and 'Multiple Reflection Count' fields. There is a toggle in the 'Thickness (mm)' box that allows the user to choose between using the absolute sample thickness ('Sample') or the offset between the sample and reference thicknesses ('Offset') for calculation.
Stage 4: The 'Calculate Optical Parameters' button evaluates the absorption, refractive index and dielectric constant for each item listed in the 'FD Selection'. The mathematical steps CaTSper follows can be found here.
The user can choose to plot and preview these constants under the 'Frequency Domain (FD)' tab. In the 'Plot Data' section, the 'Transmittance' button can be pushed in, and its plot displayed, before the 'Calculate Optical Parameters' button has been pushed. However, the 'Absorption', 'Refractive Index' and 'Dielectric Constant' buttons are greyed out and can only be pushed in once the button has been pushed and these constants evaluated.
Stage 5 and 6: The default setting pushes the 'Transmittance' button in whereas another button needs to be pushed in for that constant to be plotted. For instance, if the user wishes to plot absorption on the vertical axis in the 'PLOT 2' area, the 'Absorption' button should first be pushed in and then the 'Plot 2' button to the right-hand side clicked:
The 'Plot For Customisation' button to the bottom right corner of the 'FD Data Analysis' field will open a new window and display the plot on this figure window. Further customisation is available in this window, especially when running CaTSper in MATLAB.
Stage 7: Once the user is satisfied with the FD data analysis, clicking the 'Data Manipulation' button will transfer the evaluated transmittance, absorption, refractive index and dielectric constant to the 'Data Manipulation (DM)' tab, and open the tab for the user.
Once the FD data have been selected and appeared in the 'FD Selection' list box, the user can click the 'Save FD_DATA' to save all list items in the 'FD List' and 'FD Selection' list boxes into a '.mat' file.
Click the 'Load FD_DATA' and choose the '.mat' file created by the 'Save FD_DATA' functionality. The FD data saved in this file will then be imported to the 'FD List' and 'FD Selection' list boxes.
'ALL': add all data sets from the 'FD List' list box to the 'FD Selection' list box
'ADD': add a chosen data set from the 'FD List' list box to the 'FD Selection' list box
'DEL': remove a chosen data set from the 'FD Selection' list box
'Grid Off': turn off the grid lines on the plots
'Plot 1': reveal the plot in the 'PLOT 1' area
'Plot 2': reveal the plot in the 'PLOT 2' area
'Plot For Customisation': reveal the plot in a new window to allow for further customisation. The resulting plot is more customisable when running CaTSper in MATLAB than when running the compiled version.
'Calculate Optical Parameters': evaluate the 'Absorption', 'Refractive Index' and 'Dielectric Constant' for the data sets in the 'FD Selection' list box of the 'FD Data Analysis' section
'Legend': turn on the legend for the plots
'Data Manipulation': transfer the data sets along with calculated 'Transmittance', 'Absorption', 'Refractive Index' and 'Dielectric Constant' data to the 'Available Data Set' box under the 'Data Manipulation (DM)' tab and open the 'Data Manipulation (DM)' tab
'Jet Colormap': change the colour scheme for the plots to jet colourmap
'Load FD_DATA': import saved FD data from a '.mat' file
'Save FD_DATA': save all FD data from the 'FD List' and 'FD Selection' list boxes to a '.mat' file
'Assign FD_DATA in Workspace': assign all FD data from the 'FD List' list box to the MATLAB workspace. Only works when running CaTSper in MATLAB.
Note: Please carry out the FD analysis before commencing the following steps, otherwise, nothing will be displayed in the 'Available Data Set' box. The user will find the data processing steps under the DM tab in the following sections.
The user will find the upper half of the DM tab dedicated for this functionality. It allows the user to choose three variables and plot the variables in the 'PLOT 1' area. The variable on the x-axis (or horizontal axis) is chosen from a drop-down list whilst the y-axis (or vertical axis) can be assigned to more variables (see later).
The data sets in the 'Available Data Set' box are transferred from the 'FD Domain' tab. The user will find a series of numbers separated by space. The numbering corresponds to those listed in the 'FD Selection' list box on the 'Frequency Domain (FD)' tab. If there is nothing shown in the 'Available Data Set' box, please check your FD data analysis and ensure you have transferred the data correctly to this tab.
Stage 1: To import the data set for the plot, the user needs to define the 'Source Data Set' box. This can be done by inputting the number(s) of the data set separated by a space. For example, provided '1 2 3 4 5 6 7 8 9 10' is displayed in the 'Available Data Set' box, the user can change the value of the 'Source Data Set' box to '1 3 7 10' if only these data sets are required for the plot. Alternatively, if all ten data sets are required, the user can press the 'Import All Data' button to import '1 2 3 4 5 6 7 8 9 10' in one step. A convenient shortcut if only '1 2 3 4 7 8 9 10' are required for the plot is to import all data first and then remove the unwanted data sets '5 6' from the 'Source Data Set' box.
Stage 2: The 'Define variables' options allow the user to assign values selected from drop-down boxes from the data sets to three variables: A, B and C. These values are:
'frequency': Frequency
'ref_amplitude': Reference amplitude
'ref_phase': Reference phase
'sam_amplitude': Sample amplitude
'sam_phase': Sample phase
'transmit_amplitude': Transmittance amplitude
'transmit_phase': Transmittance phase
'refractiveIndex': Refractive index
'absorption': Absorption
'extinction': Extinction coefficient
'eReal': Real part of extinction coefficient
'eImag': Imaginary part of extinction coefficient
Stage 3 and 4: Next, assign the x-axis and y-axis data. The 'X-axis Data' is selected from a drop-down box whilst 'Y-axis Data Formulation' enables the user to use an equation formulated from any or all of A, B and C.
To illustrate, to plot ([sample amplitude] - [reference amplitude]) on the y-axis against (frequency) on the x-axis, the user should select 'sam_amplitude' and 'ref_amplitude' for 'A' and 'B' respectively, type the formula 'A-B' in the 'Y-axis Data Formulation' box, and pick 'frequency' from the 'X-axis Data' drop-down box. To evaluate the y-axis data, press 'Calculate'. When the evaluation finishes, the 'Number of Data' box will reveal the number of data sets used for the plot - useful for checking the correct calculation was carried out - and the 'Plot (individual data sets)' and 'Plot (mean and range)' that were previously greyed out will be available.
'Plot (individual data sets)' will plot each data set as a separate curve; 'Plot (mean and range)' will evaluate the mean of all y-axis values at each x-axis value and plot the average value curve as well as the region (shaded in red) within which all data sets reside.
All these plots will be shown in the 'PLOT 1' area.
For instance, to plot 'absorption' and 'frequency' on the y-axis and x-axis respectively, using all available data sets:
Click 'Import All Data';
Define A as 'absorption' (B and C can remain as their default values);
Choose 'frequency' for 'X-axis Data';
Type 'A' in the 'Y-axis Data Formulation' box;
Click 'Calculate';
Check that the value of 'Number of Data' has changed to the correct value;
Click 'Plot (individual data sets)' to give the following plot in 'PLOT 1':
[missing image]
Otherwise, the 'Plot (mean and range)' reveal the following plot 'PLOT 1':
[missing image]
The user has prepared the data set and can proceed to the next step for data extraction.
The bottom half of the 'Data Manipulation (DM)' tab is for CaTSper to extract values at, or find the peak above, a certain frequency.
Stage 5: Under the 'Frequency Base' tab, the user can extract values at a chosen terahertz frequency specified in the 'Get Data from Frequency(THz)' box. The 'Display X Lines' button will add a dashed red line to this specified frequency in the upper 'PLOT 1' area. Multiple frequencies can be specified for plotting on the same graph by entering the desired frequencies into the 'Get Data from Frequency(THz)' field with values separated by a space.
Stage 6: The 'Re-arrange Data' button finds the values on the y-axis from 'PLOT 1' at the specified frequency, as well as choosing a plot title and x-labels in the 'Measurement' and 'X-axis Data' fields respectively. The title can be updated by editing the text in the 'Measurement' field then re-plotting the graph.
Stage 7: The 'Plot' button plots the y-axis data against data set on the 'PLOT 2' area to the right-hand side. The user can define the 'X-Label' and 'Y-Label' (i.e. axis titles) by changing the corresponding text fields.
Under the 'Peak Base' tab, the user can ask CaTSper to find the peaks in the frequency domain spectrum and plot the y-axis values where the peak is found against data set number. The user can find the algorithm CaTSper uses to find peaks here.
The user needs to define the minimum peak prominence (default value '0', in the same units as the y-axis of the upper plot), lower frequency limit (default value '1 THz') and the peak number to plot, numbered left to right for each data set (default value '1'). Then, by clicking the 'Re-arrange Data' button, CaTSper will locate the peaks above the chosen frequency limit.
The 'Plot' button will plot the y-value of peak x, where x is the 'Peak Num.' chosen earlier, against the individual data set on the area to the right-hand side. The user can define the 'X-Label' and 'Y-Label' (i.e. axis titles) by changing the corresponding boxes.
'Import All Data': add all data sets from the 'Available Data Set' box to the 'Source Data Set' box
'Import All Data (Inverse Sequence)': add all data sets from the 'Available Data Set' box to the 'Source Data Set' box in reverse order
'Calculate': evaluate the chosen y-axis data
'Plot (individual data sets)': plot each data set as a separate curve
'Plot (mean and range)': evaluate the mean of each y-axis value at its corresponding x-axis value and plot the average value curve as well as the region (shaded in red) where all data sets reside
'3D Plot (Frequency x-axis)': [insert description]
'Display X Lines': add a dashed red line to the upper plot at the specified frequency
'Re-arrange Data' (frequency base): get the y-axis values from 'PLOT 1' at the specified frequency, and display a plot title in the 'Measurement' field and the x-labels in the 'X-axis data' field
'Re-arrange Data' (peak base): locate and label the peaks above the chosen frequency limit
'Plot': reveal the plot for the frequency base or peak base analysis
'Jet Colormap': change the colour scheme for the plots to jet colourmap
'Save DM_DATA': save all data processed in DM to a '.mat' file
'Assign FD_DATA in Workspace': assign all data processed in DM to the MATLAB workspace as 'DM_data'