PamCut/PamCutBase/PamCutBase.h

/*
 * PamCutBase.h
 *
 *  Created on: 6-feb-2009
 *      Author: Nicola Mori
 */

/*! \file PamCutBase.h PamCut and PamCutCollection classes definitions. */

#ifndef PAMCUTBASE_H_
#define PAMCUTBASE_H_

#include <PamLevel2.h>
#include "../CommonDefs.h"

using namespace std;

/*! @brief An abstract class to apply cuts to Pamela data.
 *
 * This class provides a basic interface for a cut object to apply to PamLevel2 data.
 */
class PamCut {
public:

  /*! @brief Constructor.
   *  @param cutName The cut's name.
   */
  PamCut(const char *cutName) :
    _cutName(cutName), _nEv(0), _nGood(0) {
  }

  /*! @brief Destructor. */
  virtual ~PamCut() {
  }

  /*! @brief The basic event check.
   *
   *  This routine applies the cut to the currently selected event, eg., to the event selected
   *  by the last PamLevel2::GetEntry() call performed by the object pointed by event. Note that
   *  OnGood() is not called by this method.
   *
   * @param event The event to analyze.
   * @return #CUTOK if the event satisfy the cut, other return values are implementation-specific.
   */

  virtual int Check(PamLevel2 *event) = 0;

  /*! @brief Applies the cut to the current event.
   *
   *  This routine applies the cut to the currently selected event, eg., it calls Check() and if the
   *  event satisfy the selection it consequently call OnGood(), otherwise it calls OnBad()(this is
   *  the only difference with Check()).
   *
   * @param event The event to analyze.
   * @return same return values as Check()
   */
  virtual int ApplyCut(PamLevel2 *event);

  /*! @brief Applies the cut to a range of events.
   *
   * This method resets the counters calling Reset() and then calls ApplyCut(PamLevel2 *event) for all
   * the events in PamLevel2 argument inside the specified range. After checking all the events, it calls
   * the private method _Finalize(), on which the tasks to be performed after the selection can be defined.
   *
   * @param events Pointer to PamLevel2 object which contains the events.
   * @param firstEvent The first event to analyze. Possible values range from 0 to \#events - 1.
   * @param lastEvent The last event to analyze.
   */
  virtual void Process(PamLevel2 *events, ULong_t firstEvent, ULong_t lastEvent);

  /*! @brief Post-selection tasks.
   *
   * Here the post-selection actions (histogram filling, parameter calculation etc.) can be  defined.
   * This routine is automatically called after a good event has been selected by
   * ApplyCut().
   * @param event The event which satisfy the cut.
   */
  virtual void OnGood(PamLevel2 *event) {
  }

  /*! @brief Post-selection tasks.
   *
   * The post-selection tasks for bad events (ie., not satisfying the cut) can be defined here.
   *
   * @see OnGood
   * @param event The event which don't satisfy the cut.
   * @param selectionResult The return value of the Check() routine.
   */
  virtual void OnBad(PamLevel2 *event, int selectionResult) {
  }

  /*! @brief Returns the number of checked events.
   *
   * @return The number of checked events.
   */
  virtual UInt_t GetNEv() {
    return _nEv;
  }
  /*! @brief Returns the number of good events.
   *
   * This counter keeps track of how many events have fulfilled the
   * conditions specified in Check.
   *
   * @return The number of good events.
   */
  virtual UInt_t GetNGood() {
    return _nGood;
  }

  /*! @brief Returns the index of currently processed event.
    *
    * This method returns the index of the currently processed event inside a #Process()
    * invocation. It has no meaning when read outside #Process().
    *
    * @return The index of the currently processed event.
    */
  ULong_t GetCurrentEvent(){
    return _currEv;
  }

  /*! @brief The pre-analysis task definition.
   *
   * This method is automatically called by Process() before the event selection;
   * override this in derived classes to perform pre-analysis tasks like opening files and so on.
   * In this base class implementation it only resets the counters for examined and good events.
   * The parameter PamLevel2 *events may serve to initialize the analysis (even if in this base class
   * implementation it is unused), so the interface includes it.
   *
   * @param events The PamLevel2 pointer to the events that will be analyzed.
   *
   * @see GetNEv(), GetNGood().
   */
  virtual void Setup(PamLevel2 *events);

  /*! @brief The post-analysis task definition.
   *
   * This method is automatically called by Process() after the event selection has been
   * performed; override this in derived classes to perform post-analysis tasks like writing
   * histograms, closing files and so on.
   */
  virtual void Finalize() {
  }

