Debian Codegraph @

docs/source/manual/The_SEC_Control_Panel_and_SEC_Plot_Panel.rst

raw
1 The SEC Control Panel and SEC Plot Panel
2 ========================================
3
4 **WARNING:** The manual is current several versions out of date. While it may
5 still be useful for some users, please refer to the tutorial for the most
6 up-to-date information.
7
8 .. _secplot:
9
10 When SEC-SAXS data is loaded into RAW, it is placed in the SEC tab of the Control
11 Panel, and displayed in the SEC Plot window. This section will cover the features
12 of the SEC control panel and the SEC plot panel.
13
14 SEC-SAXS data is assumed to come from continuous collection of images while sample is
15 being eluted from an FPLC column. Depending on the frame rate of the detector and the
16 total elution time, this can generate thousands of images. The basic approach RAW uses
17 to deal with this data is to load every scattering profile (or integrate every image
18 into a scattering profile), and associate it with a single SEC data item. For each SEC
19 item, the total (or average) intensity in each scattering profile is plotted vs. frame
20 number, where frame number is simply what position the item was loaded in (so if 10 items
21 are loaded, the frame number for the first item loaded would be 0, for the next item loaded
22 1, etc). For standard SEC-SAXS data, this intensity vs. frame number should look similar to
23 the UV chromatograph of the sample after it passes through the column. Some analysis can be
24 carried out directly on this SEC data item, and the scattering profiles of interest can be
25 extracted for further analysis.
26
27
28 The SEC control panel
29 ---------------------
30
31 The SEC control panel refers to the panel that is shown in the Control panel when the SEC
32 tab is selected.
33
34 The panel consists of three parts. The top part is a set of controls for loading SEC items,
35 controlling the SEC online mode, and analyzing SEC items. The middle part is where individual
36 SEC items loaded into RAW are shown. The bottom part consists of buttons that allow you to
37 save or remove the SEC items. Further manipulation of the SEC items can be done from the right
38 click (context) menu.
39
40 An individual item in the SEC list is the called a SEC data item. It is associated with two
41 curves on the SEC plot, one plotted on the right y axis and one on the left y axis.
42
43
44 SEC Data Items
45 ~~~~~~~~~~~~~~
46
47 When a new item is plotted, a data item is added to the SEC list in the SEC control panel. This
48 allows you to control the properties of the data item, and perform analysis on it.
49
50 The name of the data item is displayed for each item. If an item is given a different name for the
51 plot legend, this legend name is displayed in [square brackets] next to the item name. On the same
52 line as the item name, on the right side of the data item, there are several buttons that can be
53 used for further manipulation of the data item.
54
55 SEC data items are different from Manipulation and IFT data items as they have many (often hundreds
56 or thousands) of scattering profiles associated with a single data item, and they can have new
57 profiles appended to them after they are loaded.
58
59 **Note:** If there is a \* to the left of the item name (between the checkbox and the item name),
60 it indicates there are unsaved changes to the item. This can occur if the item is newly created IFT
61 data (such as from the BIFT or GNOM panels), or if item properties such as the name have been changed.
62
63
64 Showing/Hiding data items on the SEC plot
65 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
66
67 To show/hide the curves on the plot associated with a data item, click the checkbox next to the
68 filename. If the checkbox is checked, the item is currently shown on the SEC plot, if the checkbox
69 is unchecked, the item is currently hidden on the SEC plot.
70
71
72 Data item buttons
73 ~~~~~~~~~~~~~~~~~
74
75 On the right of the data item are several buttons for controlling the data item. In order of left
76 to right, these buttons have the following properties.
77
78 *Extended Info*
79
80 By hovering the mouse over the i in the blue circle button, a tooltip will appear which shows more
81 information about the item. It shows the buffer range and window size used (if any) to calculate the
82 structural parameters of the SEC data item as a function of frame number.
83
84 *Locate Line*
85
86 The target button is used to highlight the scattering profile on the graph that is associated
87 with the data item. When the target is pressed, it ‘bolds’ the line each plotted curve associated
88 with the data item (increases the line width by several points). When the target is pressed again,
89 the line width is set back to normal. You can tell if a line is currently bolded, as the target will
90 be orange instead of grey.
91
92 *Line Properties*
93
94 The colored line button has two purposes. First, the color matches the current color of the Intensity
95 curve in the SEC Plot. Second, when pressed it opens a :ref:`line properties dialog <lineproperties>`
96 which allows you to set the legend label; the line style, width, and color; the data point
97 marker style, size, line color, and fill color; and the error bar line style, width, and
98 color for each line associated with the SEC data item.
99
100 *Mark*
101
102 The star button marks an item. This is used when doing operations such as sending data frames to plot
103 or calculating structural parameters. In those cases, the marked (also referred to as starred) item
104 has a special significance.
105
106
107 Loading data items
108 ~~~~~~~~~~~~~~~~~~
109
110 SEC data items can be loaded from the :ref:`files tab <filepanel>`. There is an additional way
111 to load files available in the SEC control panel, this method is intended to be used in
112 conjunction with the SEC online mode. This method is described in the rest of this section.
113
114 At the top of the SEC control panel, there is a section for loading files. It has a button
115 “Select file in SEC run”, and then descriptive information about the file: the image prefix,
116 the run number, and the frame numbers of the file. Note that none of these descriptive fields
117 can be edited. Below the descriptive fields is an “Update” button and an “Automatically Update”
118 checkbox.
119
120 To load a SEC curve using this method, click the “Select file in SEC run” button. In the file
121 browser that pops up, select any file in the SEC data set. The data set will automatically be
122 loaded into RAW as a SEC item, and the descriptive information will be displayed in the appropriate
123 boxes. This loaded file can then be used with the SEC automatic update mode described
124 :ref:`below <secautoupdate>`.
125
126 **Note:** Due to how files are loaded from the SEC control panel, it only works for certain header
127 file types. RAW must be able to automatically determine what files are associated with the SEC run,
128 from any file in the run. At the moment, this can only be done with the G1 and G1 WAXS header file
129 formats. If you want to have a particular beamline’s file format added to this loading (and thus able
130 to use the online mode) please contact the RAW developers.
131
132
133 Updating a SEC data item
134 ~~~~~~~~~~~~~~~~~~~~~~~~
135
136 If a SEC data item is loaded via the SEC control panel, it can be updated if additional files are
137 added to the folder that are part of the data collection. This can only be done for the most recent
138 file loaded via the SEC control panel, for which the descriptive information is shown at the top of
139 the SEC control panel.
140
141 To do this update, hit the “Update” button on the SEC control panel. RAW will automatically determine
142 all of the files associated with the SEC run, based on the file you selected with the “Select file
143 in SEC run” button, determine if any of those files have not yet been loaded, and if so,
144 load the files and add them to the SEC item as appropriate.
145
146 This is useful when working at the beamline while data is being collected, as you may want
147 to start analysis of the SEC curve before all of the images are taken.
148
149
150 SEC automatic update (online mode)
151 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
152
153 .. _secautoupdate:
154
155 The SEC control panel can be used in an online mode, where a SEC curve is automatically
156 updated as data comes in. All of the conditions for manually updating a curve, described above,
157 must be met. Instead of using the “Update” button as in that section, check the “Automatically
158 Update” box in the SEC control panel.
159
160 **Note:** The automatic update will stay on even if you load a new file into the
161 SEC panel using the “Select file in SEC run” button. It will switch to updating
162 this newly loaded file. As with the “Update” button described above, the automatic
163 update only applies to the SEC data item most recently loaded in the SEC panel.
164
165
166 Selecting data items
167 ~~~~~~~~~~~~~~~~~~~~
168
169 A single data item can be selected by clicking on the item name in the SEC list
170 (similar to how you would select files in your system file browser). When an item
171 is selected, the color of the item background changes from white to gray. If the
172 item is currently selected, clicking on it will cause it to be unselected. Note
173 that for a regular click, all other selected items will be unselected when a new
174 item is selected.
175
176 Multiple items may be selected in two ways. If the Control key (Command key on Macs)
177 is held down while clicking on items, each item that is clicked on will be added to the
178 set of selected items. If a single item is first selected and then the Shift key is held
179 down and another item is selected, all of the items in the list between the two items will
180 be selected (including the second item that is clicked on).
181
182 All of the items in the list can be selected in two ways. The first is using the
183 :ref:`select all <iftselectall>` button, the second is pressing Ctrl-A (Cmd-A), the Control
184 (Command) key and the A key at the same time when you are in the SEC panel. All items
185 can be unselected by clicking in an empty spot of the SEC list (but not above or below
186 the list), or by clicking on an already selected item.
187
188 **Note:** If you have a set of selected items and wish to remove some, holding down the
189 Control (Command) key and clicking on selected items will deselect them without affecting
190 the other selected items.
191
192
193 The top buttons of the SEC item list
194 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
195
196 The SEC item list has a set of three buttons at the top of the panel. These buttons have
197 the following effects, listed from left to right.
198
199 *Show All*
200
201 Clicking on the button that looks like an eye will show all SEC items. This is the same as
202 if you manually set all of the show/hide checkboxes in the data items to on.
203
204 *Hide All*
205
206 Clicking on the button that looks like an eye with a red x through it will hide all SEC
207 items. This is the same as if you manually set all of the show/hide checkboxes in the data
208 items to off.
209
210 *Select All*
211
212 Clicking on the button that looks like a spreadsheet with selected cells will select all
213 of the SEC data items.
214
215
216 Renaming a data item
217 ~~~~~~~~~~~~~~~~~~~~
218
219 Data items can be renamed by selecting the data item of interest and selecting “Rename” in
220 the right click popup menu.
221
222 **Note:** While no characters are expressly forbidden in the filename, RAW does not sanitize
223 file names before saving, and thus special characters such as ‘/’ and ‘\\’ are likely to cause
224 problems when the file is saved.
225
226
227 Saving data items
228 ~~~~~~~~~~~~~~~~~
229
230 .. _savingsecdata:
231
232 SEC items are saved as “.sec” files, and is the only data that RAW does not save in a human
233 readable format. To save:
234
235 #. Select the item(s) to be saved.
236
237 #. Click the “Save” button or select “Save selected file(s)” from the right click menu.
238
239 #. In the window that pops up, navigate to the directory in which you want to save the files.
240
241 #. If you are saving a single item, the window will give you an opportunity to rename your
242 file if desired. Click “Save” when ready.
243
244 #. If you are saving multiple items, you simply need to select the folder for the items to
245 be saved in, and click “Open”. The items will be saved with the same names displayed in
246 the SEC Panel, in the folder that you chose.
247
248 SEC items often contain hundreds or thousands of scattering profiles, so they are not saved in a
249 human readable format. The “.sec” files that RAW saves can only be read by RAW.
250
251
252 Removing data items from the SEC list
253 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
254
255 To remove one or more data items, select them and do one of the following:
256
257 #. Press the “Delete” key on the keyboard
258
259 #. Click the “Remove” button
260
261 #. Select “Remove” from the right click menu
262
263
264 Exporting SEC data
265 ~~~~~~~~~~~~~~~~~~
266
267 The following data can be exported in a spreadsheet ready format: frame number,
268 integrated intensity, mean intensity, Rg, Rg error, I(0), I(0) error, MW, filename,
269 and, if available intensity a q=<#> where <#> is a user selected value, for each individual
270 point.
271
272 To do so:
273
274 #. Select the item(s) to be saved.
275
276 #. Select “Export data” from the right click menu.
277
278 #. In the window that pops up, navigate to the directory in which you want to save the file(s).
279
280 #. If you are saving a single item, the window will give you an opportunity to rename your
281 file if desired. Click “Save” when ready.
282
283 #. If you are saving multiple items, you simply need to select the folder for the items to be
284 saved in, and click “Open”. The items will be saved with the same names displayed in the SEC
285 Panel, in the folder that you chose.
286
287 The data is saved as a comma separated value (“.csv”) file. This can be opened directly into most
288 spreadsheet programs, such as Excel.
289
290
291 Saving all SEC scattering profiles
292 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
293
294 If you want to save every individual scattering profile loaded into a SEC data item, you can do so by:
295
296 #. Select the item(s) to be saved.
297
298 #. Select “Save all profiles as .dats” from the right click menu.
299
300 #. In the window that pops up, navigate to the directory in which you want to save the file(s).
301
302 #. Select the folder for the items to be saved in, and click “Open”. The items will be saved with
303 the same filenames displayed in the :ref:`data browser <secdatadialog>`.
304
305
306 Sending data to the main plot
307 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
308
309 Individual scattering profiles can be sent to the main plot for further analysis. This utilizes the
310 middle section of the controls at the top of the SEC Control panel.
311
312 To do so:
313
314 #. Star the SEC data item containing the scattering profiles of interest (note: if only
315 one SEC data item is loaded, it does not have to be starred).
316
317 #. Enter the data frames of interest in the “Select Data Frames:” boxes. The box on the
318 left is the first frame of interest, the box on the right is the last frame of interest.
319 All of the frames between those two endpoints (inclusively) are selected.
320
321 #. Either click the “Frames To Main Plot” button, which will send each individual frame selected
322 in part 2 to the Main plot, or click “Average To Main Plot” which will send the average of the
323 selected frames to the Main plot.
324
325 #. Click on the Manipulation panel and Main plot panel to view the scattering profiles.
326
327
328 Calculate structural parameters
329 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
330
331 .. _secparams:
332
333 You can calculate the Rg, MW, and I(0) as a function of frame number for a SEC
334 profile. This is done using the “Calculate/Plot Structural Parameters” section
335 of the SEC control panel (the bottom section of the controls at the top of the panel).
336
337 It is important to have a big picture for what is happening when this is done. First
338 you set a buffer range. All of the scattering profiles in that range will be averaged,
339 and then subtracted from every loaded scattering profile. Next you set a window size.
340 This window will be slid across the curve and all of the frames within it averaged
341 (note: this average is of the buffer subtracted scattering profiles). This Rg, MW, and
342 I(0) for this averaged profile is then calculated. Those values are assigned to the center
343 frame of the window. The window is then slid down the curve one frame, and the process is
344 repeated until the window reaches the end of the SEC data. For example, if the window size
345 is 5, the first 5 frames, frames 0, 1, 2, 3, and 4, are averaged, and have the Rg, MW, and
346 I(0) calculated. Then window is moved over by one, and frames 1, 2, 3, 4, and 5 are averaged
347 and have the Rg, MW, and I(0) calculated, and so on.
348
349 To do this:
350
351 #. Star the SEC data item containing the scattering profiles of interest (note:
352 if only one SEC data item is loaded, it does not have to be starred).
353
354 #. Enter the buffer range in the “Buffer Range” boxes. The box on the left is the
355 starting buffer frame and the box on the right is the final buffer frame.
356
357 #. Enter the window size.
358
359 #. Select the appropriate molecule type (Protein or RNA) for the molecular weight calculation.
360
361 #. Click the “Set/Update Parameters” button.
362
363 #. The structural parameters will be plotted as a function of frame number in the SEC plot.
364 If RAW was unable to determine the parameters for a particular window, then all parameters
365 in that window are set to -1.
366
367 The Rg and I(0) calculations are done using RAW’s :ref:`automatic rg function <guinierwindow>`.
368 The molecular weight calculation is done using the
369 :ref:`volume of correlation method <molweightmethods>`.
370
371 **Note:** See :ref:`below <secplottypes>` for how to show different structural parameters
372 on the SEC plot.
373
374
375 Data point browsing
376 ~~~~~~~~~~~~~~~~~~~
377
378 .. _secdatadialog:
379
380 The Frame number, integrated intensity, mean intensity, Rg, Rg error, I(0), I(0) error,
381 MW, filename, and, if available intensity a q=<#> where <#> is a user selected value,
382 for each individual point can be inspected using the data browser. To do so:
383
384 #. Right-click on the data item of interest.
385
386 #. Select “Show data” in the popup menu.
387
388
389 The SEC data item right click menu options
390 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
391
392 When you right click on a data item, a popup menu is shown. This section describes what
393 each item on the menu does.
394
395 *Remove*
396
397 Removes the item.
398
399 *Export data*
400
401 Exports the SEC data item to a spreadsheet.
402
403 *Save all profiles as .dats*
404
405 Saves all of the scattering profiles loaded into the SEC item as individual .dat files.
406
407 *Save*
408
409 Saves the selected data item(s).
410
411 *SVD*
412
413 Opens the singular value decomposition (SVD) analysis panel for the selected SEC item.
414
415 *EFA*
416
417 Opens the evolving factor analysis (EFA) panel for the selected SEC item.
418
419 *Show data*
420
421 Shows the individual data points.
422
423 *Rename*
424
425 Renames the data item.
426
427
428 The SEC panel bottom buttons
429 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
430
431 There are three buttons at the bottom of the SEC control panel. They are:
432
433 *Save*
434
435 This button saves the selected data item(s).
436
437 *Remove*
438
439 This button removes the selected data item(s) from the SEC panel.
440
441 *Clear SEC Data*
442
443 This button clears all loaded SEC data. It works the same as if you had selected
444 all of the SEC data items and then removed them.
445
446
447 The SEC Plot window
448 -------------------
449
450 The SEC plot window has only one plot, however data can be plotted on both the left
451 and right y axes. The left axis plots intensity from scattering profiles, while the
452 right axis plots structural parameters (Rg, MW, I(0)). The items associated with the
453 plotted curves are shown in the SEC control panel list.
454
455 The features that are general between all of the plots are described :ref:`elsewhere <genplotpanel>`.
456 This section will describe features unique to this plot.
457
458
459 Changing axes and plot types
460 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
461
462 .. _secplottypes:
463
464 Right-click in the plot to view a pop-up menu with different axis settings. In this
465 plot, you can change what data is plotted on each axis.
466
467 *Y Data (Left Axis)*
468
469 This allows you to change intensity plotted on the left y axis. The methods are:
470
471 * Integrated intensity (default), which is
472
473 .. math::
474 I_{tot} = \int_{q_{min}}^{q_{max}} I(q) dq
475
476 * Mean intensity, which is the average intensity across the whole scattering profile
477
478 * Intensity at q=…, which allows the user to specify a q value, and displays the
479 intensity at the nearest q point to that specified value.
480
481 *Y Data (Right Axis)*
482
483 This allows you to change which calculated structural parameter is plotted on the right y axis.
484
485 #. RG (default) which plots the Rg
486
487 #. MW which plots the molecular weight
488
489 #. I(0) which plots the I(0)
490
491 #. None, which turns off the right y axis.
492
493 *X Data*
494
495 This allows you to change what is plotted on the x axis.
496
497 * Frame Number, which plots the intensity and structural parameter as a function of frame number.
498
499 * Time, which puts the x axis in terms of experimental time.
500
501 **Note:** The time display on the x axis is only available for certain types of header
502 files. Currently only G1 and G1 WAXS header files will have associated time values.
503