Interface for iterating over entries of RNTuples and vertically concatenated RNTuples (chains).

Example usage (see ntpl012_processor.C for a full example):

#include <ROOT/RNTupleProcessor.hxx>
using ROOT::Experimental::RNTupleProcessor;
using ROOT::Experimental::RNTupleOpenSpec;
 
std::vector<RNTupleOpenSpec> ntuples = {{"ntuple1", "ntuple1.root"}, {"ntuple2", "ntuple2.root"}};
auto processor = RNTupleProcessor::CreateChain(ntuples);
 
for (const auto &entry : processor) {
   std::cout << "pt = " << *entry.GetPtr<float>("pt") << std::endl;
}

An RNTupleProcessor is created by providing one or more RNTupleOpenSpecs, each of which contains the name and storage location of a single RNTuple. The RNTuples are processed in the order in which they were provided.

The RNTupleProcessor constructor also (optionally) accepts an RNTupleModel, which determines which fields should be read. If no model is provided, a default model based on the descriptor of the first specified RNTuple will be used. If a field that was present in the first RNTuple is not found in a subsequent one, an error will be thrown.

The RNTupleProcessor provides an iterator which gives access to the REntry containing the field data for the current entry. Additional bookkeeping information can be obtained through the RNTupleProcessor itself.

Definition at line 100 of file RNTupleProcessor.hxx.

Classes
class	RIterator
	Iterator over the entries of an RNTuple, or vertical concatenation thereof. More...

Public Member Functions
	RNTupleProcessor (const RNTupleProcessor &)=delete

	RNTupleProcessor (RNTupleProcessor &&)=delete

virtual	~RNTupleProcessor ()=default

RIterator	begin ()

RIterator	end ()

ROOT::NTupleSize_t	GetCurrentEntryNumber () const
	Get the entry number that is currently being processed.

std::size_t	GetCurrentProcessorNumber () const
	Get the number of the inner processor currently being read.

const ROOT::REntry &	GetEntry () const
	Get a reference to the entry used by the processor.

const ROOT::RNTupleModel &	GetModel () const
	Get the model used by the processor.

ROOT::NTupleSize_t	GetNEntriesProcessed () const
	Get the total number of entries processed so far.

const std::string &	GetProcessorName () const
	Get the name of the processor.

RNTupleProcessor &	operator= (const RNTupleProcessor &)=delete

RNTupleProcessor &	operator= (RNTupleProcessor &&)=delete

void	PrintStructure (std::ostream &output=std::cout)
	Print a graphical representation of the processor composition.

Static Public Member Functions
static std::unique_ptr< RNTupleProcessor >	Create (RNTupleOpenSpec ntuple, std::unique_ptr< ROOT::RNTupleModel > model=nullptr, std::string_view processorName="")
	Create an RNTupleProcessor for a single RNTuple.

static std::unique_ptr< RNTupleProcessor >	CreateChain (std::vector< RNTupleOpenSpec > ntuples, std::unique_ptr< ROOT::RNTupleModel > model=nullptr, std::string_view processorName="")
	Create an RNTupleProcessor for a chain (i.e., a vertical combination) of RNTuples.

static std::unique_ptr< RNTupleProcessor >	CreateChain (std::vector< std::unique_ptr< RNTupleProcessor > > innerProcessors, std::unique_ptr< ROOT::RNTupleModel > model=nullptr, std::string_view processorName="")
	Create an RNTupleProcessor for a chain (i.e., a vertical combination) of other RNTupleProcessors.

static std::unique_ptr< RNTupleProcessor >	CreateJoin (RNTupleOpenSpec primaryNTuple, RNTupleOpenSpec auxNTuple, const std::vector< std::string > &joinFields, std::unique_ptr< ROOT::RNTupleModel > primaryModel=nullptr, std::unique_ptr< ROOT::RNTupleModel > auxModel=nullptr, std::string_view processorName="")
	Create an RNTupleProcessor for a join (i.e., a horizontal combination) of RNTuples.

static std::unique_ptr< RNTupleProcessor >	CreateJoin (std::unique_ptr< RNTupleProcessor > primaryProcessor, std::unique_ptr< RNTupleProcessor > auxProcessor, const std::vector< std::string > &joinFields, std::unique_ptr< ROOT::RNTupleModel > primaryModel=nullptr, std::unique_ptr< ROOT::RNTupleModel > auxModel=nullptr, std::string_view processorName="")
	Create an RNTupleProcessor for a join (i.e., a horizontal combination) of RNTuples.

