Content-type: text/html Man page of SpecTcl Application Programming Interface

SpecTcl Application Programming Interface

Section: NSCL Data analysis packages (3)
Updated: 0.1
Index Return to Main Contents

 

NAME

SpecTclApi - Fixed application programming interface to SpecTcl  

SYNOPSIS


#include <SpecTcl.h>


class SpecTcl
{
public:
  static SpecTcl* getInstance();
  UInt_t AssignParameterId();
  CParameter* AddParameter(STD(string) name, 
    UInt_t Id, 
    STD(string) Units);
  CParameter* AddParameter(STD(string) name, 
    UInt_t id, 
    UInt_t scale);
  CParameter* AddParameter(STD(string) name, 
    UInt_t id, 
    UInt_t scale, 
    Float_t low, Float_t high, 
    STD(string) units);
  CParameter* RemoveParameter(STD(string) name);
  CParameter* FindParameter(STD(string) name);
  CParameter* FindParameter(UInt_t Id);
  ParameterDictionaryIterator BeginParameters();
  ParameterDictionaryIterator EndParameters();
  UInt_t ParameterCount();
  CSpectrum* CreateSpectrum(STD(string) Name, 
     SpectrumType_t type, 
     DataType_t dataType, 
     STD(vector)<STD(string)> parameters, 
     STD(vector)<UInt_t> channels, 
     STD(vector)<Float_t>* pLows, 
     STD(vector)<Float_t>* pHighs);
  CSpectrum* Create1D(STD(string) name, 
       DataType_t dataType, 
       CParameter& parameter, 
       UInt_t channelcount);
  CSpectrum* Create1D(STD(string) name, 
       DataType_t dataType, 
       CParameter& parameter, 
       UInt_t channels, 
       Float_t lowLimit, Float_t hiLimit);
  CSpectrum* Create2D(STD(string) name, 
       DataType_t dataType, 
       CParameter& xParameter, 
       CParameter& yParameter, 
       UInt_t xChannels, UInt_t yChannels);
  CSpectrum* Create2D(STD(string) name, 
       DataType_t dataType, 
       CParameter& xParameter, CParameter& yParameter, 
       UInt_t xChannels, Float_t xLow, Float_t xHigh, 
       UInt_t yChannels, Float_t yLow, Float_t yHigh);
  CSpectrum* CreateG1D(STD(string) name, 
        DataType_t dataType,
        STD(vector)<CParameter> parameters, 
        UInt_t channels);
  CSpectrum* CreateG1D(STD(string) name, 
        DataType_t dataType, 
        STD(vector)<CParameter> parameters, 
        UInt_t channels, 
        Float_t lowLimit, 
        Float_t hiLimit);
  CSpectrum* CreateG2D(STD(string) name, 
        DataType_t dataType, 
        STD(vector)<CParameter> parameters, 
        UInt_t xChannels, UInt_t yChannels);
  CSpectrum* CreateG2D(STD(string) name, 
        DataType_t dataType, 
        STD(vector)<CParameter> parameters, 
        UInt_t xChannels, Float_t xLow, Float_t xHigh, 
        UInt_t yChannels, Float_t yLow, Float_t yHigh);
  CSpectrum* CreateBit(STD(string) name, 
        DataType_t dataType, 
        CParameter& parameter, 
        UInt_t channels);
  CSpectrum* CreateBit(STD(string) name, 
        DataType_t dataType, 
        CParameter& parameter, 
        UInt_t channels, UInt_t lowBit);
  CSpectrum* CreateSummary(STD(string) name, 
    DataType_t dataType, 
    STD(vector)<CParameter> parameters, 
    UInt_t channels);
  CSpectrum* CreateSummary(STD(string) name, 
    DataType_t dataType, 
    STD(vector)<CParameter> parameters, 
    UInt_t nChannels, Float_t low, Float_t high);
  void AddSpectrum(CSpectrum& spectrum);
  CSpectrum* RemoveSpectrum(STD(string) name);
  CSpectrum* FindSpectrum(STD(string) name);
  CSpectrum* FindSpectrum(UInt_t id);
  SpectrumDictionaryIterator SpectrumBegin();
  SpectrumDictionaryIterator SpectrumEnd();
  UInt_t SpectrumCount();
  void ClearSpectrum(STD(string) name);
  void ClearAllSpectra();
  CGate* CreateGate(CGateFactory::GateType gateType, 
     STD(vector)<STD(string)> names);
  CGate* CreateGate(CGateFactory::GateType gateType, 
     STD(vector)<STD(string)> parameters, 
     STD(vector)<FPoint> points);
  CGate* CreateGate(CGateFactory::GateType   gateType,
     STD(vector)<FPoint>      points,
     STD(vector)<STD(string)> spectra);
  CGate* CreateTrueGate();
  CGate* CreateFalseGate();
  CGate* CreateBand(STD(string) xparameter, STD(string) yparameter, 
     STD(vector)<FPoint> points);
  CGate* CreateContour(STD(string) xParameter, STD(string) yParameter, 
        STD(vector)<FPoint> points);
  CGate* CreateBandContour(STD(string) firstBand, STD(string) secondBand);
  CGate* CreateNotGate(STD(string) name);
  CGate* CreateAndGate(STD(vector)<STD(string)> gateNames);
  CGate* CreateOrGate(STD(vector)<STD(string)> gateNames);
  CGate* CreateCut(STD(string) parameter, Float_t low, Float_t high);
  CGate* CreateGammaCut(Float_t low, Float_t high, STD(vector)<STD(string)> constituents);
  CGate* CreateGammaBand(STD(vector)<FPoint> points, 
  STD(vector)<STD(string)> constituents);
  CGate* CreateGammaContour(STD(vector)<FPoint> points, 
     STD(vector)<STD(string)> constituents);
  void AddGate(STD(string) name, CGate* gate);
  void DeleteGate(STD(string) gateName);
  void ReplaceGate(STD(string) gateName, CGate& newGate);
  CGateContainer* FindGate(STD(string) gateName);
  CGateDictionaryIterator GateBegin();
  CGateDictionaryIterator GateEnd();
  UInt_t GateCount();
  void ApplyGate(STD(string) gateName, STD(string) spectrumName);
  void AddEventProcessor(CEventProcessor& eventProcessor, 
  const char* name = 0);
  CTclAnalyzer::EventProcessorIterator FindEventProcessor(STD(string) name);
  CTclAnalyzer::EventProcessorIterator FindEventProcessor(CEventProcessor& processor);
  void InsertEventProcessor(CEventProcessor& processor,
     CTclAnalyzer::EventProcessorIterator where, 
     const char*  name = 0);
  void RemoveEventProcessor(STD(string) name);
  void RemoveEventProcessor(CTclAnalyzer::EventProcessorIterator here);
  UInt_t ProcessingPipelineSize();
  CTclAnalyzer::EventProcessorIterator ProcessingPipelineBegin();
  CTclAnalyzer::EventProcessorIterator ProcessingPipelineEnd();
  void AddSpectrumFormatter(STD(string) name, CSpectrumFormatter& formatter);
  void AddEventSink(CEventSink& sink, const char* name = 0);
  CEventSinkPipeline::EventSinkIterator FindEventSink(STD(string) sinkName);
  CEventSinkPipeline::EventSinkIterator FindEventSink(CEventSink& sink);
  void InsertEventSink(CEventSink& sink, CEventSinkPipeline::EventSinkIterator here,
        const char* name = 0);
  CEventSink* RemoveEventSink(STD(string) name);
  CEventSink* RemoveEventSink(CEventSinkPipeline::EventSinkIterator here);
  UInt_t EventSinkPipelineSize();
  CEventSinkPipeline::EventSinkIterator EventSinkPipelineBegin();
  CEventSinkPipeline::EventSinkIterator EventSinkPiplineEnd();
  CTCLInterpreter*  getInterpreter();
};

 