  /*! @brief Returns the cut name.
   *
   * @return The cut name.
   */
  const char* GetName() const;

  /*! @brief Changes the cut's name
   *
   * @param newName The new name.
   */
  void SetName(const char *newName);

  /*! @brief The assignment operator.
   * This operator defines how to copy a PamCut object into another. In current implementation,
   * it only copies the cut's name of the RHS on the LHS.
   *
   * @param rightValue The RHS.
   * @return The new value for LHS.
   */
  PamCut& operator=(const PamCut &rightValue);

private:

  const char *_cutName;
  ULong_t _currEv;

protected:

  UInt_t _nEv; ///<  The number of analyzed events.
  UInt_t _nGood; ///<  The number of good events.
};

/*! @brief A class which applies a set of cuts to Pamela data.
 *
 * This is a multi-cut class, which inherits from PamCut. Indeed, a multi-cut can be seen as a cut composed
 * by various simpler cuts; hence the interface of PamCut is also functional for PamCutCollection. The
 * ApplyCut(PamLevel2 *event) method is overridden so as all the cuts that compose the PamCutCollection are applied to the
 * events in the same order they are added to the collection. Instead, Process(PamLevel2 *events, ULong_t firstEvent, ULong_t lastEvent)
 * is NOT overridden, since it performs the same task as the one in the base class: it is sufficient to override
 * Check(PamLevel2 *event) to replace the single-cut evaluation with a multi-cut evaluation.
 */
class PamCutCollection: public PamCut {
public:

  /*! @brief Constructor.
   * The collection can own the cuts, according to the value of the "owns" parameter.
   * If set to true, the collection will take in charge the duty of destroying cuts and
   * freeing their memory; users then should not set owns to true and explicitly call
   * delete for the cuts in the collection. If instead owns is set to false, no destruction
   * is performed by the collection; in this case, the user should issue the eventual
   * delete calls.
   *
   * @param collectionName The collection's name.
   * @param owns If true, the collection will own the cuts, ie., it will
   *             destroy them in its destructor.
   */
  PamCutCollection(const char *collectionName, bool owns = true) :
    PamCut(collectionName), _owns(owns) {
  }

  /*! @brief Destructor. */
  ~PamCutCollection();

  /*! @brief Adds a cut to the cut collection
   *  This routine adds a cut to the collection. These are stored in a vector in the same order
   *  they are inserted (the first cut would be element 0, the second cut element 1 and so on).
   *  All the references to a "cut number" or "cut index" will refer to this numbering scheme.
   *
   * @param cut The pointer to a PamCut-derived object to add to the collection.
   */
  void AddCut(PamCut *cut);

  /*! @brief The basic selection.
   *
   *  Like in the mother class, this method performs a basic check on the current event: it calls
   *  Check() for each cut previously added with AddCut(), exiting if one of them is not satisfied.
   *
   *  @param event The event to analyze.
   *  @return the index of the failed cut (range: [0, \#cuts-1], see AddCut()); #CUTOK if the event
   *  satisfies all the cuts.
   */
  int Check(PamLevel2 *event);

  /*! @brief Applies the cuts to the current event.
   *
   *  This routine works pretty much like the redefinition of Check(), calling ApplyCut() (instead of
   *  Check() )for each cut. If a cut fails, it calls OnBad(), passing the index of the failed cut as
   *  the selectionResult argument. If all the cuts are successful, it calls OnGood().
   *
   * @param event The event to analyze.
   * @return same return values as Check().
   */
  int ApplyCut(PamLevel2 *event);

  /*! @brief Returns a pointer to the iCut-th cut.
   *
   *  The return value of this method is a pointer to a PamCut object; hence, to use the specific method of
   *  derived cuts it must be cast to the proper cut class.
   *
   *  @param iCut The cut number, defined as the insertion order (from 0 to \#cuts-1, see AddCut()).
   *  @return pointer to the iCut-th cut; NULL if the specified cut cannot be found or if no cuts are present.
   * */
  PamCut *GetCut(unsigned int iCut);

  /*! @brief Searches for a cut by name.
   *
   *  The return value of this method is a pointer to a PamCut object; hence, to use the specific method of
   *  derived cuts it must be cast to the proper cut class.
   *
   * @param cutName The name of the cut to search for.
   *  @return pointer to the iCut-th cut; NULL if the specified cut cannot be found or if no cuts are present.
   * */
  PamCut *GetCut(const char *cutName);

