Chapter 7. Using the 'standard' SpecTcl GUI
Up until now we've gotten through this manual with a single picture. That's about to change. The SpecTclRC.tcl as it comes from the skeleton includes a few lines that look like this:
splash::progress $splash {Loading SpecTcl Tree Gui} 1
puts -nonewline "Starting treeparamgui..."
source $SpecTclHome/Script/SpecTclGui.tcl
puts " Done"
This loads SpecTcl's default graphical user interface. In this chapter we will take a tour of that interface complete with pictures of the UI in progress. Have a look at the figure below while we describe the highlights this tour will take.
Note that the GUI consists of a menu bar, several tabs, each of which select different pages within the GUI and a status bar at the bottom that provides information about the amount of free Display memory, and source of data being analyzed.
First we'll take a tour of the menu bar. The menubar provides access to operations that are frequently used but don't necessarily have a place on any of the tab pages.
Next we'll look at the Spectra tab. This tab allows you to create spectra of various types, apply existing gates to them and load/save files that contain the definitions.
The Parameters tab provides access to tree parameter definitions.
The Variables tab provides access to tree variable definitions and values.
The gates tab allows you to create gates. It is primarily used to create compound gates as it is easier to enter the simple gates via the displayer.
Finally the Folders tab provides a comprehensive GUI that allows you to create and manipulate spectra, gates, variables and parameters (including psuedo parameters). The folders tabname comes from the fact that the hierarchy of each object's name space is represented as a tree view using folders to indicate that you can drill down deeper into the hierarchy.
The SpecTcl GUI supports saving the analysis definitions to file. Since you may forget to do this, or perhaps SpecTcl will crash before you have a chance to do this, after each change to the analysis conditions, SpeTcl's Gui will automatically save SpecTcl's analysis state to the file failsafe.tcl in the current working directory.
7.1. The Menubar and its contents
Let's look at the menu bar one menu at a time:
7.1.1. The File menu
The file menu, as the name implies, provides the ability to save and restore objects to and from the filesystem.
Allows you to save all or part of the analysis setup to file. Note that the GUI maintains the most recent analysis state in failsafe.tcl. That file is updated after each change.
brings up the dialog below:
The checkboxes allow you to select which objects are saved to file. The lower part of the dialog allows you to choose the directory and name of the file. Online help is provided through the button. Once you've selected the items you want saved, and the file in which to save them, you can click to save the file. If you decide you don't want to save, dismisses the dialog and does nothing.
Saves only the values and units of the tree variables. This just brings up an ordinary file save dialog box from which you can pick the directory and name of the file.
. This menu item allows you to save a file that has the contents of one or more spectra. This is a two step process. First you must select the spectra to save. Second you must tell the GUI the directory/filename in which to save the specstra.
The spectrum chooser looks like this:
On the left size the spectra not yet choosen are available via their hierachical naming in a folder system. The spectra shwon are raw.00, raw.02 and so on. The list on the right are the spectra that have already been selected.
Once is clicked the dialog is dismissed an a file save dialog box appears instead to allow you to select the directory an filename into which the spectra will be saved. The swrite commmand is used to write the spectra in SpecTcl ASCII format.
Brings up a file selection dialog. The selected file is assumed to contain a saved analysis state which is loaded into SpecTcl. Note that save files are Tcl scripts so actually, this sources the script and reports errors. After sourcing the script a sbind -all is performed to attempt to put all spectra ito the spectrum viewer shared memory.
Allows you to read a file that contains spectrum data. These are files written with swrite. creates files readable by this menu entry. The menu command brings up the following dialog:
sread on which this menu option is based has several ways to read in spectra. These are reflected by the checkbuttons at the bottom of the dialog box. Here is the meaning of these checkbuttons:
- Snapshot
If this is checked, the spectrum read is a snapshot spectrum. Snapshot spectra are spectra that are never incremented.
If not checked, SpecTcl attempts to reconnect the spectrum to the underlying parameters that originally made it. If all parameters are present, the spectrum become live, incrementing based on new event data as its read in.
- Replace existing spectra
Spectrum files contain the original names of the spectrum. If this checkbox is checked and there's already a spectrum withthe specified name, it is replaced. If not, a new unique spectrum name is created from the original by appending an underscore and an integer (e.g. raw.00 might be given the name raw.00_0).
This box is, in fact orthogonal to Snapshot above. A spectrum can be replaced with a snapshot.
- Bind to display
If checked, once the spectrum has been read in, its contents are relocated to the displayer shared memory. This makes it available to the spectrum visualizer being used. If not checked, the spectrum is still loaded but is not visible to the displayer until sbind is used to bind it later.
Brings up a file selection dialog. The selected file is sourced in as a Tcl script. Any error is reported as a message box.
7.1.2. The Edit menu
Currently the menu only has one item: . This allows users to setup SpecTcl gui defaults and preferences.
The dialog below pops up:
The top part of the dialog allows you to set the default number of bins on axes of 2-d spectra. If Same as X is checked, the the Y axis entry is disabled and the value saved will be the same as for the X axis. These defaults apply to spectrum axes that are not on treeparameters as those specify suggested default axis ranges and binning.
The second section allows you to describe a few parameters relevant to the helpers used to pipe data from NSCLDAQ. NSCL DAQ Root allows you to specify where NSCLDAQ is stored. This determines where the SpecTcl GUI looks for pipe data sources appropriate to the DAQ system. Default BufferSize is the size of data source reads in bytes. For NSCLDAQ earlier than version 10.0, this must be the size of data blocks. NSCLDAQ 10.0 and later create more granular variable sized items. This value can affect I/O efficiency for those versions of the system.
The preferences are stored in ~/.SpecTclDefaults.
7.1.3. The Data Source Menu
The menu provides commands that manipulate data sources. Note that unlike the attach command used by itself, the menu items that attach data sources also start analyzing data from them.
Let's look at the commands provides.
This menu item assumes that SpecTcl is running in a system with NSCLDAQ. The online attachment uses helper processes that have been distributed with NSCLDAQ since version 7.0. Since we are not running any version older than 10.0 at the NSCL I cannot gaurantee that older versions will work.
The dialog that prompts for online connection looks like this:
The host is the host that provides the data. In NSCLDAQ, all versions, it's the host in which the primary data provider runs. For simple experiments, this is the host that runs the Readout program. For more complex experiments it will be the host that runs the end stage event builder.
For NSCLDAQ versions 10.0 and newer the ring name is the name of the ring buffer from which SpecTcl will analyze data. The final ring url will be constructed from the host and the ring.
The buffer size in bytes. For NSCLDAQ versions 10.x and earlier the size only affects I/O efficiency (typically bigger is better). For versions prior to 10.x, the size must match the blocking size of the data (prior to nscldaq-10. data were shipped around in homogeneous buffers).
The Data format radio button set selects the SpecTcl buffer decoder:
- nscl
Actually represents data older than nscldaq-10.0. It also requires a buffer size that is smaller than 128Kbytes (65536 words).
- jumbo
Represents nscldaq data older than 10.0. This is required for some MoNA data that needed buffer sizes greater 128Kbytes. The distinction is that the buffer size requires more than 16 bits.
- ring10
Data from nscldaq 10.x This is ringbuffer data prior to the addition of body headers.
- ring11
Data from nscldaq 11.0 and later. This is ringbuffer data after the addition of body headers.
 | Note |