DESCRIPTION


   The SpecTcl class provides a fixed application programming interface to the interanals of SpecTcl. Using this class ensures that your code will not require modification if the internals of SpecTcl change. The SpecTcl API is implemented as a ``singleton'' class. Singleton classes ensure that only a single instance of the class can be alive at any time. Unlike classes you may be used to using, singletons have private constructors and destructors. You get access to a singleton class by invoking its getInstance() member. This member returns a pointer to the single instance of the class, if necessary creating it on the fly.

The SpecTcl API class supports interfaces to the following subsections of SpecTcl's functionality:

Parameter Dictionary
Parameters can be created, searched for, removed and iterated through.
Spectra
Spectra of all supported types can be created. Once created they can be added to the set of spectra managed by SpecTcl. Created Spectra can be searched for, iterated through or removed. Spectra can also be cleared either individually or all spectra can be cleared at once.
Gates
All suported gate types can be created. In addition, gates can be added to the set of gates managed by SpecTcl Gates added to the set added by SpecTcl can be deleted, replaced, searched and iterated over. In addition, gates can be applied to spectra.
Event Processing Pipeline
The event processing pipeline is responsible for generating the set of parameters that SpecTcl histograms. Event processors can be dynamically added to the pipeline. Event processors can be give names which will allow you to search for specific event processors, as well as to remove them. Event processors can be inserted at any point in the pipeline. The event processing pipeline can be iterated through as well.
Event Sink Pipeline
The parameters produced by the event sink pipeline are passed to an event sink pipeline. Event sinks currently defined by SpecTcl include its histogramming engine and event filters you create. User written event sinks are also supported and this set of interfaces allows you to interact with the event sink pipeline in much the same way you can interact with the event processing pipeline.
Spectrum Formatters
Spectrum formatters are responsible for producing and reading external representations of spectra. You can add a spectrum formatter to SpecTcl making it available to the swrite and sread commands.
Tcl/Tk
You can get access to an object encapsulated Tcl/Tk interpreter. The Tcl/Tk library (Tcl++) supports an object encapsulation of Tcl/Tk. Using the functions in that library along with the interpreter you get from the SpecTcl API allows you to add commands to SpecTcl and manipulate Tcl variables.
 

SINGLETON INTERFACE

SpecTcl* getInstance()
This static function returns an instance to the SpecTcl API object. If no API object exists yet, one will be created. Once called you can invoke API functions using the object. For example, the code below adds a new parameter to SpecTcl: 

SpecTcl& api(*(SpecTcl::getInstance()));
api.AddParameter("someposition", api.AssignParameterId(), "mm");
 

PARAMETER INTERFACE

The parameter interface allows you to create parameters in the parameter dictionary. Several common argument types and return value types are used in this section of the API:

A pointer to a parameter object. Many of the functions in this section return a pointer to a parameter object.
An iterator into the parameter dictionary. Iterators are Standard Template Library constructs that act very much like pointers. Iterators can be dereferenced like a pointer, incremented and compared to other iterators. Iterators, as their name implies, are used to iterate through containers (in this case the parameter dictionary). The ParameterDictionaryIterator ``points'' to an STL pair<string, CParameter*>.
The name of a parameter. In SpecTcl, parameters must have unique names. The name of the parameter is the first element of the pair ``pointed'' to by ParameterDictionaryIterators.
The identification number of a parameter. Parameters have an id number which must be unique. The id number is the index in the event parameter array into which the parameter will be unpacked.
Parameters can have physical units. The units of a parameter are displayed by Xamine when spectra involving the parameter are displayed.
Integer parameters have a scale. The scale defines the range of values the parameter will take. Parameters with a scale value will cover the range [0, 2**scale).
Integer parameters may also have a mapping to a real coordinate space. low and high represent the range of real coordinate space covered by the integer parameter. Spectra can be displayed with either the raw channel coordinates or with channels labelled in this real coordinate space.

