Subsections

• 6.1 Using the calibration objects
  • 6.1.1 Gains
  • 6.1.2 Pedestals
  • 6.1.3 HLRatios
  • 6.1.4 LCTofs and WalkTofs
• 6.2 Building the calibration objects
  • 6.2.1 Overview
  • 6.2.2 Gains
  • 6.2.3 Pedestals
  • 6.2.4 HLRatios
  • 6.2.5 LCTofs and WalkTofs

   
6. Calibration objects

In this section we describe the different calibration data objects that are used by the Calibrator, and that you can store/retrieve from the DB.

If you have read the preceding sections (and you'd better read them!), you know that we are dealing with different calibration flavours : Gains, Pedestals, HLRatios, LCTofs, WalkTofs. We also use time-zero calibrations, but those are treated in a different way so far, so we won't discuss them here.

All the flavours have a number of common points, which lead us to define some base classes, and derive from them to implement the specifics of each flavour. This is illustrated in the class diagram (figure 5).

  

Figure 5: Class diagram for calibration data classes

[IMAGE ]

What you can store/retrieve to/from the DB (using the DataManager) are subclasses of emcFEMtuple class (which is itself a subclass of the generic emcManageable class). Notice that the emcGains class we used in example of section 5 is indeed such a subclass.

   
6.1 Using the calibration objects

Let's assume you already have at hand an emcFEMtuple object, named femtuple. Regardless of its actual type (emcGains, emcPedestals, etc...), you can apply the following methods :

// How many channels handled by femtuple ?
int n = femtuple.GetNumberOfChannels() ;
// How many FEMs handled by femtuple ?
int nfem = femtuple.GetNumberOfFEMs() ;
// AMU post-pre value for a given fem
int ifem = 2 ; // should be between 0 and nfem-1
int pp = femtuple.Get_post_pre(ifem) ;
int tp = femtuple.Get_tac_pre(ifem) ;
// Tells if femtuple is valid at time when
PHTimeStamp when ;
bool valid = femtuple.IsValid(when) ;
// Print
femtuple.Print(1) ;

// Get a pointer to a given FEM
emcCalFEM* fem = femtuple.GetFEM(ifem) ;

The last line gives access to a given calibration FEM. Again, regardless of its type (emcGainFEM, emcPedestalFEM, etc...), you can :

// Get the absolute position
int ap = fem->GetAbsPosition() ;
// Get the pin number
int pin = fem->GetPinNumber() ;
// Get the amu post-pre and tac-pre
int pp = fem->Get_post_pre() ;
int tp = fem->Get_tac_pre() ;
// Get the validity period
PHTimeStamp start,end ;
start = fem->GetStartValTime() ;
end = fem->GetEndValTime() ;
// Tells if fem is valid at time when
PHTimeStamp when ;
bool valid = fem->IsValid(when) ;

OK. Let's now turn to the real use of those objects, namely getting the calibration values for individual channels. The emcFEMtuple has a number of getValue methods for that very purpose :

/// get value method for time-independant objects
float getValue(int ichannel) const { return -9999.9 ; }

/// get value method for time-dependant objects
float getValue(int ichannel, int thetime) const { return -9999.9 ; }

/// get value method with a kind (e.g. for pedestals)
float getValue(int ichannel, int amucell, 
               const char* kind) const { return -9999.9 ; }

Those methods in fact only call the corresponding getValue of the relevant emcCalFEM subclass (depending on the flavour), after proper marshalling of the ichannel parameter (which is running from 0 to the total number of channels in a femtuple, and -usually- from 0 to 143 in a calfem).

The first method is used for time-independent objects, as HLRatios, LCTofs and WalkTofs. The second one is used for time-dependant objects, as Gains ; the time parameter is an incremental time (zero=start-of-validity period of the object). The last one is a special case used for pedestals, where you must provide the amu (post) value and the pedestals type (LG_Pre-Post, HG_Pre-Post, TAC) you wish to access.

   
6.1.1 Gains

emcGainFEM is by far the most complicated one among all the emcCalFEM sub-classes. For each channel, what is stored is a list of emcTracedValue, i.e. a list of line pieces (3 parameters=1 start time t0, 1 slope and 1 constant). Each piece of line is valid during a given time. When you request the gain value for a given channel at a given incremental time t, four cases have to be considered (figure 6) :

  

Figure 6: emcTracedValues = what is stored for Gains.

1.

t is below the time of the first TracedValue. The value returned is then the constant of the first line.

2.

t falls within one of the TracedValue. The value returned is computed by this TracedValue (=constant+ [IMAGE ]slope)

3.

t falls after the last TracedValue, but before a parameter (common to all channels in this FEM) called last_valid_time. The parameters of this last TracedValue are used to extrapolate until t

4.

t is after last_valid_time : the value returned is the one returned by the last TracedValue, at time t=last_valid_time.

NOTE: as there might be several TracedValues per channel, the Gains banks might have more than 144 items (see section 5).

Storage organization of emcGainFEM object is depicted in figure 7, together with its relation to the Gains bank organization.

  

Figure 7: emcGainFEM object and its corresponding Objy bank

You can loop over all the TracedValue using an iterator-like procedure :

// Get a filled gain fem from a femtuple (e.g.)
emcGainFEM* gainfem = dynamic_cast<emcGainFEM*>(femtuple.GetFEM(0)) ;
int i ;
emcTracedValue* val ;
for ( i = 0 ; i < gainfem->GetNumberOfChannels() ; i++ ) {
  gainfem->FirstItem(i) ;
  while ( val = gainfem->NextItem() ) {
    cout << (*val) << endl ;
  }
}

6.1.2 Pedestals

Each channel has 3 types of pedestals : HG_Pre-Post, LG_Pre-Post and TAC. For each type, there are 64 integer values (one per AMU (post) cell) (figure 8). Thus emcPedestalFEM objects are the ``fatter'' calibration objects we deal with.

  

Figure 8: emcPedestalFEM calibration object

Access to actual value is done the following way :

// Get a filled pedestal object from a femtuple (e.g.)
emcPedestalFEM* pedfem = dynamic_cast<emcPedestalFEM*>(femtuple.GetFEM(0));
int ichannel=12;
int amupost=2;
int low = pedfem->getValue(ichannel,amupost,''LG_Pre-Post'') ;
int high = pedfem->getValue(ichannel,amupost,''HG_Pre-Post'') ;
int tac = pedfem->getValue(ichannel,amupost,''TAC'') ;

6.1.3 HLRatios

In principle, there should be only one High-to-Low gain ratio for each channel. But we keep four values for each channel : an average value (which is what we are returning with the getValue method so far), a rms value, and two parameters from a linear fit : a slope and an intercept (figure 9).

  

Figure 9: emcHLRatioFEM calibration object

Note: It seems that the fitted value could be always better than the global average, in which case we would use the fitted value in getValue method [to be checked].

To access to actual values, use :

emcHLRatioFEM* hlrfem = .... ;
float av = hlrfem->GetAverage() ;
float rms = hlrfem->GetRMS() ;
float slope = hlrfem->GetSlope() ;
float inter = hlrfem->GetIntercept() ;
float globalAverage = hlrfem->GetGlobalAverage() ;
float globalRMS = hlrfem->GetGlobalFEM() ;

6.1.4 LCTofs and WalkTofs

The 2 classes emcLCTofFEM and emcWalkTofFEM are (so far) strictly identical (indeed, the second derives from the first). For each channel, two floating point values are kept. You can access them using GetValue1,2(int ichannel) methods.

   
6.2 Building the calibration objects

OK. If you have survived the reading up to this point, it means you really need those damned calibration objects ! Found a bug somewhere in a plugin and want to fix it ? Want to build you own objects ? Want to write you own plugin ? Fine. Here we go...

6.2.1 Overview

Remember that what you are trying to build are some sub-class of emcFEMtuple class. You start from an empty one, and you a) add some emcCalFEM to it b) fill the emcCalFEM objects you've added. For both type of objects, there are factories available that may be of some help (figure 5).

