Flow

Description

User-friendly handling of input and output n-tuples.

A flow consists of input and output path to n-tuples and of a slice:

DT::Flow flow(steering, inputs);
auto tIn = flow.GetInputTree(slice);
auto tOut = flow.GetOutputTree(output);
auto fOut = flow.GetOutputFile();

The last two lines can be condensed as follows:

auto [fOut, tOut] = flow.GetOutput(output);

The steering is use for the verbosity and the friendship. Setting up branches reduces to the following:

auto recEvent = flow.GetBranchReadOnly<RecEvent>("recEvent");
auto recJets = flow.GetBranchReadWrite<vector<RecJet>>("recJets");
auto recDijet = flow.GetBranchWriteOnly<RecDijet>("recDijet");

Furthermore, as it is frequent to produce histograms along the n-tuple (e.g. control plots), a flow allows to sum on the fly a histogram:

auto hIn = flow.GetInputHist<TH2>("h");
auto hIns = flow.GetInputHists("h1", "h2"); // default is TH1

Note

A one-liner is also possible:

auto hIn = DT::Flow(steering, inputs).GetInputHist("h");

#include <Flow.h>

Collaboration diagram for Flow:

Public Member Functions
std::string	DumpActiveBranches () const
	Flow (int=none, const std::vector< std::filesystem::path > &={})
	~Flow ()
ChainSlice *	GetInputTree (const Slice, const std::string &="events")
ChainSlice *	GetInputTree (const std::string &="events")
template<typename THX = TH1, size_t N>
std::array< std::unique_ptr< THX >, N >	GetInputHists (const std::array< std::string, N > &names={})
template<typename THX = TH1, typename... Args>
auto	GetInputHists (const Args... args)
template<typename THX = TH1>
std::unique_ptr< THX >	GetInputHist (const std::string &name)
TTree *	GetOutputTree (std::shared_ptr< TFile >={}, const std::source_location=std::source_location::current())
TTree *	GetOutputTree (const std::filesystem::path &, const std::source_location=std::source_location::current())
void	SetOutputFile (std::shared_ptr< TFile > fOut)
TFile *	GetOutputFile ()
std::pair< TFile *, TTree * >	GetOutput (const std::filesystem::path &, const std::source_location=std::source_location::current())
template<typename T >
T *	GetBranchReadOnly (const std::string &name, BranchMode mode=mandatory)
template<typename T >
T *	GetBranchWriteOnly (const std::string &name)
template<typename T >
T *	GetBranchReadWrite (const std::string &name, BranchMode mode=mandatory)
template<Plugin P, std::ranges::range R>
std::vector< P * >	GetPlugins (R &&plugin_paths)
std::string	DumpActiveBranches () const
	Flow (int=none, const std::vector< std::filesystem::path > &={})
	~Flow ()
ChainSlice *	GetInputTree (const Slice, const std::string &="events")
ChainSlice *	GetInputTree (const std::string &="events")
template<typename THX = TH1, size_t N>
std::array< std::unique_ptr< THX >, N >	GetInputHists (const std::array< std::string, N > &names={})
template<typename THX = TH1, typename... Args>
auto	GetInputHists (const Args... args)
template<typename THX = TH1>
std::unique_ptr< THX >	GetInputHist (const std::string &name)
TTree *	GetOutputTree (std::shared_ptr< TFile >={}, const std::source_location=std::source_location::current())
TTree *	GetOutputTree (const std::filesystem::path &, const std::source_location=std::source_location::current())
void	SetOutputFile (std::shared_ptr< TFile > fOut)
TFile *	GetOutputFile ()
std::pair< TFile *, TTree * >	GetOutput (const std::filesystem::path &, const std::source_location=std::source_location::current())
template<typename T >
T *	GetBranchReadOnly (const std::string &name, BranchMode mode=mandatory)
template<typename T >
T *	GetBranchWriteOnly (const std::string &name)
template<typename T >
T *	GetBranchReadWrite (const std::string &name, BranchMode mode=mandatory)
template<Plugin P, std::ranges::range R>
std::vector< P * >	GetPlugins (R &&plugin_paths)

