HLT/TPCLib/AliHLTTPCPad.h

   1 // -*- Mode: C++ -*-
   2 // @(#) $Id$
   3
   4 #ifndef ALIHLTTPCPAD_H
   5 #define ALIHLTTPCPAD_H
   6 /* This file is property of and copyright by the ALICE HLT Project        *
   7  * ALICE Experiment at CERN, All rights reserved.                         *
   8  * See cxx source for full Copyright notice                               */
   9
  10 /** @file   AliHLTTPCPad.h
  11     @author Matthias Richter
  12     @date
  13     @brief  Container Class for TPC Pads.
  14 */
  15
  16 // see below for class documentation
  17 // or
  18 // refer to README to build package
  19 // or
  20 // visit http://web.ift.uib.no/~kjeks/doc/alice-hlt
  21
  22 #include "AliHLTLogging.h"
  23 #include "AliHLTTPCClusters.h"
  24 #include <vector>
  25
  26 typedef Int_t AliHLTTPCSignal_t;
  27
  28 /**
  29  * @class AliHLTTPCPad
  30  * The class is a container for the raw ADC data of one TPCS pad. In order to
  31  * avoid multiple unpacking/handling of the incoming raw data, the class holds
  32  * a copy of the incoming data for one event. The copy is released when the
  33  * end of the event was announced.
  34  * The class calculates the base line of a TPC channel. Currently, only the
  35  * average value is calculated, but further extension will include channel by
  36  * channel histograming. The baseline history is kept and used for baseline
  37  * re-evaluation and correction of subsequent events.
  38  * @ingroup alihlt_tpc
  39  */
  40 class AliHLTTPCPad : public AliHLTLogging {
  41 public:
  42   /** standard constructor */
  43   AliHLTTPCPad();
  44
  45   /**
  46    * Constructor
  47    * @param offset   The number of bins to ignore at the beginning
  48    *                 of the channels
  49    * @param nofBins  The total number of bins for one channel
  50    */
  51   AliHLTTPCPad(Int_t offset, Int_t nofBins);
  52
  53   /** standard destructor */
  54   virtual ~AliHLTTPCPad();
  55
  56
  57   struct AliClusterData
  58   {
  59     UInt_t fTotalCharge;   //tot charge of cluster
  60     UInt_t fPad;       //pad value
  61     UInt_t fTime;      //time value
  62     ULong64_t fPad2;   //for error in XY direction
  63     ULong64_t fTime2;  //for error in Z  direction
  64     UInt_t fMean;          //mean in time
  65     UInt_t fFlags;         //different flags
  66     UInt_t fChargeFalling; //for deconvolution
  67     UInt_t fLastCharge;    //for deconvolution
  68     UInt_t fLastMergedPad; //dont merge twice per pad
  69   };
  70
  71   typedef struct AliClusterData AliClusterData; //!
  72
  73
  74   /**
  75    * Set the address the pad.
  76    * The address consists of row and pad number.
  77    * @param rowno    The row number
  78    * @param padno    The pad number.
  79    */
  80   Int_t SetID(Int_t rowno, Int_t padno);
  81
  82   /**
  83    * Get the row number.
  84    */
  85   Int_t GetRowNumber() const {return fRowNo;}
  86
  87   /**
  88    * Get the pad number.
  89    */
  90   Int_t GetPadNumber() const {return fPadNo;}
  91
  92   /**
  93    * Start accumulation for a new event.
  94    * The class holds internally a history of the event data. The data can
  95    * be fetched from the class without unpacking the input stream again.
  96    * @return neg. error value if failed
  97    *         - ENOMEM memory allocation failed
  98    *         - EALREADY event data acquisition already started
  99    */
 100   Int_t StartEvent();
 101
 102   /**
 103    * Check whether the event is started
 104    * @return 1 if started, 0 if not
 105    */
 106   Int_t IsStarted() const { return fpRawData!=NULL;};
 107
 108   /**
 109    * Calculate the base line from the current event data.
 110    * Only available within an event cycle. <br>
 111    * The calculation requires a minimum number of bins which contribute
 112    * to the sum, which can be specified by \e reqMinCount. The base line
 113    * calculation will also be skipped if the number of contributing bins is
 114    * less than half of the total number of time bins.
 115    * @param reqMinCount    the minimum number of bins contributing to the sum
 116    * @return neg. error value if failed
 117    *         - ENODATA to little contributing bins
 118    *         - ENOBUFS no raw data available
 119    */
 120   Int_t CalculateBaseLine(Int_t reqMinCount=1);
 121
 122   /**
 123    * Stop processing of one event.
 124    * The data history of the event will be released.
 125    * @return neg. error value if failed
 126    *         - EBADF event not started
 127    */
 128   Int_t StopEvent();
 129
 130   /**
 131    * Reset the base line history.
 132    * @return neg. error code if failed
 133    */
 134   Int_t ResetHistory();
 135
 136   /**
 137    * Set threshold.
 138    * The threshold effects to corrected data, signals smaller than threshold
 139    * are suppressed.
 140    * @param thresh   Threshold for signal correction
 141    * @return neg. error code if failed
 142    */
 143   Int_t SetThreshold(AliHLTTPCSignal_t thresh);
 144
 145   /**
 146    * Set the raw data value of a certain channel.
 147    * @param bin      Channel number
 148    * @param value    ADC value
 149    * @return neg. error value if failed
 150    *         - ERANGE bin out of range
 151    *         - BADF event cycle not started
 152    */
 153   Int_t SetRawData(Int_t bin, AliHLTTPCSignal_t value);
 154
 155   /**
 156    * Get the raw data value of the current bin.
 157    * The class holds the current read position which can be incremented by
 158    * @ref Next() and reseted by @ref Rewind().
 159    * Raw data is only available within an event cycle.
 160    * @return raw data value
 161    */
 162   AliHLTTPCSignal_t GetRawData() const {return GetRawData(fReadPos);}
 163
 164   /**
 165    * Get the corrected data value the current bin.
 166    * Corrected raw data is only available within an event cycle.
 167    * The base line value is substracted from the bin's value and suppressed
 168    * by the threshold. Bins smaller than the first bin considered for base
 169    * line calculation return 0.
 170    * The class holds the current read position which can be incremented by
 171    * @ref Next() and reseted by @ref Rewind().
 172    * @return corrected value
 173    */
 174   AliHLTTPCSignal_t GetCorrectedData() const {return GetCorrectedData(fReadPos);}
 175
 176   /**
 177    * Increment the read position.
 178    * @param bZeroSuppression  skip all bins effected by the zero suppression
 179    * @return 1 if more data available, 0 if not
 180    */
 181   Int_t Next(Int_t bZeroSuppression=kTRUE);
 182
 183   /**
 184    * Rewind the read position.
 185    * The read position is set to the first bin over the zero suppression.
 186    * @param bZeroSuppression  skip all bins effected by the zero suppression
 187    * @return 1 if more data available, 0 if not
 188    */
 189   Int_t Rewind(Int_t bZeroSuppression=kTRUE);
 190
 191   /**
 192    * Get the current read position.
 193    * @return read position, -1 if no data available
 194    */
 195   Int_t GetCurrentPosition() const {return fReadPos<fNofBins?fReadPos:-1;}
 196
 197   /**
 198    * Get the raw data value of a certain bin.
 199    * Raw data is only available within an event cycle.
 200    * @param bin      Channel number
 201    * @return raw data value
 202    */
 203   AliHLTTPCSignal_t GetRawData(Int_t bin) const;
 204
 205   /**
 206    * Get the corrected data value of a certain bin.
 207    * Corrected raw data is only available within an event cycle.
 208    * The base line value is substracted from the bin's value and suppressed
 209    * by the threshold. Bins smaller than the first bin considered for base
 210    * line calculation return 0.
 211    * @param bin      Channel number
 212    * @return corrected value
 213    */
 214   AliHLTTPCSignal_t GetCorrectedData(Int_t bin) const;
 215
 216   /**
 217    * Get the base line value of a certain channel.
 218    * @param bin      Channel number
 219    * @return base line value at bin
 220    */
 221   AliHLTTPCSignal_t GetBaseLine(Int_t bin) const;
 222
 223   /**
 224    * Get the avarage base line value.
 225    * @return average base line value
 226    */
 227   AliHLTTPCSignal_t GetAverage() const;
 228
 229   /**
 230    * Get the occupancy for the pad in fractions of 1
 231    * The occupancy is calculated from the number of time bins with non zero data
 232    * after zero suppression.
 233    * @return occupancy in percent
 234    */
 235   Float_t GetOccupancy() const;
 236
 237   /**
 238    * Get the occupancy average for the pad in fractions of 1
 239    * The occupancy is calculated from the number of time bins with non zero data
 240    * after zero suppression and averaged over all events.
 241    * @return occupancy in percent
 242    */
 243   Float_t GetAveragedOccupancy() const;
 244
 245   /**
 246    * Get the size (number of time bins) of the pad
 247    * @return number of bins
 248    */
 249   Int_t GetSize() const {return fNofBins;}
 250
 251   /**
 252    * Set the data array to -1
 253    */
 254   void SetDataToDefault();
 255   /**
 256    * Stores the signal in the data array, stores the timebin number of the signal,
 257    * and increments a counter.
 258    */
 259   void SetDataSignal(Int_t bin,Int_t signal);
 260
 261   /**
 262    * Returns the signal in the specified bin
 263    */
 264   Int_t GetDataSignal(Int_t bin) const;
 265
 266   /**
 267    * Zerosuppression where one can choose wether one want to cut on sigma(default 3) or a given adc threshold above baseline
 268    * It works like this: Finds the signals above baseline+threshold, it then looks to the right of the signals adding the
 269    * the signal below threshold but over the average. It stops when the adc value rises (since you should expect a fall)
 270    * or if the signal in that bin is below average. It now does the same thing to the left.
 271    * This is a very timeconsuming approach(but good), and will likely only be used only for cosmics and laser.
 272    * If you use sigma approach you can give as input n sigma or stick with default=3. For channels with very large signals
 273    * the (value-average)² is not calculated when value-average>50. This is due to sigma shooting sky high for only a few values.
 274    * The method is checked with 2006 cosmics data, and it looks good.
 275    * If you want to use the threshold approach you HAVE to set nSigma=-1 and threshold>0. For example: If you want all signals
 276    * 30 adc counts above threshold you should call the function like this: ZeroSuppress(-1,30)
 277    * @param nSigma          Specify nSigma above threshold default=3
 278    * @param threshold       Specify what adc threshold above average default=20 (remember to give nSigma=-1 if you want to use this approach)
 279    * @param reqMinPoint     Required minimum number of points to do zerosuppression default AliHLTTPCTransform::GetNTimeBins/2 (1024/2).
 280    * @param beginTime       Lowest timebin value. Gating grid causes some problems in the first timebins. default= 50
 281    * @param endTime         Highest timebin value. Default AliHLTTPCTransform::GetNTimeBins-1
 282    */
 283   void ZeroSuppress(Double_t nSigma,Int_t threshold,Int_t reqMinPoint,Int_t beginTime,Int_t endTime);
 284
 285   /**
 286    * Finds the cluster candidate. If atleast two signals in the data array are neighbours
 287    * they are stored in a cluster candidate vector.
 288    */
 289   void FindClusterCandidates();
 290   /**
 291    * Prints the raw data og this pad.
 292    */
 293   void PrintRawData();
 294
 295    /**
 296    * Set the Signal Threshold
 297    */
 298   void SetSignalThreshold(Int_t i){fSignalThreshold=i;}
 299
 300   /**
 301    * Set the nSigma threshold
 302    */
 303   void SetNSigmaThreshold(Double_t i){fNSigmaThreshold=i;}
 304
 305
 306   /**
 307    * Vector of cluster candidates
 308    */
 309   vector<AliHLTTPCClusters> fClusterCandidates;                    //! transient
 310
 311   /**
 312    * Vector of used clustercandidates, used so one do not use candidates multiple times
 313    */
 314   vector<Int_t> fUsedClusterCandidates;                            //! transient
 315
 316  private:
 317   /** copy constructor prohibited */
 318   AliHLTTPCPad(const AliHLTTPCPad&);
 319   /** assignment operator prohibited */
 320   AliHLTTPCPad& operator=(const AliHLTTPCPad&);
 321
 322   /**
 323    * Add a value to the base line calculation.
 324    * The value is been added to the sum if it exceeds the current base line
 325    * and bin is equal or greater than the first bin for base line calculation.
 326    * @param bin      Channel number
 327    * @param value    ADC value
 328    */
 329   Int_t AddBaseLineValue(Int_t bin, AliHLTTPCSignal_t value);
 330
 331   /** The row number of the pad */
 332   Int_t fRowNo;                                                    // see above
 333   /** The pad number of the pad */
 334   Int_t fPadNo;                                                    // see above
 335   /** Threshold for zero suppression */
 336   AliHLTTPCSignal_t fThreshold;                                    // see above
 337   /** The average base line value */
 338   AliHLTTPCSignal_t fAverage;                                      // see above
 339   /** Number of events included in the base line calculation*/
 340   Int_t fNofEvents;                                                // see above
 341   /** The sum within one event */
 342   AliHLTTPCSignal_t fSum;                                          // see above
 343   /** The number of bins contributing to the sum */
 344   Int_t fCount;                                                    // see above
 345   /** The total number of bins already set during the event */
 346   Int_t fTotal;                                                    // see above
 347   /** The maximum base line value within one event */
 348   AliHLTTPCSignal_t fBLMax;                                        // see above
 349   /** The bin for the maximum bl value within one event */
 350   Int_t fBLMaxBin;                                                 // see above
 351   /** The minimum base line value within one event */
 352   AliHLTTPCSignal_t fBLMin;                                        // see above
 353   /** The bin for the minimum bl value within one event */
 354   Int_t fBLMinBin;                                                 // see above
 355   /** The first bin included in the base line calculation */
 356   Int_t fFirstBLBin;                                               // see above
 357   /** Number of bins */
 358   Int_t fNofBins;                                                  // see above
 359
 360   /** The current read position */
 361   Int_t fReadPos;                                                  // see above
 362
 363   /** The raw data history */
 364   AliHLTTPCSignal_t* fpRawData;                                    //! transient
 365
 366   /**
 367    * Array containing the data
 368    */
 369   AliHLTTPCSignal_t* fDataSignals;                                 //! transient
 370
 371   /**
 372    * Array containing info on which bins have signals
 373    */
 374   Int_t *fSignalPositionArray;                                     //! transient
 375   Int_t fSizeOfSignalPositionArray;                                //! transient
 376
 377   Double_t fNSigmaThreshold;                                       //! transient
 378   Double_t fSignalThreshold;                                       //! transient
 379
 380   ClassDef(AliHLTTPCPad, 3)
 381 };
 382 #endif // ALIHLTTPCPAD_H