7.3. SpecTcl at Run-time

7.3.1.1. The parameter command

In Adding a new event processor to the skeleton, I described how event processors are expected to create parameters by placing them into specific slots in the rEvent array-like object they are given. In this section we will describe the parameter command, which makes the connection between these numbered slots and named SpecTcl parameters used to create histograms.

rEvent is an array-like object in the sense that it can be indexed, both on the left hand side of an assignment and in experessiosn (in C/C++ parlance both as an l-value an as an r-value). rEvent differs from normal C/C++ arrays in that it automatically expands itself as needed. [1]

This process of analyzing events in a pipeline, to produce an output rEvent 'array' is shown schematically below. In this figure, the box labelled parameters is the rEvent array which is stuffed with data in indices ranging from 0 to some largest index n.

Integer indices are all very well for programs and programmers, but are not very useful to human beings. SpecTcl therefore allows you to make a correspondence between names, and indices in the rEvent array. These names are what are usedwhen defining spectra.

The command that makes this correspondence is the parameter command. [2] In its simplest form, the parameter command looks like:

parameter slot-number parameter-name
                    

Where slot-number is an index in the rEvent array, and parameter-name is the name that will be associated with the data placed in that slot by the event processing pipeline. The mapping created by the parameter command is one-to-one. That is each slot-number can be associated with exactly one parameter-name (and obviously vica-versa). For other forms of the parameter command, see the SpecTcl Command Reference.

Here are some legal and illegal examples of parameter commands (assume that the entire example is a session):

parameter 1 Si1.de                
parameter 2 {Si1 E}               

parameter 3 Si1 E                 

parameter 4 Si1.de                
parameter 1 Si2.de                
                    

7.3.1.2. The spectrum and sbind commands

In the last section we saw how to label rEvent indices with names. In this section we will look at the most common form of the two commands that you need to know to create and view spectra. The spectrum command creates spectra. The sbind command makes those spectra available to the Xamine display application.

Since SpecTcl supports a wide variety of spectrum types, the spectrum command is rather complicated. The general form used to create a spectrum is:

spectrum spectrum-name type parameters axes
                    

Where:

Assuming that the paramters Si1.de and Si1.E have been defined, and run between 0 and 4095, the following commands define 1-d spectra for each of these parameters and a PID spectrum for the pair:

spectrum Si1.de 1 Si1.de {{0 4095 4096}}
spectrum Si1.e  1 Si1.e  {{0 4095 4096}}
spectrum Si1.pid 2 {Si1.de Si1.e} {{0 4095 512} {0 4095 512}}
                    

The 1-d spectra definitions need little explanation other than to note that the namespaces holding spectrum and parameter names are unique. Thus you can give a spectrum the name of an existing parameter. It is an error, however, to give a spectrum the name of an existing spectrum.

For the 2-d spectrum, we could have also used the Tcl list command to build up the spectrum list:

                        
spectrum Si1.pid 2 [list Si1.de Si1.e] {{0 4095 512} {0 4095 512}}

                    

The Xamine displayer that SpecTcl uses displays spectra that are stored in memory that is shared between SpecTcl and Xamine. This shared memory region is a fixed size. In SpecTcl initialization I will describe how to control the size of this shared memory region.

The set of spectra that can be displayed is limited by the size of this shared memory region. SpecTcl itself places no limits on the number and size of spectra that can be created (the operating system virtual memory limits do however). [3]

SpecTcl uses the sbind command to specify the set of spectra that are loaded into shared memory. Loading or unloading spectra from shared memory can be done dynamically and does not affect the contents of the spectrum. The unbind command is used to unload spectra from shared memory and is described in the SpecTcl Command Reference

The example below shows the two most important forms of the sbind command:

                        
sbind name1 ?name2 ...? 
sbind -all                                         
               
                    

Examples of sbind applied to the sample spectra we created earlier:

sbind Si1.de Si1.E
sbind Si1.pid

# Or more simply:

sbind -all
                        

7.3.1.3. Conditionalizing spectra, the gate and apply commands

In many cases it is useful to increment a spectrum only if some condition is true. In most cases, this condition represents some combination of assertions about the values of parameters.

SpecTcl has two commands that allow you to conditionalize a histogram. The gate command creates assertions that, when evaluated are true or false for each event. The apply command applies a gate to a spectrum, only allowing it to increment when the gate's assertions are true.

