data.h

Go to the documentation of this file.

 
#ifndef XGBOOST_DATA_H_
#define XGBOOST_DATA_H_
 
#include <dmlc/base.h>
#include <dmlc/data.h>
#include <dmlc/serializer.h>
#include <xgboost/base.h>
#include <xgboost/generic_parameters.h>
#include <xgboost/host_device_vector.h>
#include <xgboost/linalg.h>
#include <xgboost/span.h>
#include <xgboost/string_view.h>
 
#include <algorithm>
#include <limits>
#include <memory>
#include <numeric>
#include <string>
#include <utility>
#include <vector>
 
namespace xgboost {
// forward declare dmatrix.
class DMatrix;
 
enum class DataType : uint8_t {
  kFloat32 = 1,
  kDouble = 2,
  kUInt32 = 3,
  kUInt64 = 4,
  kStr = 5
};
 
enum class FeatureType : uint8_t { kNumerical = 0, kCategorical = 1 };
 
class MetaInfo {
 public:
  static constexpr uint64_t kNumField = 12;
 
  uint64_t num_row_{0};  // NOLINT
  uint64_t num_col_{0};  // NOLINT
  uint64_t num_nonzero_{0};  // NOLINT
  linalg::Tensor<float, 2> labels;
  std::vector<bst_group_t> group_ptr_;  // NOLINT
  HostDeviceVector<bst_float> weights_;  // NOLINT
  linalg::Tensor<float, 2> base_margin_;  // NOLINT
  HostDeviceVector<bst_float> labels_lower_bound_;  // NOLINT
  HostDeviceVector<bst_float> labels_upper_bound_;  // NOLINT
 
  std::vector<std::string> feature_type_names;
  std::vector<std::string> feature_names;
  /*
   * \brief Type of each feature.  Automatically set when feature_type_names is specifed.
   */
  HostDeviceVector<FeatureType> feature_types;
  /*
   * \brief Weight of each feature, used to define the probability of each feature being
   *        selected when using column sampling.
   */
  HostDeviceVector<float> feature_weights;
 
  MetaInfo()  = default;
  MetaInfo(MetaInfo&& that) = default;
  MetaInfo& operator=(MetaInfo&& that) = default;
  MetaInfo& operator=(MetaInfo const& that) = delete;
 
  void Validate(int32_t device) const;
 
  MetaInfo Slice(common::Span<int32_t const> ridxs) const;
  inline bst_float GetWeight(size_t i) const {
    return weights_.Size() != 0 ?  weights_.HostVector()[i] : 1.0f;
  }
  inline const std::vector<size_t>& LabelAbsSort() const {
    if (label_order_cache_.size() == labels.Size()) {
      return label_order_cache_;
    }
    label_order_cache_.resize(labels.Size());
    std::iota(label_order_cache_.begin(), label_order_cache_.end(), 0);
    const auto& l = labels.Data()->HostVector();
    XGBOOST_PARALLEL_STABLE_SORT(label_order_cache_.begin(), label_order_cache_.end(),
              [&l](size_t i1, size_t i2) {return std::abs(l[i1]) < std::abs(l[i2]);});
 
    return label_order_cache_;
  }
  void Clear();
  void LoadBinary(dmlc::Stream* fi);
  void SaveBinary(dmlc::Stream* fo) const;
  void SetInfo(Context const& ctx, const char* key, const void* dptr, DataType dtype, size_t num);
  void SetInfo(Context const& ctx, StringView key, StringView interface_str);
 
  void GetInfo(char const* key, bst_ulong* out_len, DataType dtype,
               const void** out_dptr) const;
 
  void SetFeatureInfo(const char *key, const char **info, const bst_ulong size);
  void GetFeatureInfo(const char *field, std::vector<std::string>* out_str_vecs) const;
 
  /*
   * \brief Extend with other MetaInfo.
   *
   * \param that The other MetaInfo object.
   *
   * \param accumulate_rows Whether rows need to be accumulated in this function.  If
   *                        client code knows number of rows in advance, set this
   *                        parameter to false.
   * \param check_column Whether the extend method should check the consistency of
   *                     columns.
   */
  void Extend(MetaInfo const& that, bool accumulate_rows, bool check_column);
 
