-
Notifications
You must be signed in to change notification settings - Fork 184
/
Copy pathindex.html
188 lines (186 loc) · 15.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
<!-- HTML header for doxygen 1.8.6-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<title>CombineHarvester: Introduction</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function() { init_search(); });
/* @license-end */
</script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
extensions: ["tex2jax.js"],
jax: ["input/TeX","output/HTML-CSS"],
});
</script>
<script type="text/javascript" async="async" src="http://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="customdoxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 70px;">
<td style="padding-left: 0.5em;">
<div id="projectname">CombineHarvester
</div>
</td>
<td> <div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.svg"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
alt=""/>
<input type="text" id="MSearchField" value="Search" accesskey="S"
onfocus="searchBox.OnSearchFieldFocus(true)"
onblur="searchBox.OnSearchFieldFocus(false)"
onkeyup="searchBox.OnSearchFieldChange(event)"/>
</span><span class="right">
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('index.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Introduction </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#getting-started">Getting started</a></li>
<li class="level1"><a href="#high-level-tools">High-level tools</a></li>
<li class="level1"><a href="#note">Other comments</a></li>
</ul>
</div>
<div class="textblock"><p><a class="anchor" id="mainpage"></a></p>
<p>This page documents the CombineHarvester framework for the production and analysis of datacards for use with the CMS <a href="https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit">combine</a> tool. The central part of this framework is the <a class="el" href="classch_1_1_combine_harvester.html">CombineHarvester</a> class, which provides a representation of the text-format datacards and the associated shape input.</p>
<p>The production of new datacards typically requires several steps, for example:</p>
<ul>
<li>Defining analysis categories, signal and background processes</li>
<li>Adding systematic uncertainties</li>
<li>Extracting the related shape inputs from ROOT files</li>
<li>Modifying this information in-place, e.g. scaling signal processes to different cross sections, switching processes from background to signal and <em>vice versa</em></li>
<li>Applying bin error merging and creating bin-by-bin uncertainties</li>
<li>Pruning the set of bin-by-bin nuisance parameters</li>
<li>Exporting to the text datacard format and creating the associated ROOT shape files</li>
</ul>
<p>All of these operations are performed either directly by methods of the CombineHarvester class, or by using higher-level helper functions (see <a class="el" href="index.html#high-level-tools">High-level tools</a> below). By design all of the input required for these steps can be specified directly in the code. This makes it possible to quickly build a datacard in a single, self-contained file, without the use of any external scripts or configuration files.</p>
<p>Other functions include extracting information about the fit model:</p>
<ul>
<li>Evaluating the expected rates of signal and background processes, both pre- and post-fit, and for the latter taking into account the nuisance parameter correlations</li>
<li>Similar evaluation of the background shapes, including the ability to scale, modify and re-bin the shapes in-place</li>
</ul>
<p>As well as histogram-based templates, the production of datacards with arbitrary RooFit PDFs and datasets is also supported.</p>
<h1><a class="anchor" id="getting-started"></a>
Getting started</h1>
<p>This repository is a "top-level" CMSSW package, i.e. it should be located at <code>$CMSSW_BASE/src/CombineHarvester</code>. It currently provides two sub-packages:</p>
<ul>
<li><b>CombineHarvester/CombineTools</b>, which contains the CombineHarvester class and other parts of the core framework</li>
<li><b>CombineHarvester/CombinePdfs</b>, which provides tools for building custom RooFit pdfs</li>
</ul>
<p>The CMSSW version that should be used with CombineHarvester is driven by the recommendation for the HiggsAnalysis/CombinedLimit package, which is also required. The latest instructions can be found <a href="https://cms-analysis.github.io/HiggsAnalysis-CombinedLimit/#setting-up-the-environment-and-installation">here</a>. The CombineHarvester framework is compatible with the CMSSW 14_1_X and 11_3_X series releases. A new release area can be set up and compiled in the following steps: </p><pre class="fragment">cmsrel CMSSW_14_1_0_pre4
cd CMSSW_14_1_0_pre4/src
cmsenv
git clone https://github.com/cms-analysis/HiggsAnalysis-CombinedLimit.git HiggsAnalysis/CombinedLimit
# IMPORTANT: Checkout the recommended tag on the link above
git clone https://github.com/cms-analysis/CombineHarvester.git CombineHarvester
git checkout v3.0.0-pre1
scram b
</pre><p> If you are using this framework for the first time we recommend taking a look through some of the examples below which demonstrate the main features:</p>
<ul>
<li><a class="el" href="intro1.html">Examples Part 1</a>: How CombineHarvester builds a datacard representation, parsing existing datacards, evaluating contents</li>
<li><a class="el" href="intro2.html">Examples Part 2</a>: Creating a new datacard, defining processes and systematics, writing text datacards</li>
<li><a class="el" href="intro3.html">Examples Part 3</a>: Creating a counting-experiment datacard and using rateParam directives to float process yields via free parameters while express other yields as functions of these parameters.</li>
<li><a class="el" href="limits.html">Limit setting</a>: Using the <code>combineTool.py</code> script to build workspaces, compute asymptotic limits and plot the ouput.</li>
</ul>
<dl class="section warning"><dt>Warning</dt><dd>To run many of these examples you must first ensure the <a href="https://github.com/roger-wolf/HiggsAnalysis-HiggsToTauTau-auxiliaries">auxiliaries</a> repository is located at <code>$CMSSW_BASE/src/auxiliaries</code> and up-to-date: <pre class="fragment">git clone https://github.com/roger-wolf/HiggsAnalysis-HiggsToTauTau-auxiliaries.git auxiliaries </pre> The input root files will be sourced from here.</dd></dl>
<p>More realistic, though less well documented, examples can be found in the following files:</p><ul>
<li><code><a class="el" href="_post_fit_shapes_from_workspace_8cpp.html">CombineTools/bin/PostFitShapesFromWorkspace.cpp</a></code> (<a class="el" href="_post_fit_shapes_from_workspace_8cpp.html">source code</a>) - see separate page <a class="el" href="post-fit-shapes-ws.html">here</a></li>
<li><code><a class="el" href="_s_m_legacy_example_8cpp.html">CombineTools/bin/SMLegacyExample.cpp</a></code> (<a class="el" href="_s_m_legacy_example_8cpp.html">source code</a>) - produces a complete set of htt datacards for the legacy Run I SM analysis (HIG-13-004). The same workflow is also possible in python, see <code>CombineTools/scripts/SMLegacyExample.py</code></li>
<li><code><a class="el" href="_m_s_s_m_yield_table_8cpp.html">CombineTools/bin/MSSMYieldTable.cpp</a></code> (<a class="el" href="_m_s_s_m_yield_table_8cpp.html">source code</a>) - produces the latex yield tables for the MSSM htt analysis (HIG-13-021). Run via the script <code>CombineTools/scripts/yield_tables_mssm_example.sh</code>. You will first need to copy the input datacards: <code>cd CombineTools; cp -r /afs/cern.ch/work/a/agilbert/public/CombineTools/data/mssm-paper-cmb ./input/</code></li>
</ul>
<h1><a class="anchor" id="high-level-tools"></a>
High-level tools</h1>
<p>A number of high-level tools have been developed to provide a more convenient interface for some common CombineHarvester tasks:</p>
<ul>
<li><a class="el" href="classch_1_1_card_writer.html" title="Automates the writing of datacards into directory structures.">ch::CardWriter</a>: In a nutshell, calls <code>CombineHarvester::WriteDatacard</code> so you don't have to. It can be used to write a set of datacards into the familiar <b>LIMITS</b> directory structure, or any other structure based on simple pattern strings.</li>
<li><a class="el" href="classch_1_1_bin_by_bin_factory.html" title="Merges bin uncertainties and creates bin-by-bin statistical uncertainties.">ch::BinByBinFactory</a>: Does the merging of bin uncertainties within a category and creates bin-by-bin shape systematics</li>
<li><a class="el" href="_copy_tools_8h.html">CopyTools.h</a>: Provides functions like <a class="el" href="namespacech.html#a27eee114b589ec9869ea3d34863e41fe" title="Duplicate the Process and Systematic objects in one instance, which are then modified by a user-suppl...">ch::CloneProcsAndSysts</a> and <a class="el" href="namespacech.html#a0f62630d67d75c1b6143c0519da2a720" title="Replace all instances of an existing systematic with two copies having modified values.">ch::SplitSyst</a> for duplicating existing processes and systematics</li>
<li><a class="el" href="namespacech.html#a5ae8a88e9e0d2120deec06e553a525f6">ch::ParseCombineWorkspace</a>: A function that can populate a CombineHarvester instance directly from a <code>combine</code> workspace. May be useful for extracting post-fit yields and shapes for more complex physics models. Should be considered experimental at the moment.</li>
</ul>
<h1><a class="anchor" id="note"></a>
Other comments</h1>
<p><b>Creating a new package</b>: It is planned that each new analysis will create their own package within the <code>CombineHarvester</code> directory, where all the datacard creation, plotting and other tools specific to the analysis will be stored. This keeps the analysis-specific code self-contained, and ensures different analyses do not disrupt each other's workflow during the development phase. We expect that some tools or functions developed for specific analyses will be of more general use, in which case they will be promoted to the common <code>CombineTools</code> package. <b>Please raise an issue <a href="https://github.com/cms-analysis/CombineHarvester/issues/new">here</a> if you would like a new package to be created for your analysis.</b></p>
<p><b>Code developments</b>: New features and developments, or even just suggestions, are always welcome - either contact the developers directly or make a pull request.</p>
<p><b>Python interface</b>: A python interface is also available - see the documentation page <a class="el" href="python-interface.html">here</a> for usage instructions. This is ultimately just a wrapper around the C++ code and most functions can be called in python in exactly the same way as their C++ counterparts. There are some functions however, especially those using template arguments, which have been adapted for python usage and may not provide exactly the same interface. Furthermore, as each C++ function has to be wrapped by hand, the python interface may occasionally lag behind the C++ one.</p>
<p><b>Error handling</b>: It is quite possible to do things in a CombineHarvester instance that don't make sense, or at least don't allow for the production of a valid datacard - for example objects with missing shape information, negative process yields and categories without either observed data or background processes. The framework has been designed to detect many of these issues at the point in which they become a problem for a given function to proceed as intended. However there is no guarantee that all such issues will be detected. If a problem is encountered, a runtime exception will be thrown indicated the nature of the problem, for example, trying to extract a histogram missing from the input root file will produce this message: </p><pre class="fragment">terminate called after throwing an instance of 'std::runtime_error'
what():
*******************************************************************************
Context: Function ch::GetClonedTH1 at
CombineHarvester/CombineTools/src/TFileIO.cc:21
Problem: TH1 eleTau_0jet_medium/ggH not found in CMSSW_7_1_5/src/auxiliaries/shapes/htt_et.inputs-sm-7TeV-hcg.root
*******************************************************************************
</pre><p> If the cause of such an error message is unclear, or if you believe the error message should not have been produced, please raise an issue here with full details on reproducing the problem: <a href="https://github.com/cms-analysis/CombineHarvester/issues/new">https://github.com/cms-analysis/CombineHarvester/issues/new</a></p>
<p>Please also raise an issue if you encounter any bugs, unintended behaviour, abrupt errors or segmentation faults - these will be addressed promptly by the developers. </p>
</div></div><!-- PageDoc -->
</div><!-- contents -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.6-->
<!-- start footer part -->
</body>
</html>