Converts a TTree into an RNTuple.

Example usage (see the ntpl008_import.C tutorial for a full example):

#include <ROOT/RNTupleImporter.hxx>
using ROOT::Experimental::RNTupleImporter;
 
auto importer = RNTupleImporter::Create("data.root", "TreeName", "output.root");
// As required: importer->SetNTupleName(), importer->SetWriteOptions(), ...
importer->Import();

The output file is created if it does not exist, otherwise the ntuple is added to the existing file. Directories in the output file are created as necessary, allowing ntuples to be stored in a nested structure (e.g. DirName/TreeName). Note that input file and output file can be identical if the ntuple is stored under a different name than the tree (use SetNTupleName()).

By default, the RNTuple is compressed with zstd, independent of the input compression. The compression settings (and other output parameters) can be changed by SetWriteOptions(). For example, to compress the imported RNTuple using lz4 (with compression level 4) instead:

auto writeOptions = importer->GetWriteOptions();
writeOptions.SetCompression(404);
importer->SetWriteOptions(writeOptions);

Most RNTuple fields have a type identical to the corresponding TTree input branch. Exceptions are

C string branches are translated to std::string fields
C style arrays are translated to std::array<...> fields
Leaf lists are translated to untyped records
Leaf count arrays are translated to anonymous collections with generic names (_collection0, _collection1, etc.). In order to keep field names and branch names aligned, RNTuple projects the members of these collections and its collection counter to the input branch names. For instance, the following input leafs:
Int_t njets

float jet_pt[njets]

float jet_eta[njets]

int

will be converted to the following RNTuple schema:
_collection0 (untyped collection)

|- float jet_pt

|- float jet_eta

std::size_t (RNTupleCardinality) njets (projected from _collection0 without subfields)

ROOT::RVec<float> jet_pt (projected from _collection0.jet_pt)

ROOT::RVec<float> jet_eta (projected from _collection0.jet_eta)

TRangeDynCast
ROOT::Detail::TRangeCast< T, true > TRangeDynCast
TRangeDynCast is an adapter class that allows the typed iteration through a TCollection.
Definition TCollection.h:359

ROOT::VecOps::RVec
A "std::vector"-like collection of values implementing handy operation to analyse them.
Definition RVec.hxx:1509

ROOT::RNTupleCardinality
Helper types to present an offset column as array of collection sizes.
Definition RNTupleTypes.hxx:29

These projections are meta-data only operations and don't involve duplicating the data.

Current limitations of the importer:

No support for trees containing TClonesArray collections
Due to RNTuple currently storing data fully split, "don't split" markers are ignored
Some types are not available in RNTuple. Please refer to the RNTuple specification for an overview of all types currently supported.

Definition at line 103 of file RNTupleImporter.hxx.

Classes
struct	RCStringTransformation
	Transform a NULL terminated C string branch into an `std::string` field. More...

struct	RImportBranch

struct	RImportField

struct	RImportGuard
	When the schema is set up and the import started, it needs to be reset before the next Import() call can start. More...

struct	RImportLeafCountCollection
	Leaf count arrays require special treatment. More...

struct	RImportReport
	Summary printed after the RNTuple writer commits (footer, streamer info, last cluster). More...

struct	RImportTransformation
	Base class to perform data transformations from TTree branches to RNTuple fields if necessary. More...

class	RProgressCallback
	Used to report every ~100 MB of compressed page payload, and at the end about the status of the import. More...

Public Types
using	FieldModifier_t = std::function<void(ROOT::RFieldBase &)>
	Used to make adjustments to the fields of the output model.

Public Member Functions
	RNTupleImporter (const RNTupleImporter &other)=delete

	RNTupleImporter (RNTupleImporter &&other)=delete

	~RNTupleImporter ()=default

RImportReport	GetLastImportReport () const
	Metrics from the most recent Import() call (always filled, even when quiet).

ROOT::RNTupleWriteOptions	GetWriteOptions () const

void	Import ()
	Import works in two steps:

RNTupleImporter &	operator= (const RNTupleImporter &other)=delete

RNTupleImporter &	operator= (RNTupleImporter &&other)=delete

void	SetConvertDotsInBranchNames (bool value)
	Whereas branch names may contain dots, RNTuple field names may not.