  /*! @brief The number of cuts contained in the collection.
   *
   * @return The number of cuts
   */
  unsigned int GetSize();

  /*! @brief The pre-analysis task definition.
   *
   * This override of the Setup() method calls Setup() for the base class PamCut, and subsequently for each cut
   * contained in the collection, in the same order the cuts were added to the collection.
   *
   * @param events The PamLevel2 pointer to the events that will be analyzed. Unused, but required by the interface.
   */
  void Setup(PamLevel2 *events);

  /*! @brief The post-analysis task definition.
   *
   * This override of the Finalize() method calls  PamCut::Finalize() and then the Finalize() method of each cut
   * contained in the collection, in the same order.
   */
  void Finalize();

  /*! @brief Assignment operator redefinition.
   * The assignment operator replaces the content of the LHS with that of RHS. The net effect would be that
   * the cuts contained in the LHS are exactly the same that are in the RHS. In particular, this means that
   * any modification to one of the cuts will propagate both to the LHS and RHS collections. Also the cut
   * name will be copied, since the implementation invokes PamCut::operator=.
   *
   * @param rightValue The RHS.
   * @return The new value for LHS.
   */
  PamCutCollection& operator=(const PamCutCollection &rightValue);

protected:
  /*! @brief A vector containing pointers to PamCut objects */
  std::vector<PamCut*> _cuts;

  /*! @brief A flag signaling if the collection owns the cuts (ie., if the collection
   *         will destroy the cuts.
   */
  bool _owns;
};