UInt_t AssignParameterId();
Returns an unsed parameter id. This function can be used to provide the Id parameter of many of the functions in this section.
CParameter* AddParameter(STD(string) name, UInt_t Id, STD(string) Units);
Adds a floating point parameter to the parameter dictionary. Floating point parameters are never scaled when they are histogrammed. Instead, the histogram must be defined to cover a specific range of the parameter space. name and id must be unique or the function will throw a CDictionaryException.
CParameter* AddParameter(STD(string) name, UInt_t Id, UInt_t scale);
Creates an integer parameter. The parameter is assumed to have a range of values from [0..2**scale). name and id must be unique or the function will throw a CDictionaryException.
CParameter* AddParameter(STD(string) name, UInt_t Id, UInt_t scale, Float_t low, Float_t high, STD(string) Units);
Creates a new integer parameter. The integer parameter also defines ``mapped'' parameter space. The mapped parameter space runs from [low..high). Thhe mapped parameter space also can have physical units associated with it. These units can be displayed on spectra that are created on this parameter. name and id must be unique or the function will throw a CDictionaryException.
CParameter* RemoveParameter(STD(string) name);
Removes the parameter named name from the parameter dictionary. A dynamically allocated pointer to the removed parameter is returned. It is the caller's responsibility to delete this parameter. If there is no parameter named name, a NULL pointer is returned. Note that since delete on a NULL is a no-op, the following is legal and safe: 

     SpecTcl& api(*(SpecTcl::getInstance()));
     delete api.RemoveParameter("NoIdeaIfThisExists");
CParameter* FindParameter(STD(string) name);
Locates the parameter named name in the parameter dictionary and returns a pointer to it. Note that the pointer returned is a pointer to the object in the parameter dictionary, not a copy. Any modifications you make to the parameter will be reflected in the way SpecTcl handles the parameter. If the named parameter does not exist, a NULL pointer will be returned. The code below determines the units associated with a parameter: 

     SpecTcl& api(*(SpecTcl::getInstance()));
     string units;
     CParameter* pParam = api.FindParameter("somename");
     if(pParam) {
        units = pParam->getUnits();
     } 
     else {
        cerr << "No such parameter\n";
     }
CParameter* FindParameter(UInt_t Id);
Given a parameter id, this function locates the parameter in the parameter dictionary and returns a pointer to it. If there is no parameter in the dictionary with this i, this function returns a NULL.
ParameterDictionaryIterator BeginParameters();
Returns an iterator that ``points'' to the start of the parameter dictionary.
ParameterDictionaryIterator EndParameters();
Returns an iterator that ``points'' past the end of the parameter dictionary. This iterator should never be de-referenced. The code below shows how to use BeginParameters and EndParameters to output the names of all parameters in the dictionary: 

    SpecTcl& api(*(SpecTcl::getInstance()));
    ParameterDictionaryIterator i = api.BeginParameters();
    while(i != api.EndParameters()) {
       cout << i->first << endl;            // i `points' to pair<string,CParameter*>
       i++;                                 // `point' to next dictionary entry.
    }
UInt_t ParameterCount();
Returns the number of parameters currently defined in the parameter dictionary.
 

SPECTRUM CREATION INTERFACE

This section of the API allows you to create any of the types of spectra supported by SpecTcl. See "SPECTRUM DICTIONARY INTERFACE" for information on how make spectra known to the Histogrammer, and spectrum command. Several common parameter types and return types are used by this section of the interface:

A pointer to a created spectrum object. This object is dynamically created. It is the responsibility of the caller to delete the spectrum object when the spectrum is no longer needed. Note that the spectrum -delete command deletes spectra that it removes from the spectrum dictionary.
The name to be associated with the spectrum. Note that spectrum creation does not enforce unique names, however the spectrum dictionary management API does require that spectra added to the dictionary be given unique names.
The type of spectrum being created. This can be any of the following values: ke1DfR for an ordinary 1d, ke2D, for an ordinary 2d, keBitmask, for a bit-mask spectrum, keSummary, for a summary spectrum, keG1D, for a multiply incremented (or Gamma) spectrum, or keG2D, for a multiply incremented (or Gamma) 2d spectrum.
The type of data the spectrum will hold For 1-d spectra this can be either keWord or keLong. For 2-d spectra this can be either keByte or keWord.
An STL vector of names of parameters that are needed to create the spectrum.
Vector of integers containing the number of channels on each axis that can be controlled at creation.
Pointer to a vector of axis low limits to associate with each axis that can be controlled at creation.
Pointer to a vector of axis high limits to associate with each axis that can be controlled at creation.
Number of channels in the spectrum.
The low and high limits in parameter space covered by the axis.
The parameter that the spectrum histograms.
The number of channels on the X and Y axis.
The parameters on the X and Y axes.
The parameter space covered by the x axis.
The parameter space covered by the y axis.
A vector of parameters needed to create the spectrum.
The number of the lowest bit that will appear in a bit mask spectrum.