Private Member Functions
template<typename T >
requires std::is_compound< T >::value std::shared_ptr< T * >	branch_cast (std::any &a)
template<typename T >
requires std::is_fundamental< T >::value std::shared_ptr< T >	branch_cast (std::any &a)
template<typename T >
requires std::is_compound< T >::value T *	GetBranchAddress (std::shared_ptr< T * > ptr)
template<typename T >
requires std::is_fundamental< T >::value T *	GetBranchAddress (std::shared_ptr< T > ptr)
template<typename T >
T *	GetBranchAddress (const std::string &name)
template<typename T >
T *	NoBranch (const std::string &name, BranchMode mode)
template<typename T >
requires std::is_compound< T >::value std::shared_ptr< T * >	branch_cast (std::any &a)
template<typename T >
requires std::is_fundamental< T >::value std::shared_ptr< T >	branch_cast (std::any &a)
template<typename T >
requires std::is_compound< T >::value T *	GetBranchAddress (std::shared_ptr< T * > ptr)
template<typename T >
requires std::is_fundamental< T >::value T *	GetBranchAddress (std::shared_ptr< T > ptr)
template<typename T >
T *	GetBranchAddress (const std::string &name)
template<typename T >
T *	NoBranch (const std::string &name, BranchMode mode)

Private Attributes
int	steering
std::vector< PluginLoader >	plugin_loaders
std::vector< std::filesystem::path >	inputs
std::unique_ptr< ChainSlice >	tIn
std::shared_ptr< TFile >	fOut
std::unique_ptr< TTree >	tOut
std::map< std::string, std::any >	branches

Constructor & Destructor Documentation

Flow() [1/2]

Flow	(	int	steering = none,
		const std::vector< std::filesystem::path > &	short_inputs = {}
	)

Constructor.

Determines the command in which Flow is called.

Parameters

steering	steering bitfield
short_inputs	ROOT files or directories

    : steering(steering), inputs(GetROOTfiles(short_inputs))
{
    if (short_inputs.size() > 0 && inputs.size() == 0)
        BOOST_THROW_EXCEPTION(fs::filesystem_error("No input was found!",
                                make_error_code(errc::no_such_file_or_directory)));
}

~Flow() [1/2]

~Flow

(

)

Destructor.

Saves the output tree (if declared) to the output file (if open).

{
    if (fOut) {
        if (tOut) {
            if (steering & verbose)
                cout << "Flow: saving output tree" << endl;
 
            fOut->cd();
            tOut->Write();
        }
        else if (steering & verbose)
            cout << "Flow: no output tree to save" << endl;
    }
    else if (tOut && (steering & verbose))
        cout << "Flow: no file to save the output tree" << endl;
 
    if (tIn) tIn->ResetBranchAddresses();
    if (tOut) tOut->ResetBranchAddresses();
}

Flow() [2/2]

Flow	(	int	= none,
		const std::vector< std::filesystem::path > &	= {}
	)

Constructor.

Determines the command in which Flow is called.

~Flow() [2/2]

~Flow

(

)

Destructor.

Saves the output tree (if declared) to the output file (if open).

Member Function Documentation

branch_cast() [1/4]

requires std::is_compound<T>::value std::shared_ptr<T*> branch_cast ( std::any &  a )

inlineprivate

Casts from std::any to shared_ptr

        {
        return std::any_cast<std::shared_ptr<T*>>(a);
    }
    catch (const std::bad_any_cast& e) {
        BOOST_THROW_EXCEPTION(e);
    }

branch_cast() [2/4]

requires std::is_compound<T>::value std::shared_ptr<T*> branch_cast ( std::any &  a )

inlineprivate

Casts from std::any to shared_ptr

        {
        return std::any_cast<std::shared_ptr<T*>>(a);
    }
    catch (const std::bad_any_cast& e) {
        BOOST_THROW_EXCEPTION(e);
    }

branch_cast() [3/4]

requires std::is_fundamental<T>::value std::shared_ptr<T> branch_cast ( std::any &  a )

inlineprivate

Casts from std::any to shared_ptr

        {
        return std::any_cast<std::shared_ptr<T>>(a);
    }
    catch (const std::bad_any_cast& e) {
        BOOST_THROW_EXCEPTION(e);
    }

branch_cast() [4/4]

requires std::is_fundamental<T>::value std::shared_ptr<T> branch_cast ( std::any &  a )

inlineprivate

Casts from std::any to shared_ptr

        {
        return std::any_cast<std::shared_ptr<T>>(a);
    }
    catch (const std::bad_any_cast& e) {
        BOOST_THROW_EXCEPTION(e);
    }

