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