Class RooSimWSTool is a tool operating on RooWorkspace objects that
can clone p.d.f.s into a series of variations that are joined together
into a RooSimultanous p.d.f.
The simplest use case to to take a workspace p.d.f as prototype and
'split' a parameter of that p.d.f into two specialized parameters
depending on a category in the dataset.
For example, given a Gaussian
p.d.f G(x,m,s) we want to construct a G_a(x,m_a,s) and a G_b(x,m_b,s)
with different mean parameters to be fit to a dataset with observables
(x,c) where c is a category with states 'a' and 'b'
Using RooSimWSTool one can create a simultaneous p.d.f from G_a and G_b
from G with the following command
RooSimWSTool wst(wspace) ;
wst.build("G_sim","G",SplitParam("m","c")) ;
From this simple example one can go to builds of arbitrary complexity
by specifying multiple SplitParam arguments on multiple parameters
involving multiple splitting categories. Splits can also be performed
in the product multiple categories, e.g.
SplitParam("m","c,d")) ;
splits parameter m in the product of states of c and d. Another possibility
is the 'constrained' split which clones the parameter for all but one state
and insert a formula specialization in a chosen state that evaluates
to 1 - sum_i(a_i) where a_i are all other specializations. For example,
given a category c with state "A","B","C","D" the specification
SplitParamConstrained("m","c","D")
will result in parameters m_A,m_B,m_C and a formula expression m_D
that evaluates to (1-(m_A+m_B+m_C)). Constrained split can also be
specified in product of categories. In that case the name of the
remainder state follows the syntax "{State1;State2}" where State1 and
State2 are the state names of the two spitting categories.
The examples so far deal with a single prototype p.d.f. It is also
possible to build with multiple prototype p.d.fs by specifying a
mapping between the prototype to use and the names of states of
a 'master' splitting category. To specify these configurations
an intermediate MultiBuildConfig must be composed with all
the necessary specifications. For example, this code
RooSimWSTool::MultiBuildConfig mbc("mc") ;
mbc.addPdf("I","G",SplitParam("m,s","c")) ;
mbc.addPdf("II,III","F",SplitParam("a","c,d")) ;
configures a build with two prototype p.d.f.s G and F.
Prototype G is used for state "I" of master split category
mc and prototype F is used for states "II" and "III" of
master split category mc. Furthermore parameters m,s of prototype G are split
in category c while parameter a of prototype F is split in
the product of categories c and d. The actual build is then
performed by passing the build configuration to RooSimWSTool, e.g.
wst.build("MASTER",mbc) ;
By default, a specialization is built for each permutation of
states of the spitting categories that are used. It is possible
to restrict the building of specialized p.d.f to a subset of states
by adding a restriction on the number of states to build as follows
mbc.restrictBuild("c","A,B") ;
The restrictBuild method can be called multiple times, but at most
once for each used splitting category. For simple builds with a single
prototype, restriction can be specified with a Restrict() argument
on the build command line
