RooCustomizer is a factory class to produce clones of a prototype composite PDF object with the same structure but different leaf servers (parameters or dependents).

RooCustomizer supports two kinds of modifications:

replaceArg(leaf_arg, repl_arg): Replaces each occurrence of leaf_arg with repl_arg in the composite pdf.
splitArg(split_arg): Build multiple clones of the same prototype. Each occurrence of split_arg is replaced with a clone of split_arg named split_arg_[MCstate], where [MCstate] is the name of the 'master category state' that indexes the clones to be built.

Example: Change the decay constant of an exponential for each run

Splitting is particularly useful when building simultaneous fits to subsets of the data sample with different background properties. In such a case, the user builds a single prototype PDF representing the structure of the signal and background and splits the dataset into categories with different background properties. Using RooCustomizer a PDF for each subfit can be constructed from the prototype that has same structure and signal parameters, but different instances of the background parameters: e.g.

...
RooExponential bg("bg","background",x,alpha) ;
RooGaussian sig("sig","signal",x,mean,sigma) ;
RooAddPdf pdf("pdf","pdf",sig,bg,sigfrac) ;
 
RooDataSet data("data","dataset",RooArgSet(x,runblock),...)
 
RooCategory runblock("runblock","run block") ;
runblock.defineType("run1") ;
runblock.defineType("run2") ;
 
RooArgSet splitLeaves;
RooCustomizer cust(pdf,runblock,splitLeaves);
cust.splitArg(alpha,runblock);
 
RooAbsPdf* pdf_run1 = cust.build("run1") ;
RooAbsPdf* pdf_run2 = cust.build("run2") ;
 
RooSimultaneous simpdf("simpdf","simpdf",RooArgSet(*pdf_run1,*pdf_run2))

If the master category state is a super category, leaves may be split by any subset of that master category. E.g. if the master category is 'A x B', leaves may be split by A, B or AxB.

In addition to replacing leaf nodes, RooCustomizer clones all branch nodes that depend directly or indirectly on modified leaf nodes, so that the input pdf is untouched by each build operation.

The customizer owns all the branch nodes including the returned top level node, so the customizer should live as longs as the cloned composites are needed.