SpecTcl has a large variety of gate types. Gate types, however break down into two categories:

In this section we are going to talk about two ways to create a slice gate (example of a primitive gate), and how to create an or gate (example of a compound gate). For more information on creating gates gates you should refer to the following material:

• Introduction to the SpecTcl folder GUI

• Introduction to treeparameter

• SpecTcl Command Reference

• Xamine Reference

The general form of a gate command is:

gate name type description
                    

In the example above, name is a name you are giving to this gate. Gate names must be uniqe, however since gates are mutable defining a gate with a duplicate name redefines that gate, so be careful. The gate namespace is separate from the spectrum and parmeter namespace so you can name gates after existing spectra and parameters with no ill effects.

type is the gate type. For our example, a slice gate, the gate type is s. Slice gate represent an interval in the value of a parameter. A slice gate asserts that for an event, the parameter is inside this fully closed interval.

description provides gate type dependent information that fully describes the gate. For a slice gate, This description is a two element list. The first element is the parameter on which the gate will be checked. The second element is a two element list that are the low and high limits of the gate interval in parameter space.

To create a gate on Si1.e that is true for events in which that parameter is in the range [100.0 .. 200.0], you would use the following gate command:

gate Si1.e.slice s {Si1.e {100 200}}
                    

Where in the example above we have named the gate Si1.e.slice

By themselves gate don't do anything [4] Each spectrum, however has a condition. A condition is a gate that must be true in an event for the event to increment that spectrum. Initially, all spectra are gated on a True gate (type T). T gates are always true, therefore initially spectra are always incremented.

The apply command specifies a gate that will be used as the condition for a set of spectra. You use the apply command to specify which gate must be true to allow a spectrum to be incremented. The form of the apply command we are intereseted in is shown below:

apply gate-name spectrum1 ?spectrum2...?
                    

This applies the gate gate-name to the spectra that make up the remainder of the parameters on the command line. Suppose we have our slice Si1.e.slice and there are spectra we only want to increment when events make the slice true named: pid1.Si1slice calibrated.energy.Si1slice. We can do this with the command:

apply Si.e.slice pid1.Si1slice calibrated.energy.Si1slice
                    

Suppose we have several slice gates: Si1.e.slice, Si2.e.slice, Si3.e.slice. Suppose we only want to increment the pid1.sliced spectrum if at least one of those gates is true. The SpecTcl or gate is a compound gate that can do just that.

Recall that compound gates are gates that depend on other gates. In the case of an or gate, the gate type is +, and the gate description is the list of gates to check.

We can accomplish our goal as follows:

gate anorgate + {Si1.e.slice Si2.e.slice Si3.e.slice}
apply anorgate pid1.sliced

                    

I promised to describe a second way to accept slice gates. Slice gates represent a cut on a parameter. It is usually visually clear where to put that cut when you look at a spectrum of that parameter. Xamine lets you pick the end points of a slice gate by clicking them on a displayed spectrum, rather than typing them in.

To do this, use the Display or Display+ buttons to display the spectrum in one of the Xamine display panes. Next click the Cut button to start accepting the cut.

The cut button should bring up the following dialog:

In the box labelled Object Name type the name of the gate. Using the left button on the mouse, click the gate limits (the order in which you click the gate points does not matter). Click the Ok button to accept the gate. For more information on how to use the dialog, click its Help button.

Most primitive gates can be entered with Xamine. See the Xamine Reference for more information about how to use Xamine to enter gates.

7.3.3.1. Context Menus

The folder GUI uses context menus to allow you to do the most common actions on an item in the folder hierarchy. A context menu is a menu that pops up in response to a click of mouse-button 3 (usually the right-most button on the mouse). Use a context menu by holding down mouse-button 3, moving the pointer over the desired selection and release the button. If you decide not to select any of the menu choices, just drive the pointer off the menu before releasing the button.

The selections available in a context menu depend on where the mouse cursor is when mouse button 3 is clicked. The context menu you will get when you are over the spectrum folder looks like this:

In this case, the New... menu selection will create a new spectrum, the Clear all selection will clear the counts in all the spectra. For each context menu, the Help selection willpop up help that describes the relevant part of the folder GUI and the context menu you have popped up.

By contrast, the context menu that will pop up when the pointer is over the Parameters folder looks like this:

