TigSort and TigSortGUI - A data analysis application for Tigress

1. Installation

Required:

• ROOT, tested with versions 5.26, 5.30, 5.34
• ROOTANA
• either TigSortGUI github for GUI version
• or TigSort github for running batches

Before installing ROOTANA, you need to set the 'ROOTSYS' environment variable, so ROOTANA will be installed with ROOT support, see http://ladd00.triumf.ca/~olchansk/rootana/. Then, you need to set the 'ROOTANA' environment variable to point to your ROOTANA installation. Example:

export ROOTSYS=$PKGS/root_v5.30
export ROOTANA=$PKGS/rootana
export PATH=$ROOTSYS/bin:$PATH
export LD_LIBRARY_PATH=$ROOTSYS/lib:$ROOTANA:$LD_LIBRARY_PATH

Check out the TigSort(GUI) code, and in the directory, and type make. The executable is tigsortGUI, which you can now move to somewhere that is in your path for easier access.

2. Running

In the following, examples are given for analysis of data taken during experiments S1107 and S1201. I used runs 1693 and 1696 from S1107, and 1861 – 1864 for S1201 for no particular reason other than that those are relatively short runs. The required configuration files are included in the source tarball.

TigSortGUI main window

2.1. From Midas file

• Load detector configuration: Menu 'Configuration' → 'DAQ addresses' → 'load from .tigsort file'
• Select S1201.tigsort or S1107.tigsort
• The trees that were defined in the input file can be selected in the drop down box above the list boxes
• The defined detectors for the selected tree will show up in the left list box
• Load data files: Menu 'Data' → 'Select midas files'
• Choose MIDAS data files, this is multiple selection
• It does not matter whether you use '.mid' or '.mid.bz2' files, ROOTANA handles both equally well

You can adjust the output file name in the text boxes on the top left: prefix - postfix - actual name of output file, prefix and postfix are used for the automatic file name generation but you can change the name directly in the third text box.
The configuration file defines the TTree structure and the detectors with their channels and signals. The input must be separated by whitespace, empty lines and lines starting with '#' are ignored.
Example configuration file:

buffer     500
tree
        name    SharcEvents
        description     Sharc data
        detector
                name    DiBx1_F
                description     Si downstream box 1 front
                datatype        Charge
                signals
                        range 0 23  0x00800317  0x00800300
                end
        end
end

Explanation:
The indentation is purely for readability and has no function.
buffer is the number of events that will be assembled before the event is further processed. This is not the number of MIDAS event fragments, but of actual events that are being assembled. The size of this buffer will depend on the trigger rate. The default value is 1000. You can check whether your buffer is sufficiently large but looking at the resulting root tree (see below). Each tree contains the trigger event ID (from the DAQ) and an analyser event ID, i.e. the order in which the events were found in the MIDAS stream by the enalyser. If the analyser ID is larger than the trigger ID, some events were probably not completely assembled.
tree: the root TTree. You can sort your data into several trees. For example, in 'S1107.tigsort', the scaler events are in a separate tree from the SHARC events.
detector: each detector in a tree must have a unique name. The signals can be given either as a range (channel_min channel_max address_min address_max), or as individual 'channel - address' combinations. The channel numbers do not need to be consecutive, nor do they need to start with 0.
datatype: there are different values that can be extracted for a detector. These are

• Charge (default)
• CFD
• LED
• WfEnergy
  • needs additional parameters for calculation of baseline and peak
  • base1Min base1Max base2Min base2Max peakMin peakMax
  • the number of baseline bins must be equal to the number of peak bins to make sense
• WfPeak: needed parameters: peakMin peakMax
• WfMinBin
• WfMaxBin
• Timestamp
• TimestampUp
• Lifetime
• TriggersAccepted
• TriggersRequested

2.2 From root file

TigSortGUI can also read back trees from root files it has previously generated. Thus, you can do the analysis stepwise, without each time re-running the MIDAS files.

• Load detector configuration: Menu 'Configuration' → 'DAQ addresses' → 'load from .root file'
• Select a root file that was previously created by TigSortGUI and contains the same tree structure as the files you want to analyse
• The tree selection combo box lists the TTrees that were found in the selected root file
• The left list box contains the TBranches belonging to the selected tree
• Load data files: Menu 'Data' → 'Select root files'
• Choose root data files, this is multiple selection, the data files must have the same tree structure as the file you selected for configuration

Note: Reading scalers back does not currently work.

2.3 Calibration

You can calibrate the energies of the detectors. Load the calibration input file from the menu: 'Configuration' → 'Calibration' or 'Formulas/Histograms' → 'load from .tigsort file'. 'S1201_gains.tigsort' contains calibration for some detectors. This file has a similar format as the input file in Section 2.1. The 'input' field specifies which detector to calibrate. The 'name' field can be omitted, if no name is given for the calibration, it will automatically be named detector_calib.