Any leaf nodes that are created by the customizer will be put into the leaf list that is passed into the customizers constructor (splitLeaves in the above example. The list owner is responsible for deleting these leaf nodes after the customizer is deleted.

Advanced techniques

Reuse nodes to customise a different PDF

By default, the customizer clones the prototype leaf node when splitting a leaf, but the user can feed pre-defined split leaves in leaf list. These leaves must have the name <split_leaf>_<splitcat_label> to be picked up. The list of pre-supplied leaves may be partial, any missing split leaves will be auto generated.

Another common construction is to have two prototype PDFs, each to be customized by a separate customizer instance, that share parameters. To ensure that the customized clones also share their respective split leaves, i.e.

PDF1(x,y, A) and PDF2(z, A) ---> PDF1_run1(x,y, A_run1) and PDF2_run1(x,y, A_run1)

PDF1_run2(x,y, A_run2) and PDF2_run2(x,y, A_run2)

y

Double_t y[n]

Definition legend1.C:17

feed the same split leaf list into both customizers. In that case, the second customizer will pick up the split leaves instantiated by the first customizer and the link between the two PDFs is retained.

Customising with pre-defined leaves

If leaf nodes are provided in the sets, the customiser will use them. This is a complete example that customises the yield parameter, and splits (automatically clones) the mean of the Gaussian. This is a short version of the tutorial rf514_RooCustomizer.C.

RooRealVar E("Energy","Energy",0,3000);
 
RooRealVar meanG("meanG","meanG", peak[1]);
RooRealVar fwhm("fwhm", "fwhm", 5/(2*Sqrt(2*Log(2))));
RooGaussian gauss("gauss", "gauss", E, meanG, fwhm);
 
RooPolynomial linear("linear","linear",E,RooArgList());
 
RooRealVar yieldSig("yieldSig", "yieldSig", 1, 0, 1.E4);
RooRealVar yieldBkg("yieldBkg", "yieldBkg", 1, 0, 1.E4);
 
RooAddPdf model("model","model",
    RooArgList(gauss,linear),
    RooArgList(yieldSig, yieldBkg));
 
RooCategory sample("sample","sample");
sample.defineType("BBG1m2T");
sample.defineType("BBG2m2T");
 
 
RooArgSet customisedLeaves;
RooArgSet allLeaves;
 
RooRealVar mass("M", "M", 1, 0, 12000);
RooFormulaVar yield1("yieldSig_BBG1m2T","sigy1","M/3.360779",mass);
RooFormulaVar yield2("yieldSig_BBG2m2T","sigy2","M/2",mass);
allLeaves.add(yield1);
allLeaves.add(yield2);
 
 
RooCustomizer cust(model, sample, customisedLeaves, &allLeaves);
cust.splitArg(yieldSig, sample);
cust.splitArg(meanG, sample);
 
auto pdf1 = cust.build("BBG1m2T");
auto pdf2 = cust.build("BBG2m2T");

Definition at line 35 of file RooCustomizer.h.

Public Member Functions
	RooCustomizer (const RooAbsArg &pdf, const char *name)
	Sterile Constructor.

	RooCustomizer (const RooAbsArg &pdf, const RooAbsCategoryLValue &masterCat, RooArgSet &splitLeafListOwned, RooArgSet *splitLeafListAll=nullptr)
	Constructor with a prototype and masterCat index category.

RooAbsArg *	build (bool verbose=false)
	Build a clone of the prototype executing all registered 'replace' rules.

RooAbsArg *	build (const char *masterCatState, bool verbose=false)
	Build a clone of the prototype executing all registered 'replace' rules and 'split' rules for the masterCat state named 'masterCatState'.

const RooArgSet &	cloneBranchList () const
	Return list of cloned branch nodes.

const RooArgSet &	cloneLeafList () const
	Return list of cloned leaf nodes.

RooAbsPdf const &	pdf () const

void	printArgs (std::ostream &os) const
	Print arguments of customizer, i.e. input p.d.f and input master category (if any)

void	printMultiline (std::ostream &os, Int_t content, bool verbose=false, TString indent="") const
	Print customizer configuration details.

void	replaceArg (const RooAbsArg &orig, const RooAbsArg &subst)
	Replace any occurrence of arg 'orig' with arg 'subst'.

void	setCloneBranchSet (RooArgSet &cloneBranchSet)
	Releases ownership of list of cloned branch nodes.

void	setOwning (bool flag)
	If flag is true, make customizer own all created components.

void	splitArg (const RooAbsArg &arg, const RooAbsCategory &splitCat)
	Split all argument 'arg' into individualized clones for each defined state of 'splitCat'.

void	splitArgs (const RooArgSet &argSet, const RooAbsCategory &splitCat)
	Split all arguments in 'set' into individualized clones for each defined state of 'splitCat'.

Protected Member Functions
	RooCustomizer (const RooCustomizer &)

RooAbsArg *	doBuild (const char *masterCatState, bool verbose)
	Back-end implementation of the p.d.f building functionality.

void	initialize ()
	Initialize the customizer.

Protected Attributes
RooArgSet *	_cloneBranchList = nullptr
	Pointer to list of cloned branches used.

RooArgSet *	_cloneNodeListAll = nullptr
	List of all cloned nodes.

RooArgSet *	_cloneNodeListOwned = nullptr
	List of owned cloned nodes.

RooArgSet	_internalCloneBranchList
	List of branches of internal clone.

RooArgSet	_masterBranchList
	List of branch nodes.

RooAbsCategoryLValue *	_masterCat = nullptr
	Pointer to input master category.

RooArgSet	_masterLeafList
	List of leaf nodes.

RooAbsArg *	_masterPdf
	Pointer to input p.d.f.

TString	_name
	Name of this object.

bool	_owning
	If true we own all created components.

TList	_replaceArgList
	List of RooAbsArgs to be replaced.

TList	_replaceSubList
	List of replacement RooAbsArgs.

TList	_splitArgList
	List of RooAbsArgs to be split.

TList	_splitCatList
	List of categories to be used for above splits.

bool	_sterile
	If true we do not have as associated master category.

#include <RooCustomizer.h>

Constructor & Destructor Documentation

◆ RooCustomizer() [1/3]

RooCustomizer::RooCustomizer	(	const RooAbsArg &	pdf,
		const RooAbsCategoryLValue &	masterCat,
		RooArgSet &	splitLeaves,
		RooArgSet *	splitLeavesAll = `nullptr`
	)

Constructor with a prototype and masterCat index category.

Customizers created by this constructor offer both the replaceArg() and splitArg() functionality.

Parameters

[in]	pdf	Proto PDF to be customised.
[in]	masterCat	Category to be used for splitting.
[in,out]	splitLeaves	All nodes created in the customisation process are added to this set. The user can provide nodes that are taken from the set if they have a name that matches `<parameterNameToBeReplaced>_<category>`.

Note: The set needs to own its contents if they are user-provided. Use e.g.
RooArgSet customisedLeaves;

auto yield1 = new RooFormulaVar("yieldSig_BBG1m2T","sigy1","M/3.360779",mass);

customisedLeaves.addOwned(*yield1);

RooAbsCollection::addOwned
virtual bool addOwned(RooAbsArg &var, bool silent=false)
Add an argument and transfer the ownership to the collection.
Definition RooAbsCollection.cxx:360

Parameters

[in,out] splitLeavesAll All leaves that are used when customising are collected here. If this set already contains leaves, they will be used for customising if the names match as above.

Definition at line 225 of file RooCustomizer.cxx.

◆ RooCustomizer() [2/3]

RooCustomizer::RooCustomizer	(	const RooAbsArg &	pdf,
		const char *	name
	)

Sterile Constructor.

Customizers created by this constructor offer only the replace() method. The supplied 'name' is used as suffix for any cloned branch nodes

Definition at line 249 of file RooCustomizer.cxx.

◆ RooCustomizer() [3/3]

RooCustomizer::RooCustomizer ( const RooCustomizer & )

protected

Member Function Documentation

◆ build() [1/2]

RooAbsArg * RooCustomizer::build ( bool verbose = false )

Build a clone of the prototype executing all registered 'replace' rules.

If verbose is set, a message is printed for each leaf or branch node modification. The returned head node owns all cloned branch nodes that were created in the cloning process.

Definition at line 349 of file RooCustomizer.cxx.

◆ build() [2/2]

RooAbsArg * RooCustomizer::build	(	const char *	masterCatState,
		bool	verbose = `false`
	)

Build a clone of the prototype executing all registered 'replace' rules and 'split' rules for the masterCat state named 'masterCatState'.

If verbose is set a message is printed for each leaf or branch node modification. The returned composite arg is owned by the customizer. This function cannot be called on customizer build with the sterile constructor.

Definition at line 385 of file RooCustomizer.cxx.

◆ cloneBranchList()

const RooArgSet & RooCustomizer::cloneBranchList ( ) const

inline

Return list of cloned branch nodes.

Definition at line 55 of file RooCustomizer.h.

◆ cloneLeafList()

const RooArgSet & RooCustomizer::cloneLeafList ( ) const

inline

Return list of cloned leaf nodes.

Definition at line 59 of file RooCustomizer.h.

◆ doBuild()

RooAbsArg * RooCustomizer::doBuild	(	const char *	masterCatState,
		bool	verbose
	)

protected

Back-end implementation of the p.d.f building functionality.

Definition at line 408 of file RooCustomizer.cxx.

◆ initialize()

void RooCustomizer::initialize ( )

protected

Initialize the customizer.

Definition at line 269 of file RooCustomizer.cxx.

◆ pdf()

RooAbsPdf const & RooCustomizer::pdf ( ) const

Definition at line 649 of file RooCustomizer.cxx.

◆ printArgs()

void RooCustomizer::printArgs ( std::ostream & os ) const

Print arguments of customizer, i.e. input p.d.f and input master category (if any)

Definition at line 598 of file RooCustomizer.cxx.

◆ printMultiline()

void RooCustomizer::printMultiline	(	std::ostream &	os,
		Int_t	content,
		bool	verbose = `false`,
		TString	indent = `""`
	)		const

Print customizer configuration details.

Definition at line 612 of file RooCustomizer.cxx.

◆ replaceArg()

void RooCustomizer::replaceArg	(	const RooAbsArg &	orig,
		const RooAbsArg &	subst
	)

Replace any occurrence of arg 'orig' with arg 'subst'.

Definition at line 329 of file RooCustomizer.cxx.

◆ setCloneBranchSet()

void RooCustomizer::setCloneBranchSet ( RooArgSet & cloneBranchSet )

Releases ownership of list of cloned branch nodes.

Install the input RooArgSet as container in which all cloned branches will be stored.

Definition at line 642 of file RooCustomizer.cxx.

◆ setOwning()

void RooCustomizer::setOwning ( bool flag )

inline

If flag is true, make customizer own all created components.

Definition at line 44 of file RooCustomizer.h.

◆ splitArg()

void RooCustomizer::splitArg	(	const RooAbsArg &	arg,
		const RooAbsCategory &	splitCat
	)

Split all argument 'arg' into individualized clones for each defined state of 'splitCat'.

The 'splitCats' category must be subset of or equal to the master category supplied in the customizer constructor.

Splitting is only available on customizers created with a master index category

Definition at line 306 of file RooCustomizer.cxx.

◆ splitArgs()

void RooCustomizer::splitArgs	(	const RooArgSet &	set,
		const RooAbsCategory &	splitCat
	)

Split all arguments in 'set' into individualized clones for each defined state of 'splitCat'.

The 'splitCats' category must be subset of or equal to the master category supplied in the customizer constructor.

Splitting is only available on customizers created with a master index category

Definition at line 283 of file RooCustomizer.cxx.

Member Data Documentation

◆ _cloneBranchList

RooArgSet* RooCustomizer::_cloneBranchList = nullptr

protected

Pointer to list of cloned branches used.

Definition at line 97 of file RooCustomizer.h.

◆ _cloneNodeListAll

RooArgSet* RooCustomizer::_cloneNodeListAll = nullptr

protected

List of all cloned nodes.

Definition at line 100 of file RooCustomizer.h.

◆ _cloneNodeListOwned

RooArgSet* RooCustomizer::_cloneNodeListOwned = nullptr

protected

List of owned cloned nodes.

Definition at line 101 of file RooCustomizer.h.

◆ _internalCloneBranchList

RooArgSet RooCustomizer::_internalCloneBranchList

protected

List of branches of internal clone.

Definition at line 96 of file RooCustomizer.h.

◆ _masterBranchList

RooArgSet RooCustomizer::_masterBranchList

protected

List of branch nodes.

Definition at line 93 of file RooCustomizer.h.

◆ _masterCat

RooAbsCategoryLValue* RooCustomizer::_masterCat = nullptr

protected

Pointer to input master category.

Definition at line 91 of file RooCustomizer.h.

◆ _masterLeafList

RooArgSet RooCustomizer::_masterLeafList

protected

List of leaf nodes.

Definition at line 94 of file RooCustomizer.h.

◆ _masterPdf

RooAbsArg* RooCustomizer::_masterPdf

protected

Pointer to input p.d.f.

Definition at line 90 of file RooCustomizer.h.

◆ _name

TString RooCustomizer::_name

protected

Name of this object.

Definition at line 81 of file RooCustomizer.h.

◆ _owning

bool RooCustomizer::_owning

protected

If true we own all created components.

Definition at line 80 of file RooCustomizer.h.

◆ _replaceArgList

TList RooCustomizer::_replaceArgList

protected

List of RooAbsArgs to be replaced.

Definition at line 86 of file RooCustomizer.h.

◆ _replaceSubList

TList RooCustomizer::_replaceSubList

protected

List of replacement RooAbsArgs.

Definition at line 87 of file RooCustomizer.h.

◆ _splitArgList

TList RooCustomizer::_splitArgList

protected

List of RooAbsArgs to be split.

Definition at line 83 of file RooCustomizer.h.

◆ _splitCatList

TList RooCustomizer::_splitCatList

protected

List of categories to be used for above splits.

Definition at line 84 of file RooCustomizer.h.

◆ _sterile

bool RooCustomizer::_sterile

protected

If true we do not have as associated master category.

Definition at line 79 of file RooCustomizer.h.

Libraries for RooCustomizer:

[legend]

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

roofit/roofitcore/inc/RooCustomizer.h
roofit/roofitcore/src/RooCustomizer.cxx

Example: Change the decay constant of an exponential for each run

Advanced techniques

Reuse nodes to customise a different PDF

Customising with pre-defined leaves

Public Member Functions

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ RooCustomizer() [1/3]

◆ RooCustomizer() [2/3]

◆ RooCustomizer() [3/3]

Member Function Documentation

◆ build() [1/2]

◆ build() [2/2]

◆ cloneBranchList()

◆ cloneLeafList()

◆ doBuild()

◆ initialize()

◆ pdf()

◆ printArgs()

◆ printMultiline()

◆ replaceArg()

◆ setCloneBranchSet()

◆ setOwning()

◆ splitArg()

◆ splitArgs()

Member Data Documentation

◆ _cloneBranchList

◆ _cloneNodeListAll

◆ _cloneNodeListOwned

◆ _internalCloneBranchList

◆ _masterBranchList

◆ _masterCat

◆ _masterLeafList

◆ _masterPdf

◆ _name

◆ _owning

◆ _replaceArgList

◆ _replaceSubList

◆ _splitArgList

◆ _splitCatList

◆ _sterile