To learn more about the context menus, and what they can do, experiment by seeing what you get when you right click over various things. There are context menus for items as well as folders. Look at the online help for each menu if the function of its items is unclear.

If you learn better by reading, you can go to the online help by clicking Help->Topics... In the help browser that pops up select the Topics->Browser item. At the bottom of that page are links to the help for each of the context menus.

7.3.3.2. Creating Spectra

The folder GUI allows you to create and edit spectrum definitions. Be aware, however that when you edit a spectrum definition, what the GUI will actually do is delete the old spectrum and create a new spectrum with the same name as the old spectrum and the new definitions. You will lose all the counts that had been accumulated in the old spectrum.

There are two ways to create a spectrum with the Folder GUI.

1. Select Spectra->Create... using the menu bar at the top of the gui window.

2. Use the context menu New... on the context menu for the Spectra folder.

Regardless of how you get there, you will be presented with an initial spectrum definition dialog:

Let's follow this through to make a spectrum named test.1d (This should create a folder test under the Spectra folder with the item 1d). If you are going to follow along, use an untailored SpecTcl (copy the Skel, and just do a make without editing anything).

First, enter the name of the new spectrum test.1d in the Spectrum Name: text box.

Different spectrum types require different sorts of information. Initially, the dialog does not know what type of spectrum you are creating. The Spectrum Type button displays a drop down menu. Select 1-d from that menu to tell the GUI you are creatig a 1-d spectrum.

The GUI expands to the spectrum specific editor for 1-d spectra:

On the left 1/2 of the dialog is subset of the folder hierarchy. A 1-d spectrum requires a parameter and may optionally have a gate applied to it. The parameter and optional gate are chosen by double clicking them on the subset browser.

Once a parameter has been selected, the right side of the dialog displays it and allows you to set the spectrum axis limits and bin count. If the parameter has been defined as a Tree parameter it may have range and resolution information. If so, the dialog will use that to suggest values for the axis limits and bin count. If the parameter has a units string associated with it, The units will be displayed as well.

We don't have any gates defined so we are only going to select a parameter and set the range and binning of the spectrum X-axis. Click the + to the left of the parameters folder (left mouse button). The Parameter folder expands to reveal an event folder. Click its + to expand it. Click the + of the raw folder this revealed.

The spectrum definition dialog should now look like this:

Each of the green square icons that has a script T with a lowercase p kerned inside it represents a parameter. The last part of the parameter name is displayed to the right of its icon, and the column of the tables to the right of the folder tree give the properties of each parameter.

Recall that periods separate parts of the hierarchy. The Parameters root folder is not part of a parameter name, but simply indicates its subfolders contain parameters. Therefore, the icon labelled 00 really represents the parameter named event.raw.00 (Parameter 00 living in folder raw that itself lives in folder event ).

Double click on the event.raw.00 icon. Note the changes in the right 1/2 of the spectrum definition dialog.

Note how the parameter you select has suggested an axis definition. Let's change that to an axis that runs from 0 to 1023 with 1024 bins. Enter 0 in the Low text entry, 1023 in the High box and 1024 in the Bins box.

Finally, create the spectrum and dismiss the dialog by clicking its Ok button. (Accept creates the spectrum but leaves the dialog displayed so you can create more spectra).

Note that there is now a + next to the Spectra folder in the main Gui. Click that +. Since we named the spectrum test.1d, we get a folder named test that also has a +. Click that + to see the spectrum (an icon that looks like a spectrum with a few peaks). Note that:

• The spectrum type, and axis definition appear in the columns to the right of the spectrum icon.

• The spectrum icon itself has a + to its left indicating it can be expanded to display more detail. If you click that + The parameter histogrammed will be displayed.

If you click the + to the left of the histogram definition, the folder GUI will look like this:

Expanding different spectrum types will provide different information about the spectrum details. For exmample, a 2-d spectrum will an item for each axis describing the parameter on that axis, and the limits and binning of that axis.

I conclude this section by encouraging you to play around creating different spectrum types, exploring the types of spectrum definition dialogs you'll see. You may also want to click on each spectrum definition dialog's Help button to explore the on-line help for each of these spectrum editors.

7.3.3.3. Creating Gates

If you have read the section on creating spectra, you already have most of the skills needed to create a gate with the folder GUI. Please note that primitive gates like slices, contours of bands can be most easily entered by clicking on spectra displayed by Xamine. Compound gates are most easily entered using the folder GUI.

