Changeset 9867

Timestamp:

08/16/10 09:07:43 (14 years ago)

Author:

tbretz

Message:

Improved comments in MJOptimizeBase.

Location:

trunk/Mars

Files:

• Changelog (modified) (1 diff)
• mjoptim/MJOptimizeBase.cc (modified) (4 diffs)
• mjoptim/MJOptimizeBase.h (modified) (2 diffs)

trunk/Mars/Changelog

@@ -44 +44 @@
      - evaluate return code of fRun->Process()
      - print return code in case of failure
+
+   * mjoptim/MJOptimizeBase.[h,cc]:
+     - improved existing comments
+     - added a full class description
+
 
 

trunk/Mars/mjoptim/MJOptimizeBase.cc

@@ -18 +18 @@
 !   Author(s): Thomas Bretz 11/2005 <mailto:tbretz@astro.uni-wuerzburg.de>
 !
-!   Copyright: MAGIC Software Development, 2005-2007
+!   Copyright: MAGIC Software Development, 2005-2010
 !
 !
@@ -30 +30 @@
 //
 // The order when reading a file is:
-//   1) Execution of PreTasks  (set by user)
-//   2) Execution of PreCuts   (set by user)
+//   1) Execution of PreTasks
+//   2) Execution of PreCuts, TestCuts, TrainCuts
 //   3) Selector               (calculated from number of requested events)
 //   4) Splitter               (if sample is split automatically in test/train)
@@ -39 +39 @@
 // you calculate a vlue which is not needed for your PreCuts, you can
 // calculate it afterwards, which will speed up execution.
+//
+// void AddPreTask(MTask *t)
+//    Add a task which is executed just after reading the events from the file
+//    this can be any kind of task or even a task list. You can use dedicated
+//    tasks performing some analysis, but also cuts (e.g. MContinue) or a
+//    general task to evaluate new parameters (e.g. MParameterCalc)
+//
+// void AddPreTask(const char *rule, const char *name="MWeight")
+//    This is a short cut to AddPreTask(MTask*) which will add a
+//    MParameterCalc to the list evaluating the given rule and storing the
+//    result in a MParameterD with the given name. For the default "MWeight",
+//    for example, the value can later be accessed by MWeight.fVal.
+//
+// The same functions are available as
+//    void AddPostTask(MTask *t)
+//    void AddPostTask(const char *rule, const char *name="MWeight")
+//
+// It is advicable to use these function if the task is not needed for your
+// event selection. The event selection (by number and by PreCuts) is done
+// in between PreTasks and PostTasks, i.e. a task which is not needed for the
+// event selection but needed later is only executed as often as necessary.
+//
+// The event selection (apart from the number of target events) can be setup
+// by the user. Therefore two functions are available
+//    void AddPreCut(const char *rule)
+//    void AddPreCut(MFilter *f)
+// Both add cuts which are executed after the PreTasks but before the
+// PostTasks. They are executed in both training and testing. To execute cuts
+// only in training or testing use
+//    void AddTrainCut(const char *rule)
+//    void AddTrainCut(MFilter *f)
+// or
+//    void AddTestCut(const char *rule)
+//    void AddTestCut(MFilter *f)
+//
+// To weight the events of your train- and test sample the following functions
+// can be used
+//    void SetWeights(const char *rule)
+//    void SetWeights(MTask *t)
+// This either adds a MParameterCalc to the list of post tasks or a MTask,
+// which is supposed to fill a MParameterD named "MWeight".
+//
+// Last but not least a function if available to add additional tasks to the
+// end of the task list for testing. This can for example be used to add
+// the filling and display of an addition histogram (e.g. add a MFillH)
+// or to do some calculation and write out the result. Basically everything
+// can be done in this way.
+//    void AddTestTask(MTask *t)
+//    void AddTestTask(const char *rule, const char *name="MWeight")
+//
+//
+// REMARK: Note that the actual behavior might still vary a bit
+//         depeding of the implementation in the derived class.
 //
 /////////////////////////////////////////////////////////////////////////////