// Create an empty femtuple of flavour Gains
emcFEMtuple* tuple = emcFEMtupleFactory::Create(``Gains'') ;
// You could also write :
// emcGains* tuple = new emcGains ;
// Append one CalFEM to it and convert it to emcGainFEM type
emcGainFEM* fem = dynamic_cast<emcGainFEM*>(
  tuple->AppendFEM(absPosition,pinNumber,post_pre,tac_pre,begin,end)) ;
// Fill the fem object (see below)
...

The actual way of filling the fem object depends on the flavour (see below).

You might also want to selectively replace 1 FEM among all those stored in an emcFEMtuple object (e.g. the one which reach its end-of-validity time). Use the emcFEMtuple::ReplaceFEM(int ifem, emcFEMtuple&) method for that purpose (see section 7 for example).

6.2.2 Gains

emcGainFEM objects are filled with emcTracedValue objects. For a number of reasons (one being to stick to some internal conventions), you should put 144 channels into it.

int j ; // channel number (0..143)
for ( j = 0 ; j < 144 ; j++) {
  time = ... ;
  constant = ... ;
  slope = ... ;
  fem->AddNewItem(j,new emcTracedValue(time,constant,slope)) ;
}
fem->SetLastValidTime(last_valid_incremental_time) ;

Note the use of the SetLastValidTime method which spans the whole FEM (see section 6.1.1). In the above example we put only one TracedValue per channel. You are free to put more per channel, e.g. :

int j ;
for ( j = 0 ; j < 144 ; j++) {
  int i ;
  for ( i = 0 ; i < j ; i++ ) {
    time = ... ;
    constant = ... ;
    slope = ... ;
    fem->AddNewItem(j,new emcTracedValue(time,constant,slope)) ;
  }
}
fem->SetLastValidTime(last_valid_incremental_time) ;

6.2.3 Pedestals

For pedestals, you must feed the object with 3 pedestals types. For each type 64 values per channel must be given.

int j ; // channel number (0..143)
for ( j = 0 ; j < 144 ; j++ ) {
  emcPedestalFEM::AmuVector vlow,vhigh,vtac ;
  int amu;
  for ( amu = 0 ; amu < 64 ; amu++ ) {
    vlow.push_back(some_ped_low_value) ;
    vhigh.push_back(some_ped_high_value) ;
    vtac.push_back(some_ped_tac_value) ;
  }
  // it's important to group the following lines (as it's an
  // append for the same channel).
  fem->AppendOneChannel("LG_Pre-Post",vlow) ;
  fem->AppendOneChannel("HG_Pre-Post",vhigh) ;
  fem->AppendOneChannel("TAC",vtac) ;   
}

6.2.4 HLRatios

Each channel must be fed with 4 floating point values.

int j ;
for ( j = 0 ; j < 144 ; j++ ) {
  fem->AppendOneChannel(some_average,some_rms,some_intercept,some_slope) ;
}

6.2.5 LCTofs and WalkTofs

Same interface as HLRatios but with only 2 values per channel (AppendOneChannel(value1,value2)).