| 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. |