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 occurence 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 splitLeafs;
RooCustomizer cust(pdf,runblock,splitLeafs);
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, leafs may be split by any subset of that master category. E.g. if the master category is 'A x B', leafs 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 (splitLeafs 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 leafs in leaf list. These leafs must have the name <split_leaf>_<splitcat_label> to be picked up. The list of pre-supplied leafs may be partial, any missing split leafs 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 leafs, 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 leafs instantiated by the first customizer and the link between the two PDFs is retained.

Customising with pre-defined leafs

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 customisedLeafs;
RooArgSet allLeafs;
 
RooRealVar mass("M", "M", 1, 0, 12000);
RooFormulaVar yield1("yieldSig_BBG1m2T","sigy1","M/3.360779",mass);
RooFormulaVar yield2("yieldSig_BBG2m2T","sigy2","M/2",mass);
allLeafs.add(yield1);
allLeafs.add(yield2);
 
 
RooCustomizer cust(model, sample, customisedLeafs, &allLeafs);
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.

	~RooCustomizer ()
	Destructor.

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 occurence 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
	Pointer to list of cloned branches used.

RooArgSet *	_cloneNodeListAll
	List of all cloned nodes.

RooArgSet *	_cloneNodeListOwned
	List of owned cloned nodes.

RooArgSet	_internalCloneBranchList
	List of branches of internal clone.

RooArgSet	_masterBranchList
	List of branch nodes.

RooAbsCategoryLValue *	_masterCat
	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 &	splitLeafs,
		RooArgSet *	splitLeafsAll = `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]	splitLeafs	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 customisedLeafs;

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

customisedLeafs.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:424

Parameters

[in,out] splitLeafsAll All leafs 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 226 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 250 of file RooCustomizer.cxx.

◆ ~RooCustomizer()

RooCustomizer::~RooCustomizer ( )

Destructor.

Definition at line 284 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 366 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 402 of file RooCustomizer.cxx.

◆ cloneBranchList()

const RooArgSet & RooCustomizer::cloneBranchList ( ) const

inline

Return list of cloned branch nodes.

Definition at line 56 of file RooCustomizer.h.

◆ cloneLeafList()

const RooArgSet & RooCustomizer::cloneLeafList ( ) const

inline

Return list of cloned leaf nodes.

Definition at line 60 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 425 of file RooCustomizer.cxx.

◆ initialize()

void RooCustomizer::initialize ( )

protected

Initialize the customizer.

Definition at line 273 of file RooCustomizer.cxx.

◆ pdf()

RooAbsPdf const & RooCustomizer::pdf ( ) const

Definition at line 665 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 615 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 629 of file RooCustomizer.cxx.

◆ replaceArg()

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

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

Definition at line 346 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 658 of file RooCustomizer.cxx.

◆ setOwning()

void RooCustomizer::setOwning ( bool flag )

inline

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

Definition at line 45 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 323 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 300 of file RooCustomizer.cxx.

Member Data Documentation

◆ _cloneBranchList

RooArgSet* RooCustomizer::_cloneBranchList

protected

Pointer to list of cloned branches used.

Definition at line 98 of file RooCustomizer.h.

◆ _cloneNodeListAll

RooArgSet* RooCustomizer::_cloneNodeListAll

protected

List of all cloned nodes.

Definition at line 101 of file RooCustomizer.h.

◆ _cloneNodeListOwned

RooArgSet* RooCustomizer::_cloneNodeListOwned

protected

List of owned cloned nodes.

Definition at line 102 of file RooCustomizer.h.

◆ _internalCloneBranchList

RooArgSet RooCustomizer::_internalCloneBranchList

protected

List of branches of internal clone.

Definition at line 97 of file RooCustomizer.h.

◆ _masterBranchList

RooArgSet RooCustomizer::_masterBranchList

protected

List of branch nodes.

Definition at line 94 of file RooCustomizer.h.

◆ _masterCat

RooAbsCategoryLValue* RooCustomizer::_masterCat

protected

Pointer to input master category.

Definition at line 92 of file RooCustomizer.h.

◆ _masterLeafList

RooArgSet RooCustomizer::_masterLeafList

protected

List of leaf nodes.

Definition at line 95 of file RooCustomizer.h.

◆ _masterPdf

RooAbsArg* RooCustomizer::_masterPdf

protected

Pointer to input p.d.f.

Definition at line 91 of file RooCustomizer.h.

◆ _name

TString RooCustomizer::_name

protected

Name of this object.

Definition at line 82 of file RooCustomizer.h.

◆ _owning

bool RooCustomizer::_owning

protected

If true we own all created components.

Definition at line 81 of file RooCustomizer.h.

◆ _replaceArgList

TList RooCustomizer::_replaceArgList

protected

List of RooAbsArgs to be replaced.

Definition at line 87 of file RooCustomizer.h.

◆ _replaceSubList

TList RooCustomizer::_replaceSubList

protected

List of replacement RooAbsArgs.

Definition at line 88 of file RooCustomizer.h.

◆ _splitArgList

TList RooCustomizer::_splitArgList

protected

List of RooAbsArgs to be split.

Definition at line 84 of file RooCustomizer.h.

◆ _splitCatList

TList RooCustomizer::_splitCatList

protected

List of categories to be used for above splits.

Definition at line 85 of file RooCustomizer.h.

◆ _sterile

bool RooCustomizer::_sterile

protected

If true we do not have as associated master category.

Definition at line 80 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 leafs

Public Member Functions

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

◆ RooCustomizer() [1/3]

◆ RooCustomizer() [2/3]

◆ ~RooCustomizer()

◆ 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