Logo ROOT  
Reference Guide
 
Loading...
Searching...
No Matches
ROOT::Experimental::RNTupleReader Class Reference

An RNTuple that is used to read data from storage.

An input ntuple provides data from storage as C++ objects. The ntuple model can be created from the data on storage or it can be imposed by the user. The latter case allows users to read into a specialized ntuple model that covers only a subset of the fields in the ntuple. The ntuple model is used when reading complete entries. Individual fields can be read as well by instantiating a tree view.

#include <iostream>
auto ntuple = RNTupleReader::Open("myNTuple", "some/file.root");
std::cout << "myNTuple has " << ntuple->GetNEntries() << " entries\n";
An RNTuple that is used to read data from storage.
static std::unique_ptr< RNTupleReader > Open(std::string_view ntupleName, std::string_view storage, const RNTupleReadOptions &options=RNTupleReadOptions())
Open an RNTuple for reading.

Definition at line 71 of file RNTupleReader.hxx.

Classes

class  RIterator
 
struct  ROpenSpec
 Used to specify the underlying RNTuples in OpenFriends() More...
 

Public Member Functions

 ~RNTupleReader ()
 
RIterator begin ()
 
std::unique_ptr< RNTupleReaderClone ()
 
void EnableMetrics ()
 Enable performance measurements (decompression time, bytes read from storage, etc.)
 
RIterator end ()
 
RNTupleCollectionView GetCollectionView (DescriptorId_t fieldId)
 
RNTupleCollectionView GetCollectionView (std::string_view fieldName)
 Raises an exception if:
 
const RNTupleDescriptorGetDescriptor ()
 Returns a cached copy of the page source descriptor.
 
RNTupleGlobalRange GetEntryRange ()
 Returns an iterator over the entry indices of the RNTuple.
 
const Detail::RNTupleMetricsGetMetrics () const
 
const RNTupleModelGetModel ()
 
NTupleSize_t GetNEntries () const
 
template<typename T >
RNTupleView< T > GetView (DescriptorId_t fieldId)
 
template<typename T >
RNTupleView< T > GetView (std::string_view fieldName)
 Provides access to an individual field that can contain either a scalar value or a collection, e.g.
 
void LoadEntry (NTupleSize_t index)
 Analogous to Fill(), fills the default entry of the model.
 
void LoadEntry (NTupleSize_t index, REntry &entry)
 Fills a user provided entry after checking that the entry has been instantiated from the ntuple model.
 
void PrintInfo (const ENTupleInfo what=ENTupleInfo::kSummary, std::ostream &output=std::cout)
 Prints a detailed summary of the ntuple, including a list of fields.
 
void Show (NTupleSize_t index, std::ostream &output=std::cout)
 Shows the values of the i-th entry/row, starting with 0 for the first entry.
 

Static Public Member Functions

static std::unique_ptr< RNTupleReaderOpen (RNTuple *ntuple, const RNTupleReadOptions &options=RNTupleReadOptions())
 
static std::unique_ptr< RNTupleReaderOpen (std::string_view ntupleName, std::string_view storage, const RNTupleReadOptions &options=RNTupleReadOptions())
 Open an RNTuple for reading.
 
static std::unique_ptr< RNTupleReaderOpen (std::unique_ptr< RNTupleModel > model, RNTuple *ntuple, const RNTupleReadOptions &options=RNTupleReadOptions())
 
static std::unique_ptr< RNTupleReaderOpen (std::unique_ptr< RNTupleModel > model, std::string_view ntupleName, std::string_view storage, const RNTupleReadOptions &options=RNTupleReadOptions())
 The caller imposes a model, which must be compatible with the model found in the data on storage.
 
static std::unique_ptr< RNTupleReaderOpenFriends (std::span< ROpenSpec > ntuples)
 Open RNTuples as one virtual, horizontally combined ntuple.
 

Private Member Functions

 RNTupleReader (std::unique_ptr< Internal::RPageSource > source)
 The model is generated from the ntuple metadata on storage.
 
 RNTupleReader (std::unique_ptr< RNTupleModel > model, std::unique_ptr< Internal::RPageSource > source)
 
void ConnectModel (RNTupleModel &model)
 
RNTupleReaderGetDisplayReader ()
 
void InitPageSource ()
 

