ScanRoot

The ScanRoot is a modified version of ROOT compiled with all the PelROOT libraries. You can use the scanroot program to process data files (.FIL) to create histograms and/or use it to do final histogram analysis such as projections, fits, etc.

Starting ScanROOT
The graphical interface
Command prompt interface
ScanRoot and ScanRootGUI objects

Starting ScanROOT

To start the ScanRoot just type:

spmroot [options] [file1] [file2] ...

where the optional parameters are:

-d or -debug = enters the program in debug mode
-h or -help = shows a help message
-t or -tools = opens the PelTools menu
file1, file2, ... = open the ROOT file and shows a TBrowser window

When the program starts it will show the following prompt

and a graphical interface as shown next.

The graphical interface

When ScanRoot starts it shows the following graphical interface:

on the top of the window there is a quick access bar with the most used commands (this is a static bar). The most simple data processing can be done by just following the order of the buttons in this bar.

The buttons in the quick access bar correspond to the following actions:

Open FIL - Opens a .FIL file for input
Load Hist - Loads a histogram code for data processing
Zero all - Zeroes all the histograms loaded in the memory
GO - Processes the events from the .FIL file
Save Hist - Saves the resulting histograms in a file
PelTools - Opens a PelTools window for data analysis

Bellow the quick access bar is located the main interface, divided in tabs. There are 3 tabs in total corresponding to:

File tab - File and I/O operations
Data processing tab - Commands used to process the data stored in FIL files
Tools tab - many tools, including the PelTools

The File tab

The File tab contains buttons and information for file I/O. The interface in this tab looks like:

The buttons in the File tab correspond to the following actions:

Open FIL - Opens a .FIL file for input
Close FIL - Closes the input file
New Output - Creates a new .FIL file for output
Close Output - Closes the output file
Load Hist - Loads a histogram code for data processing
Save Hist - Saves the resulting histograms in a file
Load L2 - Loads a event filtering code for data processing
Unload L2 - Removes the event filtering code from memory

There are also four text entries in the Tab that correspond to the file names that are being used for data processing.

The Output Saving Mode selection tab sets how the parameters are saved in the output file, if there is an output file open. The default option is to save all the parametes. If the Only new parameters is selected, the output file will contain only the new parameters that are created during data process. The original parameters from the input file are not propagated to the output. To know more about creating new paramentes, click here.

The Data tab

The Data tab contains buttons and information for data processing. The interface in this tab looks like:

The buttons in the Data tab correspond to the following actions:

Zero - Zeroes a single histogram
Zero All - Zeroes all histograms in the memory
GO - Processes the events from the input file
Set NPAR - Sets the maximum number of parameters. This defines the amout of space allocated in the memory for holding the event data. A bigger size just increases the time needed for processing the input file. However, if you have more parameters than NPAR you will loose same of them during the data processing. The default value is 128.
Call INIT - Calls the INIT function. For more detail, look at histogramming code
Call FINISH - Calls the FINISH function. For more detail, look at histogramming code

There are two selection buttons in this tab:

Data smearing - If OFF (default) all the parameters are integer values corresponding to the edge of the bin. For example, if you have a 12 bits ADC value in the input file the possible values for the corresponding paramenter are 0, 1, 2, ..., 4095. If this button is set to ON the values of the parameters are smeared inside a bin using a UNIFORM RANDOM generator. In this case, the ADC value can be any REAL number from 0 to 4095. This is important if you are applying some calibration correction in the data and want to avoid artefacts due to binning in the histogram. If smearing is ON the time to process the data is increased.
Data debug - Turns ON/OFF the debug mode (default is OFF). The debug mode prints out a lot of data information for each event.

The Tools tab

The Tools tab contains buttons and information for some useful tools. The interface in this tab looks like:

The buttons in the Tools tab correspond to the following actions:

new Canvas - Creates a new Canvas window for display
new Browser - Opens a new Browser window for navigation
PelTools - Opens the PelTools menu bar
STATS - Shows some statistics
Run Macro - Runs a user macro from file
exec Command - Executes a single ROOT command defined by the user
HELP - Opens a web browser in this documentation page
QUIT - Quits ScanROOT

Command prompt interface

The command line is particularly interesting when the user wants to automate the event processing because the user can write a macro containing the instructions to process a lot of files at once.

There are two modes of using the command line.