@@ -98 +151 @@
 //------------------------------------------------------------------------
 //
-// Add a parameter used in your filters (see AddFilter) The parameter
-// index is returned,
+// Add a parameter to the list of parameters. The index in the list is
+// returned.
 //
 //   Int_t idx = AddParameter("log10(MHillas.fSize)");
 //
-// The indices are starting with 0 always.
+// Indices are starting with 0.
 //
 Int_t MJOptimizeBase::AddParameter(const char *rule)

trunk/Mars/mjoptim/MJOptimizeBase.h

@@ -23 +23 @@
     TList fPreTasks;        // Tasks executed before cut execution
     TList fPostTasks;       // Tasks executed after cut execution
-    TList fTestTasks;       // Tasks executed after cut execution for testing
+    TList fTestTasks;       // Tasks executed at the end of the testing tasklist
 
     void AddCut(TList &l, const char *rule);
@@ -34 +34 @@
     }
 
+    // MJOptimizeBase
+    void SetDebug(Bool_t b=kTRUE) { fDebug = b; }
+
+    // Add a parameter to the list of parameters
+    Int_t AddParameter(const char *rule);
+
+    // Tasks which are executed after reading (training and testing if available)
     void AddPreTask(MTask *t)                    { Add(fPreTasks,  t); }
     void AddPreTask(const char *rule,
                     const char *name="MWeight")  { AddPar(fPreTasks, rule, name); }
 
+    // Cuts which are executed after the pre-tasks (training and testing if available)
+    void AddPreCut(const char *rule)             { AddCut(fPreCuts, rule); }
+    void AddPreCut(MFilter *f)                   { Add(fPreCuts, (MTask*)(f)); }
+
+    // Same as pre-cuts but only executed in taining or testing
+    void AddTrainCut(const char *rule)           { AddCut(fTrainCuts, rule); }
+    void AddTrainCut(MFilter *f)                 { Add(fTrainCuts, (MTask*)(f)); }
+
+    void AddTestCut(const char *rule)            { AddCut(fTestCuts, rule); }
+    void AddTestCut(MFilter *f)                  { Add(fTestCuts, (MTask*)(f)); }
+
+    // Tasks which are excuted after event selection (training and testing if available)
     void AddPostTask(MTask *t)                   { Add(fPostTasks, t); }
     void AddPostTask(const char *rule,
                      const char *name="MWeight") { AddPar(fPostTasks, rule, name); }
 
+    // Tasks executed at the end of the testing tasklist
     void AddTestTask(MTask *t)                   { Add(fTestTasks, t); }
     void AddTestTask(const char *rule,
                      const char *name="MWeight") { AddPar(fTestTasks, rule, name); }
 
-    void SetDebug(Bool_t b=kTRUE)      { fDebug = b; }
-
+    // Add calculation of weights to list of post tasks. Set fEnableWeights
     void SetWeights(const char *rule)  { if (fEnableWeights) return; fEnableWeights=kTRUE; AddPostTask(rule); }
     void SetWeights(MTask *t)          { if (fEnableWeights) return; fEnableWeights=kTRUE; AddPostTask(t);    }
-
-    void AddPreCut(const char *rule)   { AddCut(fPreCuts, rule); }
-    void AddPreCut(MFilter *f)         { Add(fPreCuts, (MTask*)(f)); }
-
-    void AddTrainCut(const char *rule) { AddCut(fTrainCuts, rule); }
-    void AddTrainCut(MFilter *f)       { Add(fTrainCuts, (MTask*)(f)); }
-
-    void AddTestCut(const char *rule)  { AddCut(fTestCuts, rule); }
-    void AddTestCut(MFilter *f)        { Add(fTestCuts, (MTask*)(f)); }
-
-    Int_t AddParameter(const char *rule);
 
     ClassDef(MJOptimizeBase, 0)//Base class for all optimizations and trainings