Accessing Spectra from SpecTcl Event Processors

This application note describes how to access spectra from enent processors in SpecTcl 2.2 and earlier. SpecTcl 3.0 will have a formal API to the SpecTcl internals. I anticipate maintaining the informal interface documented in this application note for at least a year following the release of 3.0 to allow users to migrate to the formal API.

This application note documents this procedure by walking through a sample event processor. The sample event processor uses the informal interface to SpecTcl's internals to maintain a histogram of the size of events. It does this manually rather than creating an event size parameter.

Background Information

To extend this example, you will need to become familiar with a few SpecTcl header files and the global storage that links the SpecTcl library together into the SpecTcl program. This section:

• Describes the global storage area and its header.
• Describes the headers you should become familiar with.

Global Storage

The global storage area is defined in the header Globals.h. The relevant storage for this discussion is a pointer to SpecTcl's histogramming engine. We will need to create a spectrum and make it known to the histogramming engine, as the histogramming engine also:

• Manages bindings with the displayer (Xamine)
• Contains the dictionary that the spectrum listing and manipulation commands use to locate spectra.

SpecTcl's event processing model is a pipeline. Each stage of the pipeline may contain other internal pipelines as well. The overall pipeline consists of the following elements:

• A data source (selected with the attach command).
• An analyzer that generates parameter sets for each event (this is a pipeline, containing your event processors as pipeline elements).
• An event sink. This is a pipeline as well that contains the Histogramming engine and any filters that have been defined.

The global storage area contains the following:

there are other variables defined in Globals.h however these are either not yet used or not useful to the application. For this application, we will only need the gpEventSink.

Relevant Headers

The following headers will be relevant.

• Parameter.h - Defines the CParameter class.
• Spectrum.h - Defines the generic interface to a spectrum.
• Spectrum1DL.h - Defines the specific interface to 1-d longword spectra.
• SpectrumFactory.h - Defines an object that can create spectra for you.
• Histogrammer.h - Defines the interfaces to the histogramming engine.

The example

We will describe in turn the following:

• The header for a SampleProcessor class that will create and manipulate a spectrum. The spectrum will be made known to the rest of SpecTcl and displayable just like any other spectrum.
• The include files required by the implementation of the SampleProcessor.
• The implementation of the constructor and the OnAttach function of the Sample Processor.
• The implementation of the OnBegin function of SampleProcessor. This implementation assumes that all event files have some begin run record. Slight modifications will be needed if you are using an event file format that may not have a begin record.
• The implementation of the SampleProcessor::operator() which actually manipulates the histogram.

Our strategy will be as follows:

• OnAttach will create a histogram. It will not store any references to this histogram for several reasons:
  • We want to also demonstrate how to locate existing histograms.
  • Histograms, once created could be destroyed and re-made by users. as SpecTcl runs. Therefore:
• OnBegin will attempt to locate our histogram and ensure that it is of the type expected by operator(). If it is, it will save a pointer to the histogram object in the object member data.
• operator() will ensure the histogram is still the right type and, if so, increment it.

SampleProcessor's header

The key parts of the header for SampleProcessor is shown below:

 #ifndef __SAMPLEPROCESSOR_H
 #define __SAMPLEPROCESSOR_H
 // Headers requried by this header:  

 #ifndef __EVENTPROCESSOR_H
 #include <EventProcessor.h>
 #endif

 #ifndef __HISTOTYPES_H
 #include <histotypes.h>
 #endif

 #ifndef __STL_STRING
 #include <string>
 #ifndef __STL_STRING
 #define __STL_STRING
 #endif
 #endif

 // Foward definitions:

 class CSpectrum;		// Need a spectrum in our event processro
                                // event processor.

 // These types are passed by reference to the event pipeline callout functions.

 class CAnalyzer;
 class CBufferDecoder;
 class CEvent;

 class SampleProcessor : public CEventProcessor {
 private:
  std::string   m_SpectrumName;  //!< The name of the spectrum we will create.
  CSpectrum*    m_pSpectrum;	 //!< Filled in by OnBegin.

 public:
  //! Constructor: parameterized by spectrum name.

 #ifdef HAVE_STD_NAMESPACE
  SampleProcessor(std::string SpectrumName);
 #else
  SampleProcessor(string SpectrumName);
 #endif

  // The following override the base class event pipeline callout functions.

  virtual Bool_t OnAttach(CAnalyzer& rAnalyzer); //!< Called when we join the pipeline.
  virtual Bool_t OnBegin(CAnalyzer&      rAnalyzer,
			 CBufferDecoder& rDecoder); //!< Called on begin of run.
  virtual Bool_t operator()(const Address_t    pEvent,
			    CEvent&            rEvent,
			    CAnalyzer&         rAnalyzer,
			    CBufferDecoder&    rDecoder); //!< Called each event.

 };

 #endif // include gaurd.