Protected Member Functions
	RNTupleProcessor (std::string_view processorName, std::unique_ptr< ROOT::RNTupleModel > model)
	Create a new base RNTupleProcessor.

virtual void	AddEntriesToJoinTable (Internal::RNTupleJoinTable &joinTable, ROOT::NTupleSize_t entryOffset=0)=0
	Add the entry mappings for this processor to the provided join table.

virtual ROOT::NTupleSize_t	GetNEntries ()=0
	Get the total number of entries in this processor.

virtual ROOT::NTupleSize_t	LoadEntry (ROOT::NTupleSize_t entryNumber)=0
	Load the entry identified by the provided entry number.

virtual void	PrintStructureImpl (std::ostream &output) const =0
	Processor-specific implementation for printing its structure, called by PrintStructure().

virtual void	SetEntryPointers (const ROOT::REntry &entry, std::string_view fieldNamePrefix="")=0
	Point the entry's field values of the processor to the pointers from the provided entry.

Protected Attributes
ROOT::NTupleSize_t	fCurrentEntryNumber = 0

std::size_t	fCurrentProcessorNumber = 0

std::unique_ptr< ROOT::REntry >	fEntry

std::unique_ptr< ROOT::RNTupleModel >	fModel

ROOT::NTupleSize_t	fNEntries = kInvalidNTupleIndex
	Total number of entries.

ROOT::NTupleSize_t	fNEntriesProcessed = 0

std::string	fProcessorName

Friends
class	RNTupleChainProcessor

class	RNTupleJoinProcessor

class	RNTupleSingleProcessor

struct	ROOT::Experimental::Internal::RNTupleProcessorEntryLoader

#include <ROOT/RNTupleProcessor.hxx>

Inheritance diagram for ROOT::Experimental::RNTupleProcessor:

[legend]

Constructor & Destructor Documentation

◆ RNTupleProcessor() [1/3]

ROOT::Experimental::RNTupleProcessor::RNTupleProcessor	(	std::string_view	processorName,
		std::unique_ptr< ROOT::RNTupleModel >	model )

inlineprotected

Create a new base RNTupleProcessor.

Parameters

[in]	processorName	Name of the processor. By default, this is the name of the underlying RNTuple for RNTupleSingleProcessor, the name of the first processor for RNTupleChainProcessor, or the name of the primary RNTuple for RNTupleJoinProcessor.
[in]	model	The RNTupleModel representing the entries returned by the processor.

Note: Before processing, a model must exist. However, this is handled downstream by the RNTupleProcessor's factory functions (CreateSingle, CreateChain and CreateJoin) and constructors.

Definition at line 161 of file RNTupleProcessor.hxx.

◆ RNTupleProcessor() [2/3]

ROOT::Experimental::RNTupleProcessor::RNTupleProcessor ( const RNTupleProcessor & )

delete

◆ RNTupleProcessor() [3/3]

ROOT::Experimental::RNTupleProcessor::RNTupleProcessor ( RNTupleProcessor && )

delete

◆ ~RNTupleProcessor()

virtual ROOT::Experimental::RNTupleProcessor::~RNTupleProcessor ( )

virtualdefault

Member Function Documentation

◆ AddEntriesToJoinTable()

virtual void ROOT::Experimental::RNTupleProcessor::AddEntriesToJoinTable	(	Internal::RNTupleJoinTable &	joinTable,
		ROOT::NTupleSize_t	entryOffset = 0 )

protectedpure virtual

Add the entry mappings for this processor to the provided join table.

Parameters

[in]	joinTable	the join table to map the entries to.
[in]	entryOffset	In case the entry mapping is added from a chain, the offset of the entry indexes to use with respect to the processor's position in the chain.

Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.

◆ begin()

RIterator ROOT::Experimental::RNTupleProcessor::begin ( )

inline

Definition at line 280 of file RNTupleProcessor.hxx.

◆ Create()

std::unique_ptr< ROOT::Experimental::RNTupleProcessor > ROOT::Experimental::RNTupleProcessor::Create	(	RNTupleOpenSpec	ntuple,
		std::unique_ptr< ROOT::RNTupleModel >	model = nullptr,
		std::string_view	processorName = "" )

static

Create an RNTupleProcessor for a single RNTuple.

Parameters

[in]	ntuple	The name and storage location of the RNTuple to process.
[in]	model	An RNTupleModel specifying which fields can be read by the processor. If no model is provided, one will be created based on the descriptor of the first ntuple specified.
[in]	processorName	The name to give to the processor. If empty, the name of the input RNTuple is used.

Returns: A pointer to the newly created RNTupleProcessor.

Definition at line 38 of file RNTupleProcessor.cxx.

