learner.h

Go to the documentation of this file.

 
#ifndef XGBOOST_LEARNER_H_
#define XGBOOST_LEARNER_H_
 
#include <xgboost/base.h>
#include <xgboost/feature_map.h>
#include <xgboost/generic_parameters.h>  // Context
#include <xgboost/host_device_vector.h>
#include <xgboost/model.h>
#include <xgboost/predictor.h>
#include <xgboost/task.h>
 
#include <map>
#include <memory>
#include <string>
#include <utility>
#include <vector>
 
namespace xgboost {
 
class Metric;
class GradientBooster;
class ObjFunction;
class DMatrix;
class Json;
 
enum class PredictionType : std::uint8_t {  // NOLINT
  kValue = 0,
  kMargin = 1,
  kContribution = 2,
  kApproxContribution = 3,
  kInteraction = 4,
  kApproxInteraction = 5,
  kLeaf = 6
};
 
struct XGBAPIThreadLocalEntry {
  std::string ret_str;
  std::vector<char> ret_char_vec;
  std::vector<std::string> ret_vec_str;
  std::vector<const char *> ret_vec_charp;
  std::vector<bst_float> ret_vec_float;
  std::vector<GradientPair> tmp_gpair;
  PredictionCacheEntry prediction_entry;
  std::vector<bst_ulong> prediction_shape;
};
 
class Learner : public Model, public Configurable, public dmlc::Serializable {
 public:
  ~Learner() override;
  virtual void Configure() = 0;
  virtual void UpdateOneIter(int iter, std::shared_ptr<DMatrix> train) = 0;
  virtual void BoostOneIter(int iter,
                            std::shared_ptr<DMatrix> train,
                            HostDeviceVector<GradientPair>* in_gpair) = 0;
  virtual std::string EvalOneIter(int iter,
                                  const std::vector<std::shared_ptr<DMatrix>>& data_sets,
                                  const std::vector<std::string>& data_names) = 0;
  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;
 
  virtual void InplacePredict(std::shared_ptr<DMatrix> p_m, PredictionType type, float missing,
                              HostDeviceVector<bst_float>** out_preds, uint32_t layer_begin,
                              uint32_t layer_end) = 0;
 
  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;
 
  /*
   * \brief Get number of boosted rounds from gradient booster.
   */
  virtual int32_t BoostedRounds() const = 0;
  virtual uint32_t Groups() const = 0;
 
  void LoadModel(Json const& in) override = 0;
  void SaveModel(Json* out) const override = 0;
 
  virtual void LoadModel(dmlc::Stream* fi) = 0;
  virtual void SaveModel(dmlc::Stream* fo) const = 0;
 
  virtual void SetParams(Args const& args) = 0;
  virtual void SetParam(const std::string& key, const std::string& value) = 0;
 
  virtual uint32_t GetNumFeature() const = 0;
 
  virtual void SetAttr(const std::string& key, const std::string& value) = 0;
  virtual bool GetAttr(const std::string& key, std::string* out) const = 0;
  virtual bool DelAttr(const std::string& key) = 0;
  virtual std::vector<std::string> GetAttrNames() const = 0;
  virtual  void SetFeatureNames(std::vector<std::string> const& fn) = 0;
  virtual void GetFeatureNames(std::vector<std::string>* fn) const = 0;
  virtual void SetFeatureTypes(std::vector<std::string> const& ft) = 0;
  virtual void GetFeatureTypes(std::vector<std::string>* ft) const = 0;
 
  virtual Learner *Slice(int32_t begin_layer, int32_t end_layer, int32_t step,
                         bool *out_of_bound) = 0;
  virtual std::vector<std::string> DumpModel(const FeatureMap& fmap,
                                             bool with_stats,
                                             std::string format) = 0;
 
  virtual XGBAPIThreadLocalEntry& GetThreadLocal() const = 0;
  static Learner* Create(const std::vector<std::shared_ptr<DMatrix> >& cache_data);
  virtual Context const* Ctx() const = 0;
  virtual const std::map<std::string, std::string>& GetConfigurationArguments() const = 0;
 
 protected:
  std::unique_ptr<ObjFunction> obj_;
  std::unique_ptr<GradientBooster> gbm_;
  std::vector<std::unique_ptr<Metric> > metrics_;
  Context ctx_;
};
 
struct LearnerModelParamLegacy;
 
/*
 * \brief Basic Model Parameters, used to describe the booster.
 */
struct LearnerModelParam {
 private:
  linalg::Tensor<float, 1> base_score_;
 
 public:
  /* \brief number of features  */
  uint32_t num_feature { 0 };
  /* \brief number of classes, if it is multi-class classification  */
  uint32_t num_output_group { 0 };
  /* \brief Current task, determined by objective. */
  ObjInfo task{ObjInfo::kRegression};
 
  LearnerModelParam() = default;
  // As the old `LearnerModelParamLegacy` is still used by binary IO, we keep
  // this one as an immutable copy.
  LearnerModelParam(Context const* ctx, LearnerModelParamLegacy const& user_param,
                    linalg::Tensor<float, 1> base_margin, ObjInfo t);
  LearnerModelParam(LearnerModelParamLegacy const& user_param, ObjInfo t);
  LearnerModelParam(bst_feature_t n_features, linalg::Tensor<float, 1> base_margin,
                    uint32_t n_groups)
      : base_score_{std::move(base_margin)}, num_feature{n_features}, num_output_group{n_groups} {}
 
  linalg::TensorView<float const, 1> BaseScore(Context const* ctx) const;
  linalg::TensorView<float const, 1> BaseScore(int32_t device) const;
 
  void Copy(LearnerModelParam const& that);
 
  /* \brief Whether this parameter is initialized with LearnerModelParamLegacy. */
  bool Initialized() const { return num_feature != 0 && num_output_group != 0; }
};
 
}  // namespace xgboost
#endif  // XGBOOST_LEARNER_H_