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