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