 private:
  void SetInfoFromHost(Context const& ctx, StringView key, Json arr);
  void SetInfoFromCUDA(Context const& ctx, StringView key, Json arr);
 
  mutable std::vector<size_t> label_order_cache_;
};
 
struct Entry {
  bst_feature_t index;
  bst_float fvalue;
  Entry() = default;
  XGBOOST_DEVICE Entry(bst_feature_t index, bst_float fvalue) : index(index), fvalue(fvalue) {}
  inline static bool CmpValue(const Entry& a, const Entry& b) {
    return a.fvalue < b.fvalue;
  }
  static bool CmpIndex(Entry const& a, Entry const& b) {
    return a.index < b.index;
  }
  inline bool operator==(const Entry& other) const {
    return (this->index == other.index && this->fvalue == other.fvalue);
  }
};
 
struct BatchParam {
  int gpu_id {-1};
  bst_bin_t max_bin{0};
  common::Span<float> hess;
  bool regen {false};
  double sparse_thresh{std::numeric_limits<double>::quiet_NaN()};
 
  BatchParam() = default;
  // GPU Hist
  BatchParam(int32_t device, bst_bin_t max_bin)
      : gpu_id{device}, max_bin{max_bin} {}
  // Hist
  BatchParam(bst_bin_t max_bin, double sparse_thresh)
      : max_bin{max_bin}, sparse_thresh{sparse_thresh} {}
  // Approx
  BatchParam(bst_bin_t max_bin, common::Span<float> hessian, bool regenerate)
      : max_bin{max_bin}, hess{hessian}, regen{regenerate} {}
 
  bool operator!=(BatchParam const& other) const {
    if (hess.empty() && other.hess.empty()) {
      return gpu_id != other.gpu_id || max_bin != other.max_bin;
    }
    return gpu_id != other.gpu_id || max_bin != other.max_bin || hess.data() != other.hess.data();
  }
  bool operator==(BatchParam const& other) const {
    return !(*this != other);
  }
};
 
struct HostSparsePageView {
  using Inst = common::Span<Entry const>;
 
  common::Span<bst_row_t const> offset;
  common::Span<Entry const> data;
 
  Inst operator[](size_t i) const {
    auto size = *(offset.data() + i + 1) - *(offset.data() + i);
    return {data.data() + *(offset.data() + i),
            static_cast<Inst::index_type>(size)};
  }
 
  size_t Size() const { return offset.size() == 0 ? 0 : offset.size() - 1; }
};
 
class SparsePage {
 public:
  // Offset for each row.
  HostDeviceVector<bst_row_t> offset;
  HostDeviceVector<Entry> data;
 
  size_t base_rowid {0};
 
  using Inst = common::Span<Entry const>;
 
  HostSparsePageView GetView() const {
    return {offset.ConstHostSpan(), data.ConstHostSpan()};
  }
 
  SparsePage() {
    this->Clear();
  }
 
  SparsePage(SparsePage const& that) = delete;
  SparsePage(SparsePage&& that) = default;
  SparsePage& operator=(SparsePage const& that) = delete;
  SparsePage& operator=(SparsePage&& that) = default;
  virtual ~SparsePage() = default;
 
  inline size_t Size() const {
    return offset.Size() == 0 ? 0 : offset.Size() - 1;
  }
 
  inline size_t MemCostBytes() const {
    return offset.Size() * sizeof(size_t) + data.Size() * sizeof(Entry);
  }
 
  inline void Clear() {
    base_rowid = 0;
    auto& offset_vec = offset.HostVector();
    offset_vec.clear();
    offset_vec.push_back(0);
    data.HostVector().clear();
  }
 
  inline void SetBaseRowId(size_t row_id) {
    base_rowid = row_id;
  }
 
  SparsePage GetTranspose(int num_columns, int32_t n_threads) const;
 
  void SortIndices(int32_t n_threads);
  bool IsIndicesSorted(int32_t n_threads) const;
 
  void SortRows(int32_t n_threads);
 
