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>
16 #include <xgboost/host_device_vector.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
52 HostDeviceVector<bst_float> labels_; // NOLINT
57 std::vector<bst_group_t> group_ptr_; // NOLINT
59 HostDeviceVector<bst_float> weights_; // NOLINT
65 HostDeviceVector<bst_float> base_margin_; // NOLINT
69 HostDeviceVector<bst_float> labels_lower_bound_; // NOLINT
73 HostDeviceVector<bst_float> labels_upper_bound_; // 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 {
169 bst_feature_t index;
171 bst_float fvalue;
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};
198 size_t gpu_page_size;
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.
214 HostDeviceVector<bst_row_t> offset;
216 HostDeviceVector<Entry> data;
217
218 size_t base_rowid{};
219
221 using Inst = common::Span<Entry const>;
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
240 SparsePage() {
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],
278 Entry::CmpValue);
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:
316 CSCPage() : SparsePage() {}
317 explicit CSCPage(SparsePage page) : SparsePage(std::move(page)) {}
318 };
319
320 class SortedCSCPage : public SparsePage {
321 public:
322 SortedCSCPage() : SparsePage() {}
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>
368 class BatchIteratorImpl {
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>
378 class BatchIterator {
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:
437 MetaInfo info;
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<>
526 inline BatchSet<SparsePage> DMatrix::GetBatches(const BatchParam&) {
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<>
541 inline BatchSet<CSCPage> DMatrix::GetBatches(const BatchParam&) {
542 return GetColumnBatches();
543 }
544
545 template<>
546 inline BatchSet<SortedCSCPage> DMatrix::GetBatches(const BatchParam&) {
547 return GetSortedColumnBatches();
548 }
549
550 template<>
551 inline BatchSet<EllpackPage> DMatrix::GetBatches(const BatchParam& param) {
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_
xgboost::MetaInfo::group_ptr_
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
xgboost::BatchIterator
Definition: data.h:378
xgboost::BatchIterator::operator++
void operator++()
Definition: data.h:383
xgboost::MetaInfo::num_col_
uint64_t num_col_
number of columns in the data
Definition: data.h:48
xgboost::BatchIterator::iterator_category
std::forward_iterator_tag iterator_category
Definition: data.h:380
xgboost::bst_float
float bst_float
float type, used for storing statistics
Definition: base.h:111
xgboost::DMatrix::IsDense
bool IsDense() const
Whether the matrix is dense.
Definition: data.h:474
xgboost::HostDeviceVector::Copy
void Copy(const HostDeviceVector< T > &other)
xgboost::BatchIterator::BatchIterator
BatchIterator(BatchIteratorImpl< T > *impl)
Definition: data.h:381
XGBOOST_PARALLEL_SORT
#define XGBOOST_PARALLEL_SORT(X, Y, Z)
Definition: base.h:68
xgboost::EllpackPage
A page stored in ELLPACK format.
Definition: data.h:333
xgboost::BatchIterator::operator*
const T & operator*() const
Definition: data.h:393
span.h
xgboost::BatchIterator::operator*
T & operator*()
Definition: data.h:388
xgboost::SortedCSCPage::SortedCSCPage
SortedCSCPage()
Definition: data.h:322
xgboost::common::Span::index_type
std::size_t index_type
Definition: span.h:405
xgboost::DataType::kUInt32
xgboost::BatchParam::operator!=
bool operator!=(const BatchParam &other) const
Definition: data.h:202
xgboost::MetaInfo
Meta information about dataset, always sit in memory.
Definition: data.h:40
xgboost::HostDeviceVector< bst_float >
xgboost::BatchIterator::AtEnd
bool AtEnd() const
Definition: data.h:403
xgboost::SparsePage::SetBaseRowId
void SetBaseRowId(size_t row_id)
Set the base row id for this page.
Definition: data.h:264
xgboost::SparsePage::SortRows
void SortRows()
Definition: data.h:270
xgboost::BatchParam::gpu_page_size
size_t gpu_page_size
Page size for external memory mode.
Definition: data.h:198
xgboost::BatchSet::BatchSet
BatchSet(BatchIterator< T > begin_iter)
Definition: data.h:415
xgboost::bst_feature_t
uint32_t bst_feature_t
Type for data column (feature) index.
Definition: base.h:114
xgboost::bst_omp_uint
dmlc::omp_uint bst_omp_uint
define unsigned int for openmp loop
Definition: base.h:253
xgboost::DMatrix
Internal data structured used by XGBoost during training. There are two ways to create a customized D...
Definition: data.h:451
xgboost::SparsePage
In-memory storage unit of sparse batch, stored in CSR format.
Definition: data.h:211
host_device_vector.h
A device-and-host vector abstraction layer.
xgboost::SortedCSCPage
Definition: data.h:320
xgboost::MetaInfo::labels_upper_bound_
HostDeviceVector< bst_float > labels_upper_bound_
upper bound of the label, to be used for survival analysis (censored regression)
Definition: data.h:73
dmlc::serializer::Handler< xgboost::Entry >::Read
static bool Read(Stream *strm, xgboost::Entry *data)
Definition: data.h:568
xgboost::BatchParam
Parameters for constructing batches.
Definition: data.h:192
xgboost::MetaInfo::operator=
MetaInfo & operator=(MetaInfo const &that)
Definition: data.h:79
xgboost::common::Span
span class implementation, based on ISO++20 span<T>. The interface should be the same.
Definition: span.h:126
xgboost::HostDeviceVector::Size
size_t Size() const
xgboost::DMatrix::GetBatches
BatchSet< T > GetBatches(const BatchParam &param={})
Gets batches. Use range based for loop over BatchSet to access individual batches.
xgboost::BatchParam::gpu_id
int gpu_id
The GPU device to use.
Definition: data.h:194
xgboost::BatchSet
Definition: data.h:413
xgboost::SparsePage::offset
HostDeviceVector< bst_row_t > offset
Definition: data.h:214
xgboost::Entry::Entry
XGBOOST_DEVICE Entry(bst_feature_t index, bst_float fvalue)
constructor with index and value
Definition: data.h:179
xgboost::MetaInfo::labels_lower_bound_
HostDeviceVector< bst_float > labels_lower_bound_
lower bound of the label, to be used for survival analysis (censored regression)
Definition: data.h:69
xgboost::SparsePage::SparsePage
SparsePage()
constructor
Definition: data.h:240
xgboost::CSCPage
Definition: data.h:314
xgboost::BatchSet::begin
BatchIterator< T > begin()
Definition: data.h:416
xgboost::DataType::kDouble
xgboost::EllpackPage::Impl
const EllpackPageImpl * Impl() const
Definition: data.h:360
xgboost::BatchIteratorImpl
Definition: data.h:368
xgboost::SortedCSCPage::SortedCSCPage
SortedCSCPage(SparsePage page)
Definition: data.h:323
xgboost::MetaInfo::GetWeight
bst_float GetWeight(size_t i) const
Get weight of each instances.
Definition: data.h:114
dmlc
Definition: data.h:556
xgboost::CSCPage::CSCPage
CSCPage()
Definition: data.h:316
xgboost::HostDeviceVector::HostVector
std::vector< T > & HostVector()
xgboost::Entry::operator==
bool operator==(const Entry &other) const
Definition: data.h:184
xgboost::MetaInfo::labels_
HostDeviceVector< bst_float > labels_
label of each instance
Definition: data.h:52
xgboost::SparsePage::operator[]
Inst operator[](size_t i) const
get i-th row from the batch
Definition: data.h:224
xgboost::MetaInfo::num_row_
uint64_t num_row_
number of rows in the data
Definition: data.h:46
xgboost::DataSource
This is data structure that user can pass to DMatrix::Create to create a DMatrix for training...
Definition: data.h:431
xgboost::BatchIterator::operator!=
bool operator!=(const BatchIterator &rhs) const
Definition: data.h:398
XGBOOST_DEVICE
#define XGBOOST_DEVICE
Tag function as usable by device.
Definition: base.h:84
xgboost::MetaInfo::base_margin_
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
xgboost::SparsePage::MemCostBytes
size_t MemCostBytes() const
Definition: data.h:250
xgboost
namespace of xgboost
Definition: base.h:102
xgboost::CSCPage::CSCPage
CSCPage(SparsePage page)
Definition: data.h:317
base.h
defines configuration macros of xgboost.
xgboost::SparsePage::Size
size_t Size() const
Definition: data.h:245
xgboost::DataType
DataType
data type accepted by xgboost interface
Definition: data.h:30
xgboost::SparsePage::data
HostDeviceVector< Entry > data
the data of the segments
Definition: data.h:216
xgboost::MetaInfo::num_nonzero_
uint64_t num_nonzero_
number of nonzero entries in the data
Definition: data.h:50
xgboost::Entry
Element from a sparse vector.
Definition: data.h:167
dmlc::DMLC_DECLARE_TRAITS
DMLC_DECLARE_TRAITS(is_pod, xgboost::Entry, true)
xgboost::BatchParam::BatchParam
BatchParam(int32_t device, int32_t max_bin, size_t gpu_page_size=0)
Definition: data.h:200
xgboost::DataType::kUInt64
xgboost::BatchSet::end
BatchIterator< T > end()
Definition: data.h:417
dmlc::serializer::Handler< xgboost::Entry >::Write
static void Write(Stream *strm, const xgboost::Entry &data)
Definition: data.h:563
xgboost::Entry::index
bst_feature_t index
feature index
Definition: data.h:169
xgboost::MetaInfo::LabelAbsSort
const std::vector< size_t > & LabelAbsSort() const
get sorted indexes (argsort) of labels by absolute value (used by cox loss)
Definition: data.h:118
xgboost::MetaInfo::weights_
HostDeviceVector< bst_float > weights_
weights of each instance, optional
Definition: data.h:59
xgboost::Entry::fvalue
bst_float fvalue
feature value
Definition: data.h:171
xgboost::DataType::kFloat32
xgboost::Entry::CmpValue
static bool CmpValue(const Entry &a, const Entry &b)
reversely compare feature values
Definition: data.h:181
xgboost::HostDeviceVector::Resize
void Resize(size_t new_size, T v=T())
xgboost::SparsePage::Clear
void Clear()
clear the page
Definition: data.h:255
xgboost::BatchParam::max_bin
int max_bin
Maximum number of bins per feature for histograms.
Definition: data.h:196
xgboost::DataSource::info
MetaInfo info
Meta information about the dataset The subclass need to be able to load this correctly from data...
Definition: data.h:437
xgboost::EllpackPage::Impl
EllpackPageImpl * Impl()
Definition: data.h:361