◆ CreateChain() [1/2]

std::unique_ptr< ROOT::Experimental::RNTupleProcessor > ROOT::Experimental::RNTupleProcessor::CreateChain	(	std::vector< RNTupleOpenSpec >	ntuples,
		std::unique_ptr< ROOT::RNTupleModel >	model = nullptr,
		std::string_view	processorName = "" )

static

Create an RNTupleProcessor for a chain (i.e., a vertical combination) of RNTuples.

Parameters

[in]	ntuples	A list specifying the names and locations of the RNTuples to process.
[in]	model	An RNTupleModel specifying which fields can be read by the processor. If no model is provided, one will be created based on the descriptor of the first RNTuple specified.
[in]	processorName	The name to give to the processor. If empty, the name of the first RNTuple is used.

Returns: A pointer to the newly created RNTupleProcessor.

Definition at line 46 of file RNTupleProcessor.cxx.

◆ CreateChain() [2/2]

std::unique_ptr< ROOT::Experimental::RNTupleProcessor > ROOT::Experimental::RNTupleProcessor::CreateChain	(	std::vector< std::unique_ptr< RNTupleProcessor > >	innerProcessors,
		std::unique_ptr< ROOT::RNTupleModel >	model = nullptr,
		std::string_view	processorName = "" )

static

Create an RNTupleProcessor for a chain (i.e., a vertical combination) of other RNTupleProcessors.

Parameters

[in]	innerProcessors	A list with the processors to chain.
[in]	model	An RNTupleModel specifying which fields can be read by the processor. If no model is provided, one will be created based on the model used by the first inner processor.
[in]	processorName	The name to give to the processor. If empty, the name of the first inner processor is used.

Returns: A pointer to the newly created RNTupleProcessor.

Definition at line 71 of file RNTupleProcessor.cxx.

◆ CreateJoin() [1/2]

std::unique_ptr< ROOT::Experimental::RNTupleProcessor > ROOT::Experimental::RNTupleProcessor::CreateJoin	(	RNTupleOpenSpec	primaryNTuple,
		RNTupleOpenSpec	auxNTuple,
		const std::vector< std::string > &	joinFields,
		std::unique_ptr< ROOT::RNTupleModel >	primaryModel = nullptr,
		std::unique_ptr< ROOT::RNTupleModel >	auxModel = nullptr,
		std::string_view	processorName = "" )

static

Create an RNTupleProcessor for a join (i.e., a horizontal combination) of RNTuples.

Parameters

[in]	primaryNTuple	The name and location of the primary RNTuple. Its entries are processed in sequential order.
[in]	auxNTuple	The name and location of the RNTuple to join the primary RNTuple with. The order in which its entries are processed is determined by the primary RNTuple and doesn't necessarily have to be sequential.
[in]	joinFields	The names of the fields on which to join, in case the specified RNTuples are unaligned. The join is made based on the combined join field values, and therefore each field has to be present in each specified RNTuple. If an empty list is provided, it is assumed that the specified ntuple are fully aligned.
[in]	primaryModel	An RNTupleModel specifying which fields from the primary RNTuple can be read by the processor. If no model is provided, one will be created based on the descriptor of the primary RNTuple.
[in]	auxModel	An RNTupleModel specifying which fields from the auxiliary RNTuple can be read by the processor. If no model is provided, one will be created based on the descriptor of the auxiliary RNTuple.
[in]	processorName	The name to give to the processor. If empty, the name of the primary RNTuple is used.

Returns: A pointer to the newly created RNTupleProcessor.

Definition at line 88 of file RNTupleProcessor.cxx.

◆ CreateJoin() [2/2]

std::unique_ptr< ROOT::Experimental::RNTupleProcessor > ROOT::Experimental::RNTupleProcessor::CreateJoin	(	std::unique_ptr< RNTupleProcessor >	primaryProcessor,
		std::unique_ptr< RNTupleProcessor >	auxProcessor,
		const std::vector< std::string > &	joinFields,
		std::unique_ptr< ROOT::RNTupleModel >	primaryModel = nullptr,
		std::unique_ptr< ROOT::RNTupleModel >	auxModel = nullptr,
		std::string_view	processorName = "" )

static

Create an RNTupleProcessor for a join (i.e., a horizontal combination) of RNTuples.

Parameters