DumpActiveBranches() [1/2]

std::string DumpActiveBranches ( ) const

inline

Returns a list of all active branches, formatted as a string.

    {
        auto keys = branches | std::views::keys;
        return std::accumulate(keys.begin(), keys.end(), std::string(),
                [](const std::string& str, const std::string& branch_name) {
                    return str + ' ' + branch_name;
                });
    }

DumpActiveBranches() [2/2]

std::string DumpActiveBranches ( ) const

inline

Returns a list of all active branches, formatted as a string.

    {
        auto keys = branches | std::views::keys;
        return std::accumulate(keys.begin(), keys.end(), std::string(),
                [](const std::string& str, const std::string& branch_name) {
                    return str + ' ' + branch_name;
                });
    }

GetBranchAddress() [1/6]

T* GetBranchAddress ( const std::string &  name )

inlineprivate

Get branch address from name (universal)

    {
        using namespace std;
        any& a = branches[name];
        shared_ptr ptr = branch_cast<T>(a);
        return GetBranchAddress<T>(ptr);
    }

GetBranchAddress() [2/6]

T* GetBranchAddress ( const std::string &  name )

inlineprivate

Get branch address from name (universal)

    {
        using namespace std;
        any& a = branches[name];
        shared_ptr ptr = branch_cast<T>(a);
        return GetBranchAddress<T>(ptr);
    }

GetBranchAddress() [3/6]

requires std::is_compound<T>::value T* GetBranchAddress ( std::shared_ptr< T * >  ptr )

inlineprivate

Get branch address for compound types.

    {
        return *ptr;
    }

GetBranchAddress() [4/6]

requires std::is_compound<T>::value T* GetBranchAddress ( std::shared_ptr< T * >  ptr )

inlineprivate

Get branch address for compound types.

    {
        return *ptr;
    }

GetBranchAddress() [5/6]

requires std::is_fundamental<T>::value T* GetBranchAddress ( std::shared_ptr< T >  ptr )

inlineprivate

Get branch address for fundamental types.

    {
        return ptr.get();
    }

GetBranchAddress() [6/6]

requires std::is_fundamental<T>::value T* GetBranchAddress ( std::shared_ptr< T >  ptr )

inlineprivate

Get branch address for fundamental types.

    {
        return ptr.get();
    }

GetBranchReadOnly() [1/2]

T* GetBranchReadOnly ( const std::string &  name, BranchMode  mode = mandatory  )

inline

Wrapper to initialise read-only branches.

The existence of the branch is checked before setting the address.

In practice, loading a branch whose contents should be accessed but not modified reduces to a single line:

auto recEvent = flow.GetBranchReadOnly<RecEvent>("recEvent");

< branch type (e.g. RecEvent, vector<RecJet>)

Parameters

name	branch name
mode	branch may not exist

    {
        using namespace std;
 
        if (!tIn)
            BOOST_THROW_EXCEPTION( invalid_argument("`GetInputTree()` should "
                            "be called before declaring a read-only branch") );
 
        if (!branches.contains(name)) {
 
            any branch;
            if constexpr (is_compound<T>::value)
                branch = make_shared<T*>();
            else
                branch = make_shared<T>();
 
            if (steering & verbose)
                cout << "Flow: loading read-only branch `" << name << "`" << endl;
 
            if (tIn->GetBranch(name.c_str()) == nullptr)
                return NoBranch<T>(name, mode);
 
            int err = tIn->SetBranchAddress(name.c_str(), branch_cast<T>(branch).get());
            if (steering & verbose)
                cout << "Flow: `TTree::SetBranchAddress()` returned " << to_string(err)
                     << " (check `TTree::ESetBranchAddressStatus` for the meaning)."
                     << endl;
            if (err < 0) {
                string what = "`"s + name + "` branch could not be set. "s;
                if (mode == facultative) {
                    if (steering & verbose)
                        cout << orange << "Flow: " << what << def << endl;
                    return nullptr;
                }
 
                namespace DE = Darwin::Exceptions;
                BOOST_THROW_EXCEPTION( DE::BadInput(what.c_str(), *tIn) );
            }
            branches.emplace(name, branch);
        }
 
        return GetBranchAddress<T>(name);
    }

GetBranchReadOnly() [2/2]

T* GetBranchReadOnly ( const std::string &  name, BranchMode  mode = mandatory  )