Private Attributes

std::unique_ptr< RNTupleDescriptorfCachedDescriptor
 The ntuple descriptor in the page source is protected by a read-write lock.
 
std::unique_ptr< RNTupleReaderfDisplayReader
 We use a dedicated on-demand reader for Show() and Scan().
 
Detail::RNTupleMetrics fMetrics
 
std::unique_ptr< RNTupleModelfModel
 Needs to be destructed before fSource.
 
std::unique_ptr< Internal::RPageSourcefSource
 
std::unique_ptr< Internal::RPageStorage::RTaskSchedulerfUnzipTasks
 Set as the page source's scheduler for parallel page decompression if IMT is on Needs to be destructed after the pages source is destructed (an thus be declared before)
 

#include <ROOT/RNTupleReader.hxx>

Constructor & Destructor Documentation

◆ RNTupleReader() [1/2]

ROOT::Experimental::RNTupleReader::RNTupleReader ( std::unique_ptr< RNTupleModel model,
std::unique_ptr< Internal::RPageSource source 
)
private

Definition at line 59 of file RNTupleReader.cxx.

◆ RNTupleReader() [2/2]

ROOT::Experimental::RNTupleReader::RNTupleReader ( std::unique_ptr< Internal::RPageSource source)
explicitprivate

The model is generated from the ntuple metadata on storage.

Definition at line 72 of file RNTupleReader.cxx.

◆ ~RNTupleReader()

ROOT::Experimental::RNTupleReader::~RNTupleReader ( )
default

Member Function Documentation

◆ begin()

RIterator ROOT::Experimental::RNTupleReader::begin ( )
inline

Definition at line 307 of file RNTupleReader.hxx.

◆ Clone()

std::unique_ptr< RNTupleReader > ROOT::Experimental::RNTupleReader::Clone ( )
inline

Definition at line 173 of file RNTupleReader.hxx.

◆ ConnectModel()

void ROOT::Experimental::RNTupleReader::ConnectModel ( RNTupleModel model)
private

Definition at line 28 of file RNTupleReader.cxx.

◆ EnableMetrics()

void ROOT::Experimental::RNTupleReader::EnableMetrics ( )
inline

Enable performance measurements (decompression time, bytes read from storage, etc.)

Example: inspect the reader metrics after loading every entry

#include <iostream>
auto ntuple = RNTupleReader::Open("myNTuple", "some/file.root");
// metrics must be turned on beforehand
ntuple->EnableMetrics();
for (auto i : ntuple->GetEntryRange()) {
ntuple->LoadEntry(i);
}
ntuple->PrintInfo(ENTupleInfo::kMetrics);
RNTupleGlobalRange GetEntryRange()
Returns an iterator over the entry indices of the RNTuple.
ENTupleInfo
Listing of the different options that can be printed by RNTupleReader::GetInfo()

Definition at line 329 of file RNTupleReader.hxx.

◆ end()

RIterator ROOT::Experimental::RNTupleReader::end ( )
inline

Definition at line 308 of file RNTupleReader.hxx.

◆ GetCollectionView() [1/2]

RNTupleCollectionView ROOT::Experimental::RNTupleReader::GetCollectionView ( DescriptorId_t  fieldId)
inline

Definition at line 302 of file RNTupleReader.hxx.

◆ GetCollectionView() [2/2]

RNTupleCollectionView ROOT::Experimental::RNTupleReader::GetCollectionView ( std::string_view  fieldName)
inline

Raises an exception if:

  • there is no field with the given name or,
  • the field is not a collection

Definition at line 292 of file RNTupleReader.hxx.

◆ GetDescriptor()

const ROOT::Experimental::RNTupleDescriptor & ROOT::Experimental::RNTupleReader::GetDescriptor ( )

Returns a cached copy of the page source descriptor.

The returned pointer remains valid until the next call to LoadEntry or to any of the views returned from the reader.

Definition at line 224 of file RNTupleReader.cxx.

◆ GetDisplayReader()

ROOT::Experimental::RNTupleReader * ROOT::Experimental::RNTupleReader::GetDisplayReader ( )
private

Definition at line 195 of file RNTupleReader.cxx.

◆ GetEntryRange()

RNTupleGlobalRange ROOT::Experimental::RNTupleReader::GetEntryRange ( )
inline

