Logo ROOT  
Reference Guide
RNTuple.hxx
Go to the documentation of this file.
1/// \file ROOT/RNTuple.hxx
2/// \ingroup NTuple ROOT7
3/// \author Jakob Blomer <jblomer@cern.ch>
4/// \date 2018-10-04
5/// \warning This is part of the ROOT 7 prototype! It will change without notice. It might trigger earthquakes. Feedback
6/// is welcome!
7
8/*************************************************************************
9 * Copyright (C) 1995-2019, Rene Brun and Fons Rademakers. *
10 * All rights reserved. *
11 * *
12 * For the licensing terms see $ROOTSYS/LICENSE. *
13 * For the list of contributors see $ROOTSYS/README/CREDITS. *
14 *************************************************************************/
15
16#ifndef ROOT7_RNTuple
17#define ROOT7_RNTuple
18
20#include <ROOT/RNTupleModel.hxx>
22#include <ROOT/RNTupleUtil.hxx>
23#include <ROOT/RNTupleView.hxx>
24#include <ROOT/RPageStorage.hxx>
25#include <ROOT/RStringView.hxx>
26
27#include <iterator>
28#include <memory>
29#include <sstream>
30#include <utility>
31
32namespace ROOT {
33namespace Experimental {
34
35class REntry;
36class RNTupleModel;
37
38namespace Detail {
39class RPageSink;
40class RPageSource;
41}
42
43
44/**
45 * Listing of the different options that can be printed by RNTupleReader::GetInfo()
46 */
47enum class ENTupleInfo {
48 kSummary, // The ntuple name, description, number of entries
49 kStorageDetails, // size on storage, page sizes, compression factor, etc.
50 kMetrics, // internals performance counters, requires that EnableMetrics() was called
51};
52
53/**
54 * Listing of the different entry output formats of RNTupleReader::Show()
55 */
56enum class ENTupleFormat {
57 kJSON, // prints a single entry/row in JSON format.
58};
59
60
61// clang-format off
62/**
63\class ROOT::Experimental::RNTupleReader
64\ingroup NTuple
65\brief An RNTuple that is used to read data from storage
66
67An input ntuple provides data from storage as C++ objects. The ntuple model can be created from the data on storage
68or it can be imposed by the user. The latter case allows users to read into a specialized ntuple model that covers
69only a subset of the fields in the ntuple. The ntuple model is used when reading complete entries.
70Individual fields can be read as well by instantiating a tree view.
71*/
72// clang-format on
74private:
75 std::unique_ptr<Detail::RPageSource> fSource;
76 /// Needs to be destructed before fSource
77 std::unique_ptr<RNTupleModel> fModel;
79
80 void ConnectModel();
81
82public:
83 // Browse through the entries
84 class RIterator : public std::iterator<std::forward_iterator_tag, NTupleSize_t> {
85 private:
88 public:
89 RIterator() = default;
90 explicit RIterator(NTupleSize_t index) : fIndex(index) {}
91 ~RIterator() = default;
92
93 iterator operator++(int) /* postfix */ { auto r = *this; fIndex++; return r; }
94 iterator& operator++() /* prefix */ { ++fIndex; return *this; }
95 reference operator* () { return fIndex; }
96 pointer operator->() { return &fIndex; }
97 bool operator==(const iterator& rh) const { return fIndex == rh.fIndex; }
98 bool operator!=(const iterator& rh) const { return fIndex != rh.fIndex; }
99 };
100
101
102 static std::unique_ptr<RNTupleReader> Open(std::unique_ptr<RNTupleModel> model,
103 std::string_view ntupleName,
104 std::string_view storage);
105 static std::unique_ptr<RNTupleReader> Open(std::string_view ntupleName, std::string_view storage);
106
107 /// The user imposes an ntuple model, which must be compatible with the model found in the data on storage
108 RNTupleReader(std::unique_ptr<RNTupleModel> model, std::unique_ptr<Detail::RPageSource> source);
109 /// The model is generated from the ntuple metadata on storage
110 explicit RNTupleReader(std::unique_ptr<Detail::RPageSource> source);
111 std::unique_ptr<RNTupleReader> Clone() { return std::make_unique<RNTupleReader>(fSource->Clone()); }
113
114 RNTupleModel *GetModel() { return fModel.get(); }
115 NTupleSize_t GetNEntries() const { return fSource->GetNEntries(); }
116 const RNTupleDescriptor &GetDescriptor() const { return fSource->GetDescriptor(); }
117
118 /// Prints a detailed summary of the ntuple, including a list of fields.
119 void PrintInfo(const ENTupleInfo what = ENTupleInfo::kSummary, std::ostream &output = std::cout);
120
121 /// Shows the values of the i-th entry/row, starting with 0 for the first entry. By default,
122 /// prints the output in JSON format.
123 /// Uses the visitor pattern to traverse through each field of the given entry.
124 void Show(NTupleSize_t index, const ENTupleFormat format = ENTupleFormat::kJSON, std::ostream &output = std::cout);
125
126 /// Analogous to Fill(), fills the default entry of the model. Returns false at the end of the ntuple.
127 /// On I/O errors, raises an expection.
128 void LoadEntry(NTupleSize_t index) { LoadEntry(index, fModel->GetDefaultEntry()); }
129 /// Fills a user provided entry after checking that the entry has been instantiated from the ntuple model
130 void LoadEntry(NTupleSize_t index, REntry* entry) {
131 for (auto& value : *entry) {
132 value.GetField()->Read(index, &value);
133 }
134 }
135
137
138 /// Provides access to an individual field that can contain either a scalar value or a collection, e.g.
139 /// GetView<double>("particles.pt") or GetView<std::vector<double>>("particle"). It can as well be the index
140 /// field of a collection itself, like GetView<NTupleSize_t>("particle")
141 template <typename T>
143 auto fieldId = fSource->GetDescriptor().FindFieldId(fieldName);
144 return RNTupleView<T>(fieldId, fSource.get());
145 }
147 auto fieldId = fSource->GetDescriptor().FindFieldId(fieldName);
148 return RNTupleViewCollection(fieldId, fSource.get());
149 }
150
151 RIterator begin() { return RIterator(0); }
153
155};
156
157// clang-format off
158/**
159\class ROOT::Experimental::RNTupleWriter
160\ingroup NTuple
161\brief An RNTuple that gets filled with entries (data) and writes them to storage
162
163An output ntuple can be filled with entries. The caller has to make sure that the data that gets filled into an ntuple
164is not modified for the time of the Fill() call. The fill call serializes the C++ object into the column format and
165writes data into the corresponding column page buffers. Writing of the buffers to storage is deferred and can be
166triggered by Flush() or by destructing the ntuple. On I/O errors, an exception is thrown.
167*/
168// clang-format on
170private:
171 static constexpr NTupleSize_t kDefaultClusterSizeEntries = 64000;
172 std::unique_ptr<Detail::RPageSink> fSink;
173 /// Needs to be destructed before fSink
174 std::unique_ptr<RNTupleModel> fModel;
178
179public:
180 static std::unique_ptr<RNTupleWriter> Recreate(std::unique_ptr<RNTupleModel> model,
181 std::string_view ntupleName,
182 std::string_view storage,
183 const RNTupleWriteOptions &options = RNTupleWriteOptions());
184 RNTupleWriter(std::unique_ptr<RNTupleModel> model, std::unique_ptr<Detail::RPageSink> sink);
185 RNTupleWriter(const RNTupleWriter&) = delete;
188
189 /// The simplest user interface if the default entry that comes with the ntuple model is used
190 void Fill() { Fill(fModel->GetDefaultEntry()); }
191 /// Multiple entries can have been instantiated from the tnuple model. This method will perform
192 /// a light check whether the entry comes from the ntuple's own model
193 void Fill(REntry *entry) {
194 for (auto& value : *entry) {
195 value.GetField()->Append(value);
196 }
197 fNEntries++;
198 if ((fNEntries % fClusterSizeEntries) == 0)
200 }
201 /// Ensure that the data from the so far seen Fill calls has been written to storage
202 void CommitCluster();
203};
204
205// clang-format off
206/**
207\class ROOT::Experimental::RCollectionNTuple
208\ingroup NTuple
209\brief A virtual ntuple for collections that can be used to some extent like a real ntuple
210*
211* This class is between a field and a ntuple. It carries the offset column for the collection and the default entry
212* taken from the collection model. It does not, however, have a tree model because the collection model has been merged
213* into the larger ntuple model.
214*/
215// clang-format on
217private:
219 std::unique_ptr<REntry> fDefaultEntry;
220public:
221 explicit RCollectionNTuple(std::unique_ptr<REntry> defaultEntry);
225
226 void Fill() { Fill(fDefaultEntry.get()); }
227 void Fill(REntry *entry) {
228 for (auto& treeValue : *entry) {
229 treeValue.GetField()->Append(treeValue);
230 }
231 fOffset++;
232 }
233
235};
236
237} // namespace Experimental
238} // namespace ROOT
239
240#endif
ROOT::R::TRInterface & r
Definition: Object.C:4
A collection of Counter objects with a name, a unit, and a description.
A virtual ntuple for collections that can be used to some extent like a real ntuple.
Definition: RNTuple.hxx:216
RCollectionNTuple(std::unique_ptr< REntry > defaultEntry)
Definition: RNTuple.cxx:219
RCollectionNTuple(const RCollectionNTuple &)=delete
std::unique_ptr< REntry > fDefaultEntry
Definition: RNTuple.hxx:219
RCollectionNTuple & operator=(const RCollectionNTuple &)=delete
The REntry is a collection of values in an ntuple corresponding to a complete row in the data set.
Definition: REntry.hxx:42
The on-storage meta-data of an ntuple.
Used to loop over indexes (entries or collections) between start and end.
Definition: RNTupleView.hxx:40
The RNTupleModel encapulates the schema of an ntuple.
bool operator!=(const iterator &rh) const
Definition: RNTuple.hxx:98
bool operator==(const iterator &rh) const
Definition: RNTuple.hxx:97
An RNTuple that is used to read data from storage.
Definition: RNTuple.hxx:73
static std::unique_ptr< RNTupleReader > Open(std::unique_ptr< RNTupleModel > model, std::string_view ntupleName, std::string_view storage)
Definition: RNTuple.cxx:73
std::unique_ptr< RNTupleReader > Clone()
Definition: RNTuple.hxx:111
Detail::RNTupleMetrics fMetrics
Definition: RNTuple.hxx:78
void LoadEntry(NTupleSize_t index, REntry *entry)
Fills a user provided entry after checking that the entry has been instantiated from the ntuple model...
Definition: RNTuple.hxx:130
const RNTupleDescriptor & GetDescriptor() const
Definition: RNTuple.hxx:116
void Show(NTupleSize_t index, const ENTupleFormat format=ENTupleFormat::kJSON, std::ostream &output=std::cout)
Shows the values of the i-th entry/row, starting with 0 for the first entry.
Definition: RNTuple.cxx:143
RNTupleView< T > GetView(std::string_view fieldName)
Provides access to an individual field that can contain either a scalar value or a collection,...
Definition: RNTuple.hxx:142
NTupleSize_t GetNEntries() const
Definition: RNTuple.hxx:115
std::unique_ptr< Detail::RPageSource > fSource
Definition: RNTuple.hxx:75
RNTupleReader(std::unique_ptr< RNTupleModel > model, std::unique_ptr< Detail::RPageSource > source)
The user imposes an ntuple model, which must be compatible with the model found in the data on storag...
Definition: RNTuple.cxx:46
RNTupleGlobalRange GetEntryRange()
Definition: RNTuple.hxx:136
RNTupleViewCollection GetViewCollection(std::string_view fieldName)
Definition: RNTuple.hxx:146
void LoadEntry(NTupleSize_t index)
Analogous to Fill(), fills the default entry of the model.
Definition: RNTuple.hxx:128
void PrintInfo(const ENTupleInfo what=ENTupleInfo::kSummary, std::ostream &output=std::cout)
Prints a detailed summary of the ntuple, including a list of fields.
Definition: RNTuple.cxx:88
std::unique_ptr< RNTupleModel > fModel
Needs to be destructed before fSource.
Definition: RNTuple.hxx:77
A view for a collection, that can itself generate new ntuple views for its nested fields.
An RNTupleView provides read-only access to a single field of the ntuple.
Common user-tunable settings for storing ntuples.
An RNTuple that gets filled with entries (data) and writes them to storage.
Definition: RNTuple.hxx:169
void Fill(REntry *entry)
Multiple entries can have been instantiated from the tnuple model.
Definition: RNTuple.hxx:193
void CommitCluster()
Ensure that the data from the so far seen Fill calls has been written to storage.
Definition: RNTuple.cxx:204
RNTupleWriter(std::unique_ptr< RNTupleModel > model, std::unique_ptr< Detail::RPageSink > sink)
Definition: RNTuple.cxx:176
std::unique_ptr< RNTupleModel > fModel
Needs to be destructed before fSink.
Definition: RNTuple.hxx:174
static constexpr NTupleSize_t kDefaultClusterSizeEntries
Definition: RNTuple.hxx:171
RNTupleWriter(const RNTupleWriter &)=delete
RNTupleWriter & operator=(const RNTupleWriter &)=delete
std::unique_ptr< Detail::RPageSink > fSink
Definition: RNTuple.hxx:172
void Fill()
The simplest user interface if the default entry that comes with the ntuple model is used.
Definition: RNTuple.hxx:190
static std::unique_ptr< RNTupleWriter > Recreate(std::unique_ptr< RNTupleModel > model, std::string_view ntupleName, std::string_view storage, const RNTupleWriteOptions &options=RNTupleWriteOptions())
Definition: RNTuple.cxx:194
basic_string_view< char > string_view
ENTupleInfo
Listing of the different options that can be printed by RNTupleReader::GetInfo()
Definition: RNTuple.hxx:47
std::uint64_t NTupleSize_t
Integer type long enough to hold the maximum number of entries in a column.
Definition: RNTupleUtil.hxx:42
ENTupleFormat
Listing of the different entry output formats of RNTupleReader::Show()
Definition: RNTuple.hxx:56
constexpr NTupleSize_t kInvalidNTupleIndex
Definition: RNTupleUtil.hxx:43
tbb::task_arena is an alias of tbb::interface7::task_arena, which doesn't allow to forward declare tb...
Definition: StringConv.hxx:21
static const char * what
Definition: stlLoader.cc:6
Wrap the 32bit integer in a struct in order to avoid template specialization clash with std::uint32_t...
Definition: RNTupleUtil.hxx:45
static void output(int code)
Definition: gifencode.c:226