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 <xgboost/base.h>
14 #include <xgboost/span.h>
16 
17 #include <memory>
18 #include <numeric>
19 #include <algorithm>
20 #include <string>
21 #include <utility>
22 #include <vector>
23 
24 namespace xgboost {
25 // forward declare dmatrix.
26 class DMatrix;
27 
29 enum class DataType : uint8_t {
30  kFloat32 = 1,
31  kDouble = 2,
32  kUInt32 = 3,
33  kUInt64 = 4,
34  kStr = 5
35 };
36 
37 enum class FeatureType : uint8_t {
39 };
40 
44 class MetaInfo {
45  public:
47  static constexpr uint64_t kNumField = 11;
48 
50  uint64_t num_row_{0}; // NOLINT
52  uint64_t num_col_{0}; // NOLINT
54  uint64_t num_nonzero_{0}; // NOLINT
61  std::vector<bst_group_t> group_ptr_; // NOLINT
78 
82  std::vector<std::string> feature_type_names;
86  std::vector<std::string> feature_names;
87  /*
88  * \brief Type of each feature. Automatically set when feature_type_names is specifed.
89  */
91  /*
92  * \brief Weight of each feature, used to define the probability of each feature being
93  * selected when using column sampling.
94  */
96 
98  MetaInfo() = default;
99  MetaInfo(MetaInfo&& that) = default;
100  MetaInfo& operator=(MetaInfo&& that) = default;
101  MetaInfo& operator=(MetaInfo const& that) = delete;
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  void GetInfo(char const* key, bst_ulong* out_len, DataType dtype,
162  const void** out_dptr) const;
163 
164  void SetFeatureInfo(const char *key, const char **info, const bst_ulong size);
165  void GetFeatureInfo(const char *field, std::vector<std::string>* out_str_vecs) const;
166 
167  /*
168  * \brief Extend with other MetaInfo.
169  *
170  * \param that The other MetaInfo object.
171  *
172  * \param accumulate_rows Whether rows need to be accumulated in this function. If
173  * client code knows number of rows in advance, set this parameter to false.
174  */
175  void Extend(MetaInfo const& that, bool accumulate_rows);
176 
177  private:
179  mutable std::vector<size_t> label_order_cache_;
180 };
181 
183 struct Entry {
189  Entry() = default;
195  XGBOOST_DEVICE Entry(bst_feature_t index, bst_float fvalue) : index(index), fvalue(fvalue) {}
197  inline static bool CmpValue(const Entry& a, const Entry& b) {
198  return a.fvalue < b.fvalue;
199  }
200  inline bool operator==(const Entry& other) const {
201  return (this->index == other.index && this->fvalue == other.fvalue);
202  }
203 };
204 
208 struct BatchParam {
210  int gpu_id;
212  int max_bin{0};
215  BatchParam() = default;
216  BatchParam(int32_t device, int32_t max_bin, size_t gpu_page_size = 0)
217  : gpu_id{device}, max_bin{max_bin}, gpu_page_size{gpu_page_size} {}
218  inline bool operator!=(const BatchParam& other) const {
219  return gpu_id != other.gpu_id || max_bin != other.max_bin ||
220  gpu_page_size != other.gpu_page_size;
221  }
222 };
223 
226 
229 
230  Inst operator[](size_t i) const {
231  auto size = *(offset.data() + i + 1) - *(offset.data() + i);
232  return {data.data() + *(offset.data() + i),
233  static_cast<Inst::index_type>(size)};
234  }
235 
236  size_t Size() const { return offset.size() == 0 ? 0 : offset.size() - 1; }
237 };
238 
242 class SparsePage {
243  public:
244  // Offset for each row.
248 
249  size_t base_rowid{};
250 
253 
255  inline Inst operator[](size_t i) const {
256  const auto& data_vec = data.HostVector();
257  const auto& offset_vec = offset.HostVector();
258  size_t size = offset_vec[i + 1] - offset_vec[i];
259  return {data_vec.data() + offset_vec[i],
260  static_cast<Inst::index_type>(size)};
261  }
262 
264  return {offset.ConstHostSpan(), data.ConstHostSpan()};
265  }
266 
267 
270  this->Clear();
271  }
272 
274  inline size_t Size() const {
275  return offset.Size() == 0 ? 0 : offset.Size() - 1;
276  }
277 
279  inline size_t MemCostBytes() const {
280  return offset.Size() * sizeof(size_t) + data.Size() * sizeof(Entry);
281  }
282 
284  inline void Clear() {
285  base_rowid = 0;
286  auto& offset_vec = offset.HostVector();
287  offset_vec.clear();
288  offset_vec.push_back(0);
289  data.HostVector().clear();
290  }
291 
293  inline void SetBaseRowId(size_t row_id) {
294  base_rowid = row_id;
295  }
296 
297  SparsePage GetTranspose(int num_columns) const;
298 
299  void SortRows() {
300  auto ncol = static_cast<bst_omp_uint>(this->Size());
301 #pragma omp parallel for default(none) shared(ncol) schedule(dynamic, 1)
302  for (bst_omp_uint i = 0; i < ncol; ++i) {
303  if (this->offset.HostVector()[i] < this->offset.HostVector()[i + 1]) {
304  std::sort(
305  this->data.HostVector().begin() + this->offset.HostVector()[i],
306  this->data.HostVector().begin() + this->offset.HostVector()[i + 1],
308  }
309  }
310  }
311 
316  void Push(const dmlc::RowBlock<uint32_t>& batch);
317 
328  template <typename AdapterBatchT>
329  uint64_t Push(const AdapterBatchT& batch, float missing, int nthread);
330 
335  void Push(const SparsePage &batch);
340  void PushCSC(const SparsePage& batch);
341 };
342 
343 class CSCPage: public SparsePage {
344  public:
346  explicit CSCPage(SparsePage page) : SparsePage(std::move(page)) {}
347 };
348 
349 class SortedCSCPage : public SparsePage {
350  public:
352  explicit SortedCSCPage(SparsePage page) : SparsePage(std::move(page)) {}
353 };
354 
355 class EllpackPageImpl;
362 class EllpackPage {
363  public:
370  EllpackPage();
371 
378  explicit EllpackPage(DMatrix* dmat, const BatchParam& param);
379 
381  ~EllpackPage();
382 
383  EllpackPage(EllpackPage&& that);
384 
386  size_t Size() const;
387 
389  void SetBaseRowId(size_t row_id);
390 
391  const EllpackPageImpl* Impl() const { return impl_.get(); }
392  EllpackPageImpl* Impl() { return impl_.get(); }
393 
394  private:
395  std::unique_ptr<EllpackPageImpl> impl_;
396 };
397 
398 template<typename T>
400  public:
401  virtual ~BatchIteratorImpl() = default;
402  virtual T& operator*() = 0;
403  virtual const T& operator*() const = 0;
404  virtual void operator++() = 0;
405  virtual bool AtEnd() const = 0;
406 };
407 
408 template<typename T>
410  public:
411  using iterator_category = std::forward_iterator_tag; // NOLINT
412  explicit BatchIterator(BatchIteratorImpl<T>* impl) { impl_.reset(impl); }
413 
414  void operator++() {
415  CHECK(impl_ != nullptr);
416  ++(*impl_);
417  }
418 
419  T& operator*() {
420  CHECK(impl_ != nullptr);
421  return *(*impl_);
422  }
423 
424  const T& operator*() const {
425  CHECK(impl_ != nullptr);
426  return *(*impl_);
427  }
428 
429  bool operator!=(const BatchIterator& rhs) const {
430  CHECK(impl_ != nullptr);
431  return !impl_->AtEnd();
432  }
433 
434  bool AtEnd() const {
435  CHECK(impl_ != nullptr);
436  return impl_->AtEnd();
437  }
438 
439  private:
440  std::shared_ptr<BatchIteratorImpl<T>> impl_;
441 };
442 
443 template<typename T>
444 class BatchSet {
445  public:
446  explicit BatchSet(BatchIterator<T> begin_iter) : begin_iter_(std::move(begin_iter)) {}
447  BatchIterator<T> begin() { return begin_iter_; } // NOLINT
448  BatchIterator<T> end() { return BatchIterator<T>(nullptr); } // NOLINT
449 
450  private:
451  BatchIterator<T> begin_iter_;
452 };
453 
455 
459 class DMatrix {
460  public:
462  DMatrix() = default;
464  virtual MetaInfo& Info() = 0;
465  virtual void SetInfo(const char *key, const void *dptr, DataType dtype,
466  size_t num) {
467  this->Info().SetInfo(key, dptr, dtype, num);
468  }
469  virtual void SetInfo(const char* key, std::string const& interface_str) {
470  this->Info().SetInfo(key, interface_str);
471  }
473  virtual const MetaInfo& Info() const = 0;
474 
476  XGBAPIThreadLocalEntry& GetThreadLocal() const;
477 
481  template<typename T>
482  BatchSet<T> GetBatches(const BatchParam& param = {});
483  template <typename T>
484  bool PageExists() const;
485 
486  // the following are column meta data, should be able to answer them fast.
488  virtual bool SingleColBlock() const = 0;
490  virtual ~DMatrix();
491 
493  bool IsDense() const {
494  return Info().num_nonzero_ == Info().num_row_ * Info().num_col_;
495  }
496 
507  static DMatrix* Load(const std::string& uri,
508  bool silent,
509  bool load_row_split,
510  const std::string& file_format = "auto",
511  size_t page_size = kPageSize);
512 
525  template <typename AdapterT>
526  static DMatrix* Create(AdapterT* adapter, float missing, int nthread,
527  const std::string& cache_prefix = "",
528  size_t page_size = kPageSize);
529 
548  template <typename DataIterHandle, typename DMatrixHandle,
549  typename DataIterResetCallback, typename XGDMatrixCallbackNext>
550  static DMatrix *Create(DataIterHandle iter, DMatrixHandle proxy,
551  DataIterResetCallback *reset,
552  XGDMatrixCallbackNext *next, float missing,
553  int nthread,
554  int max_bin);
555 
556  virtual DMatrix *Slice(common::Span<int32_t const> ridxs) = 0;
558  static const size_t kPageSize = 32UL << 20UL;
559 
560  protected:
561  virtual BatchSet<SparsePage> GetRowBatches() = 0;
562  virtual BatchSet<CSCPage> GetColumnBatches() = 0;
563  virtual BatchSet<SortedCSCPage> GetSortedColumnBatches() = 0;
564  virtual BatchSet<EllpackPage> GetEllpackBatches(const BatchParam& param) = 0;
565 
566  virtual bool EllpackExists() const = 0;
567  virtual bool SparsePageExists() const = 0;
568 };
569 
570 template<>
572  return GetRowBatches();
573 }
574 
575 template<>
576 inline bool DMatrix::PageExists<EllpackPage>() const {
577  return this->EllpackExists();
578 }
579 
580 template<>
581 inline bool DMatrix::PageExists<SparsePage>() const {
582  return this->SparsePageExists();
583 }
584 
585 template<>
587  return GetColumnBatches();
588 }
589 
590 template<>
592  return GetSortedColumnBatches();
593 }
594 
595 template<>
597  return GetEllpackBatches(param);
598 }
599 } // namespace xgboost
600 
601 namespace dmlc {
602 DMLC_DECLARE_TRAITS(is_pod, xgboost::Entry, true);
603 
604 namespace serializer {
605 
606 template <>
607 struct Handler<xgboost::Entry> {
608  inline static void Write(Stream* strm, const xgboost::Entry& data) {
609  strm->Write(data.index);
610  strm->Write(data.fvalue);
611  }
612 
613  inline static bool Read(Stream* strm, xgboost::Entry* data) {
614  return strm->Read(&data->index) && strm->Read(&data->fvalue);
615  }
616 };
617 
618 } // namespace serializer
619 } // namespace dmlc
620 #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:61
Definition: data.h:409
void operator++()
Definition: data.h:414
std::forward_iterator_tag iterator_category
Definition: data.h:411
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
XGBOOST_DEVICE constexpr index_type size() const __span_noexcept
Definition: span.h:531
bool IsDense() const
Whether the matrix is dense.
Definition: data.h:493
BatchIterator(BatchIteratorImpl< T > *impl)
Definition: data.h:412
#define XGBOOST_PARALLEL_SORT(X, Y, Z)
Definition: base.h:68
A page stored in ELLPACK format.
Definition: data.h:362
XGB_EXTERN_C typedef void DataIterResetCallback(DataIterHandle handle)
Callback function prototype for reseting external iterator.
const T & operator*() const
Definition: data.h:424
T & operator*()
Definition: data.h:419
std::vector< std::string > feature_type_names
Name of type for each feature provided by users. Eg. "int"/"float"/"i"/"q".
Definition: data.h:82
HostSparsePageView GetView() const
Definition: data.h:263
SortedCSCPage()
Definition: data.h:351
virtual void SetInfo(const char *key, std::string const &interface_str)
Definition: data.h:469
std::size_t index_type
Definition: span.h:405
bool operator!=(const BatchParam &other) const
Definition: data.h:218
void * DMatrixHandle
handle to DMatrix
Definition: c_api.h:30
Meta information about dataset, always sit in memory.
Definition: data.h:44
bool AtEnd() const
Definition: data.h:434
void SetBaseRowId(size_t row_id)
Set the base row id for this page.
Definition: data.h:293
void SortRows()
Definition: data.h:299
size_t gpu_page_size
Page size for external memory mode.
Definition: data.h:214
BatchSet(BatchIterator< T > begin_iter)
Definition: data.h:446
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:459
In-memory storage unit of sparse batch, stored in CSR format.
Definition: data.h:242
A device-and-host vector abstraction layer.
Definition: data.h:349
HostDeviceVector< bst_float > labels_upper_bound_
upper bound of the label, to be used for survival analysis (censored regression)
Definition: data.h:77
std::vector< std::string > feature_names
Name for each feature.
Definition: data.h:86
static bool Read(Stream *strm, xgboost::Entry *data)
Definition: data.h:613
Parameters for constructing batches.
Definition: data.h:208
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
HostDeviceVector< float > feature_weigths
Definition: data.h:95
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:210
Definition: data.h:444
HostDeviceVector< bst_row_t > offset
Definition: data.h:245
XGBOOST_DEVICE Entry(bst_feature_t index, bst_float fvalue)
constructor with index and value
Definition: data.h:195
HostDeviceVector< bst_float > labels_lower_bound_
lower bound of the label, to be used for survival analysis (censored regression)
Definition: data.h:73
SparsePage()
constructor
Definition: data.h:269
Definition: data.h:343
BatchIterator< T > begin()
Definition: data.h:447
XGBOOST_DEVICE constexpr pointer data() const __span_noexcept
Definition: span.h:526
const EllpackPageImpl * Impl() const
Definition: data.h:391
Definition: data.h:399
SortedCSCPage(SparsePage page)
Definition: data.h:352
bst_float GetWeight(size_t i) const
Get weight of each instances.
Definition: data.h:114
Definition: data.h:601
CSCPage()
Definition: data.h:345
entry to to easily hold returning information
Definition: learner.h:34
std::vector< T > & HostVector()
bool operator==(const Entry &other) const
Definition: data.h:200
HostDeviceVector< bst_float > labels_
label of each instance
Definition: data.h:56
Inst operator[](size_t i) const
get i-th row from the batch
Definition: data.h:255
bool operator!=(const BatchIterator &rhs) const
Definition: data.h:429
#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:69
size_t MemCostBytes() const
Definition: data.h:279
namespace of xgboost
Definition: base.h:102
CSCPage(SparsePage page)
Definition: data.h:346
FeatureType
Definition: data.h:37
Definition: data.h:224
virtual void SetInfo(const char *key, const void *dptr, DataType dtype, size_t num)
Definition: data.h:465
defines configuration macros of xgboost.
size_t Size() const
Definition: data.h:274
DataType
data type accepted by xgboost interface
Definition: data.h:29
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:247
Element from a sparse vector.
Definition: data.h:183
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:216
BatchIterator< T > end()
Definition: data.h:448
static void Write(Stream *strm, const xgboost::Entry &data)
Definition: data.h:608
bst_feature_t index
feature index
Definition: data.h:185
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:63
bst_float fvalue
feature value
Definition: data.h:187
static bool CmpValue(const Entry &a, const Entry &b)
reversely compare feature values
Definition: data.h:197
common::Span< Entry const > data
Definition: data.h:228
Inst operator[](size_t i) const
Definition: data.h:230
void Clear()
clear the page
Definition: data.h:284
HostDeviceVector< FeatureType > feature_types
Definition: data.h:90
common::Span< bst_row_t const > offset
Definition: data.h:227
int max_bin
Maximum number of bins per feature for histograms.
Definition: data.h:212
EllpackPageImpl * Impl()
Definition: data.h:392
size_t Size() const
Definition: data.h:236
common::Span< T const > ConstHostSpan() const
Definition: host_device_vector.h:114