  template <typename AdapterBatchT>
  uint64_t Push(const AdapterBatchT& batch, float missing, int nthread);
 
  void Push(const SparsePage &batch);
  void PushCSC(const SparsePage& batch);
};
 
class CSCPage: public SparsePage {
 public:
  CSCPage() : SparsePage() {}
  explicit CSCPage(SparsePage page) : SparsePage(std::move(page)) {}
};
 
class ExtSparsePage {
 public:
  std::shared_ptr<SparsePage const> page;
  explicit ExtSparsePage(std::shared_ptr<SparsePage const> p) : page{std::move(p)} {}
};
 
class SortedCSCPage : public SparsePage {
 public:
  SortedCSCPage() : SparsePage() {}
  explicit SortedCSCPage(SparsePage page) : SparsePage(std::move(page)) {}
};
 
class EllpackPageImpl;
class EllpackPage {
 public:
  EllpackPage();
 
  explicit EllpackPage(DMatrix* dmat, const BatchParam& param);
 
  ~EllpackPage();
 
  EllpackPage(EllpackPage&& that);
 
  size_t Size() const;
 
  void SetBaseRowId(size_t row_id);
 
  const EllpackPageImpl* Impl() const { return impl_.get(); }
  EllpackPageImpl* Impl() { return impl_.get(); }
 
 private:
  std::unique_ptr<EllpackPageImpl> impl_;
};
 
class GHistIndexMatrix;
 
template<typename T>
class BatchIteratorImpl {
 public:
  using iterator_category = std::forward_iterator_tag;  // NOLINT
  virtual ~BatchIteratorImpl() = default;
  virtual const T& operator*() const = 0;
  virtual BatchIteratorImpl& operator++() = 0;
  virtual bool AtEnd() const = 0;
  virtual std::shared_ptr<T const> Page() const = 0;
};
 
template<typename T>
class BatchIterator {
 public:
  using iterator_category = std::forward_iterator_tag;  // NOLINT
  explicit BatchIterator(BatchIteratorImpl<T>* impl) { impl_.reset(impl); }
  explicit BatchIterator(std::shared_ptr<BatchIteratorImpl<T>> impl) { impl_ = impl; }
 
  BatchIterator &operator++() {
    CHECK(impl_ != nullptr);
    ++(*impl_);
    return *this;
  }
 
  const T& operator*() const {
    CHECK(impl_ != nullptr);
    return *(*impl_);
  }
 
  bool operator!=(const BatchIterator&) const {
    CHECK(impl_ != nullptr);
    return !impl_->AtEnd();
  }
 
  bool AtEnd() const {
    CHECK(impl_ != nullptr);
    return impl_->AtEnd();
  }
 
  std::shared_ptr<T const> Page() const {
    return impl_->Page();
  }
 
 private:
  std::shared_ptr<BatchIteratorImpl<T>> impl_;
};
 
template<typename T>
class BatchSet {
 public:
  explicit BatchSet(BatchIterator<T> begin_iter) : begin_iter_(std::move(begin_iter)) {}
  BatchIterator<T> begin() { return begin_iter_; }  // NOLINT
  BatchIterator<T> end() { return BatchIterator<T>(nullptr); }  // NOLINT
 
 private:
  BatchIterator<T> begin_iter_;
};
 
struct XGBAPIThreadLocalEntry;
 
class DMatrix {
 public:
  DMatrix()  = default;
  virtual MetaInfo& Info() = 0;
  virtual void SetInfo(const char* key, const void* dptr, DataType dtype, size_t num) {
    auto const& ctx = *this->Ctx();
    this->Info().SetInfo(ctx, key, dptr, dtype, num);
  }
  virtual void SetInfo(const char* key, std::string const& interface_str) {
    auto const& ctx = *this->Ctx();
    this->Info().SetInfo(ctx, key, StringView{interface_str});
  }
  virtual const MetaInfo& Info() const = 0;
 
  XGBAPIThreadLocalEntry& GetThreadLocal() const;
  virtual Context const* Ctx() const = 0;
 
  template <typename T>
  BatchSet<T> GetBatches();
  template <typename T>
  BatchSet<T> GetBatches(const BatchParam& param);
  template <typename T>
  bool PageExists() const;
 
