Debian Codegraph @

doc/features/common/settings.rst

raw
1 .. _settings:
2
3 Settings
4 ========
5
6 .. meta::
7 :description: Settings of DataLab, the open-source scientific data analysis and visualization platform
8 :keywords: DataLab, settings, scientific, data, analysis, visualization, platform
9
10 DataLab provides a comprehensive settings dialog to customize the application behavior,
11 visualization defaults, and I/O operations. The settings are organized into five tabs:
12 General, Processing, Visualization, I/O, and Console.
13
14 General
15 -------
16
17 The General settings tab contains main window and general feature settings:
18
19 .. figure:: /images/shots/settings_main.png
20
21 General settings tab
22
23 **Color mode**
24 Choose the color mode for the application interface (e.g., light, dark, or auto).
25
26 **Process isolation**
27 When enabled, each computation runs in a separate process, preventing the application
28 from freezing during long computations. This is the recommended setting for better
29 responsiveness.
30
31 **RPC server**
32 Enable the RPC (Remote Procedure Call) server to communicate with external applications,
33 such as your own scripts running in Spyder, Jupyter, or other software. This allows
34 programmatic control of DataLab.
35
36 **Web API localhost bypass**
37 When enabled (default), connections from localhost (127.0.0.1) to the Web API do not
38 require authentication. This simplifies notebook integration when DataLab-Kernel runs
39 on the same machine. Disable for stricter security if needed.
40
41 .. note::
42
43 When this option is enabled, any application running on your local machine can
44 access the DataLab Web API without a token. Disable this option if you need
45 stricter security.
46
47 **Memory threshold**
48 Set a threshold (in MB) below which a warning is displayed before loading new data.
49 This helps prevent out-of-memory errors when working with large datasets. Set to 0
50 to disable the warning.
51
52 **Third-party plugins**
53 Enable or disable third-party plugins at startup.
54
55 **Plugins path**
56 Specify the directory path where DataLab should look for third-party plugins.
57 DataLab will also discover plugins in your PYTHONPATH.
58
59 Processing
60 ----------
61
62 The Processing settings tab controls computation behavior and default parameters:
63
64 .. figure:: /images/shots/settings_proc.png
65
66 Processing settings tab
67
68 **Operation mode**
69 Choose the operation mode for computations taking N inputs:
70
71 - **Single**: single operand mode
72 - **Pairwise**: pairwise operation mode
73
74 .. note::
75
76 These operation modes determine how DataLab handles computations involving
77 multiple objects. They apply to two types of operations:
78
79 - **N→1 operations**: Combine N (≥2) objects into 1 output (e.g. sum, average)
80 - **N+1→N operations**: Apply an operation between N (≥1) objects and 1 operand
81 to produce N outputs (e.g. difference, division)
82
83 **Single operand mode** (default): Operations are applied independently within
84 each group.
85
86 - For **N→1 operations**: All objects in each group are combined into one result
87 per group. Example with groups G1={A, B} and G2={C, D}, sum operation:
88
89 - Result: Σ(A,B) and Σ(C,D) (one per group)
90
91 - For **N+1→N operations**: Each selected object is combined with a single
92 reference operand. Example with groups G1={A, B} and G2={C, D}, difference
93 with reference R:
94
95 - In G1: A-R, B-R
96 - In G2: C-R, D-R
97
98 **Pairwise operation mode**: Objects from different groups are combined at
99 matching positions (all groups must have the same number of objects).
100
101 - For **N→1 operations**: Objects at the same position in each group are
102 combined. Example with groups G1={A, B} and G2={C, D}, sum operation:
103
104 - Result: A+C and B+D (pairing by position)
105
106 - For **N+1→N operations**: Objects at matching positions are combined pairwise.
107 Example with groups G1={A, B}, G2={C, D}, difference with group G3={E, F}:
108
109 - New group 1: A-E, B-F
110 - New group 2: C-E, D-F
111
112 **Use signal bounds for new signals**
113 When enabled, the xmin and xmax values for new signals are initialized from
114 the current signal's bounds. When disabled, default values are used.
115
116 **Use image dimensions for new images**
117 When enabled, the width and height values for new images are initialized from
118 the current image's dimensions. When disabled, default values are used.
119
120 **FFT shift**
121 Enable FFT shift to center the zero-frequency component in the frequency spectrum
122 for easier visualization and analysis.
123
124 **Extract multiple ROIs in a single object**
125 When enabled, multiple ROIs (Regions of Interest) are extracted into a single object.
126 When disabled, each ROI is extracted into a separate object.
127
128 **Ignore warnings**
129 Suppress warning messages during computations.
130
131 **X-array compatibility behavior**
132 Choose the behavior when X arrays are incompatible in multi-signal computations:
133
134 - **Ask**: display a confirmation dialog (default)
135 - **Interpolate**: automatically interpolate signals
136
137 Result management
138 ^^^^^^^^^^^^^^^^^
139
140 **Keep results in metadata after computation**
141 When enabled, results from previous analyses are kept in the object's metadata after
142 computation. When disabled, results are removed. This option is disabled by default
143 to avoid confusion from outdated results.
144
145 **Show results dialog automatically after processing**
146 When enabled, the results dialog is shown automatically after each processing operation
147 producing results. When disabled, the results dialog is not shown automatically but
148 results can still be viewed using the dedicated button or menu option.
149
150 Visualization
151 -------------
152
153 The Visualization settings tab controls how data is displayed. This tab is organized
154 into four sub-tabs: Common, Signals, Images, and Results.
155
156 Common settings
157 ^^^^^^^^^^^^^^^
158
159 The Common sub-tab contains settings that apply to all visualizations:
160
161 .. figure:: /images/shots/settings_view_common.png
162
163 Visualization settings - Common sub-tab
164
165 **Plot toolbar position**
166 Choose where to position the plot toolbar (top, bottom, left, or right of the plot).
167
168 **Ignore title insertion message**
169 Suppress the information message when inserting an object title as an annotation label.
170
171 Signals
172 ^^^^^^^
173
174 The Signals sub-tab contains settings specific to signal visualizations:
175
176 .. figure:: /images/shots/settings_view_signals.png
177
178 Visualization settings - Signals sub-tab
179
180 **Default line width**
181 Default line width for curves representing signals. This setting affects all signal
182 visualizations unless overridden individually. Note: for signals exceeding the line
183 width performance threshold (see below), the line width is automatically clamped to
184 1.0 for optimal rendering performance.
185
186 **Line width performance threshold**
187 For signals with more than this number of points (default: 1,000), line width is
188 automatically limited to 1.0 for performance reasons. This prevents the ~10x rendering
189 slowdown caused by Qt's raster engine when drawing thick lines (width > 1.0) on large
190 datasets. For smaller signals, the configured default line width applies normally.
191 This optimization is transparent and requires no user intervention.
192
193 **Use auto downsampling**
194 Enable automatic downsampling for large signals to improve performance and
195 visualization clarity.
196
197 **Downsampling max points**
198 Maximum number of points to display when downsampling is enabled (default: 10,000).
199
200 **Autoscale margin**
201 Percentage of margin to add around data when auto-scaling signal plots. A value of
202 0.2% adds a small margin for better visualization. Set to 0% for no margin (exact
203 data bounds).
204
205 **DateTime format (s/min/h)**
206 Format string for datetime X-axis labels when using standard time units (s, min, h).
207 Uses Python's strftime format codes (e.g., %H:%M:%S for hours:minutes:seconds).
208
209 **DateTime format (ms/μs/ns)**
210 Format string for datetime X-axis labels when using sub-second time units (ms, μs, ns).
211 Uses Python's strftime format codes (e.g., %H:%M:%S.%f for hours:minutes:seconds.microseconds).
212
213 **Results: edit shape styles**
214 Click this button to configure the visual style for annotation shapes
215 (rectangles, circles, segments, etc.) displayed on signal plots. This includes:
216
217 - Line style, color, and width
218 - Fill pattern, color, and transparency
219 - Symbol shape, size, and colors
220
221 These settings apply to all result shapes drawn on signal plots (e.g., peak markers,
222 FWHM indicators, feature detection results).
223
224 **Results: edit marker styles**
225 Click this button to configure the visual style for cursor markers on
226 signal plots. This includes:
227
228 - Line style, color, and width
229 - Symbol appearance
230 - Text label formatting and positioning
231 - Background transparency
232
233 These settings apply to cursor-type markers used in signal analysis results.
234
235 Images
236 ^^^^^^
237
238 The Images sub-tab contains settings specific to image visualizations:
239
240 .. figure:: /images/shots/settings_view_images.png
241
242 Visualization settings - Images sub-tab
243
244 **Lock aspect ratio to 1:1**
245 When enabled, the aspect ratio of images is locked to 1:1. When disabled, the aspect
246 ratio is determined by the physical pixel size (default and recommended setting).
247
248 **Eliminate outliers**
249 Percentage of the highest and lowest values to eliminate from the image histogram.
250 Recommended values are below 1%.
251
252 **Autoscale margin**
253 Percentage of margin to add around data when auto-scaling image plots. A value of
254 0.2% adds a small margin for better visualization. Set to 0% for no margin (exact
255 data bounds).
256
257 **Default image visualization settings**
258 Click this button to configure default visualization settings for images (colormap,
259 interpolation, contrast, etc.).
260
261 **Results: edit shape styles**
262 Click this button to configure the visual style for annotation shapes
263 displayed on image plots. Parameters are similar to signal shapes but optimized
264 for image visualization (e.g., different colors for better visibility
265 on images).
266
267 **Results: edit marker styles**
268 Click this button to configure the visual style for cursor markers on
269 image plots.
270
271 Results
272 ^^^^^^^
273
274 The Results sub-tab contains settings for displaying analysis results on plots:
275
276 .. figure:: /images/shots/settings_view_results.png
277
278 Visualization settings - Results sub-tab
279
280 These settings control how analysis results are displayed on plots to prevent
281 performance issues with large datasets:
282
283 **Maximum shapes to draw**
284 Maximum number of geometry shapes to draw on the plot (default: 1,000). When
285 the number of shapes exceeds this limit, only the first N shapes are drawn
286 and a warning label is displayed.
287
288 **Maximum cells in label**
289 Maximum number of table cells (rows × columns) to display in merged result
290 labels on plots (default: 100). When the number of cells exceeds this limit,
291 the table is truncated.
292
293 **Maximum columns in label**
294 Maximum number of columns to display in merged result labels (default: 15).
295 When the number of columns exceeds this limit, only the first N columns are
296 displayed.
297
298 **Show the merged result label by default**
299 When enabled, the merged result label is shown on the plot by default for new
300 objects. This setting can be toggled per-object using the checkbox in the
301 Properties panel.
302
303 .. note::
304
305 These settings affect only the visualization of results on plots. They do not
306 affect the actual computation or storage of results in metadata.
307
308 I/O
309 ---
310
311 The I/O settings tab controls input/output operations:
312
313 .. figure:: /images/shots/settings_io.png
314
315 I/O settings tab
316
317 **Clear workspace before loading HDF5 file**
318 When enabled, the workspace is cleared before loading an HDF5 file.
319
320 **Ask before clearing workspace**
321 When enabled, a confirmation dialog is displayed before clearing the workspace.
322
323 **HDF5 full path in title**
324 When enabled, the full path of the HDF5 dataset is used as the title for the
325 signal/image object. When disabled, only the dataset name is used.
326
327 **HDF5 file name in title**
328 When enabled, the HDF5 file name is appended as a suffix to the title of the
329 signal/image object.
330
331 Console
332 -------
333
334 The Console settings tab configures the internal console for debugging and advanced users:
335
336 .. figure:: /images/shots/settings_console.png
337
338 Console settings tab
339
340 **Console enabled**
341 Enable the internal Python console for debugging and advanced scripting.
342
343 **Show console on error**
344 When enabled, the console is automatically shown when an error occurs in the
345 application. This is useful for debugging as it allows you to see the error
346 traceback.
347
348 **External editor path**
349 Path to an external text editor to use for editing Python code from the console.
350
351 **External editor arguments**
352 Command-line arguments to pass to the external editor.