|
|
SpecTcl's handling of Event Data |
|
SpecTcl Home General Information User Guide Programmer's Guide Obtaining and Installing
Page Contents:
The Classes:
The figure below shows the set of classes which interact to analyze data in SpecTcl.
To build a tailored version of SpecTcl you will need to understand aspects of the following classes:
|
The unpacked event adjustable array |
|
|
Your derivation of the application base class |
|
|
Event processors you derive from and register on the analyzer. |
The CEvent adjustable array
The CEvent class represents an unpacked event. The histogramming kernel of SpecTcl takes parameters from CEvent objects and histograms them according to the parameters, histograms and gate applications defined by your Tcl scripts. The job of analyzing the event stream consists of taking the incoming event stream apart and filling in a CEvent array with the parameters relevant to the event.
The CMySpecTclApp application class/object
There is one object in the system of type CMySpecTclApp. This object uses its base class functionality to initialize SpecTcl and to set up the linkages between the interacting objects which make up a SpecTcl. CMySpecTclApp is is implemented in the MySpecTclApp.cpp file you receive in the skeleton distribution. At a minimum, you must modify this class to register event processors which understand the experimental data and what needs to be done to it to create a filled in CEvent array.
The CEventProcessor you derive event processors from
Event analysis in SpecTcl takes the form of an analysis pipeline. Elements in the pipeline are instances of classes derived from CEventProcessor. Event processors are registered into the analyzer by the CMySpecTclApp object through calls to its RegisterEventProcessor member function. Event processors are executed in the order in which they were registered. Usually, the first event processor will unpack the raw event into CEvent, and subsequent element in the pipeline will process this unpacked event performing e.g. calibrations, validation and physics. The results of subsequent stages in the pipeline are modifications to unpacked parameters or the creation of additional 'compiled' pseudo parameters which represent the event at a higher level of abstraction/meaning.
Event processors may also reject the event by calling the analyzers AbortEvent() member function. If the event is accepted, its size must be set by some combination of calls to the analyzer's SetEventSize() and IncrementEventSize() members. This size allows SpecTcl's analyzer to know where to find the next event in the buffer so it must be 100% accurate.
The Skeleton software includes a 2-step pipeline. The first step unpacks a fixed length event. The second step computes a single pseudo parameter.
Writing Event Processors
Event processors are called in sequence when each event is located in a physics data buffer. The CEventProcesor member functions are described below:
|
Returns |
Name |
Parameters |
Does |
|
virtual Bool_t |
OnAttach |
CAnalyzer& rAnalyzer |
Any necessary processing when the event processor is registered into the analyzer. Returns kfFALSE on failure. |
|
virtual Bool_t |
OnBegin |
CAnalyzer& rAnalyzer, |
Called for a begin run buffer. If kfFALSE is returned, then the remainder of the pipeline is aborted. |
|
virtual Bool_t |
OnEnd |
CAnalyzer& rAnalyzer, |
Called for an end run buffer. If kfFALSE is returned, then the remainder of the pipeline is aborted. |
|
virtual Bool_t |
OnPause |
CAnalyzer& rAnalyzer, |
Called for a pause run buffer. If kfFALSE is returned, then the remainder of the pipeline is aborted. |
|
virtual Bool_t |
OnResume |
CAnalyzer& rAnalyzer, |
Called for a resume run buffer. If kfFALSE is returned, then the remainder of the pipeline is aborted. |
|
virtual Bool_t |
operator() |
const Address_t pEvent, |
Called for each event in a physics buffer. At least
one element in the pipeline must set the event by calling a combination of
rAnalyzer.SetEventSize(UInt_t n) and |
|
virtual Bool_t |
OnOther |
UInt_t nType, CAnalyzer& rAnalyzer, CBufferDecoder& rDecoder |
Called whenever any buffer type not processed by the other buffer processing functions in the event processor is encountered. This is one way, for example, to get called for scaler data. The nType parameter is the buffer type code. You can use the rDecoder parameter to get the buffer contents, buffer body or other things you need to process this buffer. |
|
virtual Bool_t |
OnEventSourceOpen |
std::string name |
Called when SpecTcl attaches a new data source. This was introduced with SpecTcl 3.2 and later. The name is the name of the data source, and can have one of several formats: - File: filename – the event source is a file and the path to the filename follows the colon - Pipe from: command – the event source is a pipe and the command feeding event data to SpecTcl is given after the colon. - Tape: device - (mostly obsolete), the event source is an ANSI labelled tape with event files on it, and the device is given after the colon. - Test Source – the SpecTcl test data source is being used. - Null – The null data source (immediate end of file) is being used. |
|
virtual Bool_t |
OnEventSourceEOF |
|
Called when an end of file is encountered on the event source. Note that if the user attaches to an event source, then attaches to another one prior to the end of file, this will not get called (OnEventSourceOpen will be called for the second attach however). |
Sample Event processor.
The event processor definition below is part of the sample provided in the skeleton. It unpacks fixed length events which are preceded by a self inclusive word count.
class CFixedEventUnpacker : public CEventProcessor{public:
virtual Bool_t operator()(const Address_t pEvent, // Only need to override the unpacking
CEvent& rEvent, // behavior. All other members have
CAnalyzer& rAnalyzer, // adequate default behavior.
CBufferDecoder& rDecoder);};
Bool_t
CFixedEventUnpacker::operator()(const Address_t pEvent,
CEvent& rEvent,
CAnalyzer& rAnalyzer,
CBufferDecoder& rDecoder){ // This sample unpacker unpacks a fixed length event which is // preceded by a word count. //CTclAnalyzer& rAna((CTclAnalyzer&)rAnalyzer); // needed to call CTclAnalyzer::SetEventSize()
UShort_t* p = (UShort_t*)pEvent; // The event is made up of UShort_t's.
UShort_t nWords = *p++; // The first word of the evetn is its size.
Int_t i = 1; // This is the index of the CEvent of the first
// parameter we fill in.
// At least one member of the pipeline must tell the analyzer how // many bytes were in the raw event so it knows where to find the // next event.rAna.SetEventSize(nWords*sizeof(UShort_t)); // Set event size. In Bytes!!!!
nWords--; // The word count is self inclusive.
while(nWords) {
rEvent[i] = *p++; // Unpack into the event array.
nWords--; i++; }return kfTRUE; // kfFALSE would abort pipeline.
}
Filling in the Application Class
The CTclApplicationClass must be filled in and instantiated to complete SpecTcl initialization. At a minimum, one EventProcessor must be registered into the event pipeline. This section will describe all of the member functions in the CTclApplication class, when they are called, what they should do and what the parent's class default behavior is.
virtual void CreateAnalysisPipeline(CAnalyzer& rAnalyzer)
This function is the only one which absolutely has to be coded by you. All of the others could, in simple cases be left to their default behavior. This function is the next to the last action performed by the application initialization. The last action is to source any action scripts that the user requests (call to SourceFunctionalScripts). By this time essentially all of SpecTcl is set up.
The programmer must register the event processors which make up the analysis pipeline. For example:
static CFixedEventUnpacker Stage1;
static CAddFirst2 Stage2;...
void
CMySpecTclApp::CreateAnalysisPipeline(CAnalyzer& rAnalyzer) { RegisterEventProcessor(Stage1); RegisterEventProcessor(Stage2);}
The example above declares two event processors, Stage1 and Stage2 and registers them in the analysis pipeline.
virtual void BindTCLVariables(CTCLInterpreter& rInterp)
This function is called at the beginning of MySpecTclApp's initialization. Any tcl variables the user needs can be bound at this time to CTCLVariable objects. The default behavior is to call CTclGrammerApp::BindTCLVariables() to bind the variables which SpecTcl uses to set limits on statically allocated resources (such as DisplayMegabytes), or initial sizes of dynamically allocated resources (such as ParameterCount).
You may extend the default functionality by adding your own code.. You must not remove the call to CTclGrammerApp::BindTCLVariables() and expect SpecTcl to work.
virtual void SourceLimitScripts(CTCLInterpreter& rInterpreter)
This function is called right after BindTCLVariables. It is intended to source scripts which set variable values needed by SpecTcl or your extensions. By default, this function calls CTclGrammerApp::SourceLimitScripts() which executes SpecTclInit.tcl first in the SpecTcl distribution area adn then in your home directory if it exists.
void SetLimits()
Called after SourceLimitScripts. By now it is assumed that any tcl variables involved in static limit setting will have been bound (BindTclVariables) and initialized by user scripts (sourced by SourceLimitScripts). In this function, if there are static limits which need be set, or other configurable variables which must be initialized from Tcl variables, extend this function. Do not delete the call to CTclGrammerApp::SetLimits() as some critical SpecTcl limits are set by that call.
virtual void CreateHistogrammer ()
Called immediately after SetLimits. This function is expected to set up a data sink for the analyzer. The default call, CTclGrammerApp::CreateHistogrammer() will set up a TclHistogrammer as the data sink. If desired, this can be overridden and e.g. user specific data sinks can be registered instead.
virtual void SelectDisplayer (UInt_t nDisplaySize,
CHistogrammer& rHistogrammer)
Called after CreateHistogrammer. The nDisplaySize parameter is, if appropriate to the number of megabytes desired for display memory shared between the SpecTcl and the displayer. The rHistogrammer parameter is the histogrammer created in CreateHistogramer.
This function creates a displayer and hooks it to SpecTcl's histogrammer. The displayer by default is Xamine (via the call to CTclGrammerApp::SelectDisplayer). This can be overridden by removing that call and substituting code to generate the user's own displayer.
virtual void SetupTestDataSource ()
Called immediately after SelectDisplayer. The default action is to call CTclGrammerApp::SetupTestDataSource which in turn sets up a data source to produced 5 parameter fixed length events with gaussian distributions. If you don't have your own test data source you can leave this alone. Sample code for this is shown here. Otherwise, remove the call to CTclGrammerApp::SetupTestDataSource and add code to create your own test data source.
virtual void CreateAnalyzer (CEventSink* pSink)
Called immediately after SetupTestDataSource. Creates the data analyzer object. By default a CTclGrammerApp::CreateAnalyzer is called causeing a CTclAnalyzer object to be created and the event sink created in CreateHistogrammer linked to it. The CTclAnalyzer is the standard analyzer used by SpecTcl, if you have your own analyzer derived from and extended from the CAnalyzer class, you can create an instance of it instead and hook it into the system. Do this by removing the call to CTclGrammerApp::CreateAnalyzer and adding your own code.
virtual void SelectDecoder (CAnalyzer& rAnalyzer)
Called right after CreateAnalyzer. Selects which buffer decoder to use to process incoming buffers, creates it and attaches it to SpecTcl. The default code calls CTclGrammerApp::SelectDecoder() which in turn creates a CNSCLBufferDecoder which is suitable for decoding NSCL data buffers. If you have data from another data acquisition system, you will need to create your own CBufferDecoder derived class, instantiate it here, and hook it into the system. In order to help you do this, click for the code in CTclGrammerApp::SelectDecoder
virtual void AddCommands (CTCLInterpreter& rInterp)
Called immediately after SelectDecoder. Adds commands to the TCL interpreter. The default action is to call CTclGrammerApp::AddCommands. This call should not be removed as it registers the standard SpecTcl commands to the Tk/Tcl interpreter. You may, however extend the interpreter with commands and command packages of your own. See here for information about how to extend the interpreter with user written commands.
virtual void SetupRunControl ()
Called immediately after AddCommands. Sets up the run control system. The run control system is manipulated by the SpecTcl start and stop commands. In most cases you will not need to modify the default code. The default code calls CTclGrammerApp::SetupRunControl which sets up a run control object suitable for use in the Tc/Tk environment.
virtual void SourceFunctionalScripts (CTCLInterpreter& rInterp)
This function is called last. It provides an opportunity to source experiment specific Tcl/Tk setup scripts. The default behavior is to call CTclGrammerApp::SourceFunctionalScripts which in turn runs the SpecTclRC.tcl in the user's home and current working directories if it exists there. The attempts to run this file are enclosed in try blocks which silently catch all exceptions. If you want to source additional functional scripts, then you may add code to this function. To see how to do this; see here for a listing of CTclGrammerApp::SourceFunctionalScripts()
virtual int operator() ()
This function is the "Entry point" for the object. It is called at Tcl initialization. The default operation is to invoke CTclGrammerApp::operator() which calls the functions described on this page in the order listed. You may extend this functionality by adding code before or after this call. It is not a good idea to remove the call to CTclGrammerApp::operator() since so much of SpecTcl is set up through this function.
SpecTcl Home General Information User Guide Programmer's Guide Obtaining and Installing
Last Modified: October 28, 2003by:
fox@nscl.msu.edu
© Copyright NSCL 1999, All rights reserved