[in]	primaryProcessor	The primary processor. Its entries are processed in sequential order.
[in]	auxProcessor	The processor to join the primary processor with. The order in which its entries are processed is determined by the primary processor and doesn't necessarily have to be sequential.
[in]	joinFields	The names of the fields on which to join, in case the specified processors are unaligned. The join is made based on the combined join field values, and therefore each field has to be present in each specified processors. If an empty list is provided, it is assumed that the specified processors are fully aligned.
[in]	primaryModel	An RNTupleModel specifying which fields from the primary processor can be read by the processor. If no model is provided, one will be created based on the descriptor of the primary processor.
[in]	auxModel	An RNTupleModel specifying which fields from the auxiliary processor can be read by the processor. If no model is provided, one will be created based on the descriptor of the auxiliary processor.
[in]	processorName	The name to give to the processor. If empty, the name of the primary processor is used.

Returns: A pointer to the newly created RNTupleProcessor.

Definition at line 118 of file RNTupleProcessor.cxx.

◆ end()

RIterator ROOT::Experimental::RNTupleProcessor::end ( )

inline

Definition at line 281 of file RNTupleProcessor.hxx.

◆ GetCurrentEntryNumber()

ROOT::NTupleSize_t ROOT::Experimental::RNTupleProcessor::GetCurrentEntryNumber ( ) const

inline

Get the entry number that is currently being processed.

Definition at line 179 of file RNTupleProcessor.hxx.

◆ GetCurrentProcessorNumber()

std::size_t ROOT::Experimental::RNTupleProcessor::GetCurrentProcessorNumber ( ) const

inline

Get the number of the inner processor currently being read.

This method is only relevant for the RNTupleChainProcessor. For the other processors, 0 is always returned.

Definition at line 185 of file RNTupleProcessor.hxx.

◆ GetEntry()

const ROOT::REntry & ROOT::Experimental::RNTupleProcessor::GetEntry ( ) const

inline

Get a reference to the entry used by the processor.

Returns: A reference to the entry used by the processor.

Definition at line 203 of file RNTupleProcessor.hxx.

◆ GetModel()

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

inline

Get the model used by the processor.

Definition at line 197 of file RNTupleProcessor.hxx.

◆ GetNEntries()

virtual ROOT::NTupleSize_t ROOT::Experimental::RNTupleProcessor::GetNEntries ( )

protectedpure virtual

Get the total number of entries in this processor.

Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.

◆ GetNEntriesProcessed()

ROOT::NTupleSize_t ROOT::Experimental::RNTupleProcessor::GetNEntriesProcessed ( ) const

inline

Get the total number of entries processed so far.

Definition at line 175 of file RNTupleProcessor.hxx.

◆ GetProcessorName()

const std::string & ROOT::Experimental::RNTupleProcessor::GetProcessorName ( ) const

inline

Get the name of the processor.

Unless this name was explicitly specified during creation of the processor, this is the name of the underlying RNTuple for RNTupleSingleProcessor, the name of the first processor for RNTupleChainProcessor, or the name of the primary processor for RNTupleJoinProcessor.

Definition at line 193 of file RNTupleProcessor.hxx.

◆ LoadEntry()

virtual ROOT::NTupleSize_t ROOT::Experimental::RNTupleProcessor::LoadEntry ( ROOT::NTupleSize_t entryNumber )

protectedpure virtual

Load the entry identified by the provided entry number.

Parameters

[in] entryNumber Entry number to load

Returns: entryNumber if the entry was successfully loaded, kInvalidNTupleIndex otherwise.

Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.

◆ operator=() [1/2]

RNTupleProcessor & ROOT::Experimental::RNTupleProcessor::operator= ( const RNTupleProcessor & )

delete

◆ operator=() [2/2]

RNTupleProcessor & ROOT::Experimental::RNTupleProcessor::operator= ( RNTupleProcessor && )

delete

◆ PrintStructure()

void ROOT::Experimental::RNTupleProcessor::PrintStructure ( std::ostream & output = std::cout )

inline

Print a graphical representation of the processor composition.

Parameters

[in,out] output Stream to print to (default is stdout).

Example:

The structure of a processor representing a join between a single primary RNTuple and a chain of two auxiliary RNTuples will be printed as follows:

+-----------------------------+ +-----------------------------+
| ntuple                      | | ntuple_aux                  |
| ntuple.root                 | | ntuple_aux1.root            |
+-----------------------------+ +-----------------------------+
                                +-----------------------------+
                                | ntuple_aux                  |
                                | ntuple_aux2.root            |
                                +-----------------------------+

Definition at line 223 of file RNTupleProcessor.hxx.

◆ PrintStructureImpl()

virtual void ROOT::Experimental::RNTupleProcessor::PrintStructureImpl ( std::ostream & output ) const

protectedpure virtual

Processor-specific implementation for printing its structure, called by PrintStructure().

Parameters