void	SetFieldModifier (const FieldModifier_t &modifier)
	Add custom method to adjust column representations.

void	SetIsQuiet (bool value)
	Whether or not information and progress is printed to stdout.

void	SetMaxEntries (std::uint64_t maxEntries)

void	SetNTupleName (const std::string &name)

void	SetWriteOptions (const ROOT::RNTupleWriteOptions &options)

Static Public Member Functions
static std::unique_ptr< RNTupleImporter >	Create (std::string_view sourceFileName, std::string_view treeName, std::string_view destFileName)
	Opens the input file for reading and the output file for writing (update).

static std::unique_ptr< RNTupleImporter >	Create (TTree *sourceTree, std::string_view destFileName)
	Directly uses the provided tree and opens the output file for writing (update).

Private Member Functions
	RNTupleImporter ()=default

ROOT::RResult< void >	InitDestination (std::string_view destFileName)

ROOT::RResult< void >	PrepareSchema ()
	Sets up the connection from TTree branches to RNTuple fields, including initialization of the memory buffers used for reading and writing.

void	ReportSchema ()

void	ResetSchema ()

Private Attributes
bool	fConvertDotsInBranchNames = false
	Whether or not dot characters in branch names should be converted to underscores.

std::unique_ptr< TFile >	fDestFile

std::string	fDestFileName

std::unique_ptr< ROOT::REntry >	fEntry

FieldModifier_t	fFieldModifier

std::vector< RImportBranch >	fImportBranches

std::vector< RImportField >	fImportFields

std::vector< std::unique_ptr< RImportTransformation > >	fImportTransformations
	The list of transformations to be performed for every entry.

bool	fIsQuiet = false
	No standard output, conversely if set to false, schema information and progress is printed.

RImportReport	fLastImportReport {}

std::map< std::string, RImportLeafCountCollection >	fLeafCountCollections
	Maps the count leaf to the information about the corresponding untyped collection.

std::int64_t	fMaxEntries = -1
	The maximum number of entries to import. When this value is -1 (default), import all entries.

std::unique_ptr< ROOT::RNTupleModel >	fModel

std::string	fNTupleName

std::unique_ptr< RProgressCallback >	fProgressCallback

std::unique_ptr< TFile >	fSourceFile

TTree *	fSourceTree

ROOT::RNTupleWriteOptions	fWriteOptions

#include <ROOT/RNTupleImporter.hxx>

Member Typedef Documentation

◆ FieldModifier_t

using ROOT::Experimental::RNTupleImporter::FieldModifier_t = std::function<void(ROOT::RFieldBase &)>

Used to make adjustments to the fields of the output model.

Definition at line 106 of file RNTupleImporter.hxx.

Constructor & Destructor Documentation

◆ RNTupleImporter() [1/3]

ROOT::Experimental::RNTupleImporter::RNTupleImporter ( )

privatedefault

◆ RNTupleImporter() [2/3]

ROOT::Experimental::RNTupleImporter::RNTupleImporter ( const RNTupleImporter & other )

delete

◆ RNTupleImporter() [3/3]

ROOT::Experimental::RNTupleImporter::RNTupleImporter ( RNTupleImporter && other )

delete

◆ ~RNTupleImporter()

ROOT::Experimental::RNTupleImporter::~RNTupleImporter ( )

default

Member Function Documentation

◆ Create() [1/2]

std::unique_ptr< ROOT::Experimental::RNTupleImporter > ROOT::Experimental::RNTupleImporter::Create	(	std::string_view	sourceFileName,
		std::string_view	treeName,
		std::string_view	destFileName )

static

Opens the input file for reading and the output file for writing (update).

Definition at line 115 of file RNTupleImporter.cxx.

◆ Create() [2/2]

std::unique_ptr< ROOT::Experimental::RNTupleImporter > ROOT::Experimental::RNTupleImporter::Create	(	TTree *	sourceTree,
		std::string_view	destFileName )

static

Directly uses the provided tree and opens the output file for writing (update).

Definition at line 141 of file RNTupleImporter.cxx.

◆ GetLastImportReport()

RImportReport ROOT::Experimental::RNTupleImporter::GetLastImportReport ( ) const

inline

Metrics from the most recent Import() call (always filled, even when quiet).

