boosting.h 5.01 KB
Newer Older
Guolin Ke's avatar
Guolin Ke committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
#ifndef LIGHTGBM_BOOSTING_H_
#define LIGHTGBM_BOOSTING_H_

#include <LightGBM/meta.h>
#include <LightGBM/config.h>

#include <vector>
#include <string>

namespace LightGBM {

/*! \brief forward declaration */
class Dataset;
class ObjectiveFunction;
class Metric;

/*!
* \brief The interface for Boosting
*/
class Boosting {
public:
  /*! \brief virtual destructor */
  virtual ~Boosting() {}

  /*!
Qiwei Ye's avatar
Qiwei Ye committed
26
27
  * \brief Initialization logic
  * \param config Configs for boosting
Guolin Ke's avatar
Guolin Ke committed
28
29
30
31
  * \param train_data Training data
  * \param object_function Training objective function
  * \param training_metrics Training metric
  */
32
33
34
  virtual void Init(
    const BoostingConfig* config,
    const Dataset* train_data,
Guolin Ke's avatar
Guolin Ke committed
35
    const ObjectiveFunction* object_function,
36
    const std::vector<const Metric*>& training_metrics) = 0;
Guolin Ke's avatar
Guolin Ke committed
37
38
39
40
41
42
43
44
45

  /*!
  * \brief Add a validation data
  * \param valid_data Validation data
  * \param valid_metrics Metric for validation data
  */
  virtual void AddDataset(const Dataset* valid_data,
    const std::vector<const Metric*>& valid_metrics) = 0;

Guolin Ke's avatar
Guolin Ke committed
46
47
48
49
  /*!
  * \brief Training logic
  * \param gradient nullptr for using default objective, otherwise use self-defined boosting
  * \param hessian nullptr for using default objective, otherwise use self-defined boosting
Guolin Ke's avatar
Guolin Ke committed
50
  * \param is_eval true if need evaluation or early stop
Guolin Ke's avatar
Guolin Ke committed
51
52
  * \return True if meet early stopping or cannot boosting
  */
53
54
  virtual bool TrainOneIter(const score_t* gradient, const score_t* hessian, bool is_eval) = 0;

Guolin Ke's avatar
Guolin Ke committed
55
  virtual bool EvalAndCheckEarlyStopping() = 0;
Guolin Ke's avatar
Guolin Ke committed
56
57
58
59
60
  /*!
  * \brief Get evaluation result at data_idx data
  * \param data_idx 0: training data, 1: 1st validation data
  * \return evaluation result
  */
61
  virtual std::vector<double> GetEvalAt(int data_idx) const = 0;
62

Guolin Ke's avatar
Guolin Ke committed
63
64
  /*!
  * \brief Get current training score
Guolin Ke's avatar
Guolin Ke committed
65
  * \param out_len length of returned score
Guolin Ke's avatar
Guolin Ke committed
66
67
  * \return training score
  */
68
  virtual const score_t* GetTrainingScore(data_size_t* out_len) = 0;
Guolin Ke's avatar
Guolin Ke committed
69

Guolin Ke's avatar
Guolin Ke committed
70
71
72
73
74
75
76
  /*!
  * \brief Get prediction result at data_idx data
  * \param data_idx 0: training data, 1: 1st validation data
  * \param result used to store prediction result, should allocate memory before call this function
  * \param out_len lenght of returned score
  */
  virtual void GetPredictAt(int data_idx, score_t* result, data_size_t* out_len) const = 0;
Guolin Ke's avatar
Guolin Ke committed
77

Guolin Ke's avatar
Guolin Ke committed
78
  /*!
Hui Xue's avatar
Hui Xue committed
79
  * \brief Prediction for one record, not sigmoid transform
Guolin Ke's avatar
Guolin Ke committed
80
81
82
  * \param feature_values Feature value on this record
  * \return Prediction result for this record
  */
83
  virtual std::vector<double> PredictRaw(const double* feature_values) const = 0;
Guolin Ke's avatar
Guolin Ke committed
84
85