[in,out] output Output stream to print to.

Implemented in ROOT::Experimental::RNTupleSingleProcessor, ROOT::Experimental::RNTupleChainProcessor, and ROOT::Experimental::RNTupleJoinProcessor.

◆ SetEntryPointers()

virtual void ROOT::Experimental::RNTupleProcessor::SetEntryPointers	(	const ROOT::REntry &	entry,
		std::string_view	fieldNamePrefix = "" )

protectedpure virtual

Point the entry's field values of the processor to the pointers from the provided entry.

Parameters

[in] entry The entry whose field values to use.

Implemented in ROOT::Experimental::RNTupleChainProcessor, ROOT::Experimental::RNTupleJoinProcessor, and ROOT::Experimental::RNTupleSingleProcessor.

Friends And Related Symbol Documentation

◆ RNTupleChainProcessor

friend class RNTupleChainProcessor

friend

Definition at line 103 of file RNTupleProcessor.hxx.

◆ RNTupleJoinProcessor

friend class RNTupleJoinProcessor

friend

Definition at line 104 of file RNTupleProcessor.hxx.

◆ RNTupleSingleProcessor

friend class RNTupleSingleProcessor

friend

Definition at line 102 of file RNTupleProcessor.hxx.

◆ ROOT::Experimental::Internal::RNTupleProcessorEntryLoader

friend struct ROOT::Experimental::Internal::RNTupleProcessorEntryLoader

friend

Definition at line 101 of file RNTupleProcessor.hxx.

Member Data Documentation

◆ fCurrentEntryNumber

ROOT::NTupleSize_t ROOT::Experimental::RNTupleProcessor::fCurrentEntryNumber = 0

protected

Definition at line 116 of file RNTupleProcessor.hxx.

◆ fCurrentProcessorNumber

std::size_t ROOT::Experimental::RNTupleProcessor::fCurrentProcessorNumber = 0

protected

Definition at line 117 of file RNTupleProcessor.hxx.

◆ fEntry

std::unique_ptr<ROOT::REntry> ROOT::Experimental::RNTupleProcessor::fEntry

protected

Definition at line 108 of file RNTupleProcessor.hxx.

◆ fModel

std::unique_ptr<ROOT::RNTupleModel> ROOT::Experimental::RNTupleProcessor::fModel

protected

Definition at line 109 of file RNTupleProcessor.hxx.

◆ fNEntries

ROOT::NTupleSize_t ROOT::Experimental::RNTupleProcessor::fNEntries = kInvalidNTupleIndex

protected

Total number of entries.

Only to be used internally by the processor, not meant to be exposed in the public interface.

Definition at line 113 of file RNTupleProcessor.hxx.

◆ fNEntriesProcessed

ROOT::NTupleSize_t ROOT::Experimental::RNTupleProcessor::fNEntriesProcessed = 0

protected

Definition at line 115 of file RNTupleProcessor.hxx.

◆ fProcessorName

std::string ROOT::Experimental::RNTupleProcessor::fProcessorName

protected

Definition at line 107 of file RNTupleProcessor.hxx.

Libraries for ROOT::Experimental::RNTupleProcessor:

[legend]

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

tree/ntuple/inc/ROOT/RNTupleProcessor.hxx
tree/ntuple/src/RNTupleProcessor.cxx

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Constructor & Destructor Documentation

◆ RNTupleProcessor() [1/3]

◆ RNTupleProcessor() [2/3]

◆ RNTupleProcessor() [3/3]

◆ ~RNTupleProcessor()

Member Function Documentation

◆ AddEntriesToJoinTable()

◆ begin()

◆ Create()

◆ CreateChain() [1/2]

◆ CreateChain() [2/2]

◆ CreateJoin() [1/2]

◆ CreateJoin() [2/2]

◆ end()

◆ GetCurrentEntryNumber()

◆ GetCurrentProcessorNumber()

◆ GetEntry()

◆ GetModel()

◆ GetNEntries()

◆ GetNEntriesProcessed()

◆ GetProcessorName()

◆ LoadEntry()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ PrintStructure()

Example:

◆ PrintStructureImpl()

◆ SetEntryPointers()

Friends And Related Symbol Documentation

◆ RNTupleChainProcessor

◆ RNTupleJoinProcessor

◆ RNTupleSingleProcessor

◆ ROOT::Experimental::Internal::RNTupleProcessorEntryLoader

Member Data Documentation

◆ fCurrentEntryNumber

◆ fCurrentProcessorNumber

◆ fEntry

◆ fModel

◆ fNEntries

◆ fNEntriesProcessed

◆ fProcessorName