Note the use of forward references to minimize the include file needs of this header. The header only defines the class interfaces and their visibility.

SampleProcessor constructor and OnAttach

The constructor will only initialize storage. The constructor does not know when in the lifetime of SpecTcl it is being invoked. It is therefore dangerous for it to attempt to create Spectra as SpecTcl's data structures for maintaining spectra may not yet be fully initialized:

// Headers required

 #include <config.h>		// This is required for SpecTcl 3.0 and later!!
 #include "SampleProcessor.h"
 #include <Analyzer.h>
 #include <TCLAnalyzer.h>
 #include <BufferDecoder.h>
 #include <Event.h>
 #include <Histogrammer.h>
 #include <Spectrum1DL.h>	// pulls in Spectrum.h
 #include <Parameter.h>
 #include <SpectrumFactory.h>

 #include <Globals.h>		// This will change with the invention of the 3.0 API

 #include <iostream>

 // This is useful and handy for compilers that hide e.g. string in the std
 // namespace:

 #ifdef HAVE_STD_NAMESPACE
 using namespace std;
 #endif

 /*!
   Construct a SampleProcessor.
   The only thing we are going to do is initialize the member data:
   - m_SpectrumName   - the name the user passes in.
   - m_pSpectrum      - to null.
 */
 SampleProcessor::SampleProcessor(string SpectrumName) :
  m_SpectrumName(SpectrumName),
  m_pSpectrum(0)
 {
  
 }

The constructor saves the name of the spectrum we will create and initializes the pointer to the spectrum object to null so that the remainder of the class knows the spectrum has not yet been located.

When we are attached to the event processor (this happens only once), we will create a 1-d spectrum with 1024 channesl We'll generate a parameter to do this as well, and give it an id of 10000. The parameter will not be made known to SpecTcl as it won't reall be used.

   
 Bool_t 
 SampleProcessor::OnAttach(CAnalyzer& rAnalyzer)
 {
  // The code below will need to change as the 3.0 API gets implemented:

  CHistogrammer* pHistogrammer = static_cast<CHistogrammer*>(gpEventSink);

  // There's a factory of spectra we can use to create a spectrum and
  // assign it to a unique id.  Note that the CParameter constructor
  // will create a parameter named "Undefined" and give it the id
  // 10000.   We won't register this parameter with the histgoramming
  // engine so that we don't have to worry about duplication.

  CSpectrumFactory fact;
  CSpectrum* pSpectrum = fact.Create1D(m_SpectrumName,
				       keLong, 
				       CParameter("Deleted", 10000, ""),
				       1024);

  // If the spectrum already exists we just yell at stderr.
  // We find out about this because AddSpectrum will
  // throw an exception.

  try {
    pHistogrammer->AddSpectrum(*pSpectrum);
  }
  catch(...) {
    cerr << "Unable to add spectrum " << m_SpectrumName 
	 << " most likely this spectrum already exists\n";
  }
  return kfTRUE;
  
  
 }

Some notes:

• The mechanism to obtain a pointer to the histogram will be deprecated with SpecTcl 3.0
• CSpectrumFactory is a class that understands how to create spectra. we're asking it to create a spectrum of longs that has 1024 channels. and is incremented on a parameter named "Deleted" that we will never set.
• CHistogrammer::AddSpectrum registers a spectrum with the histogramming engine. If a spectrum already exists with this name, it will throw an exception. We turn this exception into an error mesage and continue processing.
• The spectrum is not saved. A significant amount of stuff could happen between the time we are attached to the event processing pipeline and the first data is analyzed.