In spite of this, in this section we will:

1. Create a pair of slice gates, on event.raw.00 and event.raw.01 (recall that gates are defined on parameters even though they can be created on spectra that are created on those parameters).

2. Create an OR gate that will be true whenever an event is in at least one of those gates.

3. Apply the OR gate we made in the previous step to the spectrum we created in the previous section (test.1d).

Ok, let's start by making the two slice gates. Gates have a gate definition dialog that, like the spectrum definition dialog consists of a generic and gate specific section. Bring up the gate definition dialog either by selecting Gate->Create... or by selecting New... from the Gates folder context menu.

This will bring up the generic part of the gate definition dialog:

Fill in the gate name as slices.01 and select the gate time to be a slice. This will expand the gate definition dialog to include the slice editor. Note the reminder at the top of this dialog that you can enter slice gates graphically as well.

The top part of the new area is a generic parameter choser that is used in a lot of gate definition dialogs. The top left part of the newly displayed part of the dialog is once more a subset browser. In this case the subset browser allows you to select a parameter. The right hand top part of the gate definition dialog is a list of the parameters on which the gate will be defined. In this case the dialog will only allow one parameter to be chosen.

Using the + open the Parameters folder and underneath it, successively, the event and raw folders. Chose the parameter icon that corersponds to event.raw.00. Note that

1. That parameter is removed from the list of available parameters preventing you from specifying it twice in gates that use more than one parameter.

2. The full parameter name is now in the Parameter(s) selected listbox.

Enter the slice limits at the bottom of the dialog in the text boxes labelled Low Limit: and High Limit: respectively.

Since we are going to create another slice, click the Accept button to accept the gate.

The default new gate type is another slice, so now let's enter the gate name, and select parameter. In the Gate Name: text box enter slices.02, Select the parameter event.raw.02, and enter whatever limits you feel like entering, then click Accept again.

Next we'll make a gate named OrGate which will be true when at least one of slices.01 or slices.02 are true. Enter OrgGate in the Gate Name text box. Click on the Slice button to drop down the gate type menu and select Or (+). Your dialog should now look like:

Or gates depend on other gates, rather than parameters. Therefore, the gate definition dialog consists of a browser for the existing gates, and a listbox showing the gates that have been accepted.

Open the Gates folder and then the slices folder underneath it. You should see something like this:

Double click on the two gates (slices.01 and slices.02) in any order to add them to the Dependent Gates listbox. Click the Ok button to accept this last gate and dismiss the dialog

Fully expand the Gates folder, all subfolders and items in all the subfolders. This should give you something like this:

Expanding a gate provides you with the gate dependent information about how that gate has been made.

As we know, gates are only useful when they are applied to a spectrum. Let's apply OrGat to The test.1dspectrum. There are actually three ways to get to the Gate application dialog.

1. Select Gate->Apply... which brings up the gate application dialog completely uninitialized.

2. Select the Gate... entry from a Spectrum context menu. This brings up the same dialog with the spectrum already selected.

3. Select the Apply To... entry from a Gate context menu. This brings up the same dialog with the gate already selected.

So that we can go through the entire process we'll select Gate->Apply... from the menu bar. This brings up the uninitialized gate application dialog:

Application is the process of selecting a single gate that will be applied to at least one spectrum. Open the Spectra folder and its test subfolder. Double click on the 1d spectrum to set test.1d as the only spectrum that will be applied to. If you have more than one spectrum you want to apply the same gate to, you can keep double clicking spectra until all the target spectra are listed in the Spectra: listbox.

Select that gate to apply by opening the Gates folder and double clicking on the Orgate gate icon. Your Gate application dialog should now look like:

Apply the gate by clicking the Ok button.

I will conclude this section by once more encouraging you to play with the gate definition editors. See what each gate asks you to provide, and what details each gate type provides in the folder Gui. Once more all the gate definition dialogs have a Help button that takes you to a help page appropriate to that type of gate editor.

7.3.3.4. Saving and Restoring Definitions

The set of parameter, spectrum, and gate definitions and gate applications that make up a realistic analysis can be quite large. Re-creating them each time is error-prone, and just plain no fun. SpecTcl's commands offer enough introspection capability to allow the folder GUI to write scripts that can be read in to restore these definitions at a later time.

Recognizing that you may not remember to save your definitions, or that there may be failures in the hardware or software that leave you with unsaved definitions, the folder GUI automatically writes a definition file named failsafe.tcl whenever you change the definitions.

