Debian Codegraph @

doc/features/signal/menu_processing.rst

raw
1 .. _sig-menu-processing:
2
3 Processing Signals
4 ==================
5
6 This section describes the signal processing features available in DataLab.
7
8 .. seealso::
9
10 :ref:`sig-menu-operations` for more information on operations that can be performed
11 on signals, or :ref:`sig-menu-analysis` for information on analysis features on
12 signals.
13
14 .. figure:: /images/shots/s_processing.png
15
16 Screenshot of the "Processing" menu.
17
18 When the "Signal Panel" is selected, the menus and toolbars are updated to
19 provide signal-related actions.
20
21 The "Processing" menu allows you to perform various processing on the
22 selected signals, such as smoothing, normalization, or interpolation.
23
24 Axis transformation
25 ^^^^^^^^^^^^^^^^^^^
26
27 Linear calibration
28 ~~~~~~~~~~~~~~~~~~
29
30 Create a new signal which is a linear calibration of each selected signal
31 with respect to X or Y axis:
32
33 .. list-table::
34 :header-rows: 1
35 :widths: 40, 60
36
37 * - Parameter
38 - Linear calibration
39 * - X-axis
40 - :math:`x_{1} = a.x_{0} + b`
41 * - Y-axis
42 - :math:`y_{1} = a.y_{0} + b`
43
44 Swap X/Y axes
45 ~~~~~~~~~~~~~
46
47 Create a new signal which is the result of swapping X/Y data.
48
49 Reverse X-axis
50 ~~~~~~~~~~~~~~
51
52 Create a new signal which is the result of reversing X data.
53
54 Replace X by other signal's Y
55 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
56
57 Create a new signal by combining two signals, using Y values from the second signal
58 as X coordinates for the first signal's Y values.
59
60 This feature is particularly useful for calibration scenarios, such as:
61
62 - Applying wavelength calibration to spectroscopy data
63 - Using a calibrated reference signal to rescale measurement data
64 - Combining signals where one contains calibration points
65
66 The two signals must have the same number of points. The operation directly uses
67 the Y arrays without interpolation.
68
69 .. list-table::
70 :header-rows: 1
71 :widths: 40, 60
72
73 * - Input
74 - Description
75 * - Signal 1
76 - Provides the Y data for the output signal
77 * - Signal 2
78 - Provides the Y data that becomes the X coordinates of the output signal
79
80 X-Y mode
81 ~~~~~~~~
82
83 Create a new signal by simulating the X-Y mode of an oscilloscope.
84
85 This operation plots one signal as a function of another by:
86
87 1. Finding the overlapping X range between both signals
88 2. Resampling both signals onto a common X grid within that overlap
89 3. Using the resampled Y values as coordinates (first signal's Y as X, second signal's Y as Y)
90
91 .. note::
92
93 This is different from "Replace X by other signal's Y" as it performs interpolation to handle signals
94 with different X arrays.
95
96 Convert to Cartesian coordinates
97 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
98
99 Create a new signal which is the result of converting polar coordinates to Cartesian coordinates.
100
101 This function assumes that the x-axis represents the radius and the y-axis the angle.
102
103 .. warning::
104
105 A radius cannot be negative. Any negative value is clipped to 0.
106
107
108 Convert to polar coordinates
109 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
110
111 Create a new signal which is the result of converting Cartesian coordinates to polar coordinates.
112
113 Level adjustment
114 ^^^^^^^^^^^^^^^^
115
116 Normalize
117 ~~~~~~~~~
118
119 Create a new signal which is the normalization of each selected signal
120 by maximum, amplitude, sum, energy or RMS:
121
122 .. list-table::
123 :header-rows: 1
124 :widths: 25, 75
125
126 * - Parameter
127 - Normalization
128 * - Maximum
129 - :math:`y_{1}= \dfrac{y_{0}}{\max\left(y_{0}\right)}`
130 * - Amplitude
131 - :math:`y_{1}= \dfrac{y_{0}'}{\max\left(y_{0}'\right)}` with :math:`y_{0}'=y_{0}-\min\left(y_{0}\right)`
132 * - Area
133 - :math:`y_{1}= \dfrac{y_{0}}{\sum_{n=0}^{N}y_{0}[n]}`
134 * - Energy
135 - :math:`y_{1}= \dfrac{y_{0}}{\sqrt{\sum_{n=0}^{N}\left|y_{0}[n]\right|^2}}`
136 * - RMS
137 - :math:`y_{1}= \dfrac{y_{0}}{\sqrt{\dfrac{1}{N}\sum_{n=0}^{N}\left|y_{0}[n]\right|^2}}`
138
139 Clipping
140 ~~~~~~~~
141
142 Create a new signal which is the result of clipping each selected signal.
143
144 Offset correction
145 ~~~~~~~~~~~~~~~~~
146
147 Create a new signal which is the result of offset correction of each selected signal.
148 This operation is performed by subtracting the signal baseline which is estimated by
149 the mean value of a user-defined range.
150
151 Noise addition
152 ^^^^^^^^^^^^^^
153
154 Generate new signals by adding the same noise to each selected signal.
155 The available noise types are:
156
157 .. list-table::
158 :header-rows: 1
159 :widths: 25, 75
160
161 * - Noise
162 - Description
163 * - Gaussian
164 - Normal distribution
165 * - Uniform
166 - Uniform distribution
167 * - Poisson
168 - Poisson distribution
169
170 Noise reduction
171 ^^^^^^^^^^^^^^^
172
173 Create a new signal which is the result of noise reduction of each selected signal.
174
175 The following filters are available:
176
177 .. list-table::
178 :header-rows: 1
179 :widths: 25, 75
180
181 * - Filter
182 - Formula/implementation
183 * - Gaussian filter
184 - `scipy.ndimage.gaussian_filter <https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.gaussian_filter.html>`_
185 * - Moving average
186 - `scipy.ndimage.uniform_filter <https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.uniform_filter.html>`_
187 * - Moving median
188 - `scipy.ndimage.median_filter <https://docs.scipy.org/doc/scipy/reference/generated/scipy.ndimage.median_filter.html>`_
189 * - Wiener filter
190 - `scipy.signal.wiener <https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.wiener.html>`_
191
192 Fourier analysis
193 ^^^^^^^^^^^^^^^^
194
195 Zero padding
196 ~~~~~~~~~~~~
197
198 Create a new signal which is the result of zero padding of each selected signal.
199
200 The following parameters are available:
201
202 .. list-table::
203 :header-rows: 1
204 :widths: 25, 75
205
206 * - Parameter
207 - Description
208 * - Strategy
209 - Zero padding strategy (see below)
210 * - Number of points
211 - Custom length (if `strategy` is "custom")
212
213 Zero padding strategy refers to the method used to increase the length of the signal, and it can be one of the following:
214
215 .. list-table::
216 :header-rows: 1
217 :widths: 25, 75
218
219 * - Strategy
220 - Description
221 * - next_pow2
222 - Next power of 2 (e.g. 1024 → 2048)
223 * - double
224 - Double the length (e.g. 1024 → 2048)
225 * - triple
226 - Triple the length (e.g. 1024 → 3072)
227 * - custom
228 - Custom length (user-defined)
229
230 FFT related functions
231 ~~~~~~~~~~~~~~~~~~~~~
232
233 Create a new signal which is the result of a Fourier analysis of each selected signal.
234
235 The following functions are available:
236
237 .. list-table::
238 :header-rows: 1
239 :widths: 20, 30, 50
240
241 * - Function
242 - Description
243 - Formula/implementation
244 * - FFT
245 - Fast Fourier Transform
246 - `numpy.fft.fft <https://docs.scipy.org/doc/numpy/reference/generated/numpy.fft.fft.html>`_
247 * - Inverse FFT
248 - Inverse Fast Fourier Transform
249 - `numpy.fft.ifft <https://docs.scipy.org/doc/numpy/reference/generated/numpy.fft.ifft.html>`_
250 * - Magnitude spectrum
251 - Optional: output in decibels (dB)
252 - | :math:`y_{1} = \left|\FFT\left(y_{0}\right)\right|` or
253 | :math:`y_{1} = 20 \log_{10} \left(\left|\FFT\left(y_{0}\right)\right|\right)` (dB)
254 * - Phase spectrum
255 - Phase of the FFT expressed in degrees, using `numpy.angle <https://docs.scipy.org/doc/numpy/reference/generated/numpy.angle.html>`_
256 - :math:`y_{1} = \angle \FFT\left(y_{0}\right)`
257 * - Power spectral density (PSD)
258 - Optional: output in decibels (dB). PSD is estimated using Welch's method
259 (see `scipy.signal.welch <https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.welch.html>`_)
260 - | :math:`y_{1} = \PSD\left(y_{0}\right)` or
261 | :math:`y_{1} = 10 \log_{10} \left(\PSD\left(y_{0}\right)\right)` (dB)
262
263 .. note::
264
265 FFT and inverse FFT are performed using frequency shifting if the option is enabled
266 in DataLab settings (see :ref:`settings`).
267
268 Frequency filters
269 ^^^^^^^^^^^^^^^^^
270
271 Create a new signal which is the result of applying a frequency filter to each selected signal.
272
273 The following filters are available:
274
275 .. list-table::
276 :header-rows: 1
277 :widths: 25, 75
278
279 * - Filter
280 - Description
281 * - |lowpass| Low-pass
282 - Filter out high frequencies, above a cutoff frequency
283 * - |highpass| High-pass
284 - Filter out low frequencies, below a cutoff frequency
285 * - |bandpass| Band-pass
286 - Filter out frequencies outside a range
287 * - |bandstop| Band-stop
288 - Filter out frequencies inside a range
289
290 .. |lowpass| image:: ../../../datalab/data/icons/processing/lowpass.svg
291 :width: 24px
292 :height: 24px
293 :class: dark-light no-scaled-link
294
295 .. |highpass| image:: ../../../datalab/data/icons/processing/highpass.svg
296 :width: 24px
297 :height: 24px
298 :class: dark-light no-scaled-link
299
300 .. |bandpass| image:: ../../../datalab/data/icons/processing/bandpass.svg
301 :width: 24px
302 :height: 24px
303 :class: dark-light no-scaled-link
304
305 .. |bandstop| image:: ../../../datalab/data/icons/processing/bandstop.svg
306 :width: 24px
307 :height: 24px
308 :class: dark-light no-scaled-link
309
310 For each filter, the following methods are available:
311
312 .. list-table::
313 :header-rows: 1
314 :widths: 25, 75
315
316 * - Method
317 - Description
318 * - Bessel
319 - Bessel filter, using SciPy's `scipy.signal.bessel <https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.bessel.html>`_ function
320 * - Brick wall
321 - Ideal (rectangular) filter in the frequency domain
322 * - Butterworth
323 - Butterworth filter, using SciPy's `scipy.signal.butter <https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.butter.html>`_ function
324 * - Chebyshev I
325 - Chebyshev type I filter, using SciPy's `scipy.signal.cheby1 <https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.cheby1.html>`_ function
326 * - Chebyshev II
327 - Chebyshev type II filter, using SciPy's `scipy.signal.cheby2 <https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.cheby2.html>`_ function
328 * - Elliptic
329 - Elliptic filter, using SciPy's `scipy.signal.ellip <https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.ellip.html>`_ function
330
331 Fitting
332 ^^^^^^^
333
334 Fit a model to each selected signal.
335 This can be done automatically or through an interactive curve fitting dialog.
336
337 .. list-table::
338 :header-rows: 1
339 :widths: 20, 80
340
341 * - Model
342 - Equation
343 * - Linear
344 - :math:`y = c_{0} + c_{1} \cdot x`
345 * - Polynomial
346 - :math:`y = c_{0} + c_{1} \cdot x + c_{2} \cdot x^2 + ... + c_{n} \cdot x^n`
347 * - Gaussian
348 - :math:`y = y_{0} + \dfrac{A}{\sqrt{2 \pi} \sigma} \exp\left(-\dfrac{1}{2} \left(\dfrac{x - x_{0}}{\sigma}\right)^2\right)`
349 * - Lorentzian
350 - :math:`y = y_{0} + \dfrac{A}{\pi \sigma} \cdot \dfrac{1}{1+\left(\dfrac{x-x_{0}}{\sigma}\right)^2}`
351 * - Voigt
352 - :math:`y = y_{0} + A \cdot \dfrac{\Re\left(\exp(-z^2) \cdot \operatorname{erfc}(-j \cdot z)\right)}{\sqrt{2 \pi} \sigma}` with :math:`z = \dfrac{x - x_{0} - j \cdot \sigma}{\sqrt{2} \sigma}`
353 * - Multi-Gaussian
354 - :math:`y = y_{0} + \sum_{i=0}^{N}\dfrac{A_{i}}{\sqrt{2 \pi} \sigma_{i}} \exp\left(-\dfrac{1}{2} \left(\dfrac{x - x_{0,i}}{\sigma_{i}}\right)^2\right)`
355 * - Multi-Lorentzian
356 - :math:`y = y_{0} + \sum_{i=0}^{N}\dfrac{A_{i}}{\pi \sigma_{i}} \cdot \dfrac{1}{1 + \left(\dfrac{x - x_{0,i}}{\sigma_{i}}\right)^2}`
357 * - Planck
358 - :math:`y = y_{0} + A\cdot \dfrac{2h \cdot c^2}{\lambda^5} \cdot \left(\exp\left(\dfrac{h \cdot c}{\lambda \cdot k \cdot T}\right)-1\right)^{-1}`
359 * - Two half Gaussians
360 - | :math:`y = y_{0} + A \cdot \dfrac{1}{\sqrt{2 \pi} \sigma_{0}} \cdot \exp\left(-\dfrac{1}{2}\left(\dfrac{x - x_{0}}{\sigma_{0}}\right)^2\right)` if :math:`x < x_{0}`
361 | :math:`y = y_{0} + A \cdot \dfrac{1}{\sqrt{2 \pi} \sigma_{1}} \cdot \exp\left(-\dfrac{1}{2}\left(\dfrac{x - x_{1}}{\sigma_{1}}\right)^2\right)` otherwise
362 * - Two back-to-back exponentials
363 - | :math:`y = y_{0} + A_{1} \cdot \exp\left(-x/\tau_{1}\right)` if :math:`x < 0`
364 | :math:`y = y_{0} + A_{2} \cdot \exp(-x/\tau_{2})` otherwise
365 * - Exponential
366 - :math:`y = y_{0} + A \exp\left(B \cdot x\right)`
367 * - Sinusoidal
368 - :math:`y = y_{0} + A \sin\left(2 \pi f \cdot x + \phi\right)`
369 * - Cumulative Distribution Function (CDF)
370 - :math:`y = y_{0} + A \erf\left(\dfrac{x - x_{0}}{\sqrt{2} \sigma}\right)`
371
372 Windowing
373 ^^^^^^^^^
374
375 Create a new signal which is the result of applying a window function to each selected signal.
376
377 The following window functions are available:
378
379 .. list-table::
380 :header-rows: 1
381 :widths: 20, 80
382
383 * - Window function
384 - Reference
385 * - Barthann
386 - :py:func:`scipy.signal.windows.barthann`
387 * - Bartlett
388 - :py:func:`numpy.bartlett`
389 * - Blackman
390 - :py:func:`scipy.signal.windows.blackman`
391 * - Blackman-Harris
392 - :py:func:`scipy.signal.windows.blackmanharris`
393 * - Bohman
394 - :py:func:`scipy.signal.windows.bohman`
395 * - Boxcar (rectangular)
396 - :py:func:`scipy.signal.windows.boxcar`
397 * - Cosine
398 - :py:func:`scipy.signal.windows.cosine`
399 * - Exponential
400 - :py:func:`scipy.signal.windows.exponential`
401 * - Flat top
402 - :py:func:`scipy.signal.windows.flattop`
403 * - Gaussian
404 - :py:func:`scipy.signal.windows.gaussian`
405 * - Hamming
406 - :py:func:`numpy.hamming`
407 * - Hann
408 - :py:func:`numpy.hanning`
409 * - Kaiser
410 - :py:func:`scipy.signal.windows.kaiser`
411 * - Lanczos
412 - :py:func:`scipy.signal.windows.lanczos`
413 * - Nuttall
414 - :py:func:`scipy.signal.windows.nuttall`
415 * - Parzen
416 - :py:func:`scipy.signal.windows.parzen`
417 * - Taylor
418 - :py:func:`scipy.signal.windows.taylor`
419 * - Tukey
420 - :py:func:`scipy.signal.windows.tukey`
421
422 Detrending
423 ^^^^^^^^^^
424
425 Create a new signal which is the detrending of each selected signal.
426 This features is based on SciPy's `scipy.signal.detrend <https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.detrend.html>`_ function.
427
428 The following parameters are available:
429
430 .. list-table::
431 :header-rows: 1
432 :widths: 25, 75
433
434 * - Parameter
435 - Description
436 * - Method
437 - Detrending method: 'linear' or 'constant'. See SciPy's `scipy.signal.detrend <https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.detrend.html>`_ function.
438
439 Interpolation
440 ^^^^^^^^^^^^^
441
442 Create a new signal which is the interpolation of each selected signal
443 with respect to a second signal X-axis (which might be the same as one of
444 the selected signals).
445
446 The following interpolation methods are available:
447
448 .. list-table::
449 :header-rows: 1
450 :widths: 25, 75
451
452 * - Method
453 - Description
454 * - Linear
455 - Linear interpolation, using using NumPy's `interp <https://docs.scipy.org/doc/numpy/reference/generated/numpy.interp.html>`_ function
456 * - Spline
457 - Cubic spline interpolation, using using SciPy's `scipy.interpolate.splev <https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.splev.html>`_ function
458 * - Quadratic
459 - Quadratic interpolation, using using NumPy's `polyval <https://docs.scipy.org/doc/numpy/reference/generated/numpy.polyval.html>`_ function
460 * - Cubic
461 - Cubic interpolation, using using SciPy's `Akima1DInterpolator <https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.Akima1DInterpolator.html>`_ class
462 * - Barycentric
463 - Barycentric interpolation, using using SciPy's `BarycentricInterpolator <https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.BarycentricInterpolator.html>`_ class
464 * - PCHIP
465 - Piecewise Cubic Hermite Interpolating Polynomial (PCHIP) interpolation, using using SciPy's `PchipInterpolator <https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.PchipInterpolator.html>`_ class
466
467 Resampling
468 ^^^^^^^^^^
469
470 Create a new signal which is the resampling of each selected signal.
471
472 The following parameters are available:
473
474 .. list-table::
475 :header-rows: 1
476 :widths: 25, 75
477
478 * - Parameter
479 - Description
480 * - Method
481 - Interpolation method (see previous section)
482 * - Fill value
483 - Interpolation fill value (see previous section)
484 * - Xmin
485 - Minimum X value
486 * - Xmax
487 - Maximum X value
488 * - Mode
489 - Resampling mode: step size or number of points
490 * - Step size
491 - Resampling step size
492 * - Number of points
493 - Resampling number of points
494
495 Stability analysis
496 ^^^^^^^^^^^^^^^^^^
497
498 Create a new signal which is the result of a stability analysis of each selected signal.
499
500 The following stability analysis methods are available:
501
502 .. list-table::
503 :header-rows: 1
504 :widths: 25, 75
505
506 * - Function
507 - Description
508 * - Allan variance
509 - Measure of the stability of a signal: defined as the variance of the difference between two successive measurements as a function of the time interval between them.
510 * - Allan deviation
511 - Square root of the Allan variance.
512 * - Overlapping Allan deviation
513 - A more robust version of the Allan variance that overlaps successive segments to improve statistical confidence.
514 * - Modified Allan variance
515 - A variation of the Allan variance that accounts for phase noise by introducing a filtering operation.
516 * - Hadamard variance
517 - An alternative to Allan variance, more robust to linear frequency drift in the signal
518 * - Total variance
519 - Extends the Allan variance concept to cover all possible averaging intervals.
520 * - Time deviation
521 - Derived from Allan deviation, quantifies stability in terms of time rather than frequency.
522
523 .. note::
524
525 The "All stability features" option allows to compute all stability analysis methods at once.