CSpectrum* CreateSpectrum(STD(string) Name,SpectrumType_t type,
DataType_t dataType,STD(vector)<STD(string)> parameters, STD(vector)<UInt_t> channels, STD(vector)<Float_t>* pLows, STD(vector)<Float_t>* pHighs); This general spectrum creation function can create any spectrum type supported by SpecTcl. The type of spectrum created is selectec by the type parameter. The other parameters must be sufficient in number and type to support the creation of the desired spectrum or else a CSpectrumFactoryException will be thrown. A pointer to the new spectrum (dynamically created) will be returned.
CSpectrum* Create1D(STD(string) name, DataType_t dataType, CParameter& parameter, UInt_t channels);
Creates a 1D spectrum. A pointer to the new spectrum is returned. The channels parameter not only determines the number of channels on the X axis, but the range of values of parameter covered by this spectrum is defined by it as [0..channels).
CSpectrum* Create1D(STD(string) name,DataType_t dataType, CParameter& parameter, UInt_t channels,
Float_t lowLimit, Float_t hiLimit); Creates a 1D spectrum a pointer to the new spectrum is returned. The channels parameter determine how many channels will be on the X axis. These channels cover the range [lowLimit..hiLimit]. The two spectrum creations below are essentially identical: 


    SpecTcl& api(*(SpecTcl::getInstance()));
    CParameter*  pParam = api.FindParameter("someParameter");
    api.Create1D("firstone", keLong, *pParam, 1024);
    api.Create1D("secondone", keLong, *pParam, 1024, 0.0, 1023.0);
CSpectrum* Create2D(STD(string) name, DataType_t dataType,
CParameter& xParameter, CParameter& yParameter, UInt_t xChannels, UInt_t yChannels); Creates a 2-d spectrum. A pointer to the spectrum is returned. The spectrum will histogram xParameter on the X axis vs. yParameter on the Y axis. The X axis will have xChannels channels, and the Y axis yChannels. The range of the parameters covered on each axis is determined by the number of channels on that axis. For example, the X axis will cover the range [0..xChannels-1] in parameter space.
CSpectrum* Create2D(STD(string) name, DataType_t dataType,
CParameter& xParameter0, CParameter& yParameter, UInt_t xChannels, Float_t xLow, Float_t xHigh, UInt_t yChannels, Float_t yLow, Float_t yHigh); Creates a 2-d spectrum. A pointer to the new spectrum is returned. The number of channels on each axis is determined by xChannels and IyChannels. The range of parameter space covered by the X axis is [xLow..xHigh]. The range of parameter space covered by the Y axis is [yLow..yHigh].
CSpectrum* CreateG1D(STD(string) name, DataType_t dataType,
STD(vector)<CParameter> parameters, UInt_t channels); Creates a 1-d Gamma spectrum. Gamma spectra are multiply incremented spectra. For each valid parameter specified by parameters, the spectrum is incremented as described by the value of that parameter. Note that channels not only specifies the number of channesl on the X axis of the spectrum, but also specifies the range of the parameter covered by the X axis as [0..channels]fR-1].
CSpectrum* CreateG1D(STD(string) name, DataType_t dataType, STD(vector)<CParameter> parameters,
UInt_t channels, Float_t lowLimit, Float_t hiLimit); Creates a 1-d gamma spectrum. Returns a pointer to the spectrum to the caller. The X axis is defined as having channels channels that cover the range [lowLimit..hiLimit] in parameter space.
CSpectrum* CreateG2D(STD(string) name, DataType_t dataType,
STD(vector)<CParameter> parameters, UInt_t xChannels, UInt_t yChannels); Creates a 2-d gamma spectrum. For each pair of parameters described by parameters that is valid in an event, this spectrum will be incremented as described by that ordered pair. The X axis has xChannels channels that cover the range [0..xChannels-1] in parameter space. Similarly, the Y axis has yChannels covering [0..yChannels-1].
CSpectrum* CreateG2D(STD(string) name, DataType_t dataType, STD(vector)<CParameter> parameters,
UInt_t xChannels, Float_t xLow, Float_t xHigh, UInt_t yChannels, Float_t yLow, Float_t yHigh); Creates a 2-d gamma spectrum that is incremented for each ordered pair of valid parameters in parameters. The X axis is has xChannels channels that cover the range [xLow, xHigh] in parameter space, and similarly for the Y axis using yChannels, yLow, and yHigh.
CSpectrum* CreateBit(STD(string) name, DataType_t dataType, CParameter& parameter, UInt_t channels);
Creates a bit mask spectrum For each bit set in the parameter for each event, the corresponding channel is incremented for example, if the integerized parameter value is 10 (decimal), channels 1 and 3 will be incremented.
CSpectrum* CreateBit(STD(string) name, DataType_t dataType, CParameter& parameter,

 UInt_t channels, UInt_t lowBit); Creates a bitmask spectrum. lowBit determines the bit represented by channel 0. If, for example, channels is 16, and lowBit is 4, the spectrum will display the increments in bits 4 through 19 of the integerized parameter value.
CSpectrum* CreateSummary(STD(string) name, DataType_t dataType, STD(vector)<CParameter> parameters, UInt_t channels);
Creates a summary spectrum. Summary spectra allow you to look at several supposedly identical detector channels in a detector array for anomalies such as gain mis-matches or dead channels. A summary spectrum is essentially an array of 1-d spectra put into a 2-d spectrum. Each parameter gets a channel on the X axis and increments its 1-d spectrum along the y axis. This version of the function histograms the range [0..channels-1] for each parameter.
CSpectrum* CreateSummary(STD(string) name, DataType_t dataType, STD(vector)<CParameter> parameters,
UInt_t nChannels, Float_t low, Float_t high); Creates a summary spectrum. The parameter range histogrammed is determined by low and high.
 

SPECTRUM DICTIONARY INTERFACE

The spectrum dictionary interface allows you to add to and remove entries from the spectrum dictionary. You can also search and iterate through the dictionary. The following are return values and parameters that are used in this part of the API:

A pointer to a spectrum object. Note that the spectrum creation interface dynamically creates spectra. If you no longer need a spectrum you should delete it.
A reference to a spectrum.
The name of a spectrum.
The identifier of the spectrum.
An STL iterator into a spectrum dictionary. STL iterators are pointer like objects. As such they can be dereferenced, incremented and compared. The SpectrumDictionaryIterator ``points'' to an STL pair<string, CSpectrum*>


 void AddSpectrum(CSpectrum& spectrum);
