Package: fast-datacard
fast-datacardFree software: Apache Software License 2.0Documentation:https://fast-datacard.readthedocs.io.Overviewfast-datacard is a python packaged developed within theFaster Analysis Software Taskforce (FAST)collaboration.
The main purpose of this package is to createdatacardscompatible with theHiggsCombine toolfrom data frames.
The package will take categoricalcitation neededdata frames, e.g. as created by thealphatwirlpackage, and create
the necessary ROOT and datacard outputs.Featuresconvert categorical data frames (seeexamples/data/*.csv) into valid data to use in theHiggsCombine tool.UsageThe usage is the following::fast_datacard <yaml_config_file>An exampleyamlconfig file is available:examples/datacards_config.yaml. The config file lists all the input event categories, regions, physics processes, dataframes, etc. A few things should be noted:The existence of thegeneral,regions,signals,backgroundsandsystematicsblocks is mandatory.analysis_name,version, anddatasetare just used for versioning.The value ofluminosity(float, in fb-1) is used to weight the signal and backgroundscontentanderrorto the expected luminosity.For each signal and background process namedX, there should be a file in thepath_to_dfsdirectory namedX.csv(a whitespace-separated Pandas dataframe).data_names_dfshould be equal to theprocessname used for data in the dataframe (Datain the example config file) and also should be the name of the.csvdataframe inpath_to_dfs.data_names_dcwill the name of the output data histogram and should be equal todata_obsas imposed by theHiggsCombine tool.There has to be at least one signal and one background.Backgrounds (but not signals, see below) can live only in specific region(s) (see example config file).The systematics listed in thesystematicsblock can have three types:lnN,lnU, andshape. The first two are normalization uncertainties and a value should be provided that corresponds to 1 + X, where X is the uncertainty one sigma level in percent (see example config file). For theshapetype, no value is required as the shape itself encodes the uncertainty level. There is no need to specify Up/Down in the name of the uncertainty as this will be derived from the input dataframe (see below).The systematics can apply only to a given set of signals and/or backgrounds, in which case the name of the process (identical to the one in the dataframe) should be specified. If the systematic applies to all backgrounds,backgroundscan be used instead of listing all the background processes (and the same is true forsignals).The configuration for running is also partly derived from the input dataframes, which formats should therefore follow a few rules:The columns should be named:process region category systematic variable variable_low variable_high content errorWhere:processis the name of the physics process, e.g.VBF,Ewk, etc.regionis the name of the region, e.g.Signal,ControlRegion1, etc.categoryis the name of the event category, e.g.2jet,highMass, etc. Each unique name will be considered as a different category.systematicis the name of systematic shape variation that is applied to obtain thecontentof this row. E.g. if a process is characterized by two shape systematic uncertainties namedsyst1andsyst2, then the dataframe should contain 5 variations:nominal,syst1_Up,syst1_Down,syst2_Up,syst2_Downfor each bin where this process exists.variableis the name of variable that defines the x-values in the output histograms. It is not used by the code but is mainly there to keep track of the fit variables in different categories.variable_lowandvariable_highdefine the binning along x in the output histograms used for the fit. Each unique set of (variable_low,variable_high) will be considered as a unique bin.contentis the yield for this specific (process,region,category,systematic,variable,variable_low,variable_high) bin.erroris the error assigned to the yield (please note it is not the square of the error! therefore for a Poisson experiment it should be sqrt(N).)The use ofregionorcategoryis optional in the sense that an analysis might contain only one region and one category; in this case, the value of each column needs to be filled by the same value for all rows.The signal(s) process(es) should be defined in all categories and regions, even if thecontentis 0. In other words, if you’re looking for an exotics signal namedbananas, the code assumes it will find a row withbananas‘scontentforeachbin of the analysis (i.e. the code never makes the assumption that the signal cannot live in the control regions as well).Thedatashould be defined in all categories and regions, even if thecontentis 0. If data is not defined somewhere, the category/region shouldn’t even exist in the analysis.The package will produce two sets of outputs:Text datacards that summarize the physics processes, the yields, and meta-information about the analysis.ROOT datacards that contain histrograms describing shapes that will be used in the fit.Both serve as inputs to theHiggsCombine tool.CreditsThis package was created withCookiecutterand theaudreyr/cookiecutter-pypackageproject template.History0.1.5 (2018-04-29)Fix typo0.1.4 (2018-04-29)Added error message to explain crash0.1.3 (2018-04-05)Easier handling of dataframe files0.1.2 (2018-04-04)Updated executable name and documentation0.1.1 (2018-10-01)added initial documentation0.1.0 (2018-08-21)First release on PyPI.