#endif /* PAMCUTBASE_H_ */
1	pam-fi	1.1	/*
2			* PamCutBase.h
3			*
4			* Created on: 6-feb-2009
5			* Author: Nicola Mori
6			*/
7
8			/! \file PamCutBase.h PamCut and PamCutCollection classes definitions. /
9
10			#ifndef PAMCUTBASE_H_
11			#define PAMCUTBASE_H_
12
13			#include <PamLevel2.h>
14			#include "../CommonDefs.h"
15
16			using namespace std;
17
18			/*! @brief An abstract class to apply cuts to Pamela data.
19			*
20			* This class provides a basic interface for a cut object to apply to PamLevel2 data.
21			*/
22			class PamCut {
23			public:
24
25	pam-fi	1.5	/*! @brief Constructor.
26			* @param cutName The cut's name.
27			*/
28	pam-fi	1.1	PamCut(const char *cutName) :
29			_cutName(cutName), _nEv(0), _nGood(0) {
30			}
31
32			/! @brief Destructor. /
33			virtual ~PamCut() {
34			}
35
36			/*! @brief The basic event check.
37			*
38			* This routine applies the cut to the currently selected event, eg., to the event selected
39			* by the last PamLevel2::GetEntry() call performed by the object pointed by event. Note that
40			* OnGood() is not called by this method.
41			*
42			* @param event The event to analyze.
43			* @return #CUTOK if the event satisfy the cut, other return values are implementation-specific.
44			*/
45
46			virtual int Check(PamLevel2 *event) = 0;
47
48			/*! @brief Applies the cut to the current event.
49			*
50			* This routine applies the cut to the currently selected event, eg., it calls Check() and if the
51			* event satisfy the selection it consequently call OnGood(), otherwise it calls OnBad()(this is
52			* the only difference with Check()).
53			*
54			* @param event The event to analyze.
55			* @return same return values as Check()
56			*/
57			virtual int ApplyCut(PamLevel2 *event);
58
59			/*! @brief Applies the cut to a range of events.
60			*
61			* This method resets the counters calling Reset() and then calls ApplyCut(PamLevel2 *event) for all
62			* the events in PamLevel2 argument inside the specified range. After checking all the events, it calls
63			* the private method _Finalize(), on which the tasks to be performed after the selection can be defined.
64			*
65			* @param events Pointer to PamLevel2 object which contains the events.
66			* @param firstEvent The first event to analyze. Possible values range from 0 to \#events - 1.
67			* @param lastEvent The last event to analyze.
68			*/
69			virtual void Process(PamLevel2 *events, ULong_t firstEvent, ULong_t lastEvent);
70
71			/*! @brief Post-selection tasks.
72			*
73			* Here the post-selection actions (histogram filling, parameter calculation etc.) can be defined.
74			* This routine is automatically called after a good event has been selected by
75			* ApplyCut().
76			* @param event The event which satisfy the cut.
77			*/
78			virtual void OnGood(PamLevel2 *event) {
79			}
80
81			/*! @brief Post-selection tasks.
82			*
83			* The post-selection tasks for bad events (ie., not satisfying the cut) can be defined here.
84			*
85			* @see OnGood
86			* @param event The event which don't satisfy the cut.
87			* @param selectionResult The return value of the Check() routine.
88			*/
89			virtual void OnBad(PamLevel2 *event, int selectionResult) {
90			}
91
92			/*! @brief Returns the number of checked events.
93			*
94			* @return The number of checked events.
95			*/
96			virtual UInt_t GetNEv() {
97			return _nEv;
98			}
99			/*! @brief Returns the number of good events.
100			*
101			* This counter keeps track of how many events have fulfilled the
102			* conditions specified in Check.
103			*
104			* @return The number of good events.
105			*/
106			virtual UInt_t GetNGood() {
107			return _nGood;
108			}
109
110	pam-fi	1.6	/*! @brief Returns the index of currently processed event.
111			*
112			* This method returns the index of the currently processed event inside a #Process()
113			* invocation. It has no meaning when read outside #Process().
114			*
115			* @return The index of the currently processed event.
116			*/
117			ULong_t GetCurrentEvent(){
118			return _currEv;
119			}
120
121	pam-fi	1.1	/*! @brief The pre-analysis task definition.
122			*
123			* This method is automatically called by Process() before the event selection;
124			* override this in derived classes to perform pre-analysis tasks like opening files and so on.
125			* In this base class implementation it only resets the counters for examined and good events.
126			* The parameter PamLevel2 *events may serve to initialize the analysis (even if in this base class
127			* implementation it is unused), so the interface includes it.
128			*
129			* @param events The PamLevel2 pointer to the events that will be analyzed.
130			*
131			* @see GetNEv(), GetNGood().
132			*/
133			virtual void Setup(PamLevel2 *events);
134
135	pam-fi	1.2	/*! @brief The post-analysis task definition.
136	pam-fi	1.1	*
137			* This method is automatically called by Process() after the event selection has been
138			* performed; override this in derived classes to perform post-analysis tasks like writing
139			* histograms, closing files and so on.
140			*/
141			virtual void Finalize() {
142			}
143
144			/*! @brief Returns the cut name.
145			*
146			* @return The cut name.
147			*/
148			const char* GetName() const;
149
150			/*! @brief Changes the cut's name
151			*
152			* @param newName The new name.
153			*/
154			void SetName(const char *newName);
155
156			/*! @brief The assignment operator.
157			* This operator defines how to copy a PamCut object into another. In current implementation,
158			* it only copies the cut's name of the RHS on the LHS.
159			*
160			* @param rightValue The RHS.
161			* @return The new value for LHS.
162			*/
163			PamCut& operator=(const PamCut &rightValue);
164
165			private:
166
167			const char *_cutName;
168	pam-fi	1.6	ULong_t _currEv;
169	pam-fi	1.1
170			protected:
171
172			UInt_t _nEv; ///< The number of analyzed events.
173			UInt_t _nGood; ///< The number of good events.
174			};
175
176			/*! @brief A class which applies a set of cuts to Pamela data.
177			*
178			* This is a multi-cut class, which inherits from PamCut. Indeed, a multi-cut can be seen as a cut composed
179			* by various simpler cuts; hence the interface of PamCut is also functional for PamCutCollection. The
180			* ApplyCut(PamLevel2 *event) method is overridden so as all the cuts that compose the PamCutCollection are applied to the
181			* events in the same order they are added to the collection. Instead, Process(PamLevel2 *events, ULong_t firstEvent, ULong_t lastEvent)
182			* is NOT overridden, since it performs the same task as the one in the base class: it is sufficient to override
183			* Check(PamLevel2 *event) to replace the single-cut evaluation with a multi-cut evaluation.
184			*/
185			class PamCutCollection: public PamCut {
186			public:
187
188			/*! @brief Constructor.
189	pam-fi	1.5	* The collection can own the cuts, according to the value of the "owns" parameter.
190			* If set to true, the collection will take in charge the duty of destroying cuts and
191			* freeing their memory; users then should not set owns to true and explicitly call
192			* delete for the cuts in the collection. If instead owns is set to false, no destruction
193			* is performed by the collection; in this case, the user should issue the eventual
194			* delete calls.
195	pam-fi	1.1	*
196	pam-fi	1.2	* @param collectionName The collection's name.
197	pam-fi	1.5	* @param owns If true, the collection will own the cuts, ie., it will
198			* destroy them in its destructor.
199	pam-fi	1.1	*/
200	pam-fi	1.5	PamCutCollection(const char *collectionName, bool owns = true) :
201			PamCut(collectionName), _owns(owns) {
202	pam-fi	1.1	}
203
204			/! @brief Destructor. /
205	pam-fi	1.5	~PamCutCollection();
206	pam-fi	1.1
207			/*! @brief Adds a cut to the cut collection
208			* This routine adds a cut to the collection. These are stored in a vector in the same order
209			* they are inserted (the first cut would be element 0, the second cut element 1 and so on).
210			* All the references to a "cut number" or "cut index" will refer to this numbering scheme.
211			*
212	pam-fi	1.5	* @param cut The pointer to a PamCut-derived object to add to the collection.
213	pam-fi	1.1	*/
214	pam-fi	1.5	void AddCut(PamCut *cut);
215	pam-fi	1.1
216			/*! @brief The basic selection.
217			*
218			* Like in the mother class, this method performs a basic check on the current event: it calls
219			* Check() for each cut previously added with AddCut(), exiting if one of them is not satisfied.
220			*
221	pam-fi	1.3	* @param event The event to analyze.
222	pam-fi	1.1	* @return the index of the failed cut (range: [0, \#cuts-1], see AddCut()); #CUTOK if the event
223			* satisfies all the cuts.
224			*/
225			int Check(PamLevel2 *event);
226
227			/*! @brief Applies the cuts to the current event.
228			*
229			* This routine works pretty much like the redefinition of Check(), calling ApplyCut() (instead of
230			* Check() )for each cut. If a cut fails, it calls OnBad(), passing the index of the failed cut as
231			* the selectionResult argument. If all the cuts are successful, it calls OnGood().
232			*
233			* @param event The event to analyze.
234			* @return same return values as Check().
235			*/
236			int ApplyCut(PamLevel2 *event);
237
238			/*! @brief Returns a pointer to the iCut-th cut.
239			*
240			* The return value of this method is a pointer to a PamCut object; hence, to use the specific method of
241			* derived cuts it must be cast to the proper cut class.
242			*
243			* @param iCut The cut number, defined as the insertion order (from 0 to \#cuts-1, see AddCut()).
244			* @return pointer to the iCut-th cut; NULL if the specified cut cannot be found or if no cuts are present.
245			* */
246			PamCut *GetCut(unsigned int iCut);
247
248	pam-fi	1.4	/*! @brief Searches for a cut by name.
249			*
250			* The return value of this method is a pointer to a PamCut object; hence, to use the specific method of
251			* derived cuts it must be cast to the proper cut class.
252			*
253			* @param cutName The name of the cut to search for.
254			* @return pointer to the iCut-th cut; NULL if the specified cut cannot be found or if no cuts are present.
255			* */
256			PamCut GetCut(const char cutName);
257
258	pam-fi	1.1	/*! @brief The number of cuts contained in the collection.
259			*
260			* @return The number of cuts
261			*/
262			unsigned int GetSize();
263
264			/*! @brief The pre-analysis task definition.
265			*
266			* This override of the Setup() method calls Setup() for the base class PamCut, and subsequently for each cut
267			* contained in the collection, in the same order the cuts were added to the collection.
268			*
269			* @param events The PamLevel2 pointer to the events that will be analyzed. Unused, but required by the interface.
270			*/
271			void Setup(PamLevel2 *events);
272
273			/*! @brief The post-analysis task definition.
274			*
275			* This override of the Finalize() method calls PamCut::Finalize() and then the Finalize() method of each cut
276			* contained in the collection, in the same order.
277			*/
278			void Finalize();
279
280			/*! @brief Assignment operator redefinition.
281			* The assignment operator replaces the content of the LHS with that of RHS. The net effect would be that
282			* the cuts contained in the LHS are exactly the same that are in the RHS. In particular, this means that
283			* any modification to one of the cuts will propagate both to the LHS and RHS collections. Also the cut
284			* name will be copied, since the implementation invokes PamCut::operator=.
285			*
286			* @param rightValue The RHS.
287			* @return The new value for LHS.
288			*/
289			PamCutCollection& operator=(const PamCutCollection &rightValue);
290
291			protected:
292			/! @brief A vector containing pointers to PamCut objects /
293			std::vector<PamCut*> _cuts;
294
295	pam-fi	1.5	/*! @brief A flag signaling if the collection owns the cuts (ie., if the collection
296			* will destroy the cuts.
297			*/
298			bool _owns;
299	pam-fi	1.1	};
300
301			#endif /* PAMCUTBASE_H_ */