xgboost
learner.h
Go to the documentation of this file.
1 
8 #ifndef XGBOOST_LEARNER_H_
9 #define XGBOOST_LEARNER_H_
10 
11 #include <rabit/rabit.h>
12 #include <xgboost/base.h>
13 #include <xgboost/feature_map.h>
16 #include <xgboost/model.h>
17 
18 #include <utility>
19 #include <map>
20 #include <memory>
21 #include <string>
22 #include <vector>
23 
24 namespace xgboost {
25 
26 class Metric;
27 class GradientBooster;
28 class ObjFunction;
29 class DMatrix;
30 class Json;
31 
48 class Learner : public Model, public Configurable, public rabit::Serializable {
49  public:
51  ~Learner() override;
55  virtual void Configure() = 0;
62  virtual void UpdateOneIter(int iter, DMatrix* train) = 0;
70  virtual void BoostOneIter(int iter,
71  DMatrix* train,
72  HostDeviceVector<GradientPair>* in_gpair) = 0;
80  virtual std::string EvalOneIter(int iter,
81  const std::vector<DMatrix*>& data_sets,
82  const std::vector<std::string>& data_names) = 0;
95  virtual void Predict(DMatrix* data,
96  bool output_margin,
97  HostDeviceVector<bst_float> *out_preds,
98  unsigned ntree_limit = 0,
99  bool training = false,
100  bool pred_leaf = false,
101  bool pred_contribs = false,
102  bool approx_contribs = false,
103  bool pred_interactions = false) = 0;
104 
105  void LoadModel(Json const& in) override = 0;
106  void SaveModel(Json* out) const override = 0;
107 
108  virtual void LoadModel(dmlc::Stream* fi) = 0;
109  virtual void SaveModel(dmlc::Stream* fo) const = 0;
110 
116  virtual void SetParams(Args const& args) = 0;
125  virtual void SetParam(const std::string& key, const std::string& value) = 0;
126 
135  virtual void SetAttr(const std::string& key, const std::string& value) = 0;
143  virtual bool GetAttr(const std::string& key, std::string* out) const = 0;
149  virtual bool DelAttr(const std::string& key) = 0;
154  virtual std::vector<std::string> GetAttrNames() const = 0;
158  bool AllowLazyCheckPoint() const;
166  virtual std::vector<std::string> DumpModel(const FeatureMap& fmap,
167  bool with_stats,
168  std::string format) const = 0;
174  static Learner* Create(const std::vector<std::shared_ptr<DMatrix> >& cache_data);
175 
176  virtual GenericParameter const& GetGenericParameter() const = 0;
181  virtual const std::map<std::string, std::string>& GetConfigurationArguments() const = 0;
182 
183  protected:
185  std::unique_ptr<ObjFunction> obj_;
187  std::unique_ptr<GradientBooster> gbm_;
189  std::vector<std::unique_ptr<Metric> > metrics_;
192 };
193 
194 struct LearnerModelParamLegacy;
195 
196 /*
197  * \brief Basic Model Parameters, used to describe the booster.
198  */
200  /* \brief global bias */
202  /* \brief number of features */
203  uint32_t num_feature;
204  /* \brief number of classes, if it is multi-class classification */
206 
207  LearnerModelParam() : base_score {0.5}, num_feature{0}, num_output_group{0} {}
208  // As the old `LearnerModelParamLegacy` is still used by binary IO, we keep
209  // this one as an immutable copy.
210  LearnerModelParam(LearnerModelParamLegacy const& user_param, float base_margin);
211  /* \brief Whether this parameter is initialized with LearnerModelParamLegacy. */
212  bool Initialized() const { return num_feature != 0; }
213 };
214 
215 } // namespace xgboost
216 #endif // XGBOOST_LEARNER_H_
virtual void Configure()=0
Configure Learner based on set parameters.
virtual void BoostOneIter(int iter, DMatrix *train, HostDeviceVector< GradientPair > *in_gpair)=0
Do customized gradient boosting with in_gpair. in_gair can be mutated after this call.
float bst_float
float type, used for storing statistics
Definition: base.h:111
std::vector< std::unique_ptr< Metric > > metrics_
The evaluation metrics used to evaluate the model.
Definition: learner.h:189
Definition: learner.h:199
virtual bool DelAttr(const std::string &key)=0
Delete an attribute from the booster.
virtual void UpdateOneIter(int iter, DMatrix *train)=0
update the model for one iteration With the specified objective function.
virtual void SetAttr(const std::string &key, const std::string &value)=0
Set additional attribute to the Booster.
Definition: host_device_vector.h:85
std::vector< std::pair< std::string, std::string > > Args
Definition: base.h:238
virtual void Predict(DMatrix *data, bool output_margin, HostDeviceVector< bst_float > *out_preds, unsigned ntree_limit=0, bool training=false, bool pred_leaf=false, bool pred_contribs=false, bool approx_contribs=false, bool pred_interactions=false)=0
get prediction given the model.
bool AllowLazyCheckPoint() const
Definition: generic_parameters.h:14
Defines the abstract interface for different components in XGBoost.
static Learner * Create(const std::vector< std::shared_ptr< DMatrix > > &cache_data)
Create a new instance of learner.
virtual void SetParams(Args const &args)=0
Set multiple parameters at once.
std::unique_ptr< GradientBooster > gbm_
The gradient booster used by the model.
Definition: learner.h:187
Internal data structured used by XGBoost during training. There are two ways to create a customized D...
Definition: data.h:428
A device-and-host vector abstraction layer.
bool Initialized() const
Definition: learner.h:212
Feature map data structure to help text model dump. TODO(tqchen) consider make it even more lightweig...
Definition: feature_map.h:22
Definition: model.h:17
bst_float base_score
Definition: learner.h:201
virtual bool GetAttr(const std::string &key, std::string *out) const =0
Get attribute from the booster. The property will be saved along the booster.
Definition: model.h:31
~Learner() override
virtual destructor
uint32_t num_output_group
Definition: learner.h:205
std::unique_ptr< ObjFunction > obj_
objective function
Definition: learner.h:185
Feature map data structure to help visualization and model dump.
namespace of xgboost
Definition: base.h:102
LearnerModelParam()
Definition: learner.h:207
virtual GenericParameter const & GetGenericParameter() const =0
void SaveModel(Json *out) const override=0
saves the model config to a json object
defines configuration macros of xgboost.
uint32_t num_feature
Definition: learner.h:203
Learner class that does training and prediction. This is the user facing module of xgboost training...
Definition: learner.h:48
void LoadModel(Json const &in) override=0
load the model from a json object
virtual std::vector< std::string > GetAttrNames() const =0
Get a vector of attribute names from the booster.
Data structure representing JSON format.
Definition: json.h:325
virtual std::string EvalOneIter(int iter, const std::vector< DMatrix *> &data_sets, const std::vector< std::string > &data_names)=0
evaluate the model for specific iteration using the configured metrics.
virtual const std::map< std::string, std::string > & GetConfigurationArguments() const =0
Get configuration arguments currently stored by the learner.
virtual std::vector< std::string > DumpModel(const FeatureMap &fmap, bool with_stats, std::string format) const =0
dump the model in the requested format
GenericParameter generic_parameters_
Training parameter.
Definition: learner.h:191
virtual void SetParam(const std::string &key, const std::string &value)=0
Set parameter for booster.