Debian Codegraph @

doc/features/signal/menu_analysis.rst

raw
1 .. _sig-menu-analysis:
2
3 Analysis features on Signals
4 =============================
5
6 This section describes the signal analysis 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-processing` for information on processing features on
12 signals.
13
14 .. figure:: /images/shots/s_analysis.png
15
16 Screenshot of the "Analysis" menu.
17
18 When the "Signal Panel" is selected, the menus and toolbars are updated to
19 provide signal-related actions.
20
21 The "Analysis" menu allows you to perform various computations on the
22 selected signals, such as statistics, full width at half-maximum, or
23 full width at 1/e².
24
25 .. note::
26
27 In DataLab vocabulary, an "analysis" is a feature that computes a scalar
28 result from a signal. This result is stored as metadata, and thus attached
29 to signal. This is different from a "processing" which creates a new signal
30 from an existing one.
31
32 Statistics
33 ^^^^^^^^^^
34
35 Compute statistics on selected signal and show a summary table.
36
37 .. figure:: /images/shots/s_stats.png
38
39 Example of statistical summary table: each row is associated to an ROI
40 (the first row gives the statistics for the whole data).
41
42 Histogram
43 ^^^^^^^^^
44
45 Compute histogram of selected signal and show it.
46
47 Parameters are:
48
49 .. list-table::
50 :header-rows: 1
51 :widths: 25, 75
52
53 * - Parameter
54 - Description
55 * - Bins
56 - Number of bins
57 * - Lower limit
58 - Lower limit of the histogram
59 * - Upper limit
60 - Upper limit of the histogram
61
62 .. figure:: /images/shots/s_histogram.png
63
64 Example of histogram.
65
66 Full width at half-maximum
67 ^^^^^^^^^^^^^^^^^^^^^^^^^^
68
69 Compute the Full Width at Half-Maximum (FWHM) of selected signal, using one of the following methods:
70
71 .. list-table::
72 :header-rows: 1
73 :widths: 25, 75
74
75 * - Method
76 - Description
77 * - Zero-crossing
78 - Find the zero-crossings of the signal after having centered its amplitude around zero
79 * - Gauss
80 - Fit data to a Gaussian model using least-square method
81 * - Lorentz
82 - Fit data to a Lorentzian model using least-square method
83 * - Voigt
84 - Fit data to a Voigt model using least-square method
85
86 .. figure:: /images/shots/s_fwhm.png
87
88 The computed result is displayed as an annotated segment.
89
90 Full width at 1/e²
91 ^^^^^^^^^^^^^^^^^^
92
93 Fit data to a Gaussian model using least-square method.
94 Then, compute the full width at 1/e².
95
96 .. note:: Computed scalar results are systematically stored as metadata.
97 Metadata is attached to signal and serialized with it when exporting
98 current session in a HDF5 file.
99
100 Arguments of the min and max
101 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
102
103 Compute the smallest argument of the minima and the smallest argument of the maxima of
104 the selected signal.
105
106 Abscissa at y=...
107 ^^^^^^^^^^^^^^^^^
108
109 Compute the abscissa at a given ordinate value for the selected signal.
110 If there is no solution, the displayed result is NaN.
111 If there are multiple solutions, the displayed result is the smallest value.
112
113 Peak detection
114 ^^^^^^^^^^^^^^
115
116 Create a new signal from semi-automatic peak detection of each selected signal.
117
118 .. figure:: /images/shots/s_peak_detection.png
119
120 Peak detection dialog: threshold is adjustable by moving the
121 horizontal marker, peaks are detected automatically (see vertical
122 markers with labels indicating peak position)
123
124 Sampling rate and period
125 ^^^^^^^^^^^^^^^^^^^^^^^^
126
127 Compute the sampling rate and period of selected signal.
128
129 .. warning:: This feature assumes that the X values are regularly spaced.
130
131 Dynamic parameters
132 ^^^^^^^^^^^^^^^^^^
133
134 Compute the following dynamic parameters on selected signal:
135
136 .. list-table::
137 :header-rows: 1
138 :widths: 25, 75
139
140 * - Parameter
141 - Description
142 * - f
143 - Frequency (sinusoidal fit)
144 * - ENOB
145 - Effective Number Of Bits
146 * - SNR
147 - Signal-to-Noise Ratio
148 * - SINAD
149 - Signal-to-Noise And Distortion Ratio
150 * - THD
151 - Total Harmonic Distortion
152 * - SFDR
153 - Spurious-Free Dynamic Range
154
155 Bandwidth at -3 dB
156 ^^^^^^^^^^^^^^^^^^
157
158 Determine the bandwidth at -3 dB by identifying the range of abscissa values where the signal remains greater than its maximum value minus 3 dB.
159
160 .. warning::
161
162 This feature requires that the signal is expressed in decibels (dB).
163
164 Contrast
165 ^^^^^^^^
166
167 Compute the contrast of selected signal.
168
169 The contrast is defined as the ratio of the difference and the sum of the maximum
170 and minimum values:
171
172 .. math::
173 \text{Contrast} = \dfrac{\text{max}(y) - \text{min}(y)}{\text{max}(y) + \text{min}(y)}
174
175 .. note::
176
177 This feature assumes that the signal is a profile from an image, where the contrast
178 is meaningful. This justifies the optical definition of contrast.
179
180 Extract pulse features
181 ^^^^^^^^^^^^^^^^^^^^^^
182
183 Perform comprehensive pulse analysis on selected signals, automatically extracting timing and amplitude characteristics for step and square pulse signals.
184
185 This feature provides automated pulse characterization with intelligent signal type recognition and robust parameter extraction for digital signal analysis, oscilloscope measurements, and pulse timing validation.
186
187 .. figure:: /images/shots/s_pulse_features.png
188
189 Pulse features results as displayed in the Signal View.
190
191 **Key Capabilities:**
192
193 * **Automated signal recognition**: Heuristically identifies signal type (step, square, or other) for optimal analysis
194 * **Polarity detection**: Automatically determines positive/negative pulse polarity using baseline comparison
195 * **Comprehensive timing measurements**: Extracts rise time, fall time, FWHM, and timing parameters at specific amplitude fractions
196 * **Baseline characterization**: Analyzes start and end baseline regions for accurate feature computation
197 * **Robust algorithms**: Uses advanced statistical methods with noise tolerance and error handling
198
199 **Parameters:**
200
201 .. list-table::
202 :header-rows: 1
203 :widths: 25, 75
204
205 * - Parameter
206 - Description
207 * - Signal shape
208 - Signal type selection: Auto (automatic detection), Step, or Square
209 * - Start baseline min
210 - Lower X boundary for the start (initial) baseline region
211 * - Start baseline max
212 - Upper X boundary for the start (initial) baseline region
213 * - End baseline min
214 - Lower X boundary for the end (final) baseline region
215 * - End baseline max
216 - Upper X boundary for the end (final) baseline region
217 * - Rise/Fall time
218 - Reference levels for rise/fall time measurement with predefined choices: 5%-95% (High precision), 10%-90% (IEEE standard), 20%-80% (Noisy signals), 25%-75% (Alternative)
219
220 **Extracted Features:**
221
222 The analysis computes the following pulse characteristics:
223
224 .. list-table::
225 :header-rows: 1
226 :widths: 25, 75
227
228 * - Feature
229 - Description
230 * - Signal shape
231 - Detected signal type (STEP, SQUARE, or OTHER)
232 * - Polarity
233 - Signal polarity (+1 for positive, -1 for negative pulses)
234 * - Amplitude
235 - Peak-to-peak amplitude of the pulse
236 * - Offset
237 - DC offset (baseline level)
238 * - Rise time
239 - Time from the lower to upper reference levels during rising edge
240 * - Fall time
241 - Time from the lower to upper reference levels during falling edge (square pulses only)
242 * - FWHM
243 - Full Width at Half Maximum (square pulses only)
244 * - x50
245 - Time at which signal reaches 50% of maximum amplitude
246 * - x100
247 - Time at which signal reaches 100% of maximum amplitude (plateau start)
248 * - Foot duration
249 - Duration of flat region before pulse rise
250 * - Baseline ranges
251 - Extracted start and end baseline boundary coordinates
252
253 .. note::
254
255 Results are displayed in a comprehensive table showing all extracted parameters, and as visual annotations on the signal plot. For step signals, fall-related parameters (fall_time, fwhm) are not applicable and show as None. The feature works best with well-defined pulse signals that have clear baseline regions.
256
257 Show results
258 ^^^^^^^^^^^^
259
260 Show the results of all analyses performed on the selected signals. This shows the
261 same table as the one shown after having performed a computation.
262
263 Results label
264 ^^^^^^^^^^^^^
265
266 Toggle the visibility of result labels on the plot. When enabled, this checkable
267 menu item displays result annotations (such as FWHM, peak positions, or other
268 analysis markers) directly on the signal plot.
269
270 This option is synchronized between Signal and Image panels and persists across
271 sessions. It is only enabled when results are available for the selected signal.
272
273 Plot results
274 ^^^^^^^^^^^^
275
276 Plot the results of analyses performed on the selected signals, with user-defined
277 X and Y axes (e.g. plot the FWHM as a function of the signal index).