inline

Wrapper to initialise read-only branches.

The existence of the branch is checked before setting the address.

In practice, loading a branch whose contents should be accessed but not modified reduces to a single line:

auto recEvent = flow.GetBranchReadOnly<RecEvent>("recEvent");

< branch type (e.g. RecEvent, vector<RecJet>)

Parameters

name	branch name
mode	branch may not exist

    {
        using namespace std;
 
        if (!tIn)
            BOOST_THROW_EXCEPTION( invalid_argument("`GetInputTree()` should "
                            "be called before declaring a read-only branch") );
 
        if (!branches.contains(name)) {
 
            any branch;
            if constexpr (is_compound<T>::value)
                branch = make_shared<T*>();
            else
                branch = make_shared<T>();
 
            if (steering & verbose)
                cout << "Flow: loading read-only branch `" << name << "`" << endl;
 
            if (tIn->GetBranch(name.c_str()) == nullptr)
                return NoBranch<T>(name, mode);
 
            int err = tIn->SetBranchAddress(name.c_str(), branch_cast<T>(branch).get());
            if (steering & verbose)
                cout << "Flow: `TTree::SetBranchAddress()` returned " << to_string(err)
                     << " (check `TTree::ESetBranchAddressStatus` for the meaning)."
                     << endl;
            if (err < 0) {
                string what = "`"s + name + "` branch could not be set. "s;
                if (mode == facultative) {
                    if (steering & verbose)
                        cout << orange << "Flow: " << what << def << endl;
                    return nullptr;
                }
 
                namespace DE = Darwin::Exceptions;
                BOOST_THROW_EXCEPTION( DE::BadInput(what.c_str(), *tIn) );
            }
            branches.emplace(name, branch);
        }
 
        return GetBranchAddress<T>(name);
    }

GetBranchReadWrite() [1/2]

T* GetBranchReadWrite ( const std::string &  name, BranchMode  mode = mandatory  )

inline

Wrapper to initialise read-write branches.

In practice, setting up a branch to modify its contents reduces to a single line:

auto recEvent = flow.GetBranchReadWrite<RecEvent>("recEvent");

< branch type (e.g. RecEvent, vector<RecJet>)

Parameters

name	branch name
mode	branch may not exist

    {
        using namespace std;
 
        if (!tIn)
            BOOST_THROW_EXCEPTION( invalid_argument("`GetInputTree()` should "
                            "be called before declaring a read-write branch") );
 
        if (!tOut)
            BOOST_THROW_EXCEPTION( invalid_argument("`GetOutputTree()` should "
                            "be called before declaring a read-write branch") );
 
        if (!branches.contains(name)) {
            if (GetBranchReadOnly<T>(name, mode) == nullptr)
                return NoBranch<T>(name, mode);
            if (steering & Friend)
                GetBranchWriteOnly<T>(name);
        }
 
        return GetBranchAddress<T>(name);
    }

GetBranchReadWrite() [2/2]

T* GetBranchReadWrite ( const std::string &  name, BranchMode  mode = mandatory  )

inline

Wrapper to initialise read-write branches.

In practice, setting up a branch to modify its contents reduces to a single line:

auto recEvent = flow.GetBranchReadWrite<RecEvent>("recEvent");

< branch type (e.g. RecEvent, vector<RecJet>)

Parameters

name	branch name
mode	branch may not exist

    {
        using namespace std;
 
        if (!tIn)
            BOOST_THROW_EXCEPTION( invalid_argument("`GetInputTree()` should "
                            "be called before declaring a read-write branch") );
 
        if (!tOut)
            BOOST_THROW_EXCEPTION( invalid_argument("`GetOutputTree()` should "
                            "be called before declaring a read-write branch") );
 
        if (!branches.contains(name)) {
            if (GetBranchReadOnly<T>(name, mode) == nullptr)
                return NoBranch<T>(name, mode);
            if (steering & Friend)
                GetBranchWriteOnly<T>(name);
        }
 
        return GetBranchAddress<T>(name);
    }

GetBranchWriteOnly() [1/2]

T* GetBranchWriteOnly ( const std::string &  name )

inline

Wrapper to initialise write-only branches.

In practice, setting up a new branch in a n-tuple reduces to a single line:

auto recEvent = flow.GetBranchWriteOnly<RecEvent>("recEvent");

