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. */
  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 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;

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.
   *
   * @param collectionName The collection's name.
   */
  PamCutCollection(const char *collectionName) :
    PamCut(collectionName) {
  }

  /*! @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 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;

};

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