The SampleProcessor OnBegin function

At the beginnig of the run, we locate the spectrum and save it in m_pSpectrum. We're only going to save it if:

• The spectrum exists.
• The spectrum is a 1d spectrum. We don't care if it's 1-d long or 1-d word as the event processor will use interfaces that take care of that for us.

   If we are not able to find a suitable match we complain at stderr.

 Bool_t
 SampleProcessor::OnBegin(CAnalyzer&      rAnalyzer,
	 		  CBufferDecoder& rDecoder)
 { 
  // This code needs to change as the 3.0 API gets published.

  CHistogrammer* pHistogrammer = static_cast<CHistogrammer*>(gpEventSink);

  // Locate the spectrum in the histogrammer:

  CSpectrum* pSpectrum = pHistogrammer->FindSpectrum(m_SpectrumName);
  if(pSpectrum) {
    if(pSpectrum->getSpectrumType() == ke1D) {
      m_pSpectrum = pSpectrum;
    } else {			// Not 1d
      cerr << "Found " << m_SpectrumName << " but it's not 1-d\n";
      m_pSpectrum = (CSpectrum*)kpNULL;
    }
  }
  else {			// No such spectrum...
    cerr << "No such spectrum " << m_SpectrumName << endl;
    m_pSpectrum = (CSpectrum*)kpNULL;
  }
  return kfTRUE;
 }

Notes:

• CHistogrammer::FindSpectrum locates a spectrum by name. This operation is expensive (log2(n) n - number of spectra). We therefore only want to look up the spectrum once. Unfortunately we must trust the user not to delete the spectrum while the run is in progress.
• CHistogrammer::FindSpectrum returns a null if the named histogram does not exist.
• CSpectrum::getSpectrumType() returns the type of spectrum. These spectrum types are defined in the header histotypes.h
• If we found the spectrum and it's suitable, we store a pointer to it in the member data m_pSpectrum.

The SampleProcessor::operator() function

We're just going to manually increment the histogram in a way that shows both how to get and set channels. The nasty thing to remember here is that indices are arrays of indexes. This was the only way to standardize the interface to a histogram regardless of histogram type. Another nasty is that the operator[] is a 'readonly' operator. This has to do with the fact that the underlying histogram can be any of several data types.

• We'll double check that the histogram is defined/
• We'll double check that the histogram is stil 1-d.
• We'll make sure the word count fits in the spectrum.
• We'll make the histogram histogrm the event size.
• For simplicity we will not be byte order clean.

 
 Bool_t
 SampleProcessor::operator()(const Address_t    pEvent,
			    CEvent&            rEvent,
			    CAnalyzer&         rAnalyzer,
			    CBufferDecoder&    rDecoder)
 {

  UShort_t* p = static_cast<UShort_t*>(pEvent);
  UInt_t  nWords = (ULong_t)*p;
  CTclAnalyzer& rA((CTclAnalyzer&)rAnalyzer);
  rA.SetEventSize(nWords*sizeof(UShort_t));

  // Ensure the spectrum exists and is 1-d:

  if(m_pSpectrum) {
    if(m_pSpectrum->getSpectrumType() == ke1D) {
      if(nWords < m_pSpectrum->Dimension(0)) { // Check against X dimension

	// Note that indexing is a readonly operation due to 'typeness'

	ULong_t newValue = (*m_pSpectrum)[&nWords] + 1;
	m_pSpectrum->set(&nWords, newValue);
      }
    }
  }
  return kfTRUE;
 }

Notes:

• The first section of this function is boilerplate that you'll find in most event processors. For simplicity, we're not createing a TranslatorBufferPointer. You should as that will isolate your analysis from differences in byte ordering between the data taking an data analysis system.
• CSpectrum::Dimension Returns the nubmer of channels in the dimension selected by its parameter. You can use CSpectrum::Dimensionality to determine how many dimensions the spectrum has.
• The CSpectrum::operator[] takes an array of indices and returns the value (as an unsigned long) fo the channel at those coordinates.
• CSpectrum::set sets the value of a channel given a list of indices that are the coordinates of the channel and the new value for the channel.