< branch type (e.g. RecEvent, vector<RecJet>)

Parameters

name	branch name

    {
        using namespace std;
 
        if (!tOut)
            BOOST_THROW_EXCEPTION( invalid_argument("`GetOutputTree()` should "
                                                    "be called before") );
 
        if (!branches.contains(name)) {
            if constexpr (is_compound<T>::value)
                branches.emplace(name, make_shared<T*>());
            else
                branches.emplace(name, make_shared<T>());
        }
 
        any branch = branches[name];
        shared_ptr ptr = branch_cast<T>(branch);
 
        if (steering & verbose)
            cout << "Flow: setting up a write-only branch for `" << name << "`" << endl;
 
        if (tOut->Branch(name.c_str(), ptr.get()) == nullptr) {
            namespace DE = Darwin::Exceptions;
            string what = name + " branch could not be set up";
            BOOST_THROW_EXCEPTION( DE::BadInput(what.c_str(), *tOut) );
        }
 
        return GetBranchAddress<T>(ptr);
    }

GetBranchWriteOnly() [2/2]

T* GetBranchWriteOnly ( const std::string &  name )

inline

Wrapper to initialise write-only branches.

In practice, setting up a new branch in a n-tuple reduces to a single line:

auto recEvent = flow.GetBranchWriteOnly<RecEvent>("recEvent");

< branch type (e.g. RecEvent, vector<RecJet>)

Parameters

name	branch name

    {
        using namespace std;
 
        if (!tOut)
            BOOST_THROW_EXCEPTION( invalid_argument("`GetOutputTree()` should "
                                                    "be called before") );
 
        if (!branches.contains(name)) {
            if constexpr (is_compound<T>::value)
                branches.emplace(name, make_shared<T*>());
            else
                branches.emplace(name, make_shared<T>());
        }
 
        any branch = branches[name];
        shared_ptr ptr = branch_cast<T>(branch);
 
        if (steering & verbose)
            cout << "Flow: setting up a write-only branch for `" << name << "`" << endl;
 
        if (tOut->Branch(name.c_str(), ptr.get()) == nullptr) {
            namespace DE = Darwin::Exceptions;
            string what = name + " branch could not be set up";
            BOOST_THROW_EXCEPTION( DE::BadInput(what.c_str(), *tOut) );
        }
 
        return GetBranchAddress<T>(ptr);
    }

GetInputHist() [1/2]

std::unique_ptr<THX> GetInputHist ( const std::string &  name )

inline

Load a single ROOT histogram from a list of files.

Todo:

Can we rather use a node handle to extract the unique pointer?

Parameters

name	internal path to ROOT histogram

    {
        auto hists = GetInputHists<THX,1>({name});
        THX * hist = hists.front().release();
        return std::unique_ptr<THX>(hist);
    }

GetInputHist() [2/2]

std::unique_ptr<THX> GetInputHist ( const std::string &  name )

inline

Load a single ROOT histogram from a list of files.

Todo:

Can we rather use a node handle to extract the unique pointer?

Parameters

name	internal path to ROOT histogram

    {
        auto hists = GetInputHists<THX,1>({name});
        THX * hist = hists.front().release();
        return std::unique_ptr<THX>(hist);
    }

GetInputHists() [1/4]

auto GetInputHists ( const Args...  args )

inline

Load ROOT histograms from a list of files.

In many cases, this spares from running an intermediate hadd (which can be very slow if there is a TTree in the same ROOT file).

    {
        constexpr const size_t N = sizeof...(args);
        std::array<std::string, N> names {{ args... }};
        return GetInputHists<THX, N>(names);
    }

GetInputHists() [2/4]

auto GetInputHists ( const Args...  args )

inline

Load ROOT histograms from a list of files.

In many cases, this spares from running an intermediate hadd (which can be very slow if there is a TTree in the same ROOT file).

    {
        constexpr const size_t N = sizeof...(args);
        std::array<std::string, N> names {{ args... }};
        return GetInputHists<THX, N>(names);
    }

GetInputHists() [3/4]

std::array<std::unique_ptr<THX>, N> GetInputHists ( const std::array< std::string, N > &  names = {} )

inline

Load ROOT histograms from a list of files.

In many cases, this spares from running an intermediate hadd (which can be very slow if there is a TTree in the same ROOT file).

Parameters

names