2.4 Adding sorting, formulas, cuts

There are several ways to sort and manipulate the data. You define what you want to do in input files similar to the configuration file used in Section 2.1. All objects in the same tree must have unique names (if a name is already taken, the new object will not be added, thus, if you make a mistake in an input file, you can fix it and reload the whole file, the stuff that was already loaded will be ignored. ).

• always requires 'input' field to denote which data to use.
  This must be the name of one (or more, depending on object) object that has already been defined
• each detector has two sets of data: the channels, and the energies for the channels.
  If you give the detector name as input, both will be used.
  You can also add either "_channel" or "_value" to the detector name to access the one or the other.
• sorter
  • maxValue: returns the maximum value for a detector together with the channel
  • selectChannel: choose specific channels from a detector, returns both the channel and the energy
  • combine: combine the data from several detectors/other objects
• formula
  • uses root's TFormula parser, equation must be in quotes
  • see the root TFormula documentation for details
• cut
  • tcutg: loads root TCutG, first parameter is the file name, second the name of the cut
  • range cut: parameters: minimum maximum
  • cuts can be added to objects by adding the keyword cut followed by the name of the cut.
    Only events that passed the cut will be used by this object

The input files are loaded from the menu: 'Configuration' → 'Formulas/Histograms'. This is multiple selection, just note that the objects are loaded in the correct order, i.e. that the inputs for an object are already defined when it is added. The objects that are added are also added to the list box with the detectors.
The examples included in the source tarball are

• S1201
  • formulas.tigsort
  • histos.tigsort
• S1107
  • S1107-histos.tigsort

2.5 Adding histograms

Adding histograms works the same way as adding sorters and formulas, they can be mixed in the same input file. The histograms are listed in the right-hand list box. The number of inputs defines whether the histogram is 1D or 2D. Beware that 2D histograms with large bin number take a lot of memory, and can cause the program to crash when trying to write the histograms to file.

• x/ybins parameters are: number of bins - minimum - maximum
• Waveforms
  • There are two ways to define the address for a waveform histogram:
    1. the address in hexadecimal, similar to the detector signals
    2. the input and channel of a detector
  • Only the most recent waveform is displayed

TigSortGUI main window, detectors and histograms defined

2.6 Fill root trees

Since the resulting root trees can get large, only either trees or histograms are filled. You can toggle between them using the radio buttons in the 'Fill trees or histograms' box. The default is to fill the trees. When filling the trees, you can also choose whether to create one output file for each selected input file, or whether to combine them all in one file (radio buttons in the 'RootTree output file' box). Especially for larger data files it is recommended to create separate files. These will be named using the prefix and postfix from the text boxes, and the run number.

• click 'Run' to start the analysis
• the program will keep running until the last MIDAS file ends, or you click the 'Stop' button (formerly known as the 'Run' button)
• the files with the trees are automatically written to disk (no overwrite warning!)

There is currently no way to write waveforms to a tree. This might change at some point. You can choose which of the other detectors and modules you defined will be written to the tree on the tab with the tree name. Uncheck the 'Write' box for anythiing you don't want included.

2.7 Fill histograms

• set the 'Fill trees or histograms' to 'Fill Histograms'
• Click 'Run' to start the analysis, 'Stop to end'
• you can select the histogram you want displayed in the right-hand listbox
• the histograms are not automatically written to file, click 'Save histos' to write them

Note that the bigger the histogram you are displaying, the slower the analysis; if you are impatient, unselect all histograms to fill them faster, then select one to check the progress.
When filling histograms, you can also step through the data, rather than run it continuously. The analysis will run until one histogram is filled once, then stop. This is mainly useful to look at waveforms in detail.

2.8 Preferences

To avoid multithreading, the program has to occasionally interrupt the analysis to check for GUI interaction and update the currently displayed histogram. The frequencies with which those happen can be changed in the 'Preferences' menu. The numbers are in events before the GUI is checked/ the histogram updated.

3. TigSort (without GUI)

To quickly sort MIDAS data files into root trees, it is recommended to use the command line version:
%s source tarball (last updated %s).",$filename,$path[1], date ( "M d, Y, H:i (T)",filemtime($filename))); } else printf("%s source tarball (which could not be found, contact me).",$filename); ?> Alternatively, you can download the source code from my github page.
It uses the same detector configuration files as the GUI version, described above in Section 2.1. Just run using

tigsort -cConfigFile.tigsort runXYZ.mid

or set the environment variable 'TIGSORT_INPUT'

export TIGSORT_INPUT=/path/to/ConfigFile.tigsort
tigsort runXYZ.mid

The output file will be asmXYZ.root.