Configuration of statistical models

The BlueIceExtendedModel can be fully initialized using a YAML configuration file. In the following, we’ll walk you through the basic structure and how to set up your own model.

The file consists of two parts: The definition of all parameters of the model (parameter_definition) and the likelihood configuration (likelihood_config). This means, the basic structure will look something like this:

parameter_definition:
  parameter_name_1:
    property_1: value_1
    property_2: value_2
    # ... more properties
  parameter_name_2:
    # ... definition missing
  # ... more parameters
likelihood_config:
  template_folder: null
  likelihood_terms:
  - name: term_1
    # ... some technical things missing here
    sources:
    - name: source_1
      # ... some things missing here
      parameters:
        - parameter_name_1
      template_filename: template_1.h5
    - name: source_2
      # ... source definition missing
    # ... more sources
  # ... more likelihood terms

Let’s have a closer look at the two parts.

Parameter definition

The parameter_definition section is a dictionary of all parameters of the model. Each parameter is defined by a name and a dictionary of properties. You can specify any property, which is an attribute in the Parameter class. One exception is the name attribute, which is determined by the key in the dictionary. An overview with some examples is provided in the table below.

Property Definitions
Property Name	Format	Description
`nominal_value`	float, optional	The nominal value of the parameter.
`fittable`	bool, optional	Indicates if the parameter is fittable or always fixed.
`ptype`	str, optional	The ptype of the parameter.
`uncertainty`	float or str, optional	The uncertainty of the parameter. If a string, it can be evaluated as a numpy or scipy function to define non-gaussian constraints.
`relative_uncertainty`	bool, optional	Indicates if the uncertainty is relative to the nominal_value.
`blueice_anchors`	list, optional	Anchors for blueice template morphing. Blueice will load the template for the provided values and then interpolate for any value in between.
`fit_limits`	Tuple[float, float], optional	The limits for fitting the parameter.
`parameter_interval_bounds`	Tuple[float, float], optional	Limits for computing confidence intervals.
`fit_guess`	float, optional	The initial guess for fitting the parameter.
`description`	str, optional	A description of the parameter. This is a long description that may span multiple lines in the table cell.

For the BlueIceExtendedModel, the ptype can be used to optimize performance. The following options are available:

'rate': The parameter is a rate parameter. This means it linearly scales the expectation value of a source in the model.

'livetime': The parameter is a livetime parameter. Similarly to a rate parameter it linearly scales expectation values, however, it does so for the entire likelihood term it is connected to. Also, in contrast to a rate multiplier, it is almost never a fittable parameter.

'shape': The parameter is a shape parameter. For blueice likelihoods this means that it is a template morphing parameter. For this, a template is provided at at least two blueice_anchor values and the template is interpolated for any value in between.

'efficiency': The parameter is an efficiency parameter. This means that it scales the expectation value of a source in the model for a given livetime and rate parameter.

Likelihood configuration

The likelihood configuration defines individual terms of a summed likelihood. Each term is defined as a list of sources (background and signal). Importantly, the parameters are linked to the sources and likelihood terms here. Also, the template files are specified.

In addition to the likelihood terms in the list, an ancillary likelihood term will be added automatically to the summed likelihood. It contains all the constraint terms of nuisance parameters, which are defined via the uncertainty property in the parameter definition.