Using some pre-defined functions in the ScanRoot program.
- ScanRoot has a set of pre-defined functions that makes the prompt interface easier for the user that is not familiar with C++ objects. The set of functions is limited but contains all the basic functions for the regular processing of event files.
  
  NOTE: Use this functions ONLY in the command line mode or inside macros that run in command mode. Do not use these function inside histograms or Level 2 programs because the compiler will not recognize them.
Using the pointer to the ScanRoot object.
- There is a global variable gSCAN that points to the ScanRootGui object in the computer memory. ScanRootGui is derived from ScanRoot and has public methods for all the features ScanRoot can offer. It is also possible to directly get a pointer to the PelTools and PelIO objects in the memory. The use of gSCAN pointer is more flexible than the previous method but requires some knowledge of C++ programming.
  
  NOTE: The global variable gSCAN is available only in the command line mode or inside macros that run in command mode. Do not use gSCAN inside histograms or Level 2 programs because the compiler will not recognize it.

Here is an example of a macro that process 2 .FIL files and save the histograms to files:

void macro()
{
  hac("histograms.cxx"); // loads the histogramming program
 
  openInput("file1.fil"); // opens the 1st .FIL file
  go(); // process all the events in this file
  saveHist("file1.root"); // saves the fistograms to file1.root
  closeInput();

  zero(); //zero all histograms. The file1.root WILL NOT be zeroed. Just the memory
  openInput("file2.fil"); // opens the 2nd .FIL file
  go(); // process all the events in this file
  saveHist("file2.root"); // saves the fistograms to file1.root
  closeInput();
}

To run this macro, type, at the ScanRoot prompt (if the macro is saved as macro.C)

.x macro.C

The ScanRoot pre-defined functions are:

void openInput(char* file); - opens a FIL file for INPUT
void closeInput(); - closes the input file
void rewind(); - rewinds the input file (only for version 4.1 and above)
void openOutput(char* file,int out = 0); - opens a FILL file for output. Maximum 4 outputs
void closeOutput(int out = 0); - closes the output file
void saveOnlyNewPar(bool = false); - if true saves only the new parameters to the output file
void addHist(char* file); - adds histograms saved in a file to the memory
void saveHist(char* file); - saves all the histograms in the memory to a file
void hac(char* file); - loads histogram code to the memory for data processing
void loadL2(char* file); - loads a software filter code to the memory for data processing
void unloadL2(); - unloads the software filter code
void cd(); - sets the current directory to the ScanRoot top directory
void zero(); - zeroes all histograms
void zero(char*); - zeroes the histogram defined by name
int go(int = 0); - processes N events from a FIL file. If N==0, or not given, processes the entire file. It returns the number of events processed (this return is only for version 4.1 and above).
int skip(int = 1); - skips N events in the input file. Only for version 4.1 and above. It returns the number of events actually skipped.
void tools(); - opens a PelTools window
void setNPar(int=128); - sets the maximum number of parameter to process.
void debug(bool = false); - turns on/off the debug mode. default value is false
void smearing(bool = false); - turns on/off data smearing inside a single bin. default value is false
void stat(); - shows statistics
void help(); - opens a browser windows with the documentation
ScanRootGui* getScan(); - gets a pointer to ScanRootGui object in the memory

ScanRoot and ScanRootGui objects in memory

SPMRoot and ScanROOT is constructed in a object oriented framework.

While loading histogramming or filtering code, the program (SPMRoot or ScanROOT) passes a pointer to an internal ScanRoot object. This object is responsible for all the interface between the user and the data. There are many functions available for data manipulation and environment configuration. Some of them are shortcutted in the ScanRoot pre-defined functions (above). Also, while using ScanROOT program there is a global pointer (gSCAN) to the ScanRootGui object created in the memory. The user can utilize this pointer to get access to many public methods available in this object or to other objects, such as the PelIO and PelTools objects.

The basic classes for data manipulation in this framework are listed bellow:

PelIO - This class makes all the I/O of .FIL files and event decoding
CamacIO - This class is derived from PelIO and adds the CAMAC I/O interface
ScanRoot - Basic class for data manipulation
ScanRootGui - This is derived from ScanRoot and adds the GUI framework
SPMRoot - This class defines the basic object for data acquisition and the GUI framework of SPMRoot
PelTool - This class defines all the framework of the PelTools environment.
TPeakFit - A basic class for peak fitting
TPeakFitGUI - derived from TPeakFit, it adds the GUI framework
TDialog - basic Input dialogs used in many programs
TContainer - objects from this class acts as containers for other objects
TDynamicSlice - this is the basic class for dynamic slicing of 2D histograms

The documentation for the PelROOT classes can be found here.