7.6. Using the folders tab.
The folders tab attempts to condense the entire user interface into a single page. It presents the spectra, parameters, tree variables and gates as a single tree of folders. Each folder and item within each folder has a context menu that pop up on a right click on the associated object. The context menu provides operations that make sense on that object.
As with the previous pages, we'll devote a subsection to descriptions of things that can be done on each of the top level folders and its contents.
7.6.1. Spectra folder
Let's look at the folder gui with the top level Spectra folder and all subfolders opened:
As we can see there are several objects that matter:
There's the top level Spectra folder.
There's a spectrum named calib and a spectrum named Twod right underneath the the top level folder.
There's a subfolder namedrQ that contains an array of spectrum named rQ.00, rQ.01... rQ.09.
Note that each spectrum can be opened as well. Doing so shows the parameters the spectrum depends on. If this is done for a 2-d spectrum, you see each parameter as an axis definition.
Finally quite a bit of information is displayed about spectra in this display. From this display you can get at least as much information as on the Spectra tab.
All manipulations are don via the context menus that various object types have. Let's look at those:
7.6.1.1. Top level spectra folder context menu
Right clicking the top level Spectra folder gives a context menu with the following entries:
Allows you to create new spectra.
Reloads the current definitions into the tree. This is required if changes are made either outside of the GUI or in other tabs of the GUI.
Clears all of the spectra (contents).
The folder page has extensive online help. This brings up menu item brings up help on the things that can be done in the folderse Spectra tree.
New... Creating a new spectrum. This brings up the top level spectrum editor:
The actual form of the spectrum editor depends on the type of spectrum being created. You can enter the name or specify you're making an array of spectra (just like for the Spectra tab) here, but the main thing you need to do is select the spectrum type from the drop down menu at the upper left of the top level spectrum editor.
The remainder of this section will go over the various spectrum types and how to use the editors associated with them. Note that in some cases, because of the way window managers work, you may need to resize an editor to see all of it. Note as well that all spectrum editors have a button. Finally note that the spectrum editor is not a modal dialog. That is the remainder of the GUI remains alive while you are interacting with it. The UI, however only allows a single spectrum editor to be open at any time.
1-d spectra. The figure below shows the editor for a 1-d spectrum.
1-d Spectra require you to select a single parameter. You do this by double clicking that parameter in the Parameters folder hierarchy at the left of the dialog. Doing so fills in the parameter information box at the right of the editor.
If the parameter had suggested high/low/bin/units information that is also loaded into the parameter information box. Note that you can edit the low/hig/bins to set alternative axis limits and binning as desired.
You can apply an initial gate to the spectrum. This is done by browsing for the desired gate in the Gates folder hierarchy to the left of the editor and double clicking the desired gate. The applied gate appears to the right of the Gate label at the top of the editor.
Naturally you may make mistakes. If you choose the wrong parameter, simply choose the right one and it, and its recommended axis definition will replace the parameter you selected. If you chose the wrong gate again, simply choose the right one and it will replace the one you chose. Finally if you chose a gate and decide that you actually don't want to gate the spectrum, double click the gate name at the top of the editor and you'll no longer be creating a gated spectrum. If you chose the wrong spectrum type just pull down the spectrum type menu again and choose the right type.
The mechanics of spetrum creation for all spectrum types are very similar to this. You choose the parameters you need, you edit axis definitions and you optionally select a gate. When the spectrum is defined as you desire, simply click to create and dismiss the dialog or to create the dialog but leave it open to define another spectrum. dismisses the dialog doing nothing. as always brings up some help on this aspect of the user interface.
2-d spectrum editor. The 2-d spectrum editor is shown below. As the name implies, 2d spectra represent a two dimensinoal grid. One of the seleted parameters, the X parameter is the X coordinate axis and the other the Y parameter is the Y coordinate axis. If the event has both parameters, and applied gate is satisfied, the two parameters define an x/y point whose bin is incremented.
The only difference between the 1-d and 2-d spectrum editors is that you must choose two parameters, an X and a Y parameter and optionally modify the axis definitions of one or both of those axes.
Note that in the figure, the X parameter is highlighted. This means that the next parameter you select from the parameters folder will be the new X parameter. Selecting a parameter automatically alternates the highlight. Thus after selecting an X parameter the Y parameter is highlighted. After selecting a Y parameter, the X parameter is highlighted.
This allows for a natural selection of first the X and then the Y parameters of the histogram. If you click on the x Parameter or y Parameter text that box will become the selected box and the next selected parameter will be placed there.
All the editing operations described for a 1-d spectrum apply with the addition that double clicking the name of a parameter in a parameter box will remove it from the box, making the parameter for that axis undefined. Note as well that the assumption is that you won't plot a parameter against itself so once you've selected a parameter as either the X or Y parameter, it is removed from the Parameters folder so that you can't accidently select it again.
The spectrum editor requires you to fully describe the spectrum. If you attempt to click or before defining the minimal required information (spectrum name, X and Y parameters) a dialog will pop up informing you the spectrum is not yet fully defined.
While the checkbox is present, you can only create arrays of 1-d spectra. An error dialog reminding you of that fact pops up if the array checkbox is selected when you click either or . Finally if a spectrum with this name already exists you are asked to confirm the replacement of that spectrum with your newly defined spectrum.
Gamma-1d spectrum editor. A gamma-1d spectrum is a multiply incremented spectrum. An arbitrary number of parameters can be put on a common scale on the X axis. For each event that satisfies the spectrum's gate, a channel incremented for each parameter the spectrum depends on that has been given a value.
In addition to applying a gate on gamma spectra, gamma spectra can have folds set on them to explore correlated, multi-gamma emisssions in a single event.
The gamma-1d spectrum editor looks like this:
The only difference between this editor and the 1-d spectrum editor is that the parameters for the axis are shown in a list box and you can select as many of them as desired. Each parameter is selected by double clicking it in the Parameters folder hierarchy. It is assumed that you don't want a parameter to appear twice so each selected parameter is removed from the parameters folder hierarchy.
If you accidently add a parameter you did not intend, double click it in the Parameters listbox and it will be removed, and added back to the Parameters folder hierarchy.
Gamma-2d spectrum editor. A Gamma-2d spectrum is a multiply incremeted 2-d spectrum. it is incremented for all ordered pairs of parameters used to define the spectrum. Suppose, for exmaple that parameters p1, p2, p3 have values and are parameters in the spectrum. Increments will occur for the coordinates that correspond to (p1,p2), (p1, p3) and (p2, p3).
Gamma-2d spectra therefore create blobs for each pair of correlated gamma rays a reaction might produce. Similarly Gamma-2d spectra can have folds applied to them to spot additional corellated gammas that are in coincidence with pairs.
Contours and bands that are accepted on a gamma 2d spectrum are true if there is one or more pairs of parameters that make the gate true. In the increment example above, a gamma countour would be true if any of the three increments above would have fallen inside the gate.
Gamma 2-d x/y spectrum editor. The gamma 2-d x/y spectrum, also called a gamma deluxe spectrum is a multiply incremented spectrum. Unlike the gamma 2d spectrum, parameters are assigned to an X or Y axis. Increments occur for all combinations of x/y parameters an event has defined.
Suppose for example, an event has parameters p1, p2 defined and these are on the X axis of a Gamma 2-d x/y spectrum. Suppose similarly, parameters p3,p4 are defined and on the y axis. The following coordinates will be incremented: (p1, p3), (p1, p4), (p2, p3), (p2, p4).
The spectrum editor for this kind of spectrum looks like this:
Fill in the X parameter box by selecting (single click) parameters from the parametr list and then clicking the button to add parameters one at a time to the X parameter list box. Similarly for Y parameters, click to add a parameter to the Y parameter list box.
Double clicking a parameter in a list box removes it from the listbox.
Gamma summary spectra. Gamma summary spectra are like summary spectra except that each vertical channel column, instead of being a 1-d spectrum is a gamma spectrum. The editor for that type of spectrum looks like this:
The idea of the editor is that you build up the parameters on the x axis one column at a time. Select channels by double clicking them until you have the set of parameters you want in channel 0. Then click and select the channels for channel 1. Continue this process until all X axis channels are fully defined.
2-d sum spectrum. You can think of a 2-d sum spectrum as the sum of several 2-d spectra. The spectrum is defined on a set of ordered x/y parameter pairs. Increments are done for each defined pair. Suppose, for example, the spectrum is defined with x parameters (p1, p2, p3) and y parameters (p4, p5, p6). Suppose an event defines parameters p1, p2, p3, p4 and p6; The channels defined by the points (p1, p4) and (p3, p6) are incrmented. The spectrum in this case is like the sum of spectra defined on (p1, p4), (p2, p5), and (p3, p6).
The editor looks like this:
You can select parameters either by selecting them one at a time or, if you have a 2d spectrum whose parameters you want to select for this spectrum you can select it:
Double clicking a 2d spectrum from the Spectra folders adds the x and y parameters of that spectrum to to the x and y parameter list of the editor.
Selecting a parameter from the parameter folder (double clicking), adds it to the list box of the paramters for the axis whose radio button is selected and advances the radio button to the next axis.
If you double click a parameter in one of the list boxes that has a mate on the other axis, both parameters are removed from the spectrum.
If you double click a parameter in one of the axis listboxes that does not have a corresponding parameter in the other listbox, only that parameter is removed..
Summary spectrum editor. A summary spectrum is a 2-d spectrum whose vertical columns are 1-d spectra. Summary spectra provide a simple way to look at the health of a highly segmented array of parameters.
Here's the editor for a summary spectrum:
Double click parameters to add them to the parameter list box. Double clicking a parameter in the listbox, removes it.
Bitmask spectrum editor. A bitmask spectrum is useful when you have parameters that represent trigger masks. A bitmask spectrum assigns one channel per bit of the parameter value and increments channels for each bit set in the parameter.
Suppose, for example, the parameter chosen for the spetrum has the value 0x237. Channels 0,1,2,4,5,9 wil be incremented. One channel for each bit set in the parameters [1]
Here's the editor:
The appearance and the mechanics of this editor are the same as for a 1-d spectrum.
Strip chart spectrum editor. As the name implies a strip chart spectrum plots the value of one parameter against another as it increases (usually with time) or decreases. A strip chart has a 'time axis' parameter that is the x axis, and a value axis parameter. The time parameter selects a bin which the value parameter is then added to.
Strip chart spectra feature a sliding X axis. If the time parameter goes out of the range of the X axis (on either side) the X axis is redefined, and data in the spectra are shifted accordingly.
The strip chart spectrum editor is shown below:
You m ust select a time axis parameter and a value axis paramter. Note that the time axis parameter is highlighted indicating the next selected parameter will be the time axis parameter. When you select a parameter the highlighted axis will switch. You can also click an axis to select it.
Loading the time axis will, if that is a tree parameter, set an initial low/high/binning for the x axis although that can change with time. You can also edit those values.
7.6.1.2. Spectrum context menu
Right clicking on a spectrum brings up different context menu:
Brings up the spectrum editor appropriate to the type of spectrum and preloads it with the current spectrum definition.
You can use this to modify the definition of an existing spectrum or, by changing the spectrum name in the spectrum editor, use an existing spectrum definition as a starting point for a new spectrum definition.
Clears only that spectrum.
Brings up the gate application dialog shown below. Double click a gate to apply it to the spectrum and click to confirm that application. If you select the wrong gate, simply select the right one.
Removes any gate applied to the spectrum. This is actually done by applying a True gate to the spectrum named -Ungated-.
Brings up a file selection dialog box the contents of the Spectrum on which the context menu was brought up will be written to file.
After prompting for confirmation (and getting it) deletes the spectrum on which the context menu was popped up.
Displays help on the context menu entries.
7.6.2. Parameters folder
The parameters folder displays all parameters, whether they have been defined as tree parameters or not. Parameters that are not tree parameters can be given limits, binning and units. In addition, Pseudo parameters can be defined.
The context menu for the Parameters folder contains the following menu entries:
Allows you to define a new parameter that, event by event, is computed from a tcl script. See the SpecTcl pseudo command for more information about pseudo parameters.
The pseudo parameter editor looks like this:
In the top part you can fill in the charactersitics of the new parameter. Especially important is the Depends on: entry box. That should be a space separated list of the names of the parameters required to compute the parameter.
The bottom text widget is where you put the Tcl code needed to compute the parameter. Note that each parameter name becomes the name of a variable in the scope of that script. In addition, for each parameter an isValid variable is also created that is a boolean which is true if the parameter has been given a value.
For example, if a pseudo is defined that depends on par1 and par2, the body of the pseudo might be:
Be very aware of the range of substitutions. That is where the name being substituted for ends in the absence of quotations. Specifically a period ends the name that is substituted unless the name is quoted. So, for example, suppose the case above depended on the variables raw.par1 and raw.par2. You would need to quote your variable names as shown below:
Updates the user interface's knowledge of the objects SpecTcl knows about.
Provides help on the context menu.
Parameters themselves have a and item as well as an context menu item. The Psueod item operates as for the folder's context menu. The item brings up an editor for parameter limits, binning and units:
This dialog should be pretty self explanatory.
7.6.3. Variables folder
The variables folder allows you to view and manipulate tree variables and tree arrays. The context menu for top folder just has and items.
Variables themselves don't have a context menu. The only think you can do with a variable is edit it. Double clicking a variable brings up an editor like this:
The use of the variable editor should be fairly self evident.
7.6.4. Gates folder
The gates folder allows you to list and manipulate gates. Each gate has structure underneath it. Opening the gate shows the full definition of the gate. Both the top level gates folder and individual gates have context menus.
In addition to and menu, the top level folder's context menu contains a item which allows you to create a new gate. This is mostly useful for compound gates as simple gates can be entered more easily in the viewers.
The context menu of gates themselves includes:
Brings up the gate editor with all values initialized to that of the gate that brought up the context menu.
Brings up a dialog that allows you to select one or more spectra to which the gate will be applied.
Allows you, after confirmation to delete the gate. Note that deleted gates don't atually get deleted, they get turned into false gates so that gates that depend on them operate in a consistent manner.
In addition to the context menus, double clicking on a gate brings up a gate editor which allows you to modify the gate's definition or to use it as a starting point for another gate.
Let's look at the Gate creation/edit dialog and then at the Gate application dialog
7.6.4.1. Gate creation/edit dialog
As with the spectrum creation/edit dialog, the gate creation and edit dialog's appearance depends on the gate type. In this section we'll go over how to interact with the editor for all gate types.
When you want to create a gate, the gate editor first looks like this:
The only thing you can do with this dialog is set the gate name, the gate type, cancel the operation, or get online help. Once you select the gate type. the dialog will change appearance in accordance with the type of gate you are creating. If you are editing an existing gate the gate type and dialog appearance are selected from the gate being edited.
And gate editor. And gates are compound gates that are true only if all dependent gates are true. Note that dependent gates may be other compound gates allowing for the stepwise construction of arbitraty gate logic.
The And gate editor is shwon below:
Buid up the list of dependent gates by double clicking on gates in the Gates folder to the left of the dialog. If you select a gate by mistake, double click it in the Dependent Gates list box to remove it.
Or gate editor. Or gates are compound gates which are true if at least one of their dependent gates are true. Note that again dependent gates can also be compound gates allowing you to build up arbitrary gate logic. The appearance and mechanics of the Or gate editor is identical to that of the And gate editor
Not gate editor. Not gates are compound gates that have a single dependent gate (which may itself be compound). Then Not gate is true if its dependent gate is False, and vica versa. The Not gate shares the same gate editor as the And gate editor. , however only works if a single gate is in the Dependent gates list box. In the future, not gates will get its own gate editor, one that makes it much clearer only one gate can be selected.
Slice editor. Slices represent a region of interest on a single parameter. Slices are primitive gates that can be entered graphically in the viewers. When entering gates graphically it is important to note that those gates are entered on the underlying parameter not on the spectrum as sometimes people say.
The slice editor is shown below. Note that it reminds you that you probably could enter gates like this more easily graphically.
Use the Parameters folder to choose which parameter the cut is on and set the low and high limits of the cut at the bottom of the dialog. If you selected the wrong parameter, just select the correct one and the parameter will be replaced.
Gamma slice editor. A gamma slice is a slice that depends on a number of parameters. Gamma slices only have meaning when applied to other gamma spectra. In that case they are treated as folds. A gamma spectrum is only incremented for parameters that do not make the gate true.
The gamma slice editor is identical to Slice gate editor except that an arbitrary number of parameters can be added to the selected parameter list box. If a gamma 1-D spectrum has been created with the appropriate parameters, a gamma gate can also be entered graphicall on the viewer.
Band gate editor. A band is a gate that represents and open poly line in the two dimensional space defined by a pair of parameters. Bands are true if an event defines both parameters and results in a pointe below the poly line. If you want a band to be the space above the poly line you can create a not gate from the band.
Bands can be easily entered by accepting its points on a viewere by accepting points on a spectrum that is defined on the parameters. Again a reminder. Gates are defined on parameters regardless of the fact that for convenience they may be drawn on spectra.
The band gate editor looks like this:
In the parameters list box, the top parameter selected is the X parameter and the bottom one, the Y parameter. Select parameters fromt he folder hierarchy on the left side of the GUI. Selecting more than two parameters results in the top one disappearing and the bottom one becoming the X parameter. You can also remove a parameter by double clicking it in the list box.
The points of the gate can be entered in the next point entry. Points are floating point pairs whose values are separated by whitespace. The Enter key adds the point, as does the button. Points can be removed either by clicking which deletes the last point and double cliking on the point to delete.
Contour gate editor. Contoure gates are gates defined in the two dimensional space defined by a pair of parameters. Contours are closed polylines. The polyline is closed by connecting its last pont to its first. The gate is true for events that define both of its parameter and for which the point defined by the event is inside the closed polyline.
It is possible to draw all sorts of pathalogical figures. SpecTcl has a consistent definition. A point is considered inside the gate if a line in any direction from the point extended to infinity will cross an odd number of polyline edges. A point is outside if it crosses an even number of edges.
The interior of the gate shown below is shaded.
The contour editor is the same as the Band gate editor. The only difference betweena band and a contour, after all is that contours connect the last point to he first to form a closed figure.
Gamma band and Gamma contour editor. Gamma bands and contours are special gates used to define folds on gamma spectra. When applied to a gamma spectrum, points are incremented only if their paramters are not points that are inside the gate. These gate share the Band gate editor.
7.6.4.2. Gate application dialog
The gate application dialog allows you to apply a single gate, the one that brought up the context menu, to one or more spectra. Recall that spectra only increment for events in which their applied gate is true.
The dialog looks like this:
Select the spectra you want the gate applied to. If you accidentally select a spectrum you don't want the gate applied to, double click it in the listbox to remove it.
Note that spectra selected are removed from the spectrum tree as applying the same gate to a spectrum twice doesn't hurt but is not really meaningful.