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