Debian Codegraph @

doc/features/signal/menu_edit.rst

raw
1 .. _sig-menu-edit:
2
3 Manipulate metadata and annotations
4 ===================================
5
6 This section describes how to manipulate metadata and annotations in DataLab.
7
8 Signal metadata contains various information about the signal or its representation,
9 such as view settings, Regions Of Interest (ROIs), processing chain history,
10 analysis results, and any other information that you may have added to the metadata
11 of a signal (or that comes from the signal file itself).
12
13 .. figure:: /images/shots/s_edit.png
14
15 Screenshot of the "Edit" menu.
16
17 The "Edit" menu allows you to perform classic editing operations on the current signal
18 or group of signals (create/rename group, move up/down, delete signal/group of signals,
19 etc.).
20
21 As detailed below, it also allows you to:
22
23 - Navigate and utilize the processing chain history through actions like "Recompute"
24 and "Select source objects".
25 - Manipulate metadata and annotations associated with the current signal, thanks to the
26 "Metadata" and "Annotations" submenus which provide the following features.
27
28 Recompute
29 ---------
30
31 The "Recompute" |recompute| action allows you to recompute the selected signal(s) using
32 their original processing parameters. This is useful when you want to re-execute the
33 processing chain that was used to create a signal, for example after modifying global
34 settings or dependencies.
35
36 .. |recompute| image:: ../../../datalab/data/icons/edit/recompute.svg
37 :width: 24px
38 :height: 24px
39 :class: dark-light no-scaled-link
40
41 .. note::
42
43 This action is only available for signals that were created through processing
44 operations and have stored processing parameters.
45
46 Select source objects
47 ---------------------
48
49 The "Select source objects" |goto_source| action allows you to select the source
50 object(s) that were used to create the currently selected signal. This helps trace
51 back the processing history and understand which original signals were used as input
52 for the current result.
53
54 .. |goto_source| image:: ../../../datalab/data/icons/edit/goto_source.svg
55 :width: 24px
56 :height: 24px
57 :class: dark-light no-scaled-link
58
59 .. note::
60
61 This action is only available when exactly one signal is selected and that signal
62 has source object references.
63
64 Metadata
65 --------
66
67 .. figure:: /images/shots/s_edit_metadata.png
68
69 Screenshot of the "Metadata" submenu.
70
71 Copy/paste metadata
72 ^^^^^^^^^^^^^^^^^^^
73
74 As metadata contains useful information about the signal, it can be copied and pasted
75 from one signal to another by selecting the "Copy metadata" |metadata_copy| and
76 "Paste metadata" |metadata_paste| actions in the "Edit" menu.
77
78 .. |metadata_copy| image:: ../../../datalab/data/icons/edit/metadata_copy.svg
79 :width: 24px
80 :height: 24px
81 :class: dark-light no-scaled-link
82
83 .. |metadata_paste| image:: ../../../datalab/data/icons/edit/metadata_paste.svg
84 :width: 24px
85 :height: 24px
86 :class: dark-light no-scaled-link
87
88 This feature allows you to tranfer those information from one signal to another:
89
90 - :ref:`Regions Of Interest (ROIs) <sig-menu-roi>`: that is a very efficient way to reuse
91 the same ROI on different signals and easily compare the results of the analysis
92 on those signals
93 - Analyze results, such as peak positions or FHWM intervals (the relevance of
94 transferring such information depends on the context and is up to the user to decide)
95 - Any other information that you may have added to the metadata of a signal
96
97 .. note::
98
99 Copying metadata from a signal to another will overwrite the metadata of the
100 destination signal (for the metadata keys that are common to both signals)
101 or simply add the metadata keys that are not present in the destination signal.
102
103 Import/export metadata
104 ^^^^^^^^^^^^^^^^^^^^^^
105
106 Metadata can also be imported and exported from/to a JSON file using the "Import
107 metadata" |metadata_import| and "Export metadata" |metadata_export| actions in the
108 "Edit" menu. This is exactly the same as the copy/paste metadata feature (see above
109 for more details on the use cases of this feature), but it allows you to save the
110 metadata to a file and then import it back later.
111
112 .. |metadata_import| image:: ../../../datalab/data/icons/edit/metadata_import.svg
113 :width: 24px
114 :height: 24px
115 :class: dark-light no-scaled-link
116
117 .. |metadata_export| image:: ../../../datalab/data/icons/edit/metadata_export.svg
118 :width: 24px
119 :height: 24px
120 :class: dark-light no-scaled-link
121
122 Delete metadata
123 ^^^^^^^^^^^^^^^
124
125 When deleting metadata using the "Delete metadata" |metadata_delete| action in the
126 "Edit" menu, you will be prompted to confirm the deletion of Region of Interests (ROIs)
127 if they are present in the metadata. After this eventual confirmation, the metadata
128 will be deleted, meaning that analysis results, ROIs, and any other information
129 associated with the signal will be lost.
130
131 .. |metadata_delete| image:: ../../../datalab/data/icons/edit/metadata_delete.svg
132 :width: 24px
133 :height: 24px
134 :class: dark-light no-scaled-link
135
136 Add metadata
137 ------------
138
139 The "Add metadata" |metadata_add| action allows you to add custom metadata items to
140 one or more selected signals. This is useful for tagging signals with experiment IDs,
141 sample names, processing steps, or any other custom information.
142
143 .. |metadata_add| image:: ../../../datalab/data/icons/edit/metadata_add.svg
144 :width: 24px
145 :height: 24px
146 :class: dark-light no-scaled-link
147
148 .. figure:: /images/shots/s_add_metadata.png
149
150 Add metadata dialog.
151
152 When you select "Add metadata..." from the Edit menu, a dialog appears where you can:
153
154 - **Metadata key**: Enter the name of the metadata field to add
155 - **Value pattern**: Define a pattern for the metadata value using Python format strings
156 - **Conversion**: Choose how to store the value (string, float, integer, or boolean)
157 - **Preview**: See how the metadata will be added to each selected signal
158
159 The value pattern supports the following placeholders:
160
161 - ``{title}``: Signal title
162 - ``{index}``: 1-based index of the signal in the selection
163 - ``{count}``: Total number of selected signals
164 - ``{xlabel}``, ``{xunit}``, ``{ylabel}``, ``{yunit}``: Axis labels and units
165 - ``{metadata[key]}``: Access existing metadata values
166
167 You can also use format modifiers:
168
169 - ``{title:upper}``: Convert to uppercase
170 - ``{title:lower}``: Convert to lowercase
171 - ``{index:03d}``: Format as 3-digit number with leading zeros
172
173 **Examples:**
174
175 - Add experiment ID: key=``experiment_id``, pattern=``EXP_{index:03d}``, conversion=string
176 → Creates metadata like ``experiment_id="EXP_001"``
177
178 - Add sample temperature: key=``temperature``, pattern=``{metadata[temp]}``, conversion=float
179 → Copies temperature from existing metadata and converts to float
180
181 - Mark processed signals: key=``is_processed``, pattern=``true``, conversion=bool
182 → Sets ``is_processed=True`` for all selected signals
183
184 Annotations
185 -----------
186
187 Annotations are visual elements that can be added to signals to highlight specific
188 features, mark regions of interest, or add explanatory notes. DataLab provides a
189 dedicated submenu in the "Edit" menu for managing annotations.
190
191 .. figure:: /images/shots/s_edit_annotations.png
192
193 Screenshot of the "Annotations" submenu.
194
195 Copy/paste annotations
196 ^^^^^^^^^^^^^^^^^^^^^^
197
198 Annotations can be copied from one signal and pasted to one or more other signals
199 using the "Copy annotations" |annotations_copy| and "Paste annotations" |annotations_paste|
200 actions. This is useful when you want to apply the same visual markers across multiple
201 signals.
202
203 .. |annotations_copy| image:: ../../../datalab/data/icons/edit/annotations_copy.svg
204 :width: 24px
205 :height: 24px
206 :class: dark-light no-scaled-link
207
208 .. |annotations_paste| image:: ../../../datalab/data/icons/edit/annotations_paste.svg
209 :width: 24px
210 :height: 24px
211 :class: dark-light no-scaled-link
212
213 The "Paste annotations" action is only enabled when there are annotations in the
214 clipboard (i.e., after using "Copy annotations").
215
216 Edit annotations
217 ^^^^^^^^^^^^^^^^
218
219 The "Edit annotations" |annotations_edit| action opens a dialog where you can view,
220 add, modify, or remove annotations from the current signal. This provides a visual
221 way to manage all annotations on a signal.
222
223 .. |annotations_edit| image:: ../../../datalab/data/icons/edit/annotations_edit.svg
224 :width: 24px
225 :height: 24px
226 :class: dark-light no-scaled-link
227
228 Import/export annotations
229 ^^^^^^^^^^^^^^^^^^^^^^^^^^
230
231 Annotations can be saved to and loaded from JSON files (.dlabann extension) using
232 the "Import annotations" |annotations_import| and "Export annotations" |annotations_export|
233 actions. This allows you to:
234
235 - Save annotation sets for later reuse
236 - Share annotations with colleagues
237 - Archive annotations separately from signal data
238 - Apply the same annotations to different signals across sessions
239
240 .. |annotations_import| image:: ../../../datalab/data/icons/edit/annotations_import.svg
241 :width: 24px
242 :height: 24px
243 :class: dark-light no-scaled-link
244
245 .. |annotations_export| image:: ../../../datalab/data/icons/edit/annotations_export.svg
246 :width: 24px
247 :height: 24px
248 :class: dark-light no-scaled-link
249
250 The "Export annotations" action is only available when the selected signal has
251 annotations.
252
253 Delete annotations
254 ^^^^^^^^^^^^^^^^^^
255
256 The "Delete annotations" |annotations_delete| action removes all annotations from the
257 selected signal(s). This action is only enabled when the selected signal(s) have
258 annotations.
259
260 .. |annotations_delete| image:: ../../../datalab/data/icons/edit/annotations_delete.svg
261 :width: 24px
262 :height: 24px
263 :class: dark-light no-scaled-link
264
265 .. note::
266
267 Annotations are stored separately from metadata and analysis results. Deleting
268 annotations does not affect ROIs or other metadata items.
269
270 Signal titles
271 -------------
272
273 Signal titles may be considered as metadata from a user point of view, even if they
274 are not stored in the metadata of the signal (but in an attribute of the signal object).
275
276 The "Edit" menu allows you to:
277
278 - "Add object title to plot": this action will add a label on top of the signal
279 with its title.
280
281 - "Copy titles to clipboard" |copy_titles|: this action will copy the titles of the
282 selected signals to the clipboard, which might be useful to paste them in a text
283 editor or in a spreadsheet.
284
285 Example of the content of the clipboard:
286
287 .. code-block:: text
288
289 g001:
290 s001: lorentz(a=1,sigma=1,mu=0,ymin=0)
291 s002: derivative(s001)
292 s003: wiener(s002)
293 g002: derivative(g001)
294 s004: derivative(s001)
295 s005: derivative(s002)
296 s006: derivative(s003)
297 g003: fft(g002)
298 s007: fft(s004)
299 s008: fft(s005)
300 s009: fft(s006)
301
302 .. |copy_titles| image:: ../../../datalab/data/icons/edit/copy_titles.svg
303 :width: 24px
304 :height: 24px
305 :class: dark-light no-scaled-link