Definition at line 286 of file RNTupleImporter.hxx.

◆ GetWriteOptions()

ROOT::RNTupleWriteOptions ROOT::Experimental::RNTupleImporter::GetWriteOptions ( ) const

inline

Definition at line 273 of file RNTupleImporter.hxx.

◆ Import()

void ROOT::Experimental::RNTupleImporter::Import ( )

Import works in two steps:

PrepareSchema() calls SetBranchAddress() on all the TTree branches and creates the corresponding RNTuple fields and the model
An event loop reads every entry from the TTree, applies transformations where necessary, and writes the output entry to the RNTuple.

Definition at line 421 of file RNTupleImporter.cxx.

◆ InitDestination()

ROOT::RResult< void > ROOT::Experimental::RNTupleImporter::InitDestination ( std::string_view destFileName )

private

Definition at line 165 of file RNTupleImporter.cxx.

◆ operator=() [1/2]

RNTupleImporter & ROOT::Experimental::RNTupleImporter::operator= ( const RNTupleImporter & other )

delete

◆ operator=() [2/2]

RNTupleImporter & ROOT::Experimental::RNTupleImporter::operator= ( RNTupleImporter && other )

delete

◆ PrepareSchema()

ROOT::RResult< void > ROOT::Experimental::RNTupleImporter::PrepareSchema ( )

private

Sets up the connection from TTree branches to RNTuple fields, including initialization of the memory buffers used for reading and writing.

Definition at line 196 of file RNTupleImporter.cxx.

◆ ReportSchema()

void ROOT::Experimental::RNTupleImporter::ReportSchema ( )

private

Definition at line 176 of file RNTupleImporter.cxx.

◆ ResetSchema()

void ROOT::Experimental::RNTupleImporter::ResetSchema ( )

private

Definition at line 186 of file RNTupleImporter.cxx.

◆ SetConvertDotsInBranchNames()

void ROOT::Experimental::RNTupleImporter::SetConvertDotsInBranchNames ( bool value )

inline

Whereas branch names may contain dots, RNTuple field names may not.

By setting this option, dot characters are automatically converted into underscores to prevent the importer from throwing an exception.

Definition at line 280 of file RNTupleImporter.hxx.

◆ SetFieldModifier()

void ROOT::Experimental::RNTupleImporter::SetFieldModifier ( const FieldModifier_t & modifier )

inline

Add custom method to adjust column representations.

Will be called for every field of the frozen model before it is attached to the page sink

Definition at line 290 of file RNTupleImporter.hxx.

◆ SetIsQuiet()

void ROOT::Experimental::RNTupleImporter::SetIsQuiet ( bool value )

inline

Whether or not information and progress is printed to stdout.

Definition at line 283 of file RNTupleImporter.hxx.

◆ SetMaxEntries()

void ROOT::Experimental::RNTupleImporter::SetMaxEntries ( std::uint64_t maxEntries )

inline

Definition at line 276 of file RNTupleImporter.hxx.

◆ SetNTupleName()

void ROOT::Experimental::RNTupleImporter::SetNTupleName ( const std::string & name )

inline

Definition at line 275 of file RNTupleImporter.hxx.

◆ SetWriteOptions()

void ROOT::Experimental::RNTupleImporter::SetWriteOptions ( const ROOT::RNTupleWriteOptions & options )

inline

Definition at line 274 of file RNTupleImporter.hxx.

Member Data Documentation

◆ fConvertDotsInBranchNames

bool ROOT::Experimental::RNTupleImporter::fConvertDotsInBranchNames = false

private

Whether or not dot characters in branch names should be converted to underscores.

If this option is not set and a branch with a '.' is encountered, the importer will throw an exception.

Definition at line 231 of file RNTupleImporter.hxx.

◆ fDestFile

std::unique_ptr<TFile> ROOT::Experimental::RNTupleImporter::fDestFile

private

Definition at line 226 of file RNTupleImporter.hxx.

◆ fDestFileName

std::string ROOT::Experimental::RNTupleImporter::fDestFileName

private

Definition at line 224 of file RNTupleImporter.hxx.

◆ fEntry

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

private

Definition at line 243 of file RNTupleImporter.hxx.

◆ fFieldModifier

