contur.factories package¶
Submodules¶
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 combineLikelihood
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
blocksThis 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 otherNote
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_likelihood(likelihood)[source]¶
Add a
Likelihood
block to this combination likelihood- Parameters
likelihood (
Likelihood
) – Instance of computed Likelihood
- calc_cls()[source]¶
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
- Parameters
bw – bin widths
s (
list[float]
) – Signal countbg (
list[float]
) – Background countnobs (
list[float]
) – Observed countserr (
list[float]
) – Signal error countscov (
numpy.ndarray
) – Covariance matrix for observablesuncov (
numpy.ndarray
) – Covariance matrix for observables assuming no correlation
- Keyword Arguments
thcov (
numpy.ndarray
) – Covariance matrix for the background simulationthuncov (
numpy.ndarray
) – Covariance matrix for the background simulation, assuming no correlationratio (
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 measurementuseTheory (
bool
) – Flag if background simulation and errors are to be usedlumi (
float
) – the integrated luminosity for the measurement. used to calculate expect stat uncertainty on signalsxsec (
float
) – Signal cross-section in picobarns, if non-nullnuisErrs (
dict{numpy.ndarray}
) – Dict of component breakdown of covthErrs (
dict{numpy.ndarray}
) – Dict of component breakdown of thcov
Todo
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
)
- pval_to_cls(pval_tuple)[source]¶
Method to calculate a cls when passed background and signal p values.
- Parameters
pval_tuple (
Tuple of floats
) – Tuple, first element p-value of signal hypothesis, second p-value of background- Returns
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
)
- ts_to_cls(ts_tuple_list)[source]¶
Method to directly cast a list of tuples of test statistics (tuple contains background and signal test stats) into a list of CLs values
- Parameters
ts_tuple_list (
list
) – list of tuples of tests statistics (tuples of the form (test stat background, test stat background))- Returns
CLs
list
– List of Confidence Intervals in CLs formalism
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 internalinbox
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
- build_axes()[source]¶
Function to build the axis dictionaries used for plotting, parameter space points are otherwise stored unordered
- Built variables
mapAxis (
dict
)plotAxis (
dict
)
- property frame¶
A
pandas.DataFrame
representing the CLs interval for each point ininbox
type (
pandas.DataFrame
)
- property inbox¶
The master list of
ParamYodaPoint
instances added to the Depot instancetype (
list
[ParamYodaPoint
])
- property map_axis¶
Dictionary of the sampled values in each axis
type (
dict
) – key – Parameter name (string
), value – (numpy.ndarray
)
- merge(depot)[source]¶
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
- Parameters
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
)
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- Parameters
ana_obj (
YODA.AnalysisObject
) –YODA
AO to dressxsec (
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
Note
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
)
- 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 histogramtype (
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 ofyoda_factories_HistFactory
which extracts the requiredLikelihood
block from each aos. This class then contains the aggregated information for all of these instances across the entireYODA
file.path to output plot objects is detemined by contur.config.plot_dir
- Parameters
yodaFilePath (
string
) – Validos.path
filesystem YODA file location- Keyword Arguments
noStack (
bool
) – Mark true to not stack the signal on background in plotting (cosmetic)
- build_full_likelihood(omittedPool='')[source]¶
Function to build the full likelihood representing this entire
YODA
fileThis function takes the
sorted_likelihood_blocks
and combines them as statistically uncorrelated diagonal contributions to aCombinedLikelihood
instance which is stored as an attribute to this class aslikelihood
- Keyword Arguments
omittedPools (
string
) – String of analysis pools to omit
- property dominant_pool¶
returns the likelihood block with the highest confidence level
- property likelihood¶
The full likelihood representing the
YODA
file in it’s entiretytype (
CombinedLikelihood
)
- property likelihood_blocks¶
The list of all component likelihood blocks extracted from the
YODA
fileThis attribute is the total information in the
YODA
file, but does not account for potential correlation/ overlap between the members of the listtype (
list
[Likelihood
])
- sort_blocks(omitted_pools='')[source]¶
Function that sorts the list of likelihood blocks extracted from the
YODA
fileThis function implements the sorting algorithm to sort the list of all extracted
Likelihood
blocks in thelikelihood_blocks
list, storing the reduced list in thesorted_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
fileThis attribute is derived from the
likelihood_blocks
attribute, and is the result of sorting this list (usingsort_blocks()
), resulting in the list of components entering into the calculatedfull_likelihood
type (
list
[Likelihood
])
- contur.factories.yoda_factories.init_ref(aopath=[])[source]¶
Function to load all reference data and theory yoda data
This function makes the calls to the
contur.data
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
list``[``string
]
- 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.
- Parameters
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.
- Type
YODA.AnalysisObject
- Type
- Type
boolean
- Type
- Type
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 classesyoda_factories
– Contains classes to processYODA
objects and control data flow betweendepot
andlikelihood
likelihood
– Contains classes to construct likelihood functions from numerical inputs