Returns an iterator over the entry indices of the RNTuple.

Example: iterate over all entries and print each entry in JSON format

using ROOT::Experimental::ENTupleShowFormat;
#include <iostream>
auto ntuple = RNTupleReader::Open("myNTuple", "some/file.root");
for (auto i : ntuple->GetEntryRange()) {
ntuple->Show(i);
}

Definition at line 250 of file RNTupleReader.hxx.

◆ GetMetrics()

const Detail::RNTupleMetrics & ROOT::Experimental::RNTupleReader::GetMetrics ( ) const
inline

Definition at line 330 of file RNTupleReader.hxx.

◆ GetModel()

const ROOT::Experimental::RNTupleModel & ROOT::Experimental::RNTupleReader::GetModel ( )

Definition at line 122 of file RNTupleReader.cxx.

◆ GetNEntries()

NTupleSize_t ROOT::Experimental::RNTupleReader::GetNEntries ( ) const
inline

Definition at line 179 of file RNTupleReader.hxx.

◆ GetView() [1/2]

template<typename T >
RNTupleView< T > ROOT::Experimental::RNTupleReader::GetView ( DescriptorId_t  fieldId)
inline

Definition at line 284 of file RNTupleReader.hxx.

◆ GetView() [2/2]

template<typename T >
RNTupleView< T > ROOT::Experimental::RNTupleReader::GetView ( std::string_view  fieldName)
inline

Provides access to an individual field that can contain either a scalar value or a collection, e.g.

GetView<double>("particles.pt") or GetView<std::vector<double>>("particle"). It can as well be the index field of a collection itself, like GetView<NTupleSize_t>("particle").

Raises an exception if there is no field with the given name.

Example: iterate over a field named "pt" of type float

#include <iostream>
auto ntuple = RNTupleReader::Open("myNTuple", "some/file.root");
auto pt = ntuple->GetView<float>("pt");
for (auto i : ntuple->GetEntryRange()) {
std::cout << i << ": " << pt(i) << "\n";
}
TPaveText * pt

Definition at line 273 of file RNTupleReader.hxx.

◆ InitPageSource()

void ROOT::Experimental::RNTupleReader::InitPageSource ( )
private

Definition at line 46 of file RNTupleReader.cxx.

◆ LoadEntry() [1/2]

void ROOT::Experimental::RNTupleReader::LoadEntry ( NTupleSize_t  index)
inline

Analogous to Fill(), fills the default entry of the model.

Returns false at the end of the ntuple. On I/O errors, raises an exception.

Definition at line 223 of file RNTupleReader.hxx.

◆ LoadEntry() [2/2]

void ROOT::Experimental::RNTupleReader::LoadEntry ( NTupleSize_t  index,
REntry entry 
)
inline

Fills a user provided entry after checking that the entry has been instantiated from the ntuple model.

Definition at line 233 of file RNTupleReader.hxx.

◆ Open() [1/4]

std::unique_ptr< ROOT::Experimental::RNTupleReader > ROOT::Experimental::RNTupleReader::Open ( RNTuple ntuple,
const RNTupleReadOptions options = RNTupleReadOptions() 
)
static

Definition at line 97 of file RNTupleReader.cxx.

◆ Open() [2/4]

std::unique_ptr< ROOT::Experimental::RNTupleReader > ROOT::Experimental::RNTupleReader::Open ( std::string_view  ntupleName,
std::string_view  storage,
const RNTupleReadOptions options = RNTupleReadOptions() 
)
static

Open an RNTuple for reading.

Throws an RException if there is no RNTuple with the given name.

Example: open an RNTuple and print the number of entries

#include <iostream>
auto ntuple = RNTupleReader::Open("myNTuple", "some/file.root");
std::cout << "myNTuple has " << ntuple->GetNEntries() << " entries\n";

Definition at line 89 of file RNTupleReader.cxx.

◆ Open() [3/4]

std::unique_ptr< ROOT::Experimental::RNTupleReader > ROOT::Experimental::RNTupleReader::Open ( std::unique_ptr< RNTupleModel model,
RNTuple ntuple,
const RNTupleReadOptions options = RNTupleReadOptions() 
)
static

Definition at line 104 of file RNTupleReader.cxx.

◆ Open() [4/4]

