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  kStr = 5
36 };
37 
38 enum class FeatureType : uint8_t {
40 };
41 
45 class MetaInfo {
46  public:
48  static constexpr uint64_t kNumField = 11;
49 
51  uint64_t num_row_{0}; // NOLINT
53  uint64_t num_col_{0}; // NOLINT
55  uint64_t num_nonzero_{0}; // NOLINT
62  std::vector<bst_group_t> group_ptr_; // NOLINT
79 
83  std::vector<std::string> feature_type_names;
87  std::vector<std::string> feature_names;
88  /*
89  * \brief Type of each feature. Automatically set when feature_type_names is specifed.
90  */
92 
94  MetaInfo() = default;
95  MetaInfo(MetaInfo&& that) = default;
96  MetaInfo& operator=(MetaInfo&& that) = default;
97  MetaInfo& operator=(MetaInfo const& that) {
98  this->num_row_ = that.num_row_;
99  this->num_col_ = that.num_col_;
100  this->num_nonzero_ = that.num_nonzero_;
101 
102  this->labels_.Resize(that.labels_.Size());
103  this->labels_.Copy(that.labels_);
104 
105  this->group_ptr_ = that.group_ptr_;
106 
107  this->weights_.Resize(that.weights_.Size());
108  this->weights_.Copy(that.weights_);
109 
110  this->base_margin_.Resize(that.base_margin_.Size());
111  this->base_margin_.Copy(that.base_margin_);
112 
113  this->labels_lower_bound_.Resize(that.labels_lower_bound_.Size());
114  this->labels_lower_bound_.Copy(that.labels_lower_bound_);
115 
116  this->labels_upper_bound_.Resize(that.labels_upper_bound_.Size());
117  this->labels_upper_bound_.Copy(that.labels_upper_bound_);
118  return *this;
119  }
120 
124  void Validate(int32_t device) const;
125 
126  MetaInfo Slice(common::Span<int32_t const> ridxs) const;
132  inline bst_float GetWeight(size_t i) const {
133  return weights_.Size() != 0 ? weights_.HostVector()[i] : 1.0f;
134  }
136  inline const std::vector<size_t>& LabelAbsSort() const {
137  if (label_order_cache_.size() == labels_.Size()) {
138  return label_order_cache_;
139  }
140  label_order_cache_.resize(labels_.Size());
141  std::iota(label_order_cache_.begin(), label_order_cache_.end(), 0);
142  const auto& l = labels_.HostVector();
143  XGBOOST_PARALLEL_SORT(label_order_cache_.begin(), label_order_cache_.end(),
144  [&l](size_t i1, size_t i2) {return std::abs(l[i1]) < std::abs(l[i2]);});
145 
146  return label_order_cache_;
147  }
149  void Clear();
154  void LoadBinary(dmlc::Stream* fi);
159  void SaveBinary(dmlc::Stream* fo) const;
167  void SetInfo(const char* key, const void* dptr, DataType dtype, size_t num);
177  void SetInfo(const char* key, std::string const& interface_str);
178 
179  void GetInfo(char const* key, bst_ulong* out_len, DataType dtype,
180  const void** out_dptr) const;
181 
182  void SetFeatureInfo(const char *key, const char **info, const bst_ulong size);
183  void GetFeatureInfo(const char *field, std::vector<std::string>* out_str_vecs) const;
184 
185  /*
186  * \brief Extend with other MetaInfo.
187  *
188  * \param that The other MetaInfo object.
189  *
190  * \param accumulate_rows Whether rows need to be accumulated in this function. If
191  * client code knows number of rows in advance, set this parameter to false.
192  */
193  void Extend(MetaInfo const& that, bool accumulate_rows);
194 
195  private:
197  mutable std::vector<size_t> label_order_cache_;
198 };
199 
201 struct Entry {
207  Entry() = default;
213  XGBOOST_DEVICE Entry(bst_feature_t index, bst_float fvalue) : index(index), fvalue(fvalue) {}
215  inline static bool CmpValue(const Entry& a, const Entry& b) {
216  return a.fvalue < b.fvalue;
217  }
218  inline bool operator==(const Entry& other) const {
219  return (this->index == other.index && this->fvalue == other.fvalue);
220  }
221 };
222 
226 struct BatchParam {
228  int gpu_id;
230  int max_bin{0};
233  BatchParam() = default;
234  BatchParam(int32_t device, int32_t max_bin, size_t gpu_page_size = 0)
235  : gpu_id{device}, max_bin{max_bin}, gpu_page_size{gpu_page_size} {}
236  inline bool operator!=(const BatchParam& other) const {
237  return gpu_id != other.gpu_id || max_bin != other.max_bin ||
238  gpu_page_size != other.gpu_page_size;
239  }
240 };
241 
245 class SparsePage {
246  public:
247  // Offset for each row.
251 
252  size_t base_rowid{};
253 
256 
258  inline Inst operator[](size_t i) const {
259  const auto& data_vec = data.HostVector();
260  const auto& offset_vec = offset.HostVector();
261  size_t size;
262  // in distributed mode, some partitions may not get any instance for a feature. Therefore
263  // we should set the size as zero
264  if (rabit::IsDistributed() && i + 1 >= offset_vec.size()) {
265  size = 0;
266  } else {
267  size = offset_vec[i + 1] - offset_vec[i];
268  }
269  return {data_vec.data() + offset_vec[i],
270  static_cast<Inst::index_type>(size)};
271  }
272 
275  this->Clear();
276  }
277 
279  inline size_t Size() const {
280  return offset.Size() == 0 ? 0 : offset.Size() - 1;
281  }
282 
284  inline size_t MemCostBytes() const {
285  return offset.Size() * sizeof(size_t) + data.Size() * sizeof(Entry);
286  }
287 
289  inline void Clear() {
290  base_rowid = 0;
291  auto& offset_vec = offset.HostVector();
292  offset_vec.clear();
293  offset_vec.push_back(0);
294  data.HostVector().clear();
295  }
296 
298  inline void SetBaseRowId(size_t row_id) {
299  base_rowid = row_id;
300  }
301 
302  SparsePage GetTranspose(int num_columns) const;
303 
304  void SortRows() {
305  auto ncol = static_cast<bst_omp_uint>(this->Size());
306 #pragma omp parallel for default(none) shared(ncol) schedule(dynamic, 1)
307  for (bst_omp_uint i = 0; i < ncol; ++i) {
308  if (this->offset.HostVector()[i] < this->offset.HostVector()[i + 1]) {
309  std::sort(
310  this->data.HostVector().begin() + this->offset.HostVector()[i],
311  this->data.HostVector().begin() + this->offset.HostVector()[i + 1],
313  }
314  }
315  }
316 
321  void Push(const dmlc::RowBlock<uint32_t>& batch);
322 
333  template <typename AdapterBatchT>
334  uint64_t Push(const AdapterBatchT& batch, float missing, int nthread);
335 
340  void Push(const SparsePage &batch);
345  void PushCSC(const SparsePage& batch);
346 };
347 
348 class CSCPage: public SparsePage {
349  public:
351  explicit CSCPage(SparsePage page) : SparsePage(std::move(page)) {}
352 };
353 
354 class SortedCSCPage : public SparsePage {
355  public:
357  explicit SortedCSCPage(SparsePage page) : SparsePage(std::move(page)) {}
358 };
359 
360 class EllpackPageImpl;
367 class EllpackPage {
368  public:
375  EllpackPage();
376 
383  explicit EllpackPage(DMatrix* dmat, const BatchParam& param);
384 
386  ~EllpackPage();
387 
388  EllpackPage(EllpackPage&& that);
389 
391  size_t Size() const;
392 
394  void SetBaseRowId(size_t row_id);
395 
396  const EllpackPageImpl* Impl() const { return impl_.get(); }
397  EllpackPageImpl* Impl() { return impl_.get(); }
398 
399  private:
400  std::unique_ptr<EllpackPageImpl> impl_;
401 };
402 
403 template<typename T>
405  public:
406  virtual ~BatchIteratorImpl() = default;
407  virtual T& operator*() = 0;
408  virtual const T& operator*() const = 0;
409  virtual void operator++() = 0;
410  virtual bool AtEnd() const = 0;
411 };
412 
413 template<typename T>
415  public:
416  using iterator_category = std::forward_iterator_tag; // NOLINT
417  explicit BatchIterator(BatchIteratorImpl<T>* impl) { impl_.reset(impl); }
418 
419  void operator++() {
420  CHECK(impl_ != nullptr);
421  ++(*impl_);
422  }
423 
424  T& operator*() {
425  CHECK(impl_ != nullptr);
426  return *(*impl_);
427  }
428 
429  const T& operator*() const {
430  CHECK(impl_ != nullptr);
431  return *(*impl_);
432  }
433 
434  bool operator!=(const BatchIterator& rhs) const {
435  CHECK(impl_ != nullptr);
436  return !impl_->AtEnd();
437  }
438 
439  bool AtEnd() const {
440  CHECK(impl_ != nullptr);
441  return impl_->AtEnd();
442  }
443 
444  private:
445  std::shared_ptr<BatchIteratorImpl<T>> impl_;
446 };
447 
448 template<typename T>
449 class BatchSet {
450  public:
451  explicit BatchSet(BatchIterator<T> begin_iter) : begin_iter_(std::move(begin_iter)) {}
452  BatchIterator<T> begin() { return begin_iter_; } // NOLINT
453  BatchIterator<T> end() { return BatchIterator<T>(nullptr); } // NOLINT
454 
455  private:
456  BatchIterator<T> begin_iter_;
457 };
458 
460 
464 class DMatrix {
465  public:
467  DMatrix() = default;
469  virtual MetaInfo& Info() = 0;
470  virtual void SetInfo(const char *key, const void *dptr, DataType dtype,
471  size_t num) {
472  this->Info().SetInfo(key, dptr, dtype, num);
473  }
474  virtual void SetInfo(const char* key, std::string const& interface_str) {
475  this->Info().SetInfo(key, interface_str);
476  }
478  virtual const MetaInfo& Info() const = 0;
479 
481  XGBAPIThreadLocalEntry& GetThreadLocal() const;
482 
486  template<typename T>
487  BatchSet<T> GetBatches(const BatchParam& param = {});
488  template <typename T>
489  bool PageExists() const;
490 
491  // the following are column meta data, should be able to answer them fast.
493  virtual bool SingleColBlock() const = 0;
495  virtual ~DMatrix();
496 
498  bool IsDense() const {
499  return Info().num_nonzero_ == Info().num_row_ * Info().num_col_;
500  }
501 
512  static DMatrix* Load(const std::string& uri,
513  bool silent,
514  bool load_row_split,
515  const std::string& file_format = "auto",
516  size_t page_size = kPageSize);
517 
530  template <typename AdapterT>
531  static DMatrix* Create(AdapterT* adapter, float missing, int nthread,
532  const std::string& cache_prefix = "",
533  size_t page_size = kPageSize);
534 
553  template <typename DataIterHandle, typename DMatrixHandle,
554  typename DataIterResetCallback, typename XGDMatrixCallbackNext>
555  static DMatrix *Create(DataIterHandle iter, DMatrixHandle proxy,
556  DataIterResetCallback *reset,
557  XGDMatrixCallbackNext *next, float missing,
558  int nthread,
559  int max_bin);
560 
561  virtual DMatrix *Slice(common::Span<int32_t const> ridxs) = 0;
563  static const size_t kPageSize = 32UL << 20UL;
564 
565  protected:
566  virtual BatchSet<SparsePage> GetRowBatches() = 0;
567  virtual BatchSet<CSCPage> GetColumnBatches() = 0;
568  virtual BatchSet<SortedCSCPage> GetSortedColumnBatches() = 0;
569  virtual BatchSet<EllpackPage> GetEllpackBatches(const BatchParam& param) = 0;
570 
571  virtual bool EllpackExists() const = 0;
572  virtual bool SparsePageExists() const = 0;
573 };
574 
575 template<>
577  return GetRowBatches();
578 }
579 
580 template<>
581 inline bool DMatrix::PageExists<EllpackPage>() const {
582  return this->EllpackExists();
583 }
584 
585 template<>
586 inline bool DMatrix::PageExists<SparsePage>() const {
587  return this->SparsePageExists();
588 }
589 
590 template<>
592  return GetColumnBatches();
593 }
594 
595 template<>
597  return GetSortedColumnBatches();
598 }
599 
600 template<>
602  return GetEllpackBatches(param);
603 }
604 } // namespace xgboost
605 
606 namespace dmlc {
607 DMLC_DECLARE_TRAITS(is_pod, xgboost::Entry, true);
608 
609 namespace serializer {
610 
611 template <>
612 struct Handler<xgboost::Entry> {
613  inline static void Write(Stream* strm, const xgboost::Entry& data) {
614  strm->Write(data.index);
615  strm->Write(data.fvalue);
616  }
617 
618  inline static bool Read(Stream* strm, xgboost::Entry* data) {
619  return strm->Read(&data->index) && strm->Read(&data->fvalue);
620  }
621 };
622 
623 } // namespace serializer
624 } // namespace dmlc
625 #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:62
Definition: data.h:414
void operator++()
Definition: data.h:419
uint64_t num_col_
number of columns in the data
Definition: data.h:53
std::forward_iterator_tag iterator_category
Definition: data.h:416
void * DataIterHandle
handle to a external data iterator
Definition: c_api.h:191
float bst_float
float type, used for storing statistics
Definition: base.h:111
bool IsDense() const
Whether the matrix is dense.
Definition: data.h:498
void Copy(const HostDeviceVector< T > &other)
BatchIterator(BatchIteratorImpl< T > *impl)
Definition: data.h:417
#define XGBOOST_PARALLEL_SORT(X, Y, Z)
Definition: base.h:68
A page stored in ELLPACK format.
Definition: data.h:367
XGB_EXTERN_C typedef void DataIterResetCallback(DataIterHandle handle)
Callback function prototype for reseting external iterator.
const T & operator*() const
Definition: data.h:429
T & operator*()
Definition: data.h:424
std::vector< std::string > feature_type_names
Name of type for each feature provided by users. Eg. "int"/"float"/"i"/"q".
Definition: data.h:83
SortedCSCPage()
Definition: data.h:356
virtual void SetInfo(const char *key, std::string const &interface_str)
Definition: data.h:474
std::size_t index_type
Definition: span.h:405
bool operator!=(const BatchParam &other) const
Definition: data.h:236
void * DMatrixHandle
handle to DMatrix
Definition: c_api.h:30
Meta information about dataset, always sit in memory.
Definition: data.h:45
bool AtEnd() const
Definition: data.h:439
void SetBaseRowId(size_t row_id)
Set the base row id for this page.
Definition: data.h:298
void SortRows()
Definition: data.h:304
size_t gpu_page_size
Page size for external memory mode.
Definition: data.h:232
BatchSet(BatchIterator< T > begin_iter)
Definition: data.h:451
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:261
Internal data structured used by XGBoost during training.
Definition: data.h:464
In-memory storage unit of sparse batch, stored in CSR format.
Definition: data.h:245
A device-and-host vector abstraction layer.
Definition: data.h:354
HostDeviceVector< bst_float > labels_upper_bound_
upper bound of the label, to be used for survival analysis (censored regression)
Definition: data.h:78
std::vector< std::string > feature_names
Name for each feature.
Definition: data.h:87
static bool Read(Stream *strm, xgboost::Entry *data)
Definition: data.h:618
Parameters for constructing batches.
Definition: data.h:226
MetaInfo & operator=(MetaInfo const &that)
Definition: data.h:97
span class implementation, based on ISO++20 span<T>. The interface should be the same.
Definition: span.h:126
uint64_t bst_ulong
unsigned long integers
Definition: base.h:109
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:228
Definition: data.h:449
HostDeviceVector< bst_row_t > offset
Definition: data.h:248
XGBOOST_DEVICE Entry(bst_feature_t index, bst_float fvalue)
constructor with index and value
Definition: data.h:213
HostDeviceVector< bst_float > labels_lower_bound_
lower bound of the label, to be used for survival analysis (censored regression)
Definition: data.h:74
SparsePage()
constructor
Definition: data.h:274
Definition: data.h:348
BatchIterator< T > begin()
Definition: data.h:452
const EllpackPageImpl * Impl() const
Definition: data.h:396
Definition: data.h:404
SortedCSCPage(SparsePage page)
Definition: data.h:357
bst_float GetWeight(size_t i) const
Get weight of each instances.
Definition: data.h:132
Definition: data.h:606
CSCPage()
Definition: data.h:350
entry to to easily hold returning information
Definition: learner.h:35
std::vector< T > & HostVector()
bool operator==(const Entry &other) const
Definition: data.h:218
HostDeviceVector< bst_float > labels_
label of each instance
Definition: data.h:57
Inst operator[](size_t i) const
get i-th row from the batch
Definition: data.h:258
uint64_t num_row_
number of rows in the data
Definition: data.h:51
bool operator!=(const BatchIterator &rhs) const
Definition: data.h:434
#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:70
size_t MemCostBytes() const
Definition: data.h:284
namespace of xgboost
Definition: base.h:102
CSCPage(SparsePage page)
Definition: data.h:351
FeatureType
Definition: data.h:38
virtual void SetInfo(const char *key, const void *dptr, DataType dtype, size_t num)
Definition: data.h:470
defines configuration macros of xgboost.
size_t Size() const
Definition: data.h:279
DataType
data type accepted by xgboost interface
Definition: data.h:30
XGB_EXTERN_C typedef int XGDMatrixCallbackNext(DataIterHandle iter)
Callback function prototype for getting next batch of data.
HostDeviceVector< Entry > data
the data of the segments
Definition: data.h:250
uint64_t num_nonzero_
number of nonzero entries in the data
Definition: data.h:55
Element from a sparse vector.
Definition: data.h:201
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:234
BatchIterator< T > end()
Definition: data.h:453
static void Write(Stream *strm, const xgboost::Entry &data)
Definition: data.h:613
bst_feature_t index
feature index
Definition: data.h:203
const std::vector< size_t > & LabelAbsSort() const
get sorted indexes (argsort) of labels by absolute value (used by cox loss)
Definition: data.h:136
HostDeviceVector< bst_float > weights_
weights of each instance, optional
Definition: data.h:64
bst_float fvalue
feature value
Definition: data.h:205
static bool CmpValue(const Entry &a, const Entry &b)
reversely compare feature values
Definition: data.h:215
void Resize(size_t new_size, T v=T())
void Clear()
clear the page
Definition: data.h:289
HostDeviceVector< FeatureType > feature_types
Definition: data.h:91
int max_bin
Maximum number of bins per feature for histograms.
Definition: data.h:230
EllpackPageImpl * Impl()
Definition: data.h:397