Debian Codegraph @

doc/features/common/overview.rst

raw
1 .. _overview:
2
3 Overview
4 ========
5
6 .. meta::
7 :description: Overview and basic concepts of DataLab, the open-source scientific data analysis and visualization platform
8 :keywords: DataLab, workspace, scientific, data, analysis, visualization, platform
9
10 Basic concepts
11 --------------
12
13 Working with DataLab is very easy. The user interface is intuitive and
14 self-explanatory. The main window is divided into two main areas:
15
16 - The left area shows the list of data sets which are currently loaded in
17 DataLab, distibuted over two tabs: **Signals** and **Images**. The user can
18 switch between the two tabs by clicking on the corresponding tab: this
19 switches the main window to the corresponding panel, as well as the menu
20 and toolbar contents. Below the list of data sets, a **Properties** view
21 shows information about the currently selected data set.
22
23 - The right area shows the visualization of the currently selected data set.
24 The visualization is updated automatically when the user selects a new data
25 set in the list of data sets.
26
27 .. figure:: /images/shots/s_app_at_startup.png
28
29 DataLab main window, at startup.
30
31 Internal data model and workspace
32 ---------------------------------
33
34 DataLab has its own internal data model, in which data sets are organized around
35 a tree structure. Each panel in the main window corresponds to a branch of the
36 tree. Each data set shown in the panels corresponds to a leaf of the tree. Inside
37 the data set, the data is organized in an object-oriented way, with a set of
38 attributes and methods. The data model is described in more details in the
39 API section (see :mod:`sigima.objects`).
40
41 For each data set (1D signal or 2D image), not only the data itself is stored,
42 but also a set of metadata, which describes the data or the way it has to be
43 displayed. The metadata is stored in a dictionary, which is accessible through
44 the ``metadata`` attribute of the data set (and may also be browsed in the
45 **Properties** view, with the **Metadata** button).
46
47 The DataLab **Workspace** is defined as the collection of all data sets which
48 are currently loaded in DataLab, in both the **Signals** and **Images** panels.
49
50 Loading and saving the workspace
51 --------------------------------
52
53 The following actions are available to manage the workspace from the **File** menu:
54
55 - **Open HDF5 file**: load a workspace from an HDF5 file.
56
57 - **Save to HDF5 file**: save the current workspace to an HDF5 file.
58
59 - **Browse HDF5 file**: open the :ref:`h5browser` to explore the content of an
60 HDF5 file and import data sets into the workspace.
61
62 .. note::
63
64 Data sets may also be saved or loaded individually, using data formats
65 such as `.txt` or `.npy` for 1D signals (see :ref:`open_signal` for the
66 list of supported formats), , or `.tiff` or `.dcm` for 2D images
67 (see :ref:`open_image` for the list of supported formats).
68
69 Interactive object creation and processing
70 ------------------------------------------
71
72 DataLab provides an interactive workflow for creating objects and adjusting processing
73 parameters, allowing you to fine-tune results without creating multiple objects.
74
75 Interactive object creation
76 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
77
78 When creating a new signal or image using the creation functions (e.g., Gaussian signal,
79 2D peak image, etc.), DataLab stores the creation parameters in the object's metadata.
80 This enables interactive parameter adjustment after creation:
81
82 1. Create a signal or image using **Operations** > **Create** menu
83 2. Select the created object in the list
84 3. A **Creation** tab appears in the Properties panel (bottom-left)
85 4. Modify any creation parameter (amplitude, frequency, size, etc.)
86 5. Click **Apply** to regenerate the object with new parameters
87
88 The object is updated in-place, preserving any subsequent processing or analysis results.
89 This is particularly useful for:
90
91 - Exploring different parameter values without cluttering the workspace
92 - Fine-tuning object characteristics while observing the results
93 - Educational purposes to demonstrate parameter effects
94
95 .. note::
96
97 Interactive creation is only available for objects created with parameter classes
98 (not for imported data from files).
99
100 Interactive 1-to-1 processing
101 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
102
103 When applying a 1-to-1 processing operation that has configurable parameters (e.g.,
104 Gaussian filter, threshold, morphological operations), DataLab stores the processing
105 metadata, enabling parameter adjustment and re-processing:
106
107 1. Apply a processing operation with parameters (e.g., **Processing** > **Filtering** > **Gaussian filter**)
108 2. The result object contains processing metadata (parameters, source object, function name)
109 3. Select the processed object in the list
110 4. A **Processing** tab appears in the Properties panel
111 5. Modify processing parameters (e.g., filter sigma value)
112 6. Click **Apply** to re-process with updated parameters
113
114 The processed object is updated in-place with the new results. This workflow is ideal for:
115
116 - Iteratively tuning filter parameters while observing results in real-time
117 - Adjusting threshold values without creating multiple intermediate objects
118 - Experimenting with different morphological structure element sizes
119 - Educational demonstrations of parameter effects on processing results
120
121 .. note::
122
123 **Processing metadata requirements:**
124
125 - Only works for 1-to-1 processing functions with parameter classes
126 - Processing functions without parameters (e.g., absolute value, inverse) work as before
127 - Source object must still exist for re-processing (error shown if deleted)
128
129 **Not supported for:**
130
131 - 2-to-1 processing (operations combining two objects)
132 - n-to-1 processing (operations aggregating multiple objects)
133 - These patterns don't benefit significantly from interactive parameter adjustment
134
135 Example workflow
136 ^^^^^^^^^^^^^^^^
137
138 Here's a typical workflow using interactive processing:
139
140 1. **Create a test signal**: Operations > Create > Gaussian signal
141
142 - Initial parameters: amplitude=1.0, mu=50, sigma=10
143
144 2. **Adjust creation parameters**: In the Creation tab, change sigma to 20, click Apply
145
146 - Signal is regenerated with new width
147
148 3. **Apply Gaussian filter**: Processing > Filtering > Gaussian filter
149
150 - Initial sigma=2.0
151
152 4. **Fine-tune filtering**: In the Processing tab, try sigma=1.0, then sigma=5.0
153
154 - Each Apply updates the filtered result
155 - Compare different smoothing levels without creating multiple objects
156
157 This interactive approach provides immediate visual feedback and keeps your workspace
158 organized by avoiding proliferation of test objects with slightly different parameters.