OpTHyLiC

Optimized Tool for Hybrid Limits Computation


Introduction

OpTHyLiC is a software tool computing observed and expected upper limits on poissonian process rates using a hybrid frequentist-bayesian CLs method. This tool can be used for simple counting experiments where only signal, background and observed yields are provided or for multi-bin experiments where binned distributions of discriminating variables are provided. It is simple, light, and fast. Even in realistic cases with dozens of nuisance parameters and several channels, limits are typically computed in less than one minute. It can be used with an arbitrary number of channels and backgrounds. It takes into account statistical and systematic uncertainties, as well as correlations of systematic uncertainties across samples and channels.

OpTHyLiC can be downloaded below. On this page can also be found the documentation of this software together with its prerequisites and with basic intructions for installation and usage, as well as informations about its developpers and its licence.


Download

The tarball containing the latest version of OpTHyLiC can be downloaded from this link.
The latest version is v2.04.

Documentation

A detailed documentation of OpTHyLiC and of the statistical method it relies on is published in Computer Physics Communications:
E. Busato, D. Calvet, and T. Theveneaux-Pelzer, OpTHyLiC: an Optimised Tool for Hybrid Limits Computation, arXiv:1502.02610 [hep-ex], Computer Physics Communications 226 (2018) 136-150.
The authors would be thankfull to the OpTHyLiC users for citing this paper whenever this software is used for a study reported in a public document.

Details of the usage of the code can be found in the online documentation.


Prerequisites

To use OpTHyLiC, a version of the ROOT software is needed. Versions as old as 5.28/00b have been tested, but older ones may also be ok.

OpTHyLiC can be run with ROOT macros, but executables can also be compiled. In that case, the gcc compiler is needed. Versions as old as 4.3.0 have been tested, but older ones may also be ok. To use a different compiler, one would have to modify the INSTALL script mentioned below.

If the features involving the C++11 standard are to be used, gcc 4.8.2 or newer is needed for creating executables. For running OpTHyLiC with ROOT macros with these C++11 features, ROOT 6.02/03 or newer is required.

More details can be found in Section 4.1 of the documentation.


Installation and usage

To install OpTHyLiC, the tarball containing the source code must be downloaded from the link given above. The tarball must be extracted in some directory: Then, the installation is done in three steps: In the first step, the compilation is prepared by creating a Makefile which structure depends on how OpTHyLiC is intended to be used. Several options can be parsed to the INSTALL script in order to configure the installation. Without any option, the INSTALL script prepares for the use of OpTHyLiC with ROOT macros, without the C++11 features. The available options can be listed by using the --help (or -h) option. Details on the configuration are given in Section 4.2 of the documentation.

In the second step, the shared libraries are compiled according to the Makefile.

Finally, the script sourced in the last step updates the LD_LIBRARY_PATH environment variable with the directory where the shared libraries are available.

Once installed, the libraries can be used from anywhere after having sourced the setup.[c]sh script. The example script runLimits.C, available in the examples/ directory, illustrates the computation of limits. It can be used with the following syntax: Several methods allow to compute limits, print tables of yields of processes with their uncertainties, or to plot various distributions. The syntax of these methods and details on the structure of the input files are described in the online documentation.

About

OpTHyLiC has been developed by Emmanuel Busato, David Calvet and Timothée Theveneaux-Pelzer, from the ATLAS team at the LPC Clermont-Ferrand. Questions and suggestions may be sent to the following e-mail address:
opthylicSPAMNOTin2p3.fr

This software is distributed under the GNU General Public Licence version 3 (GPLv3). More informations can be found in the GPL webpage. Logo GPLv3


They use OpTHyLiC

Several uses of OpTHyLiC are referenced here. If you use OpTHyLiC, please let us know and we will add your document to the list.


Last change: 2018-03-29

Valid HTML 4.01 Transitional CSS Valide !