xgboost
data.h
Go to the documentation of this file.
1 
7 #ifndef XGBOOST_DATA_H_
8 #define XGBOOST_DATA_H_
9 
10 #include <dmlc/base.h>
11 #include <dmlc/data.h>
12 #include <dmlc/serializer.h>
13 #include <rabit/rabit.h>
14 #include <xgboost/base.h>
15 #include <xgboost/span.h>
17 
18 #include <memory>
19 #include <numeric>
20 #include <algorithm>
21 #include <string>
22 #include <utility>
23 #include <vector>
24 
25 namespace xgboost {
26 // forward declare dmatrix.
27 class DMatrix;
28 
30 enum class DataType : uint8_t {
31  kFloat32 = 1,
32  kDouble = 2,
33  kUInt32 = 3,
34  kUInt64 = 4
35 };
36 
40 class MetaInfo {
41  public:
43  static constexpr uint64_t kNumField = 9;
44 
46  uint64_t num_row_{0}; // NOLINT
48  uint64_t num_col_{0}; // NOLINT
50  uint64_t num_nonzero_{0}; // NOLINT
57  std::vector<bst_group_t> group_ptr_; // NOLINT
74 
76  MetaInfo() = default;
77  MetaInfo(MetaInfo&& that) = default;
78  MetaInfo& operator=(MetaInfo&& that) = default;
79  MetaInfo& operator=(MetaInfo const& that) {
80  this->num_row_ = that.num_row_;
81  this->num_col_ = that.num_col_;
82  this->num_nonzero_ = that.num_nonzero_;
83 
84  this->labels_.Resize(that.labels_.Size());
85  this->labels_.Copy(that.labels_);
86 
87  this->group_ptr_ = that.group_ptr_;
88 
89  this->weights_.Resize(that.weights_.Size());
90  this->weights_.Copy(that.weights_);
91 
92  this->base_margin_.Resize(that.base_margin_.Size());
93  this->base_margin_.Copy(that.base_margin_);
94 
95  this->labels_lower_bound_.Resize(that.labels_lower_bound_.Size());
96  this->labels_lower_bound_.Copy(that.labels_lower_bound_);
97 
98  this->labels_upper_bound_.Resize(that.labels_upper_bound_.Size());
99  this->labels_upper_bound_.Copy(that.labels_upper_bound_);
100  return *this;
101  }
102 
106  void Validate(int32_t device) const;
107 
108  MetaInfo Slice(common::Span<int32_t const> ridxs) const;
114  inline bst_float GetWeight(size_t i) const {
115  return weights_.Size() != 0 ? weights_.HostVector()[i] : 1.0f;
116  }
118  inline const std::vector<size_t>& LabelAbsSort() const {
119  if (label_order_cache_.size() == labels_.Size()) {
120  return label_order_cache_;
121  }
122  label_order_cache_.resize(labels_.Size());
123  std::iota(label_order_cache_.begin(), label_order_cache_.end(), 0);
124  const auto& l = labels_.HostVector();
125  XGBOOST_PARALLEL_SORT(label_order_cache_.begin(), label_order_cache_.end(),
126  [&l](size_t i1, size_t i2) {return std::abs(l[i1]) < std::abs(l[i2]);});
127 
128  return label_order_cache_;
129  }
131  void Clear();
136  void LoadBinary(dmlc::Stream* fi);
141  void SaveBinary(dmlc::Stream* fo) const;
149  void SetInfo(const char* key, const void* dptr, DataType dtype, size_t num);
159  void SetInfo(const char* key, std::string const& interface_str);
160 
161  private:
163  mutable std::vector<size_t> label_order_cache_;
164 };
165 
167 struct Entry {
173  Entry() = default;
179  XGBOOST_DEVICE Entry(bst_feature_t index, bst_float fvalue) : index(index), fvalue(fvalue) {}
181  inline static bool CmpValue(const Entry& a, const Entry& b) {
182  return a.fvalue < b.fvalue;
183  }
184  inline bool operator==(const Entry& other) const {
185  return (this->index == other.index && this->fvalue == other.fvalue);
186  }
187 };
188 
192 struct BatchParam {
194  int gpu_id;
196  int max_bin{0};
199  BatchParam() = default;
200  BatchParam(int32_t device, int32_t max_bin, size_t gpu_page_size = 0)
201  : gpu_id{device}, max_bin{max_bin}, gpu_page_size{gpu_page_size} {}
202  inline bool operator!=(const BatchParam& other) const {
203  return gpu_id != other.gpu_id || max_bin != other.max_bin ||
204  gpu_page_size != other.gpu_page_size;
205  }
206 };
207 
211 class SparsePage {
212  public:
213  // Offset for each row.
217 
218  size_t base_rowid{};
219 
222 
224  inline Inst operator[](size_t i) const {
225  const auto& data_vec = data.HostVector();
226  const auto& offset_vec = offset.HostVector();
227  size_t size;
228  // in distributed mode, some partitions may not get any instance for a feature. Therefore
229  // we should set the size as zero
230  if (rabit::IsDistributed() && i + 1 >= offset_vec.size()) {
231  size = 0;
232  } else {
233  size = offset_vec[i + 1] - offset_vec[i];
234  }
235  return {data_vec.data() + offset_vec[i],
236  static_cast<Inst::index_type>(size)};
237  }
238 
241  this->Clear();
242  }
243 
245  inline size_t Size() const {
246  return offset.Size() == 0 ? 0 : offset.Size() - 1;
247  }
248 
250  inline size_t MemCostBytes() const {
251  return offset.Size() * sizeof(size_t) + data.Size() * sizeof(Entry);
252  }
253 
255  inline void Clear() {
256  base_rowid = 0;
257  auto& offset_vec = offset.HostVector();
258  offset_vec.clear();
259  offset_vec.push_back(0);
260  data.HostVector().clear();
261  }
262 
264  inline void SetBaseRowId(size_t row_id) {
265  base_rowid = row_id;
266  }
267 
268  SparsePage GetTranspose(int num_columns) const;
269 
270  void SortRows() {
271  auto ncol = static_cast<bst_omp_uint>(this->Size());
272 #pragma omp parallel for default(none) shared(ncol) schedule(dynamic, 1)
273  for (bst_omp_uint i = 0; i < ncol; ++i) {
274  if (this->offset.HostVector()[i] < this->offset.HostVector()[i + 1]) {
275  std::sort(
276  this->data.HostVector().begin() + this->offset.HostVector()[i],
277  this->data.HostVector().begin() + this->offset.HostVector()[i + 1],
279  }
280  }
281  }
282 
287  void Push(const dmlc::RowBlock<uint32_t>& batch);
288 
299  template <typename AdapterBatchT>
300  uint64_t Push(const AdapterBatchT& batch, float missing, int nthread);
301 
306  void Push(const SparsePage &batch);
311  void PushCSC(const SparsePage& batch);
312 };
313 
314 class CSCPage: public SparsePage {
315  public:
317  explicit CSCPage(SparsePage page) : SparsePage(std::move(page)) {}
318 };
319 
320 class SortedCSCPage : public SparsePage {
321  public:
323  explicit SortedCSCPage(SparsePage page) : SparsePage(std::move(page)) {}
324 };
325 
326 class EllpackPageImpl;
333 class EllpackPage {
334  public:
341  EllpackPage();
342 
349  explicit EllpackPage(DMatrix* dmat, const BatchParam& param);
350 
352  ~EllpackPage();
353 
355  size_t Size() const;
356 
358  void SetBaseRowId(size_t row_id);
359 
360  const EllpackPageImpl* Impl() const { return impl_.get(); }
361  EllpackPageImpl* Impl() { return impl_.get(); }
362 
363  private:
364  std::unique_ptr<EllpackPageImpl> impl_;
365 };
366 
367 template<typename T>
369  public:
370  virtual ~BatchIteratorImpl() = default;
371  virtual T& operator*() = 0;
372  virtual const T& operator*() const = 0;
373  virtual void operator++() = 0;
374  virtual bool AtEnd() const = 0;
375 };
376 
377 template<typename T>
379  public:
380  using iterator_category = std::forward_iterator_tag; // NOLINT
381  explicit BatchIterator(BatchIteratorImpl<T>* impl) { impl_.reset(impl); }
382 
383  void operator++() {
384  CHECK(impl_ != nullptr);
385  ++(*impl_);
386  }
387 
388  T& operator*() {
389  CHECK(impl_ != nullptr);
390  return *(*impl_);
391  }
392 
393  const T& operator*() const {
394  CHECK(impl_ != nullptr);
395  return *(*impl_);
396  }
397 
398  bool operator!=(const BatchIterator& rhs) const {
399  CHECK(impl_ != nullptr);
400  return !impl_->AtEnd();
401  }
402 
403  bool AtEnd() const {
404  CHECK(impl_ != nullptr);
405  return impl_->AtEnd();
406  }
407 
408  private:
409  std::shared_ptr<BatchIteratorImpl<T>> impl_;
410 };
411 
412 template<typename T>
413 class BatchSet {
414  public:
415  explicit BatchSet(BatchIterator<T> begin_iter) : begin_iter_(std::move(begin_iter)) {}
416  BatchIterator<T> begin() { return begin_iter_; } // NOLINT
417  BatchIterator<T> end() { return BatchIterator<T>(nullptr); } // NOLINT
418 
419  private:
420  BatchIterator<T> begin_iter_;
421 };
422 
430 template<typename T>
431 class DataSource : public dmlc::DataIter<T> {
432  public:
438 };
439 
451 class DMatrix {
452  public:
454  DMatrix() = default;
456  virtual MetaInfo& Info() = 0;
458  virtual const MetaInfo& Info() const = 0;
462  template<typename T>
463  BatchSet<T> GetBatches(const BatchParam& param = {});
464  template <typename T>
465  bool PageExists() const;
466 
467  // the following are column meta data, should be able to answer them fast.
469  virtual bool SingleColBlock() const = 0;
471  virtual ~DMatrix() = default;
472 
474  bool IsDense() const {
475  return Info().num_nonzero_ == Info().num_row_ * Info().num_col_;
476  }
477 
488  static DMatrix* Load(const std::string& uri,
489  bool silent,
490  bool load_row_split,
491  const std::string& file_format = "auto",
492  size_t page_size = kPageSize);
493 
506  template <typename AdapterT>
507  static DMatrix* Create(AdapterT* adapter, float missing, int nthread,
508  const std::string& cache_prefix = "",
509  size_t page_size = kPageSize);
510 
511  virtual DMatrix* Slice(common::Span<int32_t const> ridxs) = 0;
513  static const size_t kPageSize = 32UL << 20UL;
514 
515  protected:
516  virtual BatchSet<SparsePage> GetRowBatches() = 0;
517  virtual BatchSet<CSCPage> GetColumnBatches() = 0;
518  virtual BatchSet<SortedCSCPage> GetSortedColumnBatches() = 0;
519  virtual BatchSet<EllpackPage> GetEllpackBatches(const BatchParam& param) = 0;
520 
521  virtual bool EllpackExists() const = 0;
522  virtual bool SparsePageExists() const = 0;
523 };
524 
525 template<>
527  return GetRowBatches();
528 }
529 
530 template<>
531 inline bool DMatrix::PageExists<EllpackPage>() const {
532  return this->EllpackExists();
533 }
534 
535 template<>
536 inline bool DMatrix::PageExists<SparsePage>() const {
537  return this->SparsePageExists();
538 }
539 
540 template<>
542  return GetColumnBatches();
543 }
544 
545 template<>
547  return GetSortedColumnBatches();
548 }
549 
550 template<>
552  return GetEllpackBatches(param);
553 }
554 } // namespace xgboost
555 
556 namespace dmlc {
557 DMLC_DECLARE_TRAITS(is_pod, xgboost::Entry, true);
558 
559 namespace serializer {
560 
561 template <>
562 struct Handler<xgboost::Entry> {
563  inline static void Write(Stream* strm, const xgboost::Entry& data) {
564  strm->Write(data.index);
565  strm->Write(data.fvalue);
566  }
567 
568  inline static bool Read(Stream* strm, xgboost::Entry* data) {
569  return strm->Read(&data->index) && strm->Read(&data->fvalue);
570  }
571 };
572 
573 } // namespace serializer
574 } // namespace dmlc
575 #endif // XGBOOST_DATA_H_
std::vector< bst_group_t > group_ptr_
the index of begin and end of a group needed when the learning task is ranking.
Definition: data.h:57
Definition: data.h:378
void operator++()
Definition: data.h:383
uint64_t num_col_
number of columns in the data
Definition: data.h:48
std::forward_iterator_tag iterator_category
Definition: data.h:380
float bst_float
float type, used for storing statistics
Definition: base.h:111
bool IsDense() const
Whether the matrix is dense.
Definition: data.h:474
void Copy(const HostDeviceVector< T > &other)
BatchIterator(BatchIteratorImpl< T > *impl)
Definition: data.h:381
#define XGBOOST_PARALLEL_SORT(X, Y, Z)
Definition: base.h:68
A page stored in ELLPACK format.
Definition: data.h:333
const T & operator*() const
Definition: data.h:393
T & operator*()
Definition: data.h:388
SortedCSCPage()
Definition: data.h:322
std::size_t index_type
Definition: span.h:405
bool operator!=(const BatchParam &other) const
Definition: data.h:202
Meta information about dataset, always sit in memory.
Definition: data.h:40
bool AtEnd() const
Definition: data.h:403
void SetBaseRowId(size_t row_id)
Set the base row id for this page.
Definition: data.h:264
void SortRows()
Definition: data.h:270
size_t gpu_page_size
Page size for external memory mode.
Definition: data.h:198
BatchSet(BatchIterator< T > begin_iter)
Definition: data.h:415
uint32_t bst_feature_t
Type for data column (feature) index.
Definition: base.h:114
dmlc::omp_uint bst_omp_uint
define unsigned int for openmp loop
Definition: base.h:253
Internal data structured used by XGBoost during training. There are two ways to create a customized D...
Definition: data.h:451
In-memory storage unit of sparse batch, stored in CSR format.
Definition: data.h:211
A device-and-host vector abstraction layer.
Definition: data.h:320
HostDeviceVector< bst_float > labels_upper_bound_
upper bound of the label, to be used for survival analysis (censored regression)
Definition: data.h:73
static bool Read(Stream *strm, xgboost::Entry *data)
Definition: data.h:568
Parameters for constructing batches.
Definition: data.h:192
MetaInfo & operator=(MetaInfo const &that)
Definition: data.h:79
span class implementation, based on ISO++20 span<T>. The interface should be the same.
Definition: span.h:126
BatchSet< T > GetBatches(const BatchParam &param={})
Gets batches. Use range based for loop over BatchSet to access individual batches.
int gpu_id
The GPU device to use.
Definition: data.h:194
Definition: data.h:413
HostDeviceVector< bst_row_t > offset
Definition: data.h:214
XGBOOST_DEVICE Entry(bst_feature_t index, bst_float fvalue)
constructor with index and value
Definition: data.h:179
HostDeviceVector< bst_float > labels_lower_bound_
lower bound of the label, to be used for survival analysis (censored regression)
Definition: data.h:69
SparsePage()
constructor
Definition: data.h:240
Definition: data.h:314
BatchIterator< T > begin()
Definition: data.h:416
const EllpackPageImpl * Impl() const
Definition: data.h:360
Definition: data.h:368
SortedCSCPage(SparsePage page)
Definition: data.h:323
bst_float GetWeight(size_t i) const
Get weight of each instances.
Definition: data.h:114
Definition: data.h:556
CSCPage()
Definition: data.h:316
std::vector< T > & HostVector()
bool operator==(const Entry &other) const
Definition: data.h:184
HostDeviceVector< bst_float > labels_
label of each instance
Definition: data.h:52
Inst operator[](size_t i) const
get i-th row from the batch
Definition: data.h:224
uint64_t num_row_
number of rows in the data
Definition: data.h:46
This is data structure that user can pass to DMatrix::Create to create a DMatrix for training...
Definition: data.h:431
bool operator!=(const BatchIterator &rhs) const
Definition: data.h:398
#define XGBOOST_DEVICE
Tag function as usable by device.
Definition: base.h:84
HostDeviceVector< bst_float > base_margin_
initialized margins, if specified, xgboost will start from this init margin can be used to specify in...
Definition: data.h:65
size_t MemCostBytes() const
Definition: data.h:250
namespace of xgboost
Definition: base.h:102
CSCPage(SparsePage page)
Definition: data.h:317
defines configuration macros of xgboost.
size_t Size() const
Definition: data.h:245
DataType
data type accepted by xgboost interface
Definition: data.h:30
HostDeviceVector< Entry > data
the data of the segments
Definition: data.h:216
uint64_t num_nonzero_
number of nonzero entries in the data
Definition: data.h:50
Element from a sparse vector.
Definition: data.h:167
DMLC_DECLARE_TRAITS(is_pod, xgboost::Entry, true)
BatchParam(int32_t device, int32_t max_bin, size_t gpu_page_size=0)
Definition: data.h:200
BatchIterator< T > end()
Definition: data.h:417
static void Write(Stream *strm, const xgboost::Entry &data)
Definition: data.h:563
bst_feature_t index
feature index
Definition: data.h:169
const std::vector< size_t > & LabelAbsSort() const
get sorted indexes (argsort) of labels by absolute value (used by cox loss)
Definition: data.h:118
HostDeviceVector< bst_float > weights_
weights of each instance, optional
Definition: data.h:59
bst_float fvalue
feature value
Definition: data.h:171
static bool CmpValue(const Entry &a, const Entry &b)
reversely compare feature values
Definition: data.h:181
void Resize(size_t new_size, T v=T())
void Clear()
clear the page
Definition: data.h:255
int max_bin
Maximum number of bins per feature for histograms.
Definition: data.h:196
MetaInfo info
Meta information about the dataset The subclass need to be able to load this correctly from data...
Definition: data.h:437
EllpackPageImpl * Impl()
Definition: data.h:361