You may also explicitly save and restore definitions from a named file. To save your definitions to file, click the File->Save... selection from the menu bar. This bring sup the following dialog:

The set of checkboxes at the top of the widget describe which definitions will be saved to file. By default all definitions are saved. The remainder of the dialog box allows you to choose a file to which the definitions will be saved. Once you have done that, click Ok to save the file.

For the sample spectra we have been creating, this setup file will look like:

#  SpecTclGUI save file created Fri Jan 04 04:31:12 PM EST 2008
#  SpecTclGui Version: 1.0
#      Author: Ron Fox (fox@nscl.msu.edu)

#New Tree Parameters:


#Modified Tree Parameters:


# Pseudo parameter definitions


# Tree variable definitions:


# Spectrum Definitions

catch {spectrum -delete test.1d}
spectrum test.1d 1 event.raw.00 {{0.000000 1023.000000 1024}}

# Gate definitions in reverse dependency order

gate slices.01 s {event.raw.01 {100.000000 200.000000}}
gate slices.02 s {event.raw.02 {0.000000 150.000000}}
gate OrGate + {slices.01 slices.02}

# Gate Applications:

apply OrGate  test.1d

#  filter definitions: ALL FILTERS ARE DISABLED!!!!!!!
                    

A few observations:

• The configuration file is just a Tcl script you could just source it in and refresh the tree parameters.

• Spectra are deleted before being created, the catch command ensures that if the spectrum does not exist the script will continue to execute.

• Gates are written out in reverse dependency order. That is A gate will not be written to the configuration file until all gates it depends on have first been written. This ensures that loading the file will always work (consider what would happen if OrGate had been written prior to slices.02.

While definition files can just be sourced, the folder GUI also provides a File->Load... Menubar menu item. This just brings up a file chooser dialog. When you select the desired file, SpecTcl will source it in, refresh the object browser and sbind all spectra.

7.3.3.5. Selecting Data Sources

SpecTcl analyzes data from a data source. The current version of SpecTcl understands two types of data sources:

• File; File data sources in turn can be either raw event files or filtered data files.

• Pipe; Pipe data sources are programs that write data to their standard output which is connected by means of a pipe to SpecTcl.

There are also two special cases of piped data sources that are important:

• Connecting to the online system (via spectcldaq, a pipe data source in the NSCL data acquisition system.

• Connecting to a list of run files (called cluster files by some.

The folder gui Data Source menu has menu entries that allow you to connect to any of these types of data sources. In this section, we will examine each of the option on the Data Source menu and the dialogs they bring up.

Clicking on Data Source->Online (spectrodaq)... displays the following dialog:

The Host entry box is where you will enter the name of the computer that is attached to the experiment (from which you are accepting) data. If the default buffersize is not correct you can adjust it with either the up and down arrows or by typing the correct size in the Buffer size in bytes: spinbox.

Click the Ok when you are ready to take data. The Help provides more information about the dialog. The default buffer size can also be set in the Edit->Preferences... dialog.

In the dialog below:

use the file chooser section of the dialog to select the event file to read. If the buffersize of that event size is not the same as the buffersize in the Buffer Size: spinbox, select the correct buffer size using the spin box arrows or by typing a value in to the entry. When the dialog is filled in correctly, click the Ok to start analyzing data from the selected file.

Attaching to the online system, and attaching to a list of runs (cluster file) is a special case of attaching to a pipe data source. When you attach to a pipe data source, you get the following dialog:

Use the file browser to select the command or type in the command in the Selectiontext box. Enter any command line arguments or switches the command should receive in the Parameers text box. If necessary use the Buffer Size spinbox to set the correct buffersize.

When you have filled in the dialog correctly, click the Ok to start analyzing data from the program.

The Data Source->List of runs... selection brings up the dialog shown below:

Simply select the cluster file (the file with the list of event file names), and click Ok to start analyzing. The file will be analyzed with the default buffer size which can be set using the Edit->Preferences... menu selection.

To open a filter file data source with the folder Gui, you should click on Data Source->Filter File.... You will first see a dialog that reminds you that you must have built SpecTcl properly to accept filter files. Click on Ok to continue or on Cancel if your SpecTcl has not been built to handle filter files.

If you click on Ok You will get a file chooser from which you can select the filter file to use as the data source.