  /*!
Qiwei Ye's avatar
Qiwei Ye committed
86
  * \brief Prediction for one record, sigmoid transformation will be used if needed
Guolin Ke's avatar
Guolin Ke committed
87
88
89
  * \param feature_values Feature value on this record
  * \return Prediction result for this record
  */
90
  virtual std::vector<double> Predict(const double* feature_values) const = 0;
wxchan's avatar
wxchan committed
91
92
93
94
95
96
  
  /*!
  * \brief Predtion for one record with leaf index
  * \param feature_values Feature value on this record
  * \return Predicted leaf index for this record
  */
97
  virtual std::vector<int> PredictLeafIndex(
98
    const double* feature_values) const = 0;
99

Guolin Ke's avatar
Guolin Ke committed
100
  /*!
101
  * \brief save model to file
Guolin Ke's avatar
Guolin Ke committed
102
103
104
  * \param num_used_model number of model that want to save, -1 means save all
  * \param is_finish is training finished or not
  * \param filename filename that want to save to
Guolin Ke's avatar
Guolin Ke committed
105
  */
Guolin Ke's avatar
Guolin Ke committed
106
  virtual void SaveModelToFile(int num_used_model, bool is_finish, const char* filename) = 0;
Guolin Ke's avatar
Guolin Ke committed
107
108
109
110
111

  /*!
  * \brief Restore from a serialized string
  * \param model_str The string of model
  */
Guolin Ke's avatar
Guolin Ke committed
112
  virtual void LoadModelFromString(const std::string& model_str) = 0;
Guolin Ke's avatar
Guolin Ke committed
113
114
115
116
117
118
119

  /*!
  * \brief Get max feature index of this model
  * \return Max feature index of this model
  */
  virtual int MaxFeatureIdx() const = 0;

Guolin Ke's avatar
Guolin Ke committed
120
121
122
123
124
125
  /*!
  * \brief Get index of label column
  * \return index of label column
  */
  virtual int LabelIdx() const = 0;

Guolin Ke's avatar
Guolin Ke committed
126
127
128
129
130
  /*!
  * \brief Get number of weak sub-models
  * \return Number of weak sub-models
  */
  virtual int NumberOfSubModels() const = 0;
131
132
133
134
135
  
  /*!
  * \brief Get number of classes
  * \return Number of classes
  */
Guolin Ke's avatar
Guolin Ke committed
136
  virtual int NumberOfClasses() const = 0;
137
138
139
140
141

  /*!
  * \brief Set number of used model for prediction
  */
  virtual void SetNumUsedModel(int num_used_model) = 0;
142
  
143
144
145
146
147
  /*!
  * \brief Get Type name of this boosting object
  */
  virtual const char* Name() const = 0;

Guolin Ke's avatar
Guolin Ke committed
148
149
150
151
152
153
  Boosting() = default;
  /*! \brief Disable copy */
  Boosting& operator=(const Boosting&) = delete;
  /*! \brief Disable copy */
  Boosting(const Boosting&) = delete;

154
  static void LoadFileToBoosting(Boosting* boosting, const char* filename);
Guolin Ke's avatar
Guolin Ke committed
155
156
157
  /*!
  * \brief Create boosting object
  * \param type Type of boosting
158
159
  * \param config config for boosting
  * \param filename name of model file, if existing will continue to train from this model
Guolin Ke's avatar
Guolin Ke committed
160
161
  * \return The boosting object
  */
162
163
164
165
166
167
168
169
170
  static Boosting* CreateBoosting(BoostingType type, const char* filename);

  /*!
  * \brief Create boosting object from model file
  * \param filename name of model file
  * \return The boosting object
  */
  static Boosting* CreateBoosting(const char* filename);

Guolin Ke's avatar
Guolin Ke committed
171
172
173
174
};

}  // namespace LightGBM

Guolin Ke's avatar
Guolin Ke committed
175
#endif   // LightGBM_BOOSTING_H_