path to ROOT histograms

                                                   {} 
            )
    {
        using namespace std;
        namespace fs = filesystem;
 
        if (inputs.size() == 0)
            BOOST_THROW_EXCEPTION( invalid_argument("Empty list of input files") );
 
        array<unique_ptr<THX>, N> sums;
        for (const fs::path& input: inputs) {
            auto fIn = make_unique<TFile>(input.c_str(), "READ");
            for (size_t i = 0; i < N; ++i) {
                const string& name = names[i];
                unique_ptr<THX> h(fIn->Get<THX>(name.c_str()));
                if (!h) {
                    namespace DE = Darwin::Exceptions;
                    BOOST_THROW_EXCEPTION(
                            DE::BadInput(Form("`%s` cannot be found in (one of) the "
                                              " file(s).", name.c_str()), fIn));
                }
                if (sums[i])
                    sums[i]->Add(h.get());
                else {
                    sums[i] = std::move(h);
                    sums[i]->SetDirectory(nullptr);
                }
            }
        }
        return sums;
    }

GetInputHists() [4/4]

std::array<std::unique_ptr<THX>, N> GetInputHists ( const std::array< std::string, N > &  names = {} )

inline

Load ROOT histograms from a list of files.

In many cases, this spares from running an intermediate hadd (which can be very slow if there is a TTree in the same ROOT file).

Parameters

names

path to ROOT histograms

                                                   {} 
            )
    {
        using namespace std;
        namespace fs = filesystem;
 
        if (inputs.size() == 0)
            BOOST_THROW_EXCEPTION( invalid_argument("Empty list of input files") );
 
        array<unique_ptr<THX>, N> sums;
        for (const fs::path& input: inputs) {
            auto fIn = make_unique<TFile>(input.c_str(), "READ");
            for (size_t i = 0; i < N; ++i) {
                const string& name = names[i];
                unique_ptr<THX> h(fIn->Get<THX>(name.c_str()));
                if (!h) {
                    namespace DE = Darwin::Exceptions;
                    BOOST_THROW_EXCEPTION(
                            DE::BadInput(Form("`%s` cannot be found in (one of) the "
                                              " file(s).", name.c_str()), fIn));
                }
                if (sums[i])
                    sums[i]->Add(h.get());
                else {
                    sums[i] = std::move(h);
                    sums[i]->SetDirectory(nullptr);
                }
            }
        }
        return sums;
    }

GetInputTree() [1/4]

ChainSlice * GetInputTree	(	const Slice	slice,
		const std::string &	name = "events"
	)

Load chain from a list of files with non-empty trees.

internal path to TTree

Parameters

slice

number and index of slice

{
    GetInputTree(name);
 
    if (tIn->GetEntries() == 0) {
        tIn.reset();
        BOOST_THROW_EXCEPTION(invalid_argument("Empty trees in input!"));
    }
 
    if (slice.first == 0 || slice.first <= slice.second)
        BOOST_THROW_EXCEPTION(invalid_argument("The number of slices " + to_string(slice.first)
              + " must be larger than the index of the current slice " + to_string(slice.second)));
 
    // Restrict the tIn to the entries for the slice
    const auto entries = tIn->GetEntries();
    tIn->SetBegin(entries * ((slice.second + 0.) / slice.first));
    tIn->SetEnd(entries * ((slice.second + 1.) / slice.first));
 
    return tIn.get();
}

GetInputTree() [2/4]

ChainSlice* GetInputTree	(	const	Slice,
		const std::string &	= "events"
	)

Load chain from a list of files with non-empty trees.

internal path to TTree

Parameters

Slice

number and index of slice

GetInputTree() [3/4]

ChainSlice * GetInputTree

(

const std::string &

name = "events"

)

Load chain from a list of files with possibly empty trees.

internal path to TTree

{
    if (tIn) {
        if (steering & verbose)
            cout << "Flow: returning the existing input tree "
                    "(arguments are ignored)" << endl;
        return tIn.get();
    }
 
    if (inputs.empty())
        BOOST_THROW_EXCEPTION( invalid_argument("Empty list of input files") );
 
    tIn = make_unique<ChainSlice>(name.c_str());
    for (const auto& input: inputs) {
        int code = tIn->Add(input.c_str(), 0);
        // "If nentries<=0 and wildcarding is not used,
        // returns 1 if the file exists and contains the correct tree
        //     and 0 otherwise" (ROOT Doxygen)
        if (code == 1) continue; // i.e. the tree was found successfully
        tIn.reset();
        auto fIn = make_unique<TFile>(input.c_str(), "READ");
        BOOST_THROW_EXCEPTION(DE::BadInput("The tree cannot be "
                        "found in (one of) the input file(s).", fIn));
    }
 
    return tIn.get();
}

