Debian Codegraph @

doc/intro/tutorials/spectrum.rst

raw
1 :octicon:`book;1em;sd-text-info` Processing a spectrum
2 ======================================================
3
4 .. meta::
5 :description: Tutorial on how to process a spectrum with DataLab, the open-source scientific data analysis and visualization platform
6 :keywords: spectrum, signal processing, data analysis, scientific data, visualization, open-source, software, DataLab, tutorial
7
8 This example shows how to process a spectrum with DataLab:
9
10 - Read the spectrum from a file
11 - Apply a filter to the spectrum
12 - Extract a region of interest
13 - Fit a model to the spectrum
14 - Save the workspace to a file
15
16 DataLab menus change depending on the context. Since we are going to work with a
17 spectrum, a 1D signal, we need to select the Signal Panel before proceeding.
18
19 In a typical workflow, we would open DataLab and read the spectrum from a file using
20 "File > Open...", the |fileopen_sig| button in the toolbar, or by dragging and
21 dropping the file into the panel on the right. However, for this tutorial,
22 we will use the "Plugins > Test data > Load spectrum of paracetamol" feature to
23 generate a test spectrum, which is convenient for demonstration purposes.
24
25 .. |fileopen_sig| image:: ../../../datalab/data/icons/io/fileopen_sig.svg
26 :width: 24px
27 :height: 24px
28 :class: dark-light no-scaled-link
29
30 .. figure:: ../../images/tutorials/spectrum/01.png
31
32 The "File > Open..." menu to open a spectrum file.
33
34 .. figure:: ../../images/tutorials/spectrum/02.png
35
36 The "Plugins > Test data > Load spectrum of paracetamol" plugin to generate the
37 test spectrum for this tutorial.
38
39 Once opened, the spectrum is displayed in the main window. It is a 1D signal, so it is
40 displayed as a curve. The horizontal axis is the energy axis, and the vertical axis
41 is the intensity axis.
42
43 .. figure:: ../../images/tutorials/spectrum/03.png
44
45 The spectrum displayed on the "Signal View" panel.
46
47 The signal is quite clean. However, to demonstrate DataLab's filtering capabilities,
48 we will apply a Wiener filter to reduce any residual noise while
49 preserving the spectral features. This is available under
50 "Processing > Noise Reduction > Wiener filter".
51
52 .. figure:: ../../images/tutorials/spectrum/04.png
53
54 The "Processing > Noise Reduction > Wiener filter" menu option.
55
56 .. figure:: ../../images/tutorials/spectrum/05.png
57
58 The result displayed in the main window.
59
60 Let's focus our analysis on one of the peaks of interest. To do that,
61 we define a region of interest (ROI) around the feature we want to analyze
62 and use the "ROI > Extract..." menu to extract it.
63 The "Regions of interest" dialog box will be displayed. Select an area and click "OK".
64 A confirmation window will appear—click "Yes" to extract the region of interest.
65 A new signal containing the ROI will be created and displayed in the main window.
66
67 .. figure:: ../../images/tutorials/spectrum/06.png
68
69 The "Operations > ROI extraction" menu.
70
71 .. figure:: ../../images/tutorials/spectrum/07.png
72
73 The "Regions of interest" dialog box displayed.
74
75 .. figure:: ../../images/tutorials/spectrum/08.png
76
77 The region of interest displayed in the main window.
78
79 .. figure:: ../../images/tutorials/spectrum/09.png
80
81 Open the model fitting window with "Processing > Fitting > Gaussian fit".
82
83
84 .. figure:: ../../images/tutorials/spectrum/11.png
85
86 The result of the fit displayed in the main window.
87
88 .. figure:: ../../images/tutorials/spectrum/12.png
89
90 Both the full spectrum and the fit are selected in the "Signals" panel, so that
91 both are displayed in the visualization panel on the left. This allows for easy
92 visual comparison if needed for the analysis.
93
94 Linear detrending
95 -----------------
96
97 After fitting the main peak, we may want to remove any baseline drift
98 present in the entire spectrum.
99 The detrending function in DataLab performs a linear fit across the entire signal,
100 including the peaks. In our signal, the peaks occupy a large portion of the data,
101 which is acceptable for signals where peaks are symmetrically distributed around the
102 center with similar amplitudes. However, this is not the case here, so we cannot
103 expect this function to work well. Nevertheless, this example illustrates
104 how DataLab functions can be combined to perform more advanced analyses.
105
106 To visualize the limitation mentioned above, we will apply the detrending
107 function directly to the filtered signal. It's important to remember that we previously set
108 a ROI on the signal to focus on the main peak. We need to remove
109 this ROI constraint to perform detrending on the full signal.
110 To execute the detrending, we use "Processing > Detrending", choose
111 the linear detrending method, and click "OK". The result will be
112 displayed in the main window.
113
114 .. figure:: ../../images/tutorials/spectrum/13.png
115
116 The "Processing > Detrending" feature.
117
118 .. figure:: ../../images/tutorials/spectrum/14.png
119
120 We choose a linear detrending method, and we click on "OK".
121
122 .. figure:: ../../images/tutorials/spectrum/15.png
123
124 The result of the detrending displayed in the main window.
125
126 Comparing the filtered and detrended signals shows, as expected,
127 that the detrending function does not work well on this signal.
128 As explained earlier, this is because the algorithm performs a linear fit
129 across the entire signal, including the peaks. The effect is clearly visible in the plot:
130 the higher peaks on the left start at an intensity value lower than those on the right
131 after detrending, and all peaks have a baseline below zero.
132
133 Improved detrending with peak exclusion
134 -----------------------------------------
135
136 To overcome the detrending function's limitation, we can draw inspiration from the
137 behavior of the detrended signal. We've already identified the problem: the
138 linear fit includes both the baseline and the peaks.
139
140 For better detrending, we can first exclude the peaks and then perform
141 a linear fit only on the non-peak regions. We can reasonably expect this approach to
142 provide a more accurate baseline estimation and a better detrended signal.
143
144 This is illustrated in the following steps:
145
146 .. figure:: ../../images/tutorials/spectrum/15b.png
147
148 We select the regions corresponding to the regions without peaks.
149
150 .. figure:: ../../images/tutorials/spectrum/15c.png
151
152 A linear fit is performed only on the selected regions.
153
154 .. figure:: ../../images/tutorials/spectrum/15d.png
155
156 The linear baseline obtained from the fit is shown.
157
158 .. figure:: ../../images/tutorials/spectrum/15e.png
159
160 We delete the rois to apply the detrending on the whole signal.
161
162 .. figure:: ../../images/tutorials/spectrum/15f.png
163
164 We use the "difference" operation to subtract the baseline from the original signal.
165
166 .. figure:: ../../images/tutorials/spectrum/15g.png
167
168 We select the linear baseline to perform the subtraction.
169
170 .. figure:: ../../images/tutorials/spectrum/15h.png
171
172 The resulting detrended signal is shown, now with a correct baseline.
173
174
175 Automatic peak detection
176 -------------------------
177
178 We can use DataLab's "Multi-Gaussian fit" function to automatically identify
179 and fit multiple peaks in the spectrum by selecting
180 "Processing > Fitting > Multi-Gaussian fit" from the menu.
181
182 .. figure:: ../../images/tutorials/spectrum/16.png
183
184 First, the "Signal peak detection" dialog box appears. You can adjust
185 the vertical cursor position to set the threshold for peak detection
186 and specify the minimum distance between peaks. Then click "OK".
187
188 .. figure:: ../../images/tutorials/spectrum/17.png
189
190 The "Multi-Gaussian fit" dialog box appears. An automatic fit is performed
191 by default. Click "OK" (or optionally adjust the parameters manually using
192 the sliders, or modify the automatic fitting parameters).
193
194 .. figure:: ../../images/tutorials/spectrum/18.png
195
196 The result of the fit is displayed in the main window. Here we selected both the
197 spectrum and the fit in the "Signals" panel on the right, so both are displayed
198 in the visualization panel on the left.
199
200 Alternatively, we could use the "Peak detection" feature from the "Analysis" menu to
201 detect peaks in the spectrum. This is the first step of the "Multi-Gaussian fit"
202 function and can be used independently to detect peaks without performing a fit,
203 creating a signal with a delta function at each detected peak position.
204
205 .. figure:: ../../images/tutorials/spectrum/19.png
206
207 Open the "Peak detection" window with "Analysis > Peak detection".
208
209 .. figure:: ../../images/tutorials/spectrum/21.png
210
211 After adjusting the peak detection parameters (using the same dialog as
212 for the multi-Gaussian fit), click "OK". Then select both the
213 "peak_detection" result and the original spectrum in the "Signals" panel
214 to display them together in the visualization panel on the left.
215
216 Saving the workspace
217 --------------------
218
219 Finally, we can save the workspace to a file. The workspace contains all signals
220 loaded or created in DataLab, along with processing results and
221 visualization settings (such as curve colors).
222
223 .. figure:: ../../images/tutorials/spectrum/21.png
224
225 Save the workspace to a file with "File > Save to HDF5 file...",
226 or the |filesave_h5| button in the toolbar.
227
228 .. |filesave_h5| image:: ../../../datalab/data/icons/io/filesave_h5.svg
229 :width: 24px
230 :height: 24px
231 :class: dark-light no-scaled-link
232
233 If you want to load the workspace again, you can use the "File > Open HDF5 file..."
234 (or the |fileopen_h5| button in the toolbar) to load the whole workspace, or the
235 "File > Browse HDF5 file..." (or the |h5browser| button in the toolbar) to load
236 only a selection of data sets from the workspace.
237
238 .. |fileopen_h5| image:: ../../../datalab/data/icons/io/fileopen_h5.svg
239 :width: 24px
240 :height: 24px
241 :class: dark-light no-scaled-link
242
243 .. |h5browser| image:: ../../../datalab/data/icons/h5/h5browser.svg
244 :width: 24px
245 :height: 24px
246 :class: dark-light no-scaled-link