|---|---|
If SpecTcl attaches while data taking is inactive, it can and will determine the format of the data. It's not abnormal to attach SpecTcl to a run that's in progress so it's always safer to provide the correct nscldaq version. |
. Provides a mechanism to create a file data source. The format of data can be set just s it is for online data sources.
The dialog for choosing a file looks like this:
The top part of the dialog is just a file chooser that allows you to select the event file. The bottom part a buffering size and format selector just like on the dialog to select an online data source.
Allows you to attach an arbitrary program that emits data on its standard output. This is the general case of a SpecTcl pipe data source. One use might be to use zcat to de-compress a gzipped event file and analyze.
The pipe dialog includes a file selector to select the program to be run on the pipe. An entry labeled Parameters: allows you to provide command line parameters to program. For example you can use the file selector to select /usr/bin/zcat and put the name of a compressed event file in the parameters entry.
The remainder of the dialog provides buffersize and format selection controls as in all of the other data source selection dialogs.
This option allows you to playback a sequence of run files. The list of files to process are held in a file that some experimental groups call a Cluster file (presumably be cause these files specify a cluster of runs to process).
The clusterchooser dialog is shown below:
The dialog allows you to choose the cluster file. This file is a simple text file. Each line of the file must be the path to an event file. The event files are analyzed in the order specified by the cluster file.
Note that cluster files are one way to playback multi-segmented event files, however recent versions of the SpecTclGUI script recognize segmented runs when you select a file data source and give you the option of playing back all of the segments of the run rather than just the one selected.
. Specifies that you want to playback a filter file. Since SpecTcl must be programmatically configured to playback filter files, the first time you select this option you'll be reminded of that and aksed to confirm your version of SpecTcl can decode filter files.
Once you confirm that you have a properly configured SpecTcl, an ordinary file chooser dialog lets you select the filter file you want to replay. Filter files have a format that is independent of data acquisition system and version. Therefore there's no need to set a buffer size or a version number as there is for the other data sources.
. This menu item detaches SpecTcl from any currently attached source. It actually does this by attaching SpecTcl to the file /dev/null. This file always returns an end file condition when read.
7.1.4. The Filters menu
Filters are a mechanism to store some subset of data into files that can be quickly decoded by SpecTcl at playback time. A filter is gate and a list of parameters. When the gate is true, all of the parameters in the filter are written to file. Thus filters allow you to select both a subset of events as and a subset of parameters.
SpecTcl must be prepared to read back filter files. The specifics of that are described in Analyzing filter files. The menu allows you to:
Create new filters
Enable or disable existing filters (disabled filters do not write data).
Play back filter files (same as ).
Let's look at the items on the menu:
. The filter commands are somewhat complicated. This menu item provides a wizard that makes defining gates simple.
The first step of the wizard prompts for a filter name. All SpecTcl filters must have a unique name.
Note that the introductory page of the wizard als provides an overview of the steps required to create a filter. Choose a new filter name, enter it in the text entry and click to proceed to the next step of the filter wizard:
The gate filter determines which events are written to the filter file. Only events that satisfy the gate will be written. Open the gates folder in the top of this page of the wizard. Browse the tree of gates until you find the one you want and double-click it to select it.
The selected gate will be shown at the bottom of this wizard page next to the Gate Chosen: label. If you selected the wrong gate simply double-click the right one to replace the chosen gate.
When you've selected the right gate, click to move on to the next wizard screen.
Brows the parameter display and double click parameters to add them to the list of parameters on the right. If, by mistake you add a parameter you don't want, double-click it to remove it from the selected parameters list.
When the parameter list is what you want, click to advance to the next, and last, screen of the wizard:
This wizard page allows you to choose a directory and name for the filter output file. This is the file into which filtered data will be written. You may also specify the filter as Active. Active filters write data, inactive filters don't.
Complete the filter definition by choosing a filter file and deciding whether or not to activate the filter. Click to finish defining the filter.
A filter does not output data unless it is enabled. The enable/disable state of filters can be manipulated in the dialog accessed through the
This dialog is shown below:
The dialog provides a checkbox next to each filter definition. Check the box to enable the filter, uncheck to disable. Once you've made your selections, click to make the appropriate changes. The dialog provides not only filter names, but the complete definition of each filter.
This is identical to . It allows you to attach the output of a filter as a data source. Note that to successfullly do this your SpecTcl must have been configured to decode data from filter files. See Analyzing filter files for instructions.
7.1.5. The Spectra menu
This menu provides access to common operations on spectra. These operations are also available in other parts of the user interface.
This is identical to . The desired spectra are save in an ASCII file. For information about the format of this file, see the programmer reference manual. A description of the user interface is available in the section describing the menu.
Identical to . Spectra can be read in either as snapshots or connected to the histogrammer where possible. The spectra can overwrite existing spectra or create new, uniquely named spectra. See the menu documentation section for details.
. Clears the contents of all defined spectra. Note that if you have defined spectra that are not bound to the displayer shared memory, those are also cleared. By clearing a spectrum, we mean that all of the channels in the spectrum are set to zero.
Allows you to create spectra. The operation of the dialog this menu item creates will be described completely in the Using the folders tab..
The Spectra tab provides another method for creating spectra which is superior for simple 1-D and 2-D spectra. Other spectra can be easily created with this page, as long as some simple parameter naming conventions are observed.
Allows you to delete a spectrum definition. Once deleted the spectrum no longer exists.
The spectrum to be deleted is selected via a hierarchical spectrum selection dialog. See below
Navigate the folder hierarchy and double click the spectra you want deleted (you may delete several at once). If you accidentally choose the wong spectrum, double click it in the Selected Spectra listbox at the right of the dialog.
Once the Selected Spectra list box contains the spectra you want to destroy, click to delete the spectra. You will be prompted to confirm the deletion befor it actually is performed. Use caution as deleting a spectrum cannot be undone (other than by redefining it).
Gates are conditions that are checked for each event. Every spectrum has a gate applied to it (even if it's just a true gate). The spectrum is only incremented when an event has satisfied the gate applied to the specturm and the event has set values for the required parameters.
This menu command allows you to change the gate that is applied to a set of spectra. Note that the Spectra tab has a control that does this easily for single spectra. The dialog used by the menu command allows the same gate to be applied to several spectra.
Using the spectra folder hierarchy, select the spectra that will have a gate applied. Using the Gates folder hierearchy, chose the gate to apply. If you selected an incorrect spectrum, you can remove it from the Spectra: list box by double clicking it. If you chose the wrong gate, simply choose another.
When the gate and spectra have been properly chosen, click to apply the gate to the designated spectra.
7.1.6. The Gate menu
This menu allows you to manipulate gates and their definitions. The commands int this menu are available elsewhere in the UI, however there may be times when it is simpler to use this menu than to switch notebook tabs to access that functionality.
Brings up the gate editor and allows you to create any type of gate. Note that most simple gates can be created more simply from the displayer. Compound gates, however can be created with this menu entry, in the folder tab (same GUI mechanics) or in the Gates tab of the Gui (different GUI mechanics).
The GUI mechanics for this menu item will be described in Using the folders tab. If you want to know another way to create gates from this UI see Using the Gates page.
Allows you to apply a gate to one or more spectra. This operation is the same as See SpectraApply Gate... for information about the UI mechanics required to complete this operation.
Allows you to select a set of gates to delete. Note that in order to make compound gate handling predicatable and uniform as gates are deleted, deleted gates are actually replaced with gates that are always False rather than being totally deleted.
This command brings up the dialog below:
Navigate the gate tree hierarchi, double clicking gates you want to delete. If you select a gate you didn't intend to select, double click int in the selected gates list box. When you are done, click . You will be ptrompted to confirm your selection. If you do, the selected gates will be destroyed.