TSModelBuilder The TSModelBuilder class allows to create a complete definition of a statistical model to be passed to the TSModelFactory class to run HistFactory. The specifics of the model to be created have to be provided as configuration data by means of a TQFolder structure. A model is represented by the root instance of a TQFolder structure holding detailed definitions of channels, samples, systematic uncertainties as well as the corresponding histograms. Creation of a model by the TSModelBuilder class is split into two different steps: the preparation step and the finalization step. The finalization step involves retrieving histograms and counter representing signal and background expectations as well as data observations from a sample folders (instances of TQSampleFolder) either stored in external files or made available as memory resident object. Furthermore, it involves the analysis of variations corresponding to systematic uncertainties and their proper treatment. The configuration has to be provided as the following structure: Samples/ A folder listing all samples to be used in the model (entries starting with a dot "." are ignored) {sample/} [one folder for each sample] <Path> Default path to the corresponding sample (with respect to the base sample folder), e.g. "sig/em/mh125/ggf". Placeholders (e.g. "$(mass)") can be used and will be replaced using tags from configuration of corresponding channel and from Parameter block. <Type> [optional] The type of the corresponding sample, e.g. "S" for signal, "B" for background, and "D" for data <ActivateStatError> [optional, default as in TSModelFactory (false)] <StatErrorHisto> [optional] <NormalizeByTheory> [optional, default as in TSModelFactory (true)] {additional-items/} [one folder for each additional items] <AppliesToChannels> String filter to be passed by name of channel in order to copy corresponding item to final instance of sample Channels/ A folder listing all channels (regions) to be used in the model (entries starting with a dot "." are ignored) {channel/} [one folder for each channel/region] <Histogram> Name of histogram to be used for corresponding channel, e.g. "CutTopoDPhill_0jet/MT". <Counter> Name of counter to be used for corresponding channel, e.g. "CutTopoDPhill_0jet" (counter will be converted to 1-bin histogram) <StatRelErrorThreshold> <StatConstraintType> <RemapXTo> Number of bins to remap X axis of histogram to (histogram is remapped such that histogram obtained from <PathRemapFlat> is approximately flat). <RemapYTo> Number of bins to remap Y axis of histogram to (histogram is remapped such that histogram obtained from <PathRemapFlat> is approximately flat). Please note: remapping both X and Y axes simultaneously is not supported. <PathRemapFlat> Path to histogram to become approximately flat by remapping <RemapSlices> Controls whether when remapping a 2D histogram each bin of the dimension NOT subject to the remapping is remapped individually (<RemapSlices> == true) or only the full projection (<RemapSlices> == false). This option is true by default <convertTo1D> Definition of conversion ("unfolding", "unrolling") of a 2D histogram to a 1D histogram. <HistogramOptions> ***** For documentation of the following options please refer to the documentation of TQSampleDataReader::getHistogram(...) ***** <cutBinLowX> Removing bins from histograms <cutBinHighX> /... <cutBinLowY> /... <cutBinHighY> /... <cutBinLow> /... <cutBinHigh> /... <zoomBinLowX> Zooming into histograms <zoomBinHighX> /... <zoomBinLowY> /... <zoomBinHighY> /... <zoomBinLow> /... <zoomBinHigh> /... <projXBinLowY> Projecting 2D histograms onto one if its axes <projXBinHighY> /... <projXBinY> /... <projX> /... <projYBinLowX> /... <projYBinHighX> /... <projYBinX> /... <projY> /... <rebinX> Rebinning histograms <rebin> /... <rebinY> /... <rebinZ> /... <scale> Scaling the histogram <verbosity> Temporarily setting the verbosity mode of the TQSampleDataReader class <applyPoissonErrors> Set bin errors of histogram to sqrt(bin contents) <forSample.<sample>.XXX> Variations/ A folder listing all (systematic) variations to be used in the model (entries starting with a dot "." are ignored) {variation/} [one folder for each (systematic) variation] <SampleFolder> Location of the sample folder of the corresponding variation, e.g. "samples.root:samples_Nominal". Please note: there at least needs to be a "Nominal" folder Systematics/ A folder listing all sources of systematic uncertainties to be used in the model (entries starting with a dot "." are ignored) {systematic/} [one folder for each source of systematic uncertainty] <Up> Name of UP variation corresponding to systematic uncertainty (must be listed in Variations/ folder) <Down> Name of DOWN variation corresponding to systematic uncertainty (must be listed in Variations/ folder) <IsOverallSys> Selects if systematic uncertainty is treated as a normalization systematic ('OverallSys') <IsHistoSys> Selects if systematic uncertainty is treated as a shape systematic ('HistoSys'). Please note: the normalization component is factorized and removed for 'HistoSys' <Include> String filter tested for each combination of channel (region) and sample (in the form "<channel>:<sample>") which has to be pass in order that the corresponding systematic uncertainty is considered for this combination of channel/sample <Exclude> String filter tested for each combination of channel (region) and sample (in the form "<channel>:<sample>") which must NOT be pass in order that the corresponding systematic uncertainty is considered for this combination of channel/sample (if a combination passes both the inclusion and the exclusion filter it is excluded) <InterpCode> Interpolation code to be used by HistFactory <OverallSysMagnification> Factor to artificially magnify the normalization response of the systematic uncertainty <HistoSysMagnification> Factor to artificially magnify the shape response of the systematic uncertainty <Magnification> Factor passed as default to <OverallSysMagnification> and <HistoSysMagnification> Parameters <Name> <Title> <OutputFilePrefix> <ExportOnly> <POI> Name of the Parameter Of Interest (POI) <Lumi> Luminosity scale factor <LumiRelErr> Relative luminosity uncertainty <SysRelThreshold> Minimum relative variation to be exceeded by a systematic variation in order to be considered <SysRelMin> Minimum relative variation to be exceeded by a systematic variation in order to not be ignored <SysRelCutoff> Maximum relative variation a systematic variation must not exceed in order to be considered <SysRelCap> The maximum relative variation a systematic variation. If the maximum is exceeded, the relative variation is set to this maximum <MinBinContent> The minimum bin content of histograms of each process (except Data histograms). If the bin content is lower than this minimum it is set to the minimum The model built by the TSModelBuilder class uses the convention that each element available in HistFactory (e.g. a "Sample", a "Channel", a "NormFactor) is represented by a corresponding instance of TQFolder whose name prefix indicates the type of element followed by the name of the element (e.g. "Sample.ttbar"). Properties of an element are stored as tags on the corresponding folders and sub-elements are represented by sub folders. Available elements and their properties are: - Channel ("Channel.name/"); - <StatRelErrorThreshold> - <StatConstraintType> - Sample ("Sample.name/"); - <Histo> - <.HistogramFile> - <.HistogramPathPrefix> - <NormalizeByTheory> - <ActivateStatError> - <StatErrorHisto> - NormFactor ("NormFactor.name/"); - <Val> - <Low> - <High> - <Const> - OverallSys ("OverallSys.name/"); - <High> - <Low> - HistoSys ("HistoSys.name/"); - <HistoHigh> - <HistoLow> - <.HistogramFile> - <.HistogramPathPrefix> It will have to following structure: {Channel.*/} [one folder for each channel] {Sample.*/} [one folder for each sample in channel] .Configuration/ The model configuration folder after the model building process which includes additional information (e.g. bin boundaries from remapping) .Configuration.PreBuild/ A copy of the model configuration folder BEFORE the model building process .Histograms/ All histograms used in the model building process (including those created from counter on-the-fly) are stored here (this is also the folder written to a ROOT file to let HistFactory grab the histograms from). A model created by the TSModelBuilder class is interfaced by the TSModelFactory class to HistFactory.
| virtual Bool_t | CheckTObjectHashConsistency() const |
| Inheritance Chart: | |||||||||||||
|
Creates the basic channel definitions of a model from configuration <config> and returns true in case of success or false in case of failure.
Creates the basic channel definitions of a model from configuration <config> and returns true in case of success or false in case of failure.
Finalizes the model <model> based on the configuration <config> by collecting all histograms, including systematic uncertainties inferred from variations of input histograms, and returns true in case of success or false otherwise.
Builds a model from configuration <config> and returns a pointer to the corresponding instance of TQFolder representing the model or a NULL pointer in case of failure
remove a variation from a model
collect all histograms from the sample folder and store them in the model
name of channel
name of channel
merge bins of a histogram such that no histogram has contributions below mergeBins.minimalBinContent (default: 0), and the stack has no bin below mergeBins.minimalSummedBinContent (default: 1)
collect all histograms from the sample folder