GetInputTree() [4/4]

ChainSlice* GetInputTree

(

const std::string &

= "events"

)

Load chain from a list of files with possibly empty trees.

internal path to TTree

GetOutput() [1/2]

std::pair< TFile *, TTree * > GetOutput	(	const std::filesystem::path &	fOutName,
		const std::source_location	location = std::source_location::current()
	)

Get both the output file and the output tree in one go.

upstream function

Parameters

fOutName

output directory

{
    shared_ptr<TFile> fOut = Darwin::Tools::GetOutputFile(fOutName, location);
    return {fOut.get(), GetOutputTree(fOut, location)};
}

GetOutput() [2/2]

std::pair<TFile *, TTree *> GetOutput	(	const std::filesystem::path &	,
		const std::source_location	= std::source_location::current()
	)

Get both the output file and the output tree in one go.

upstream function

GetOutputFile() [1/2]

TFile* GetOutputFile ( )

inline

Get a raw pointer to the output file.

{ return fOut.get(); }

GetOutputFile() [2/2]

TFile* GetOutputFile ( )

inline

Get a raw pointer to the output file.

{ return fOut.get(); }

GetOutputTree() [1/4]

TTree* GetOutputTree	(	const std::filesystem::path &	,
		const std::source_location	= std::source_location::current()
	)

Create an output TTree object.

upstream function

GetOutputTree() [2/4]

TTree * GetOutputTree	(	const std::filesystem::path &	fOutName,
		const std::source_location	location = std::source_location::current()
	)

Create an output TTree object.

upstream function

Parameters

fOutName

output directory

{
    shared_ptr<TFile> fOut = Darwin::Tools::GetOutputFile(fOutName, location);
    return GetOutputTree(fOut, location);
}

GetOutputTree() [3/4]

TTree* GetOutputTree	(	std::shared_ptr< TFile >	= {},
		const std::source_location	= std::source_location::current()
	)

Create an output TTree object.

If the TTree already exists, either clone the input TChain or define the input TChain as a friend of the new TTree. Else a brand new TTree is stored.

The title of the TTree is used to store (retrieve) the name of the present (previous) command. When loading a tree with friends, one can refer to old versions of the branches by prefixing them with the corresponding command name.

Todo:

TTree::BuildIndex() to preserve the association despite skipped events?

upstream function

GetOutputTree() [4/4]

TTree * GetOutputTree	(	std::shared_ptr< TFile >	fOut = {},
		const std::source_location	location = std::source_location::current()
	)

Create an output TTree object.

If the TTree already exists, either clone the input TChain or define the input TChain as a friend of the new TTree. Else a brand new TTree is stored.

The title of the TTree is used to store (retrieve) the name of the present (previous) command. When loading a tree with friends, one can refer to old versions of the branches by prefixing them with the corresponding command name.

Todo:

TTree::BuildIndex() to preserve the association despite skipped events?

upstream function

Note

We use the title to store the current command. When the present tree is used as a friend, this title will supsersede its name. Exceptions:

• no title was found,
• or the present name is the same as the last title (i.e. running twice the same command).

Parameters

fOut	output file