Adds a spectrum to the spectrum dictionary. When a spectrum is in the Spectrum Dictionary, SpecTcl will increment it as required for each event. In addition, SpecTcl's commands will become aware of the spectrum. These commands include spectrum, channel, sbind, sread, and swrite among others. Adding a spectrum to the Spectrum dictionary does not imply that the dictionary will manage its storage, however.
CSpectrum* RemoveSpectrum(STD(string) name);
Removes the spectrum named name from the spectrum dictionary. The function returns a pointer to the spectrum that was removed or NULL if the spectrum does not exist. Since the API's spectrum creation interface dynamically allocates spectra, you will typically need to delete the spectrum at this point if you are done with it. For example assume a spectrum named george has been added to the spectrum dictionary to fully remove and destroy the spectrum: 


    SpecTcl& api(*(SpecTcl::getInstance()));
    CSpectrum* pSpectrum = api.RemoveSpectrum("george");
    delete     pSpectrum;
CSpectrum* FindSpectrum(STD(string) name);
Locates a spectrum in the spectrum dictionary and returns a pointer to it. If the spectrum does not exist, then NULL is returned. Note that since the spectrum lives in the spectrum dictionary, you must not use the pointer to destroy it. The following sample code locates the spectrum named george and determines its type, if the spectrum does not exist, the type is set to keUnknown. 


   SpecTcl&       api(*(SpecTcl::getInstance()));
   CSpectrum*     pSpectrum = api.FindSpectrum("george");
   SpectrumType_t eType;
   if(pSpectrum) {
      eType = pSpectrum->getSpectrumType();
   }
   else {
      eType = keUnknown;
   }
CSpectrum* FindSpectrum(UInt_t id);
Locates a spectrum given it's id.
SpectrumDictionaryIterator SpectrumBegin();
Returns a start of iteration iterator into the spectrum dictionary. The sample code below shows how to print out the names of each spectrum in the dictionary. Recall that a SpectrumDictionaryIterator is a pointer like object to a pair<string, CSpectrum*>, where the string is the name of the spectrum, and the CSpectrum* is a pointer to the spectrum itself. 


     SpecTcl&                   api(*(SpecTcl::getInstance()));
     SpectrumDictionaryIterator p = api.SpectrumBegin();
     while(p != api.SpectrumEnd()) {
       cerr << p->first << endl;
       p++;
     }
SpectrumDictionaryIterator SpectrumEnd();
Returns a spectrum dictionary end of iteration iterator. This iterator should never be dereferenced. It should only be used as an in the code sample above to determine when to stop iterating.
UInt_t SpectrumCount();
Returns the number of spectra that are currently in the spectrum dictionary.
 

SPECTRUM CLEAR FUNCTIONS

While each spectrumh has a clear member function, the API provides two clear convenience functions. For these:

is the name of the spectrum to clear.

void ClearSpectrum(STD(string) name);
If the spectrum name exists in the spectrum dictionary it is cleared. If the spectrum does not exist, then a CDictionaryException is thrown.

 void ClearAllSpectra();
Clears all of the spectra in the spectrum dictionary.
 

GATE CREATION

The gate creation API allows you to create any type of gate supported by SpecTcl. Once created you may either manually check a gate or you can add it to the gate dictionary where SpecTcl will automatically check it as needed. Gates added to the gate dictionary are also known to all SpecTcl gate manipulation commands such as gate and apply.

Within the gate dictionary, gates are maintained in gate containers. Gate containers allow a gate with a specific name to have a fixed handle that can be used to reference the gate. This makes it very easy to modify the definition of a gate without the effects of that modification rippling through the entire gate subsystem.

The gate creation API uses several common parameters and return types:

A pointer to a gate. The gate creationals all return this.
The type of gate being created. At present this is one of: And, band, bandcontour, contour, cut, deleted, falseg, Not, Or, trueg, gammacut, gammaband and gammacontour.
For compound gates; the names of the gates that make up this gate. The gates in the name list must have been entered in the gate dictionary.
The names of the parameters that are important to a primitive gate.
The set of points that make up a primitive gate.
The set of spectra that are important to a gamma gate.
The name of the parmeter a cut is defined on.
The name of the X parameter in a band or contour.
The name of the Y parameter in a band or contour.
The lower and upper limits of a cut.
The names of the two bands that will be used to create a contour.