FieldModifier_t ROOT::Experimental::RNTupleImporter::fFieldModifier

private

Definition at line 240 of file RNTupleImporter.hxx.

◆ fImportBranches

std::vector<RImportBranch> ROOT::Experimental::RNTupleImporter::fImportBranches

private

Definition at line 244 of file RNTupleImporter.hxx.

◆ fImportFields

std::vector<RImportField> ROOT::Experimental::RNTupleImporter::fImportFields

private

Definition at line 245 of file RNTupleImporter.hxx.

◆ fImportTransformations

std::vector<std::unique_ptr<RImportTransformation> > ROOT::Experimental::RNTupleImporter::fImportTransformations

private

The list of transformations to be performed for every entry.

Definition at line 249 of file RNTupleImporter.hxx.

◆ fIsQuiet

bool ROOT::Experimental::RNTupleImporter::fIsQuiet = false

private

No standard output, conversely if set to false, schema information and progress is printed.

Definition at line 237 of file RNTupleImporter.hxx.

◆ fLastImportReport

RImportReport ROOT::Experimental::RNTupleImporter::fLastImportReport {}

private

Definition at line 238 of file RNTupleImporter.hxx.

◆ fLeafCountCollections

std::map<std::string, RImportLeafCountCollection> ROOT::Experimental::RNTupleImporter::fLeafCountCollections

private

Maps the count leaf to the information about the corresponding untyped collection.

Definition at line 247 of file RNTupleImporter.hxx.

◆ fMaxEntries

std::int64_t ROOT::Experimental::RNTupleImporter::fMaxEntries = -1

private

The maximum number of entries to import. When this value is -1 (default), import all entries.

Definition at line 234 of file RNTupleImporter.hxx.

◆ fModel

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

private

Definition at line 242 of file RNTupleImporter.hxx.

◆ fNTupleName

std::string ROOT::Experimental::RNTupleImporter::fNTupleName

private

Definition at line 225 of file RNTupleImporter.hxx.

◆ fProgressCallback

std::unique_ptr<RProgressCallback> ROOT::Experimental::RNTupleImporter::fProgressCallback

private

Definition at line 239 of file RNTupleImporter.hxx.

◆ fSourceFile

std::unique_ptr<TFile> ROOT::Experimental::RNTupleImporter::fSourceFile

private

Definition at line 221 of file RNTupleImporter.hxx.

◆ fSourceTree

TTree* ROOT::Experimental::RNTupleImporter::fSourceTree

private

Definition at line 222 of file RNTupleImporter.hxx.

◆ fWriteOptions

ROOT::RNTupleWriteOptions ROOT::Experimental::RNTupleImporter::fWriteOptions

private

Definition at line 227 of file RNTupleImporter.hxx.

Libraries for ROOT::Experimental::RNTupleImporter:

[legend]

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

tree/ntupleutil/inc/ROOT/RNTupleImporter.hxx
tree/ntupleutil/src/RNTupleImporter.cxx

Classes

Public Types

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Member Typedef Documentation

◆ FieldModifier_t

Constructor & Destructor Documentation

◆ RNTupleImporter() [1/3]

◆ RNTupleImporter() [2/3]

◆ RNTupleImporter() [3/3]

◆ ~RNTupleImporter()

Member Function Documentation

◆ Create() [1/2]

◆ Create() [2/2]

◆ GetLastImportReport()

◆ GetWriteOptions()

◆ Import()

◆ InitDestination()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ PrepareSchema()

◆ ReportSchema()

◆ ResetSchema()

◆ SetConvertDotsInBranchNames()

◆ SetFieldModifier()

◆ SetIsQuiet()

◆ SetMaxEntries()

◆ SetNTupleName()

◆ SetWriteOptions()

Member Data Documentation

◆ fConvertDotsInBranchNames

◆ fDestFile

◆ fDestFileName

◆ fEntry

◆ fFieldModifier

◆ fImportBranches

◆ fImportFields

◆ fImportTransformations

◆ fIsQuiet

◆ fLastImportReport

◆ fLeafCountCollections

◆ fMaxEntries

◆ fModel

◆ fNTupleName

◆ fProgressCallback

◆ fSourceFile

◆ fSourceTree

◆ fWriteOptions