  // the following are column meta data, should be able to answer them fast.
  virtual bool SingleColBlock() const = 0;
  virtual ~DMatrix();
 
  bool IsDense() const {
    return Info().num_nonzero_ == Info().num_row_ * Info().num_col_;
  }
 
  static DMatrix* Load(const std::string& uri,
                       bool silent,
                       bool load_row_split,
                       const std::string& file_format = "auto");
 
  template <typename AdapterT>
  static DMatrix* Create(AdapterT* adapter, float missing, int nthread,
                         const std::string& cache_prefix = "");
 
  template <typename DataIterHandle, typename DMatrixHandle, typename DataIterResetCallback,
            typename XGDMatrixCallbackNext>
  static DMatrix* Create(DataIterHandle iter, DMatrixHandle proxy, std::shared_ptr<DMatrix> ref,
                         DataIterResetCallback* reset, XGDMatrixCallbackNext* next, float missing,
                         int nthread, bst_bin_t max_bin);
 
  template <typename DataIterHandle, typename DMatrixHandle,
            typename DataIterResetCallback, typename XGDMatrixCallbackNext>
  static DMatrix *Create(DataIterHandle iter, DMatrixHandle proxy,
                         DataIterResetCallback *reset,
                         XGDMatrixCallbackNext *next, float missing,
                         int32_t nthread, std::string cache);
 
  virtual DMatrix *Slice(common::Span<int32_t const> ridxs) = 0;
  static const size_t kPageSize = 32UL << 12UL;
 
 protected:
  virtual BatchSet<SparsePage> GetRowBatches() = 0;
  virtual BatchSet<CSCPage> GetColumnBatches() = 0;
  virtual BatchSet<SortedCSCPage> GetSortedColumnBatches() = 0;
  virtual BatchSet<EllpackPage> GetEllpackBatches(const BatchParam& param) = 0;
  virtual BatchSet<GHistIndexMatrix> GetGradientIndex(const BatchParam& param) = 0;
  virtual BatchSet<ExtSparsePage> GetExtBatches(BatchParam const& param) = 0;
 
  virtual bool EllpackExists() const = 0;
  virtual bool GHistIndexExists() const = 0;
  virtual bool SparsePageExists() const = 0;
};
 
template<>
inline BatchSet<SparsePage> DMatrix::GetBatches() {
  return GetRowBatches();
}
 
template <>
inline bool DMatrix::PageExists<EllpackPage>() const {
  return this->EllpackExists();
}
 
template <>
inline bool DMatrix::PageExists<GHistIndexMatrix>() const {
  return this->GHistIndexExists();
}
 
template<>
inline bool DMatrix::PageExists<SparsePage>() const {
  return this->SparsePageExists();
}
 
template<>
inline BatchSet<CSCPage> DMatrix::GetBatches() {
  return GetColumnBatches();
}
 
template<>
inline BatchSet<SortedCSCPage> DMatrix::GetBatches() {
  return GetSortedColumnBatches();
}
 
template<>
inline BatchSet<EllpackPage> DMatrix::GetBatches(const BatchParam& param) {
  return GetEllpackBatches(param);
}
 
template <>
inline BatchSet<GHistIndexMatrix> DMatrix::GetBatches(const BatchParam& param) {
  return GetGradientIndex(param);
}
 
template <>
inline BatchSet<ExtSparsePage> DMatrix::GetBatches() {
  return GetExtBatches(BatchParam{});
}
}  // namespace xgboost
 
namespace dmlc {
DMLC_DECLARE_TRAITS(is_pod, xgboost::Entry, true);
 
namespace serializer {
 
template <>
struct Handler<xgboost::Entry> {
  inline static void Write(Stream* strm, const xgboost::Entry& data) {
    strm->Write(data.index);
    strm->Write(data.fvalue);
  }
 
  inline static bool Read(Stream* strm, xgboost::Entry* data) {
    return strm->Read(&data->index) && strm->Read(&data->fvalue);
  }
};
 
}  // namespace serializer
}  // namespace dmlc
#endif  // XGBOOST_DATA_H_