AbstractCost.h
Go to the documentation of this file.
1 //===========================================================================
2 /*!
3  *
4  *
5  * \brief cost function for quantitative judgement of deviations of predictions from target values
6  *
7  *
8  *
9  * \author T. Glasmachers
10  * \date 2011
11  *
12  *
13  * \par Copyright 1995-2017 Shark Development Team
14  *
15  * <BR><HR>
16  * This file is part of Shark.
17  * <http://shark-ml.org/>
18  *
19  * Shark is free software: you can redistribute it and/or modify
20  * it under the terms of the GNU Lesser General Public License as published
21  * by the Free Software Foundation, either version 3 of the License, or
22  * (at your option) any later version.
23  *
24  * Shark is distributed in the hope that it will be useful,
25  * but WITHOUT ANY WARRANTY; without even the implied warranty of
26  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
27  * GNU Lesser General Public License for more details.
28  *
29  * You should have received a copy of the GNU Lesser General Public License
30  * along with Shark. If not, see <http://www.gnu.org/licenses/>.
31  *
32  */
33 
34 #ifndef SHARK_OBJECTIVEFUNCTIONS_ABSTRACTCOST_H
35 #define SHARK_OBJECTIVEFUNCTIONS_ABSTRACTCOST_H
36 
37 
38 #include <shark/LinAlg/Base.h>
39 #include <shark/Core/INameable.h>
40 #include <shark/Core/Flags.h>
41 #include <shark/Data/Dataset.h>
42 
43 namespace shark {
44 
45 
46 /// \brief Cost function interface
47 ///
48 /// \par
49 /// In Shark a cost function encodes the severity of a deviation
50 /// of predictions from targets. This concept is more general than
51 /// that or a loss function, because it does not necessarily amount
52 /// to (uniformly) averaging a loss function over samples.
53 /// In general, the loss depends on the true (training) label and
54 /// the prediction in a not necessarily symmetric way. Also, in
55 /// the most general case predictions can be in a different format
56 /// than labels. E.g., the model prediction could be a probability
57 /// distribution, while the label is a single value.
58 ///
59 /// \par
60 /// The concept of an AbstractCost function is different from that
61 /// encoded by the ErrorFunction class. A cost function compares
62 /// model predictions to labels. It does not know about the model
63 /// making the predictions, and thus it can not handle LabeledData
64 /// directly. However, it is one of the components necessary to
65 /// process LabeledData in an ErrorFunction.
66 ///
67 template<class LabelT, class OutputT = LabelT>
68 class AbstractCost : public INameable
69 {
70 public:
71  typedef OutputT OutputType;
72  typedef LabelT LabelType;
73  typedef typename Batch<OutputType>::type BatchOutputType;
74  typedef typename Batch<LabelType>::type BatchLabelType;
75 
76  virtual ~AbstractCost()
77  { }
78 
79  /// list of features a cost function can have
80  enum Feature {
81  HAS_FIRST_DERIVATIVE = 1,
82  HAS_SECOND_DERIVATIVE = 2,
83  IS_LOSS_FUNCTION = 4,
84  };
85 
86  SHARK_FEATURE_INTERFACE;
87 
88  /// returns true when the first parameter derivative is implemented
89  bool hasFirstDerivative() const{
90  return m_features & HAS_FIRST_DERIVATIVE;
91  }
92  //~ /// returns true when the second parameter derivative is implemented
93  //~ bool hasSecondDerivative() const{
94  //~ return m_features & HAS_SECOND_DERIVATIVE;
95  //~ }
96 
97  /// returns true when the cost function is in fact a loss function
98  bool isLossFunction() const{
99  return m_features & IS_LOSS_FUNCTION;
100  }
101 
102  /// Evaluates the cost of predictions, given targets.
103  /// \param targets target values
104  /// \param predictions predictions, typically made by a model
105  virtual double eval(Data<LabelType> const& targets, Data<OutputType> const& predictions) const = 0;
106 
107  double operator () (Data<LabelType> const& targets, Data<OutputType> const& predictions) const
108  { return eval(targets, predictions); }
109 };
110 
111 
112 }
113 #endif