CGate* CreateGate(CGateFactory::GateType gateType, STD(vector)<STD(string)> gateNames);
Creates a compound gate of the type selected by gateType. The gate will be composed of the gates named by the vector gateNames all of the gates in gateNames must have been entered in the gate dictionary either by SpecTcl or application software.

 CGate* CreateGate(CGateFactory::GateType
gateType,STD(vector)<STD(string)> parameters, STD(vector)<FPoint>points); Creates a primitive gate of the type described by gateType. The gate is defined on the set of points set on the parameters.

 CGate* CreateGate(CGateFactory::GateType gateType, STD(vector)<FPoint> points,
STD(vector)<STD(string)> spectra); Creates a gamma gate of the type described by gateType. The coordinates of the points that make up the gate are in points and the gate is defined on spectra. Note that there will be drastic changes to semantics of gamma gates work that may invalidate this interface in the near future. We apologize for this instability in the API, but believe that this change in gate semantics is necessary to meet the analysis needs of SpecTcl's user community.
CGate* CreateTrueGate();
Creates a gate that is always true when checked.
CGate* CreateFalseGate();
Creates a gate that is always false when checked.
CGate* CreateBand(STD(string) xParameter, STD(string) yParameter, STD(vector)<FPoint> points);
Creates a band gate defined on xParameter and yParameter. The points of the band are in points. A band gate is an open polyline that connects the gate points. The gate is true if the xParameter, and yParameter for an event are below the gate line. Note that the gate checking engine in SpecTcl is sufficiently intelligent to deal consistently with pathalogical bands, including those that have switchbacks and loops. For these gates, imagine that vertical lines extend downward from the end points of the gate and are joined at infinity to form a contour. Insidedness as defined for contour gates makes the band true.
CGate* CreateContour(STD(string) xParameter, STD(string) yParameter, STD(vector)<FPoint> points);
Creates a contour. Parameters have identical meanings as for CreateBand, however the points define a closed polygon. Events whose xParameter and yParameter are inside the polygon make the gate true. The gate engine for SpecTcl is sufficiently intelligent that it can deal consistently with pathalogical polygons including polygons with loops, and path crossings. Insidedness is defined by an `odd crossing' rule. A point is inside the polygon if a line extended to infinity in any direction crosses an odd number of polygon boundaries. Note that for practical purposes, the gate is checked by extending a horizontal line segment from the point to the left end of the polygon's bounding box and counting the boundary crossings of that line segment.
CGate* CreateBandContour(STD(string) firstBand, STD(string) secondBand);
Creates a band contour. A band contour is a contour that is formed by joining the leftmost and right most points of the bands firstBand and secondBand. While the resulting gate is something very much like the AND gate of firstBand with the NOT of secondBand, for clarity the gate produced is actually a contour, and evaluated as a the contour described above. This sort of gate is intended to allow users to set off particle groups in the deltaE-E plot of an Si detector (e.g.), with bands and the from those bands, produce contours around the individual particle species. Note that this implies that if one of the constituent bands is modified, the bandcontour is not modified.
CGate* CreateNotGate(STD(string) name);
Creates a gate that is true whenever the gate name is not true, and vica-versa.
CGate* CreateAndGate(STD(vector)<STD(string)> gateNames);
Creates a gate that is true only when all of the gates in the list gateNames are true.
CGate* CreateOrGate(STD(vector)<STD(string)> gateNames);
Creates a gate that is true whenever at least one gate in the list gateNames is true.
CGate* CreateCut(STD(string) parameter, Float_t low, Float_t high);
Creates a gate that is a cut on parameter. The gate is true for every event where parameter is in the range [low..high].
CGate* CreateGammaCut(Float_t low, Float_t high,STD(vector)<STD(string)> spectra);
Creates a gamma cut. Gamma cuts are applied to gamma spectra. They act as folds. For each parameter that is in the gate, the spectrum is incremented for all other parameters.

Note that the semantics of gamma gates and spectra are likely to change in the near future. We apologize for this potential instability in the API, however we feel that the changes anticipated will better serve the needs of the SpecTcl user community. For now spectra is a list of spectra on which to display this cut.

Gate* CreateGammaBand(STD(vector)<FPoint> points, STD(vector)<STD(string)> spectra);
Creates a gamma band gate. The points that define the band are in points. The spectra that this band should display on are in spectra. Gamma bands can only be applied to gamma spectra. If any pair of parameters for that spectrum are in the gamma band, the spectrum is incremented for all other parameters or parameter pairs if 2-d.

Note that the semantics of gamma gates and spectra are likely to change in the near future. We apologize for this potential instability in the API, however we feel that the changes anticipated will better serve the needs of the SpecTcl user community. For now spectra is a list of spectra on which to display this cut.

CGate* CreateGammaContour(STD(vector)<FPoint> points, STD(vector)<STD(string)> spectra);
Creates a gamma contour. Gamma contours are handled identically to gamma bands (see above.. including the warning about gate semantics), however the spectra gated is incremented when parameters are inside the contour.
 

GATE DICTIONARY API

The gate dictionary API allows you to add gates to the gate dictionary, delete gates, replace the definition of existing gates, locate the gate container that is the invariant handle to a gate and iterate through the gate dictionary. In addition, you can apply gates in the gate dicationary to a spectrum.

The gate dictionary is structured as an STL container of pair<string, CGateContainer*> entries. The string is the name of the gate, and the CGateContainer is a pointer like entity that, for all intents and purposes can be treated as a pointer to the gate. The address of the gate container will never change, even if the underlying gate is modified. This allows you to use the gate container as an invariant pointer to the gate, regardless of the gate's definition.

Common return types and parameters to this section include:

A pointer to a gate.
The name of a gate.
A reference to a gate.
A pointer to a gate container. The gate container can be used as if it were a pointer to the underlying gate. It will remain valid even if the underlying gate is moedified. Note that when a gate is deleted, its gate container will point to a False gate.
A gate iterator is a pointer like object that can be dereferenced, incremented and compared to other CGate DictionaryIterators. When dereferenced, the gate iterator `points' to the dictionary entry for a gate which is a pair<string, CGateContainer*>.

void AddGate(STD(string) name, CGate* gate);
Adds a gate to the gate dictionary. The gate will be given the name as its name. Gate names must be unique, therefore a CDictionaryException is thrown if you attempt to create a gate with a name that is already in the dictionary. Once added, gates will be checked by SpecTcl for each event as needed. In addition, gates in the gate dictionary will be visible to SpecTcl's gate commands such as gate, and apply. SpecTcl will ensure that gates that are in the dictionary are displayed on ``appropriate'' spectra.
void DeleteGate(STD(string) gateName);
Deletes the gate named gateName. If the gate does not exist, a CDictionaryException is thrown.
void ReplaceGate(STD(string) gateName, CGate& newGate);
The definition of the gate gateName is replaced by that of newGate. Since internally all SpecTcl gate references are through gate containers, this change is immediately visible. If the gate gateName does not exist, a CDictionaryException is thrown.
CGateContainer* FindGate(STD(string) gateName);
Locates the gate container that is the invariant pointer to the gate gateName. A pointer to the gate container is returned. Note that if the gate does not exist, a CDictionaryException is thrown. The following sample code shows how this can be used to get the current type of the gate named george. 


    SpecTcl& api(*(SpecTcl::getInstance()));
    try {
        CGateContainer& pGate(*(FindGate("george")));
        cerr << "The gate george is of type: " << pGate->Type() << endl;
    }
    catch (CDictionaryException& e) {
      cerr << "The gate george does not exist\n";
    }
