Logo ROOT  

Reference Guide
 
Loading...
Searching...
No Matches
List of all members | Classes | Public Types | Public Member Functions | Static Public Member Functions | Private Member Functions | Private Attributes | List of all members
ROOT::Experimental::RNTupleImporter Class Reference
NTuple-related classes

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();
ROOT::Experimental::RNTupleImporter
Converts a TTree into an RNTuple.
Definition RNTupleImporter.hxx:103
ROOT::Experimental::RNTupleImporter::Create
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).
Definition RNTupleImporter.cxx:80

The output file is created if it does not exist, otherwise the ntuple is added to the existing file. 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]
    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)
    ROOT::VecOps::RVec
    A "std::vector"-like collection of values implementing handy operation to analyse them.
    Definition RVec.hxx:1529
    ROOT::RNTupleCardinality
    Helper types to present an offset column as array of collection sizes.
    Definition RNTupleUtil.hxx:34
    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  RImportTransformation
 Base class to perform data transformations from TTree branches to RNTuple fields if necessary. More...
 
class  RProgressCallback
 Used to report every ~100 MB (compressed), and at the end about the status of the import. More...
 

Public Types

using FieldModifier_t = std::function< void(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
 
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 (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 (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::Experimental::RResult< void > InitDestination (std::string_view destFileName)
 
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< 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.
 
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< RNTupleModel > fModel
 
std::string fNTupleName
 
std::unique_ptr< RProgressCallback > fProgressCallback
 
std::unique_ptr< TFile > fSourceFile
 
TTree * fSourceTree
 
RNTupleWriteOptions fWriteOptions
 

#include <ROOT/RNTupleImporter.hxx>

Member Typedef Documentation

◆ FieldModifier_t

using ROOT::Experimental::RNTupleImporter::FieldModifier_t = std::function<void(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 80 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 106 of file RNTupleImporter.cxx.

◆ GetWriteOptions()

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

Definition at line 255 of file RNTupleImporter.hxx.

◆ Import()

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

Import works in two steps:

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

Definition at line 371 of file RNTupleImporter.cxx.

◆ InitDestination()

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

Definition at line 130 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::Experimental::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 161 of file RNTupleImporter.cxx.

◆ ReportSchema()

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

Definition at line 141 of file RNTupleImporter.cxx.

◆ ResetSchema()

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

Definition at line 151 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 262 of file RNTupleImporter.hxx.

◆ SetFieldModifier()

void ROOT::Experimental::RNTupleImporter::SetFieldModifier ( 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 269 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 265 of file RNTupleImporter.hxx.

◆ SetMaxEntries()

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

Definition at line 258 of file RNTupleImporter.hxx.

◆ SetNTupleName()

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

Definition at line 257 of file RNTupleImporter.hxx.

◆ SetWriteOptions()

void ROOT::Experimental::RNTupleImporter::SetWriteOptions ( RNTupleWriteOptions  options)
inline

Definition at line 256 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 214 of file RNTupleImporter.hxx.

◆ fDestFile

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

Definition at line 209 of file RNTupleImporter.hxx.

◆ fDestFileName

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

Definition at line 207 of file RNTupleImporter.hxx.

◆ fEntry

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

Definition at line 225 of file RNTupleImporter.hxx.

◆ fFieldModifier

FieldModifier_t ROOT::Experimental::RNTupleImporter::fFieldModifier
private

Definition at line 222 of file RNTupleImporter.hxx.

◆ fImportBranches

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

Definition at line 226 of file RNTupleImporter.hxx.

◆ fImportFields

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

Definition at line 227 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 231 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 220 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 229 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 217 of file RNTupleImporter.hxx.

◆ fModel

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

Definition at line 224 of file RNTupleImporter.hxx.

◆ fNTupleName

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

Definition at line 208 of file RNTupleImporter.hxx.

◆ fProgressCallback

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

Definition at line 221 of file RNTupleImporter.hxx.

◆ fSourceFile

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

Definition at line 204 of file RNTupleImporter.hxx.

◆ fSourceTree

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

Definition at line 205 of file RNTupleImporter.hxx.

◆ fWriteOptions

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

Definition at line 210 of file RNTupleImporter.hxx.

Libraries for ROOT::Experimental::RNTupleImporter:
[legend]
The documentation for this class was generated from the following files: