contur.factories package


contur.factories.likelihood module

This module contains the implementation of the likelihood calculation

Abstracted from the underlying YODA objects, this module defines two ways to construct likelihood functions from numerical types:

  • Likelihood – The base likelihood building blocks, representing the information extracted from an underlying histogram of potentially correlated observables.

  • CombinedLikelihood – A shell to combine Likelihood blocks into a full likelihood, automatically encodes assumption that the included blocks are uncorrelated.

class contur.factories.likelihood.CombinedLikelihood[source]

Bases: contur.factories.likelihood.Likelihood

Shell to combine Likelihood blocks

This class is used to extract the relevant test statistic from each individual Likelihood and combine them This is initialised with no arguments as it is just a shell to combine the individual components, and automatically encodes the fact that each block is uncorrelated with each other


Technically this could be constructued by building a Likelihood with a master covariance matrix made forming block diagonals with each individual component. Avoiding this is faster but less rigourous


Add a Likelihood block to this combination likelihood


likelihood (Likelihood) – Instance of computed Likelihood


Call the calculation of the CLs confidence interval

Triggers the parent class calculation of the CLs interval based on the sum of test statistics added with the add_likelihood() method

class contur.factories.likelihood.Likelihood(bw, nobs, cov, uncov, bg=None, s=None, serr=None, theorycov=None, theoryuncov=None, nuisErrs=None, thErrs=None, ratio=False, profile=False, useTheory=False, lumi=1.0, sxsec=None, bxsec=None, tags='')[source]

Bases: object

Fundamental likelihood-block class and confidence-interval calculator

This class defines the structure of a series of observables to be constructed into a hypothesis test

  • bw – bin widths

  • s (list[float]) – Signal count

  • bg (list[float]) – Background count

  • nobs (list[float]) – Observed count

  • serr (list[float]) – Signal error counts

  • cov (numpy.ndarray) – Covariance matrix for observables

  • uncov (numpy.ndarray) – Covariance matrix for observables assuming no correlation

Keyword Arguments
  • thcov (numpy.ndarray) – Covariance matrix for the background simulation

  • thuncov (numpy.ndarray) – Covariance matrix for the background simulation, assuming no correlation

  • ratio (bool) – Flag if data is derived from a ratio measurement (not general! caveat emptor!)

  • profile (bool) – Flag if data is derived from a profile histogram measurement

  • useTheory (bool) – Flag if background simulation and errors are to be used

  • lumi (float) – the integrated luminosity for the measurement. used to calculate expect stat uncertainty on signal

  • sxsec (float) – Signal cross-section in picobarns, if non-null

  • nuisErrs (dict{numpy.ndarray}) – Dict of component breakdown of cov

  • thErrs (dict{numpy.ndarray}) – Dict of component breakdown of thcov


Currently the execution of the calculation runs on automatically on initialisation, this should be factored have an exposed method that is then called instead

property CLs

CLs hypothesis test value (ratio of p_s_b and p_b)

type (float)

property index

Index of max bin if correlations unused, otherwise returns None

type (int)

property p_b

p-value of b only hypothesis

type (float)

property p_s_b

p-value of s+b hypothesis

type (float)

property pools

Pool that the test belongs to

settable parameter

type (string)


Method to calculate a cls when passed background and signal p values.


pval_tuple (Tuple of floats) – Tuple, first element p-value of signal hypothesis, second p-value of background


CLs float – Confidence Interval in CLs formalism

property subpools

Subpool the test belongs to

settable parameter

type (string)

property tags

Name(s) of source histograms for this block

settable parameter

type (string)

property ts_b

Test statistic of b only hypothesis

type (float)

property ts_s_b

Test statistic of the s+b hypothesis

type (float)


Method to directly cast a list of tuples of test statistics (tuple contains background and signal test stats) into a list of CLs values


ts_tuple_list (list) – list of tuples of tests statistics (tuples of the form (test stat background, test stat background))


CLs list – List of Confidence Intervals in CLs formalism


Method to convert test statistic to log pval


ts (float) – Single or numpy array of test statistics to convert to a p-values with a Gaussian


p-value float

contur.factories.depot module

The Depot module contains the Depot class defining the parent analysis class

This is intended to be the high level analysis control, most user access methods should be implemented at this level

class contur.factories.depot.Depot(noStack=False)[source]

Bases: object

Parent analysis class to initialise

This can be initialised as a blank canvas, then the desired workflow is to add parameter space points to the Depot using the add_point() method. This appends each considered point to the objects internal inbox

Path for writing out objects is determined by contur.config.plot_dir

Keyword Arguments
  • noStack (Bool) – Flag if visual objects should be automatically stacked

add_custom_point(logfile, param_dict)[source]

Function to add a custom file, typically read as a string, to the

add_point(yodafile, param_dict)[source]

Add yoda file and the corresponding parameter point into the depot


Function to build the axis dictionaries used for plotting, parameter space points are otherwise stored unordered

Built variables
  • mapAxis (dict)

  • plotAxis (dict)

export(path, include_dominant_pools=True, include_per_pool_cls=False)[source]
property frame

A pandas.DataFrame representing the CLs interval for each point in inbox

type (pandas.DataFrame)

property inbox

The master list of ParamYodaPoint instances added to the Depot instance

type ( list [ ParamYodaPoint ])

property map_axis

Dictionary of the sampled values in each axis

type (dict) – key – Parameter name (string), value – (numpy.ndarray)


Function to merge one conturDepot instance with another, note matching of parameter point for each item in the target instance is required or the entry will be skipped


depot (contur.conturDepot) – Additional instance to conturDepot to merge with this one

property plot_axis

Dictionary of the offset midpoints in each axis, for colormesh purposes

type (dict) – key – Parameter name (string), value – (numpy.ndarray)


Function to trigger rerunning of the sorting algorithm on all items in the inbox, typically if this list has been affected by a merge by a call to contur.depot.merge()


Function to write out a “map” file containing the full pickle of this depot instance


outDir (string) – String of filesystem location to write out the pickle of this instance to

class contur.factories.depot.ParamYodaPoint(paramPoint, yodaFactory)[source]

Bases: object

Book keeping class relating

  • paramPoint (dict) – key string param name : value float

  • yodaFactory (contur.depot.yoda_factory) – yoda_factory object, conturs YODA file reader

contur.factories.yoda_factories module

The yoda_factories module contains three main components in the middle of the data flow, sitting between the high level steering in contur.factories.Depot class and the lower level statistics in the contur.factories.Likelihood class

class contur.factories.yoda_factories.HistFactory(ana_obj, xsec, nev, aopaths=None)[source]

Bases: object

Processes and decorates YODA.AnalysisObject to a testable format, filling a candidate block by default

  • ana_obj (YODA.AnalysisObject) – YODA AO to dress

  • xsec (YODA.Scatter1D) – _XSEC scatter recording generator cross section in YODA file (contained in all Rivet run outputs)

  • nev (YODA.Scatter1D) – _EVTCOUNT scatter recording total generated events in YODA file (contained in all Rivet run outputs)

Keyword Arguments
  • aopath (list) – List of rivet.AOPath ID’s to load, default empty list loads everything in $RIVET_REF_PATH

property CLs

CLs score derived from this histogram


this duplicates the method defined in ::attr::likelihood

type (float)

property background

Background model, scaled if required

type (YODA.Scatter2D)

property bgplot

Background data for plotting

type (YODA.Scatter2D)

property data_scale

Scale factor applied to the refdata histogram/scatter

type (float)


Public member function to build yoda plot members for interactive runs

property has_theory

Bool representing if a theory prediction was found for the input signal

type (bool)

property likelihood

The instance of Likelihood derived from this histogram

type (Likelihood)

property ref

Reference data, observed numbers input to test, scaled if required

type (YODA.Scatter2D)

property refplot

Reference data for plotting

type (YODA.Scatter2D)

property scaled

Bool representing if there is additional scaling applied on top of luminosity

type (bool)

property signal_scale

Scale factor applied to the signal histogram/scatter, derived generally from input nEv and xs

type (float)

property sigplot

Signal for plotting

type (YODA.Scatter2D)

property stack

Stacked, unscaled Signal+background for plotting

type (YODA.Scatter2D)

property thy

Reference SM theory data, scaled if required

type (YODA.Scatter2D)

property thyplot

Theory for plotting

type (YODA.Scatter2D)

class contur.factories.yoda_factories.YodaFactory(yodaFilePath, noStack=False)[source]

Bases: object

Class controlling Conturs YODA file processing ability

This class is initialised from an os path to a YODA analysis object file and dresses it by iterating through each ao and wrapping that in an instance of yoda_factories_HistFactory which extracts the required Likelihood block from each aos. This class then contains the aggregated information for all of these instances across the entire YODA file.

path to output plot objects is detemined by contur.config.plot_dir


yodaFilePath (string) – Valid os.path filesystem YODA file location

Keyword Arguments
  • noStack (bool) – Mark true to not stack the signal on background in plotting (cosmetic)


Function to build the full likelihood representing this entire YODA file

This function takes the sorted_likelihood_blocks and combines them as statistically uncorrelated diagonal contributions to a CombinedLikelihood instance which is stored as an attribute to this class as likelihood

Keyword Arguments
  • omittedPools (string) – String of analysis pools to omit

property dominant_pool

returns the likelihood block with the highest confidence level


Method to drop likelihood_blocks with nan for cls

property likelihood

The full likelihood representing the YODA file in it’s entirety

type (CombinedLikelihood)

property likelihood_blocks

The list of all component likelihood blocks extracted from the YODA file

This attribute is the total information in the YODA file, but does not account for potential correlation/ overlap between the members of the list

type ( list [ Likelihood ])


Function that sorts the list of likelihood blocks extracted from the YODA file

This function implements the sorting algorithm to sort the list of all extracted Likelihood blocks in the likelihood_blocks list, storing the reduced list in the sorted_likelihood_blocks list

Keyword Arguments
  • omittedPools (string) – String of analysis pools to omit

property sorted_likelihood_blocks

The list of reduced component likelihood blocks extracted from the YODA file

This attribute is derived from the likelihood_blocks attribute, and is the result of sorting this list (using sort_blocks()), resulting in the list of components entering into the calculated full_likelihood

type ( list [ Likelihood ])


Function to load all reference data and theory yoda data

This function makes the calls to the module and builds the various background and data models on the fly for use in construction of the statistical tests.

arg aopath

List of rivet.AOPath ID’s to load, default empty list loads everything in $RIVET_REF_PATH

type aopath


contur.factories.yoda_factories.root_n_errors(ao, is_evcount, nx=0.0, lumi=1.0, replace=False)[source]

Function to include root(number of expected events) errors in the uncertainties of 2D scatter.

The uncertainty based on the expected events for the relevant integrated luminosity. This is not about MC statistics!

The minimum uncertainty is one event… we are not doing proper low-stat treatment in tails, so this is a conservative fudge.

  • ao – The YODA analysis object to be manipulated.

  • nx – factor needed to convert to number of events for none-uniform bin widths (<0, not used, ==0, do nothing).

  • is_evcount – True is the plot is in event numbers. Otherwise assumed to be a differential cross section.

  • lumi – Integrated luminiosity used to get event counts from differential cross sections

  • replace – If True replace the uncertainties. In False (default) add them in quadrature.











contur.factories.yoda_factories.scale_scatter_2d(ao, sf)[source]

Module contents

The factories package contains the collection of modules defining the analysis data flow

The factories module contains three submodules:

  • depot – Contains the high level analysis steering classes

  • yoda_factories – Contains classes to process YODA objects and control data flow between depot and likelihood

  • likelihood – Contains classes to construct likelihood functions from numerical inputs