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