std::unique_ptr< ROOT::Experimental::RNTupleReader > ROOT::Experimental::RNTupleReader::Open ( std::unique_ptr< RNTupleModel model,
std::string_view  ntupleName,
std::string_view  storage,
const RNTupleReadOptions options = RNTupleReadOptions() 
)
static

The caller imposes a model, which must be compatible with the model found in the data on storage.

Definition at line 81 of file RNTupleReader.cxx.

◆ OpenFriends()

std::unique_ptr< ROOT::Experimental::RNTupleReader > ROOT::Experimental::RNTupleReader::OpenFriends ( std::span< ROpenSpec ntuples)
static

Open RNTuples as one virtual, horizontally combined ntuple.

The underlying RNTuples must have an identical number of entries. Fields in the combined RNTuple are named with the ntuple name as a prefix, e.g. myNTuple1.px and myNTuple2.pt (see tutorial ntpl006_friends)

Definition at line 112 of file RNTupleReader.cxx.

◆ PrintInfo()

void ROOT::Experimental::RNTupleReader::PrintInfo ( const ENTupleInfo  what = ENTupleInfo::kSummary,
std::ostream &  output = std::cout 
)

Prints a detailed summary of the ntuple, including a list of fields.

Example: print summary information to stdout

#include <iostream>
auto ntuple = RNTupleReader::Open("myNTuple", "some/file.root");
ntuple->PrintInfo();
// or, equivalently:
ntuple->PrintInfo(ENTupleInfo::kSummary, std::cout);

Example: print detailed column storage data to stderr

#include <iostream>
auto ntuple = RNTupleReader::Open("myNTuple", "some/file.root");
ntuple->PrintInfo(ENTupleInfo::kStorageDetails, std::cerr);

For use of ENTupleInfo::kMetrics, see EnableMetrics.

Definition at line 131 of file RNTupleReader.cxx.

◆ Show()

void ROOT::Experimental::RNTupleReader::Show ( NTupleSize_t  index,
std::ostream &  output = std::cout 
)

Shows the values of the i-th entry/row, starting with 0 for the first entry.

By default, prints the output in JSON format. Uses the visitor pattern to traverse through each field of the given entry.

Definition at line 202 of file RNTupleReader.cxx.

Member Data Documentation

◆ fCachedDescriptor

std::unique_ptr<RNTupleDescriptor> ROOT::Experimental::RNTupleReader::fCachedDescriptor
private

The ntuple descriptor in the page source is protected by a read-write lock.

We don't expose that to the users of RNTupleReader::GetDescriptor(). Instead, if descriptor information is needed, we clone the descriptor. Using the descriptor's generation number, we know if the cached descriptor is stale. Retrieving descriptor data from an RNTupleReader is supposed to be for testing and information purposes, not on a hot code path.

Definition at line 89 of file RNTupleReader.hxx.

◆ fDisplayReader

std::unique_ptr<RNTupleReader> ROOT::Experimental::RNTupleReader::fDisplayReader
private

We use a dedicated on-demand reader for Show() and Scan().

Printing data uses all the fields from the full model even if the analysis code uses only a subset of fields. The display reader is a clone of the original reader.

Definition at line 83 of file RNTupleReader.hxx.

◆ fMetrics

Detail::RNTupleMetrics ROOT::Experimental::RNTupleReader::fMetrics
private

Definition at line 90 of file RNTupleReader.hxx.

◆ fModel

std::unique_ptr<RNTupleModel> ROOT::Experimental::RNTupleReader::fModel
private

Needs to be destructed before fSource.

Definition at line 79 of file RNTupleReader.hxx.

◆ fSource

std::unique_ptr<Internal::RPageSource> ROOT::Experimental::RNTupleReader::fSource
private

Definition at line 77 of file RNTupleReader.hxx.

◆ fUnzipTasks

std::unique_ptr<Internal::RPageStorage::RTaskScheduler> ROOT::Experimental::RNTupleReader::fUnzipTasks
private

Set as the page source's scheduler for parallel page decompression if IMT is on Needs to be destructed after the pages source is destructed (an thus be declared before)

Definition at line 75 of file RNTupleReader.hxx.

Libraries for ROOT::Experimental::RNTupleReader:

The documentation for this class was generated from the following files: