Point Cloud Library (PCL)  1.8.0
stats_estimator.h
1 /*
2  * Software License Agreement (BSD License)
3  *
4  * Point Cloud Library (PCL) - www.pointclouds.org
5  * Copyright (c) 2010-2011, Willow Garage, Inc.
6  *
7  * All rights reserved.
8  *
9  * Redistribution and use in source and binary forms, with or without
10  * modification, are permitted provided that the following conditions
11  * are met:
12  *
13  * * Redistributions of source code must retain the above copyright
14  * notice, this list of conditions and the following disclaimer.
15  * * Redistributions in binary form must reproduce the above
16  * copyright notice, this list of conditions and the following
17  * disclaimer in the documentation and/or other materials provided
18  * with the distribution.
19  * * Neither the name of Willow Garage, Inc. nor the names of its
20  * contributors may be used to endorse or promote products derived
21  * from this software without specific prior written permission.
22  *
23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
24  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
25  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
26  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
27  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
28  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
29  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
30  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
31  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
33  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
34  * POSSIBILITY OF SUCH DAMAGE.
35  *
36  */
37 
38 #ifndef PCL_ML_DT_STATS_ESTIMATOR_H_
39 #define PCL_ML_DT_STATS_ESTIMATOR_H_
40 
41 #include <pcl/common/common.h>
42 
43 #include <ostream>
44 #include <vector>
45 
46 namespace pcl
47 {
48 
49  /** \brief Class interface for gathering statistics for decision tree learning. */
50  template <
51  class LabelDataType,
52  class NodeType,
53  class DataSet,
54  class ExampleIndex >
55  class PCL_EXPORTS StatsEstimator
56  {
57 
58  public:
59 
60  /** \brief Destructor. */
61  virtual
63 
64  /** \brief Returns the number of brances a node can have (e.g. a binary tree has 2). */
65  virtual size_t
66  getNumOfBranches () const = 0;
67 
68  /** \brief Computes and sets the statistics for a node.
69  * \param[in] data_set The data set used for training.
70  * \param[in] examples The examples used for computing the statistics for the specified node.
71  * \param[in] label_data The labels corresponding to the examples.
72  * \param[out] node The destination node for the statistics.
73  */
74  virtual void
75  computeAndSetNodeStats (DataSet & data_set,
76  std::vector<ExampleIndex> & examples,
77  std::vector<LabelDataType> & label_data,
78  NodeType & node ) const = 0;
79 
80  /** \brief Returns the label of the specified node.
81  * \param[in] node The node from which the label is extracted. */
82  virtual LabelDataType
83  getLabelOfNode (NodeType & node) const = 0;
84 
85  /** \brief Computes the information gain obtained by the specified threshold on the supplied feature evaluation results.
86  * \param[in] data_set The data set used for extracting the supplied result values.
87  * \param[in] examples The examples used to extract the supplied result values.
88  * \param[in] label_data The labels corresponding to the examples.
89  * \param[in] results The results obtained from the feature evaluation.
90  * \param[in] flags The flags obtained together with the results.
91  * \param[in] threshold The threshold which is used to compute the information gain.
92  */
93  virtual float
94  computeInformationGain (DataSet & data_set,
95  std::vector<ExampleIndex> & examples,
96  std::vector<LabelDataType> & label_data,
97  std::vector<float> & results,
98  std::vector<unsigned char> & flags,
99  const float threshold) const = 0;
100 
101  /** \brief Computes the branch indices obtained by the specified threshold on the supplied feature evaluation results.
102  * \param[in] results The results obtained from the feature evaluation.
103  * \param[in] flags The flags obtained together with the results.
104  * \param[in] threshold The threshold which is used to compute the branch indices.
105  * \param[out] branch_indices The destination for the computed branch indices.
106  */
107  virtual void
108  computeBranchIndices (std::vector<float> & results,
109  std::vector<unsigned char> & flags,
110  const float threshold,
111  std::vector<unsigned char> & branch_indices) const = 0;
112 
113  /** \brief Computes the branch indices obtained by the specified threshold on the supplied feature evaluation results.
114  * \param[in] result The result obtained from the feature evaluation.
115  * \param[in] flag The flag obtained together with the result.
116  * \param[in] threshold The threshold which is used to compute the branch index.
117  * \param[out] branch_index The destination for the computed branch index.
118  */
119  virtual void
120  computeBranchIndex (const float result,
121  const unsigned char flag,
122  const float threshold,
123  unsigned char & branch_index) const = 0;
124 
125  /** \brief Generates code for computing the branch indices for the specified node and writes it to the specified stream.
126  * \param[in] node The node for which the branch index estimation code is generated.
127  * \param[out] stream The destionation for the code.
128  */
129  virtual void
130  generateCodeForBranchIndexComputation (NodeType & node,
131  std::ostream & stream) const = 0;
132 
133  /** \brief Generates code for computing the output for the specified node and writes it to the specified stream.
134  * \param[in] node The node for which the output estimation code is generated.
135  * \param[out] stream The destionation for the code.
136  */
137  virtual void
138  generateCodeForOutput (NodeType & node,
139  std::ostream & stream ) const = 0;
140 
141  };
142 
143 }
144 
145 #endif
virtual ~StatsEstimator()
Destructor.
Class interface for gathering statistics for decision tree learning.