xgboost
learner.h
Go to the documentation of this file.
1 
8 #ifndef XGBOOST_LEARNER_H_
9 #define XGBOOST_LEARNER_H_
10 
11 #include <dmlc/any.h>
12 #include <xgboost/base.h>
13 #include <xgboost/feature_map.h>
16 #include <xgboost/model.h>
17 #include <xgboost/predictor.h>
18 #include <xgboost/task.h>
19 
20 #include <map>
21 #include <memory>
22 #include <string>
23 #include <utility>
24 #include <vector>
25 
26 namespace xgboost {
27 
28 class Metric;
29 class GradientBooster;
30 class ObjFunction;
31 class DMatrix;
32 class Json;
33 
34 enum class PredictionType : std::uint8_t { // NOLINT
35  kValue = 0,
36  kMargin = 1,
37  kContribution = 2,
39  kInteraction = 4,
41  kLeaf = 6
42 };
43 
47  std::string ret_str;
49  std::vector<char> ret_char_vec;
51  std::vector<std::string> ret_vec_str;
53  std::vector<const char *> ret_vec_charp;
55  std::vector<bst_float> ret_vec_float;
57  std::vector<GradientPair> tmp_gpair;
61  std::vector<bst_ulong> prediction_shape;
62 };
63 
80 class Learner : public Model, public Configurable, public dmlc::Serializable {
81  public:
83  ~Learner() override;
87  virtual void Configure() = 0;
94  virtual void UpdateOneIter(int iter, std::shared_ptr<DMatrix> train) = 0;
102  virtual void BoostOneIter(int iter,
103  std::shared_ptr<DMatrix> train,
104  HostDeviceVector<GradientPair>* in_gpair) = 0;
112  virtual std::string EvalOneIter(int iter,
113  const std::vector<std::shared_ptr<DMatrix>>& data_sets,
114  const std::vector<std::string>& data_names) = 0;
128  virtual void Predict(std::shared_ptr<DMatrix> data,
129  bool output_margin,
130  HostDeviceVector<bst_float> *out_preds,
131  unsigned layer_begin,
132  unsigned layer_end,
133  bool training = false,
134  bool pred_leaf = false,
135  bool pred_contribs = false,
136  bool approx_contribs = false,
137  bool pred_interactions = false) = 0;
138 
151  virtual void InplacePredict(dmlc::any const &x,
152  std::shared_ptr<DMatrix> p_m,
153  PredictionType type,
154  float missing,
155  HostDeviceVector<bst_float> **out_preds,
156  uint32_t layer_begin, uint32_t layer_end) = 0;
157 
161  virtual void CalcFeatureScore(std::string const& importance_type,
163  std::vector<bst_feature_t>* features,
164  std::vector<float>* scores) = 0;
165 
166  /*
167  * \brief Get number of boosted rounds from gradient booster.
168  */
169  virtual int32_t BoostedRounds() const = 0;
170  virtual uint32_t Groups() const = 0;
171 
172  void LoadModel(Json const& in) override = 0;
173  void SaveModel(Json* out) const override = 0;
174 
175  virtual void LoadModel(dmlc::Stream* fi) = 0;
176  virtual void SaveModel(dmlc::Stream* fo) const = 0;
177 
183  virtual void SetParams(Args const& args) = 0;
192  virtual void SetParam(const std::string& key, const std::string& value) = 0;
193 
198  virtual uint32_t GetNumFeature() const = 0;
199 
208  virtual void SetAttr(const std::string& key, const std::string& value) = 0;
216  virtual bool GetAttr(const std::string& key, std::string* out) const = 0;
222  virtual bool DelAttr(const std::string& key) = 0;
227  virtual std::vector<std::string> GetAttrNames() const = 0;
232  virtual void SetFeatureNames(std::vector<std::string> const& fn) = 0;
237  virtual void GetFeatureNames(std::vector<std::string>* fn) const = 0;
242  virtual void SetFeatureTypes(std::vector<std::string> const& ft) = 0;
247  virtual void GetFeatureTypes(std::vector<std::string>* ft) const = 0;
248 
252  bool AllowLazyCheckPoint() const;
263  virtual Learner *Slice(int32_t begin_layer, int32_t end_layer, int32_t step,
264  bool *out_of_bound) = 0;
272  virtual std::vector<std::string> DumpModel(const FeatureMap& fmap,
273  bool with_stats,
274  std::string format) = 0;
275 
276  virtual XGBAPIThreadLocalEntry& GetThreadLocal() const = 0;
282  static Learner* Create(const std::vector<std::shared_ptr<DMatrix> >& cache_data);
286  virtual GenericParameter const* Ctx() const = 0;
291  virtual const std::map<std::string, std::string>& GetConfigurationArguments() const = 0;
292 
293  protected:
295  std::unique_ptr<ObjFunction> obj_;
297  std::unique_ptr<GradientBooster> gbm_;
299  std::vector<std::unique_ptr<Metric> > metrics_;
302 };
303 
304 struct LearnerModelParamLegacy;
305 
306 /*
307  * \brief Basic Model Parameters, used to describe the booster.
308  */
310  /* \brief global bias */
312  /* \brief number of features */
313  uint32_t num_feature { 0 };
314  /* \brief number of classes, if it is multi-class classification */
315  uint32_t num_output_group { 0 };
316  /* \brief Current task, determined by objective. */
318 
319  LearnerModelParam() = default;
320  // As the old `LearnerModelParamLegacy` is still used by binary IO, we keep
321  // this one as an immutable copy.
322  LearnerModelParam(LearnerModelParamLegacy const& user_param, float base_margin, ObjInfo t);
323  /* \brief Whether this parameter is initialized with LearnerModelParamLegacy. */
324  bool Initialized() const { return num_feature != 0; }
325 };
326 
327 } // namespace xgboost
328 #endif // XGBOOST_LEARNER_H_
xgboost::Args
std::vector< std::pair< std::string, std::string > > Args
Definition: base.h:265
xgboost::Learner::DumpModel
virtual std::vector< std::string > DumpModel(const FeatureMap &fmap, bool with_stats, std::string format)=0
dump the model in the requested format
predictor.h
Interface of predictor, performs predictions for a gradient booster.
task.h
xgboost::XGBAPIThreadLocalEntry::prediction_entry
PredictionCacheEntry prediction_entry
Temp variable for returning prediction result.
Definition: learner.h:59
xgboost::PredictionCacheEntry
Contains pointer to input matrix and associated cached predictions.
Definition: predictor.h:35
xgboost::LearnerModelParam::num_output_group
uint32_t num_output_group
Definition: learner.h:315
model.h
Defines the abstract interface for different components in XGBoost.
xgboost::Learner::Slice
virtual Learner * Slice(int32_t begin_layer, int32_t end_layer, int32_t step, bool *out_of_bound)=0
Slice the model.
xgboost::Learner::SetParams
virtual void SetParams(Args const &args)=0
Set multiple parameters at once.
xgboost::Learner::Configure
virtual void Configure()=0
Configure Learner based on set parameters.
xgboost::Learner::GetFeatureNames
virtual void GetFeatureNames(std::vector< std::string > *fn) const =0
Get the feature names for current booster.
xgboost::GenericParameter
Definition: generic_parameters.h:15
xgboost::PredictionType::kInteraction
@ kInteraction
xgboost::ObjInfo::kRegression
@ kRegression
Definition: task.h:27
xgboost::HostDeviceVector
Definition: host_device_vector.h:86
xgboost::XGBAPIThreadLocalEntry::ret_vec_charp
std::vector< const char * > ret_vec_charp
result holder for returning string pointers
Definition: learner.h:53
xgboost::Learner::BoostOneIter
virtual void BoostOneIter(int iter, std::shared_ptr< DMatrix > train, HostDeviceVector< GradientPair > *in_gpair)=0
Do customized gradient boosting with in_gpair. in_gair can be mutated after this call.
xgboost::LearnerModelParam::Initialized
bool Initialized() const
Definition: learner.h:324
host_device_vector.h
A device-and-host vector abstraction layer.
xgboost::LearnerModelParam::base_score
bst_float base_score
Definition: learner.h:311
xgboost::Learner::SetParam
virtual void SetParam(const std::string &key, const std::string &value)=0
Set parameter for booster.
xgboost::Learner::Predict
virtual void Predict(std::shared_ptr< DMatrix > data, bool output_margin, HostDeviceVector< bst_float > *out_preds, unsigned layer_begin, unsigned layer_end, 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.
base.h
defines configuration macros of xgboost.
xgboost::XGBAPIThreadLocalEntry::prediction_shape
std::vector< bst_ulong > prediction_shape
Temp variable for returning prediction shape.
Definition: learner.h:61
xgboost::Learner::Ctx
virtual GenericParameter const * Ctx() const =0
Return the context object of this Booster.
xgboost::PredictionType::kContribution
@ kContribution
feature_map.h
Feature map data structure to help visualization and model dump.
xgboost::XGBAPIThreadLocalEntry::ret_str
std::string ret_str
result holder for returning string
Definition: learner.h:47
xgboost::Learner::obj_
std::unique_ptr< ObjFunction > obj_
objective function
Definition: learner.h:295
xgboost::XGBAPIThreadLocalEntry::ret_vec_float
std::vector< bst_float > ret_vec_float
returning float vector.
Definition: learner.h:55
xgboost::Learner::gbm_
std::unique_ptr< GradientBooster > gbm_
The gradient booster used by the model.
Definition: learner.h:297
xgboost::LearnerModelParam
Definition: learner.h:309
xgboost::FeatureMap
Feature map data structure to help text model dump. TODO(tqchen) consider make it even more lightweig...
Definition: feature_map.h:22
xgboost::Learner::SetAttr
virtual void SetAttr(const std::string &key, const std::string &value)=0
Set additional attribute to the Booster.
xgboost::Learner::GetAttr
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.
xgboost::Learner::GetFeatureTypes
virtual void GetFeatureTypes(std::vector< std::string > *ft) const =0
Get the feature types for current booster.
xgboost::Learner::UpdateOneIter
virtual void UpdateOneIter(int iter, std::shared_ptr< DMatrix > train)=0
update the model for one iteration With the specified objective function.
xgboost::XGBAPIThreadLocalEntry::ret_vec_str
std::vector< std::string > ret_vec_str
result holder for returning strings
Definition: learner.h:51
xgboost::Model
Definition: model.h:17
xgboost::Learner::Create
static Learner * Create(const std::vector< std::shared_ptr< DMatrix > > &cache_data)
Create a new instance of learner.
xgboost::Learner::AllowLazyCheckPoint
bool AllowLazyCheckPoint() const
xgboost::PredictionType::kApproxInteraction
@ kApproxInteraction
xgboost::LearnerModelParam::task
ObjInfo task
Definition: learner.h:317
xgboost::Learner::InplacePredict
virtual void InplacePredict(dmlc::any const &x, std::shared_ptr< DMatrix > p_m, PredictionType type, float missing, HostDeviceVector< bst_float > **out_preds, uint32_t layer_begin, uint32_t layer_end)=0
Inplace prediction.
xgboost::PredictionType::kLeaf
@ kLeaf
xgboost::Learner::SetFeatureNames
virtual void SetFeatureNames(std::vector< std::string > const &fn)=0
Set the feature names for current booster.
xgboost::PredictionType::kValue
@ kValue
xgboost::Learner::Groups
virtual uint32_t Groups() const =0
xgboost::Configurable
Definition: model.h:31
xgboost::XGBAPIThreadLocalEntry::tmp_gpair
std::vector< GradientPair > tmp_gpair
temp variable of gradient pairs.
Definition: learner.h:57
xgboost::Learner::GetNumFeature
virtual uint32_t GetNumFeature() const =0
Get the number of features of the booster.
xgboost::Learner::~Learner
~Learner() override
virtual destructor
xgboost::Learner::generic_parameters_
GenericParameter generic_parameters_
Training parameter.
Definition: learner.h:301
xgboost::XGBAPIThreadLocalEntry
entry to to easily hold returning information
Definition: learner.h:45
xgboost::Learner::GetAttrNames
virtual std::vector< std::string > GetAttrNames() const =0
Get a vector of attribute names from the booster.
generic_parameters.h
xgboost::common::Span
span class implementation, based on ISO++20 span<T>. The interface should be the same.
Definition: span.h:148
xgboost::PredictionType::kMargin
@ kMargin
xgboost::Learner::GetConfigurationArguments
virtual const std::map< std::string, std::string > & GetConfigurationArguments() const =0
Get configuration arguments currently stored by the learner.
xgboost::Learner::CalcFeatureScore
virtual void CalcFeatureScore(std::string const &importance_type, common::Span< int32_t const > trees, std::vector< bst_feature_t > *features, std::vector< float > *scores)=0
Calculate feature score. See doc in C API for outputs.
xgboost::XGBAPIThreadLocalEntry::ret_char_vec
std::vector< char > ret_char_vec
result holder for returning raw buffer
Definition: learner.h:49
xgboost::Learner::SaveModel
void SaveModel(Json *out) const override=0
saves the model config to a JSON object
xgboost::Learner
Learner class that does training and prediction. This is the user facing module of xgboost training....
Definition: learner.h:80
xgboost::Learner::EvalOneIter
virtual std::string EvalOneIter(int iter, const std::vector< std::shared_ptr< DMatrix >> &data_sets, const std::vector< std::string > &data_names)=0
evaluate the model for specific iteration using the configured metrics.
xgboost::Learner::metrics_
std::vector< std::unique_ptr< Metric > > metrics_
The evaluation metrics used to evaluate the model.
Definition: learner.h:299
xgboost::Learner::GetThreadLocal
virtual XGBAPIThreadLocalEntry & GetThreadLocal() const =0
xgboost::Json
Data structure representing JSON format.
Definition: json.h:352
xgboost::LearnerModelParam::LearnerModelParam
LearnerModelParam()=default
xgboost::Learner::BoostedRounds
virtual int32_t BoostedRounds() const =0
xgboost::LearnerModelParam::num_feature
uint32_t num_feature
Definition: learner.h:313
xgboost::PredictionType
PredictionType
Definition: learner.h:34
xgboost::ObjInfo
A struct returned by objective, which determines task at hand. The struct is not used by any algorith...
Definition: task.h:24
xgboost::PredictionType::kApproxContribution
@ kApproxContribution
xgboost::Learner::DelAttr
virtual bool DelAttr(const std::string &key)=0
Delete an attribute from the booster.
xgboost::Learner::SetFeatureTypes
virtual void SetFeatureTypes(std::vector< std::string > const &ft)=0
Set the feature types for current booster.
xgboost::Learner::LoadModel
void LoadModel(Json const &in) override=0
load the model from a JSON object
xgboost
namespace of xgboost
Definition: base.h:110
xgboost::bst_float
float bst_float
float type, used for storing statistics
Definition: base.h:119