CGateDictionaryIterator GateBegin();
Returns a start of iteration iterator. This can be used to loop over the set of gates in the gate dictionary. The sample code below shows how to list out the names of all the gates: 


    SpecTcl& api(*(SpecTcl::getInstance()));
    CGateDictionaryIterator i = api.GateBegin();
    while (i !+ api.GateEnd()) {
      cerr << i->first << endl;
    }
CGateDictionaryIterator GateEnd();
Returns an end of iteration iterator to the gate dictionary.
UInt_t GateCount();
Returns the number of gates in the gate dictionary.
void ApplyGate(STD(string) gateName, STD(string) spectrumName);
Applies a the gate gateName to the spectrum spectrumName if either the gate or the spectrum don't exist, a CDictionaryException will be thrown. The effect of applying the gate is immediate. Note as well that the gate is applied via a gate container. Therefore subsequent changes in the gate definition will be immediately reflected in the way the spectrum is incremented.
 

EVENT PROCESSOR PIPELINE INTERFACE

For SpecTcl to work correctly it must have user written code that transforms raw events into unpacked events (called parameters or parameter arrays or CEvent's). In order to support good, modular programming practices, SpecTcl allows the programmer to split up this transformation into sequential stages. This set of sequentially called transformations is called the Event processing pipeline. The programmer can build up the event processing pipeline by inserting Event processors into the pipeline in the order in which he/she wants them run. Almost any non-trivial analysis problem is typically broken down into manageable steps through this mechanism. This mechanism is also used to ``bolt'' several detector systems together into an experiment, allowing the software development for each detector system to be done indepedently of the other groups. At the NSCL, event data are structured into 'labelled' packets with a leading size. This allows event processors to easily ignore packets they do not understand while processing those they do.

The event processor pipeline interface allows you to append event processors into the pipeline or insert them prior to any existing element. As of SpecTcl 3.0, Event processors can be given names, and searched for within the pipeline by the names they were assigned. For compatibility with prior versions of SpecTcl, unnamed event processors are supported (they are assigned a unique hard to guess name). Event processors can be dyamically removed from the pipeline. For example, if you want to analyze filtered data, you will want to remove all of the event processing pipeline elements that decode the raw event data as the filter processor should be used to replace those. You can also iterate through the event processing pipeline.

The event processor pipeline interface uses several common return types and parameters described below:


 A reference to an event processor you have created.
The name of an event processor in situations where the event processor name is optional.
The name of an event processor in situations where the event processor name is mandatory.
An iterator into the event processor pipeline. Iterators into the event processor pipeline are pointer like objects that can be dereferenced, incremented, and compared to other CTclAnalyzer::EventProcessorIterator objects. When dereferenced, they will obtain a pair<string, CEventProcessor*> where the string is the name of the event processor and the CEventProcessor* is a pointer to the event processor itself.

void AddEventProcessor(CEventProcessor& eventProcessor, const char* name = 0);
Appends an event processor to the end of the event processor pipeline. This will cause the event processor's OnAttach member to be called, notifying it of the addition to the event pipeline. If the name parameter is omitted, a unique non-obvious name is assigned.
CTclAnalyzer::EventProcessorIterator FindEventProcessor(STD(string) sname);
Returns an iterator to the event processor named sname. If the event processor does not exist, the iterator returned is an end of iteration iterator (compares as equal to ProcessingPipelineEnd()). Recall that the iterator will `point' to a pair<string, CEventProcessor*> where the string is the name associated with the event processor. Suppose you have registered an event processor named george, of type GeorgeEventProcessor. If this event processor has a member named prod, you can located george and call prod as follows: 


    SpecTcl&  api(*(SpecTcl::getInstance()));
    CTclAnalyzer::EventProcessorIterator p = api.FindEventProcessor("george");
    if(p != api.ProcessingPipelineEnd()) {                // "george" was found.
      try {
         GeorgeEventProcessor* pProc =
                           dynamic_cast<GeorgeEventProcessor*>(p->second);
         // The dynamic cast will throw if "george" is of the wrong type.
    
         pProc->prod();                 // Prod the event processor.

      }
      catch(...) {                      // not of type GeorgeEventProcessor
        cerr << "george is not the right type of event processor\n";
      }
    }
CTclAnalyzer::EventProcessorIterator FindEventProcessor(CEventProcessor& eventProcessor);
Given a reference to an event processor (eventProcessor) you have entered into the event processing pipeline, this function returns an iterator that points to the pair<string, CEventProcessor*> such that the event processor pointer points to that event processor. If the event processor is not in the event processor pipeline, the end of iteration iterator (ProcessingPipelineEnd()) is returned. Given that you have an event processor object george in the event pipeline, the code below lists the names of the event processors that follow it in the pipeline: 


     SpecTcl& api(*(SpecTcl::getInstance()));
     CTclAnalyzer::EventProcessorIterator p = api.FindEventProcessor(george);
     if (p != api.ProcessingPipelineEnd()) {
        cerr << "My processor is named: " << p->first << endl;
        cerr << "It is followed by: \n";
        p++;
        while (p != api.ProcessingPipelineEnd()) {
            cerr << p->first << endl;
        }
     }
void InsertEventProcessor(CEventProcessor& eventProcessor,CTclAnalyzer::EventProcessorIterator where,
const char* sname = 0); Inserts a new event processor in the pipeline prior to the position of the event processor indicated by the iterator. The following code is equivalent to AddEventProcessor: 


     SpecTcl& api(*(SpecTcl::getInstance()));
     api.InsertEventProcessor(george, api.ProcessingPipelineEnd(), "george");
void RemoveEventProcessor(STD(string) sname);
Removes the event processor named sname. If the event processor does not exist, this is a no-op at this time. In the future, we reserve the right to throw a CDictionaryException.
void RemoveEventProcessor(CTclAnalyzer::EventProcessorIterator here);
Removes the event processor `pointed' to by the iterator here.
UInt_t ProcessingPipelineSize();
Returns the number of elements in the event processing pipeline.
CTclAnalyzer::EventProcessorIterator ProcessingPipelineBegin();
Returns a start of iteration iterator to the event processing pipeline.
CTclAnalyzer::EventProcessorIterator ProcessingPipelineEnd();
Returns an end of iteration iterator to the event processing pipeline.
 

EVENT SINK PIPELINE API

Once the event processing pipeline has created a parameter array (CEvent), bunches of these are grouped into a CEventList object and passed to a pipeline of event sinks. Event sinks are expected to do analysis on the unpacked CEvent objects in the CEventList. At present, SpecTcl has two predefined types of event sinks: CHistogrammer which increments histograms depending on the gate and histogram definitions it has been given, and CFilter which produce filtered data sets. You can produce your own application specific event sinks and add them to the event sink pipeline if you have a need to do so.

The API into the event sink pipeline supplies the same functionality as that of the API for the Event Processing pipeline. See EVENT PROCESSOR PIPELINE INTERFACE for a summary of that interface. The functions in this interface, all make use of a common set of return types and parameters. These are described below:

A reference to an evernt sink.
An optional name to give an event sink in the pipeline. If none is given, the subsystem creates a unique unobvious name.
A mandatory name of an event sink (e.g. as in the searching functions).
An iterator to the event sink pipeline. Iterators are pointer like objects that can be derefrenced, incremented and compared to each other. Iterators to elements of the event sink pipeline `point' to STL pair<string, CEventSink*> objects. The string is the name of the sink while the CEventSink* is a pointer to the event sink at that stage of the pipeline.
A pointer to an event sink.

void AddEventSink(CEventSink& sink, const char* name = 0);
Appends an event sink to the event sink pipeline. Once appended, the event sink's OnAttach member is called.
CEventSinkPipeline::EventSinkIterator FindEventSink(STD(string) sinkName);
Locates the iterator that corresponds to the event sink sinkName. If the sink is not found, an end of iteration iterator is returned.
CEventSinkPipeline::EventSinkIterator FindEventSink(CEventSink& sink);
Locates and returns the event sink specified in the event sink pipeline and returns an iterator to it. If the sink is not in the event sink pipeline, an end of iteration iterator is returned. The code example below shows how to let the system choose a name for an event sink and then determine what name was assigned: 


    SpecTcl& api(*(SpecTcl::getInstance()));
    api.AddEventSink(somesink);               // System chooses the name.
    CEventSinkPipeline::EventSinkIterator p = api.FindEventSink(somesink);
    string sinkName = p->first;
void InsertEventSink(CEventSink& sink, CEventSinkPipeline::EventSinkIterator here,
const char* name = 0); Inserts a new event sink prior to the sink specified by here. The code below is equivalent to call to AddEventSink. 


    SpecTcl& api(*(SpecTcl::getInstance()));
    api.InsertEventSink(somesink, api.EventSinkPipelineEnd(), "somesink");

 CEventSink* RemoveEventSink(STD(string) name);
Removes the sink name from the event sink pipeline and returns a pointer to it. If the sink does not exist, a NULL pointer is returned. The OnDetach member of the sink is called to notify it that it is being detached from the pipeline.
CEventSink* RemoveEventSink(CEventSinkPipeline::EventSinkIterator here);
Removes the event sink `pointed' to by the iterator here from the event sink pipeline and returns a pointer to the sink itself. The OnDetach member function of the sink is called to notify it that it is being detached from the pipeline

 UInt_t EventSinkPipelineSize();
Returns the number of elements int he event sink pipeline.
CEventSinkPipeline::EventSinkIterator EventSinkPipelineBegin();
Returns a beginning of iteration iterator for the event sink pipeline.
CEventSinkPipeline::EventSinkIterator EventSinkPiplineEnd();
Returns an end of iteration iterator for the event sink pipelne. The sample below shows how to use this function to list the names of the event sinks in the pipeline: 


    SpecTcl& api(*(SpecTcl::getInstance()));
    CEventSinkPipeline::EventSinkIterator p = api.EventSinkPipelineBegin();
    while (p != api.EventSinkPipelineEnd()) {
      cerr << p->first << endl;
    }
 

MISCELLANEOUS


  This section describes API member functions that don't fit nicely into any of the function groups described above.

void AddSpectrumFormatter(STD(string) name, CSpectrumFormatter& formatter);
SpecTcl's sread and swrite commands accept a swtich (-format) that specifies the format of the spectrum file that is being read or written. The set of formats recognized by these commands is extensible. SpecTcl's mechanism for extending this set of formats is to register a set of named spectrum formatters. Each formatter is capable of reading and writing single spectra from or to a C++ input or output stream. AddSpectrumFormatter is an API function that allows you to register your own spectrum formatters with SpecTcl. Once registered, the sread and swrite commands will understand the formatter and add it to the usage string for their commands.
CTCLInterpreter* getInterpreter();
Returns the object encapsualted Tcl/Tk interpreter being used to process SpecTcl commands.

 

Index

NAME
SYNOPSIS
DESCRIPTION
SINGLETON INTERFACE
PARAMETER INTERFACE
SPECTRUM CREATION INTERFACE
SPECTRUM DICTIONARY INTERFACE
SPECTRUM CLEAR FUNCTIONS
GATE CREATION
GATE DICTIONARY API
EVENT PROCESSOR PIPELINE INTERFACE
EVENT SINK PIPELINE API
MISCELLANEOUS
This document was created by man2html, using the manual pages.
Time: 13:58:24 GMT, March 17, 2005