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/io.h> // for Serializable
12 #include <xgboost/base.h> // for bst_feature_t, bst_target_t, bst_float, Args, GradientPair, ..
13 #include <xgboost/context.h> // for Context
14 #include <xgboost/linalg.h> // for Tensor, TensorView
15 #include <xgboost/metric.h> // for Metric
16 #include <xgboost/model.h> // for Configurable, Model
17 #include <xgboost/span.h> // for Span
18 #include <xgboost/task.h> // for ObjInfo
19 
20 #include <algorithm> // for max
21 #include <cstdint> // for int32_t, uint32_t, uint8_t
22 #include <map> // for map
23 #include <memory> // for shared_ptr, unique_ptr
24 #include <string> // for string
25 #include <utility> // for move
26 #include <vector> // for vector
27 
28 namespace xgboost {
29 class FeatureMap;
30 class Metric;
31 class GradientBooster;
32 class ObjFunction;
33 class DMatrix;
34 class Json;
35 struct XGBAPIThreadLocalEntry;
36 template <typename T>
37 class HostDeviceVector;
38 
39 enum class PredictionType : std::uint8_t { // NOLINT
40  kValue = 0,
41  kMargin = 1,
42  kContribution = 2,
44  kInteraction = 4,
46  kLeaf = 6
47 };
48 
65 class Learner : public Model, public Configurable, public dmlc::Serializable {
66  public:
68  ~Learner() override;
72  virtual void Configure() = 0;
79  virtual void UpdateOneIter(std::int32_t iter, std::shared_ptr<DMatrix> train) = 0;
89  virtual void BoostOneIter(std::int32_t iter, std::shared_ptr<DMatrix> train,
90  linalg::Matrix<GradientPair>* in_gpair) = 0;
98  virtual std::string EvalOneIter(int iter,
99  const std::vector<std::shared_ptr<DMatrix>>& data_sets,
100  const std::vector<std::string>& data_names) = 0;
114  virtual void Predict(std::shared_ptr<DMatrix> data, bool output_margin,
115  HostDeviceVector<bst_float>* out_preds, bst_layer_t layer_begin,
116  bst_layer_t layer_end, bool training = false, bool pred_leaf = false,
117  bool pred_contribs = false, bool approx_contribs = false,
118  bool pred_interactions = false) = 0;
119 
130  virtual void InplacePredict(std::shared_ptr<DMatrix> p_m, PredictionType type, float missing,
131  HostDeviceVector<float>** out_preds, bst_layer_t layer_begin,
132  bst_layer_t layer_end) = 0;
133 
137  virtual void CalcFeatureScore(std::string const& importance_type,
139  std::vector<bst_feature_t>* features,
140  std::vector<float>* scores) = 0;
141 
142  /*
143  * \brief Get number of boosted rounds from gradient booster.
144  */
145  virtual int32_t BoostedRounds() const = 0;
149  virtual std::uint32_t Groups() const = 0;
150 
151  void LoadModel(Json const& in) override = 0;
152  void SaveModel(Json* out) const override = 0;
153 
154  virtual void LoadModel(dmlc::Stream* fi) = 0;
155  virtual void SaveModel(dmlc::Stream* fo) const = 0;
156 
162  virtual void SetParams(Args const& args) = 0;
171  virtual void SetParam(const std::string& key, const std::string& value) = 0;
172 
177  virtual uint32_t GetNumFeature() const = 0;
178 
187  virtual void SetAttr(const std::string& key, const std::string& value) = 0;
195  virtual bool GetAttr(const std::string& key, std::string* out) const = 0;
201  virtual bool DelAttr(const std::string& key) = 0;
206  virtual std::vector<std::string> GetAttrNames() const = 0;
211  virtual void SetFeatureNames(std::vector<std::string> const& fn) = 0;
216  virtual void GetFeatureNames(std::vector<std::string>* fn) const = 0;
221  virtual void SetFeatureTypes(std::vector<std::string> const& ft) = 0;
226  virtual void GetFeatureTypes(std::vector<std::string>* ft) const = 0;
227 
238  virtual Learner* Slice(bst_layer_t begin, bst_layer_t end, bst_layer_t step,
239  bool* out_of_bound) = 0;
247  virtual std::vector<std::string> DumpModel(const FeatureMap& fmap,
248  bool with_stats,
249  std::string format) = 0;
250 
251  virtual XGBAPIThreadLocalEntry& GetThreadLocal() const = 0;
257  static Learner* Create(const std::vector<std::shared_ptr<DMatrix> >& cache_data);
261  virtual Context const* Ctx() const = 0;
266  virtual const std::map<std::string, std::string>& GetConfigurationArguments() const = 0;
267 
268  protected:
270  std::unique_ptr<ObjFunction> obj_;
272  std::unique_ptr<GradientBooster> gbm_;
274  std::vector<std::unique_ptr<Metric> > metrics_;
277 };
278 
279 struct LearnerModelParamLegacy;
280 
284 enum class MultiStrategy : std::int32_t {
285  kOneOutputPerTree = 0,
286  kMultiOutputTree = 1,
287 };
288 
293  private:
298  linalg::Tensor<float, 1> base_score_;
299 
300  public:
308  std::uint32_t num_output_group{0};
317 
318  LearnerModelParam() = default;
319  // As the old `LearnerModelParamLegacy` is still used by binary IO, we keep
320  // this one as an immutable copy.
321  LearnerModelParam(Context const* ctx, LearnerModelParamLegacy const& user_param,
323  LearnerModelParam(LearnerModelParamLegacy const& user_param, ObjInfo t,
326  std::uint32_t n_groups, bst_target_t n_targets, MultiStrategy multi_strategy)
327  : base_score_{std::move(base_score)},
328  num_feature{n_features},
329  num_output_group{std::max(n_groups, n_targets)},
331 
334 
335  void Copy(LearnerModelParam const& that);
336  [[nodiscard]] bool IsVectorLeaf() const noexcept {
338  }
339  [[nodiscard]] bst_target_t OutputLength() const noexcept { return this->num_output_group; }
340  [[nodiscard]] bst_target_t LeafLength() const noexcept {
341  return this->IsVectorLeaf() ? this->OutputLength() : 1;
342  }
343 
344  /* \brief Whether this parameter is initialized with LearnerModelParamLegacy. */
345  [[nodiscard]] bool Initialized() const { return num_feature != 0 && num_output_group != 0; }
346 };
347 
348 } // namespace xgboost
349 #endif // XGBOOST_LEARNER_H_
Defines configuration macros and basic types for xgboost.
Feature map data structure to help text model dump. TODO(tqchen) consider make it even more lightweig...
Definition: feature_map.h:22
Data structure representing JSON format.
Definition: json.h:368
Learner class that does training and prediction. This is the user facing module of xgboost training....
Definition: learner.h:65
virtual std::vector< std::string > GetAttrNames() const =0
Get a vector of attribute names from the booster.
virtual void UpdateOneIter(std::int32_t iter, std::shared_ptr< DMatrix > train)=0
update the model for one iteration With the specified objective function.
virtual void InplacePredict(std::shared_ptr< DMatrix > p_m, PredictionType type, float missing, HostDeviceVector< float > **out_preds, bst_layer_t layer_begin, bst_layer_t layer_end)=0
Inplace prediction.
virtual void SetParam(const std::string &key, const std::string &value)=0
Set parameter for booster.
virtual void LoadModel(dmlc::Stream *fi)=0
std::vector< std::unique_ptr< Metric > > metrics_
The evaluation metrics used to evaluate the model.
Definition: learner.h:274
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.
virtual std::vector< std::string > DumpModel(const FeatureMap &fmap, bool with_stats, std::string format)=0
dump the model in the requested format
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.
~Learner() override
virtual destructor
virtual XGBAPIThreadLocalEntry & GetThreadLocal() const =0
virtual const std::map< std::string, std::string > & GetConfigurationArguments() const =0
Get configuration arguments currently stored by the learner.
virtual void SetFeatureNames(std::vector< std::string > const &fn)=0
Set the feature names for current booster.
virtual void SaveModel(dmlc::Stream *fo) const =0
virtual Context const * Ctx() const =0
Return the context object of this Booster.
virtual void Configure()=0
Configure Learner based on set parameters.
virtual int32_t BoostedRounds() const =0
virtual bool DelAttr(const std::string &key)=0
Delete an attribute from the booster.
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.
virtual void SetParams(Args const &args)=0
Set multiple parameters at once.
virtual void SetAttr(const std::string &key, const std::string &value)=0
Set additional attribute to the Booster.
std::unique_ptr< ObjFunction > obj_
objective function
Definition: learner.h:270
std::unique_ptr< GradientBooster > gbm_
The gradient booster used by the model.
Definition: learner.h:272
virtual void GetFeatureNames(std::vector< std::string > *fn) const =0
Get the feature names for current booster.
void LoadModel(Json const &in) override=0
load the model from a JSON object
virtual void SetFeatureTypes(std::vector< std::string > const &ft)=0
Set the feature types for current booster.
void SaveModel(Json *out) const override=0
saves the model config to a JSON object
static Learner * Create(const std::vector< std::shared_ptr< DMatrix > > &cache_data)
Create a new instance of learner.
virtual Learner * Slice(bst_layer_t begin, bst_layer_t end, bst_layer_t step, bool *out_of_bound)=0
Slice the model.
Context ctx_
Training parameter.
Definition: learner.h:276
virtual std::uint32_t Groups() const =0
Get the number of output groups from the model.
virtual void BoostOneIter(std::int32_t iter, std::shared_ptr< DMatrix > train, linalg::Matrix< GradientPair > *in_gpair)=0
Do customized gradient boosting with in_gpair.
virtual void Predict(std::shared_ptr< DMatrix > data, bool output_margin, HostDeviceVector< bst_float > *out_preds, bst_layer_t layer_begin, bst_layer_t 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.
virtual uint32_t GetNumFeature() const =0
Get the number of features of the booster.
virtual void GetFeatureTypes(std::vector< std::string > *ft) const =0
Get the feature types for current booster.
span class implementation, based on ISO++20 span<T>. The interface should be the same.
Definition: span.h:422
A tensor view with static type and dimension. It implements indexing and slicing.
Definition: linalg.h:294
A tensor storage. To use it for other functionality like slicing one needs to obtain a view first....
Definition: linalg.h:762
Linear algebra related utilities.
interface of evaluation metric function supported in xgboost.
Defines the abstract interface for different components in XGBoost.
Definition: intrusive_ptr.h:207
Core data structure for multi-target trees.
Definition: base.h:87
std::vector< std::pair< std::string, std::string > > Args
Definition: base.h:310
PredictionType
Definition: learner.h:39
std::uint32_t bst_target_t
Type for indexing into output targets.
Definition: base.h:113
std::int32_t bst_layer_t
Type for indexing boosted layers.
Definition: base.h:117
std::uint32_t bst_feature_t
Type for data column (feature) index.
Definition: base.h:97
MultiStrategy
Strategy for building multi-target models.
Definition: learner.h:284
Definition: model.h:31
Runtime context for XGBoost. Contains information like threads and device.
Definition: context.h:133
A type for device ordinal. The type is packed into 32-bit for efficient use in viewing types like lin...
Definition: context.h:34
Basic model parameters, used to describe the booster.
Definition: learner.h:292
std::uint32_t num_output_group
The number of classes or targets.
Definition: learner.h:308
LearnerModelParam(Context const *ctx, LearnerModelParamLegacy const &user_param, linalg::Tensor< float, 1 > base_margin, ObjInfo t, MultiStrategy multi_strategy)
bool Initialized() const
Definition: learner.h:345
LearnerModelParam(bst_feature_t n_features, linalg::Tensor< float, 1 > base_score, std::uint32_t n_groups, bst_target_t n_targets, MultiStrategy multi_strategy)
Definition: learner.h:325
MultiStrategy multi_strategy
Strategy for building multi-target models.
Definition: learner.h:316
linalg::TensorView< float const, 1 > BaseScore(DeviceOrd device) const
bst_target_t OutputLength() const noexcept
Definition: learner.h:339
LearnerModelParam(LearnerModelParamLegacy const &user_param, ObjInfo t, MultiStrategy multi_strategy)
void Copy(LearnerModelParam const &that)
linalg::TensorView< float const, 1 > BaseScore(Context const *ctx) const
bst_target_t LeafLength() const noexcept
Definition: learner.h:340
ObjInfo task
Current task, determined by objective.
Definition: learner.h:312
bool IsVectorLeaf() const noexcept
Definition: learner.h:336
bst_feature_t num_feature
The number of features.
Definition: learner.h:304
Definition: model.h:17
A struct returned by objective, which determines task at hand. The struct is not used by any algorith...
Definition: task.h:24
@ kRegression
Definition: task.h:27