{
    if (tOut) {
        if (steering & verbose)
            cout << "Flow: returning the existing output tree" << endl;
 
        return tOut.get();
    }
 
    if (fOut)
        SetOutputFile(fOut);
 
    const auto title = fs::path(location.file_name()).stem().string();
 
    if (!tIn) {
        if (steering & verbose)
            cout << "Flow: creating a new output tree" << endl;
 
        tOut = make_unique<TTree>("events", title.c_str());
    }
    else if (steering & Friend) {
        if (steering & verbose)
            cout << "Flow: creating a friend tree" << endl;
 
        tOut = make_unique<TTree>("events", title.c_str());
        tIn->GetEntry(0); // necessary to load a(ny) TTree
 
        // find the name of the previous command
        string lastFunc = tIn->GetTree()->GetTitle();
        // -> this is supposed to store the name of the last command
        if (lastFunc == "") {
            cerr << orange << "Unable to identify the command used to "
                              "obtain the input from the title.\n" << def;
            lastFunc = "previous";
        }
        else if (lastFunc == title) {
            cerr << orange << "Running twice the same command in a row. "
                              "Adding `previous2` ahead of the title.\n" << def;
            lastFunc = "previous2"s + title;
        }
 
        // add friend
        SlicedFriendElement::AddTo(tOut.get(), tIn.get(), lastFunc.c_str());
 
        // copy metainfo
        TList * userinfo = tIn->GetTree()->GetUserInfo();
        tOut->GetUserInfo()->AddAll(userinfo);
        userinfo->Clear(); // necessary to prevent the TTree destructor from deleting
                           // all elements in the list (avoid double deletion)
    }
    else {
        if (steering & verbose)
            cout << "Flow: creating a clone tree" << endl;
 
        tOut = unique_ptr<TTree>(tIn->CloneTree(0));
        tOut->SetTitle(title.c_str());
    }
    if (fOut)
        tOut->SetDirectory(fOut.get());
    return tOut.get();
}

GetPlugins() [1/2]

std::vector<P*> GetPlugins ( R &&  plugin_paths )

inline

Load and get plugins.

Todo:

Clarify order in which the plugins should be destroyed in case of non-trivial interplay between plugins (GitLab).

    {
        using namespace std;
        namespace fs = filesystem;
 
        for (fs::path file: plugin_paths)
            plugin_loaders.emplace_back(file, steering);
 
        auto plugins = plugin_loaders | views::transform(&PluginLoader::Get<P>)
                                      | views::join
                                      | views::common;
        return vector<P*>(plugins.begin(), plugins.end());
    }

GetPlugins() [2/2]

std::vector<P*> GetPlugins ( R &&  plugin_paths )

inline

Load and get plugins.

Todo:

Clarify order in which the plugins should be destroyed in case of non-trivial interplay between plugins (GitLab).

    {
        using namespace std;
        namespace fs = filesystem;
 
        for (fs::path file: plugin_paths)
            plugin_loaders.emplace_back(file, steering);
 
        auto plugins = plugin_loaders | views::transform(&PluginLoader::Get<P>)
                                      | views::join
                                      | views::common;
        return vector<P*>(plugins.begin(), plugins.end());
    }

NoBranch() [1/2]

T* NoBranch ( const std::string &  name, BranchMode  mode  )

inlineprivate

Wrapper either to return a nullptr or to throw an error.

    {
        if (mode == facultative)
            return nullptr;
 
        namespace DE = Darwin::Exceptions;
        std::string what = name + " branch could not be found";
        BOOST_THROW_EXCEPTION( DE::BadInput(what.c_str(), *tIn) );
    }

NoBranch() [2/2]

T* NoBranch ( const std::string &  name, BranchMode  mode  )

inlineprivate

Wrapper either to return a nullptr or to throw an error.

    {
        if (mode == facultative)
            return nullptr;
 
        namespace DE = Darwin::Exceptions;
        std::string what = name + " branch could not be found";
        BOOST_THROW_EXCEPTION( DE::BadInput(what.c_str(), *tIn) );
    }

SetOutputFile() [1/2]

void SetOutputFile ( std::shared_ptr< TFile >  fOut )

inline

Set the output file where the output TTree should be saved.

{ this->fOut = fOut; }

SetOutputFile() [2/2]

void SetOutputFile ( std::shared_ptr< TFile >  fOut )

inline

Set the output file where the output TTree should be saved.

{ this->fOut = fOut; }

Member Data Documentation

branches

std::map< std::string, std::any > branches

private

pointers to mounted branches

fOut

std::shared_ptr< TFile > fOut

private

output ROOT file

inputs

std::vector< std::filesystem::path > inputs

private

ROOT files or directories.

plugin_loaders

std::vector< PluginLoader > plugin_loaders

private

See also

PluginLoader

steering

int steering

private

steering from Options, mostly useful for friends

tIn

std::unique_ptr< ChainSlice > tIn

private

input chain

tOut

std::unique_ptr< TTree > tOut

private

output tree

---

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

• /builds/cms-analysis/general/DasAnalysisSystem/Core/Installer/Darwin/interface/Flow.h
• /builds/cms-analysis/general/DasAnalysisSystem/Core/Installer/Darwin/src/Flow.cc