matching package

Submodules

matching.clusterTools module

class matching.clusterTools.AverageSMS(smsList=[])

Bases: TheorySMS

Represents an SMS or list of SMS containing only the basic attributes required for clustering or computing efficiencies/upper limits. Its properties are given by the average properties of the SMS it represents and its weight is given by the total weight of all SMS.

Initialize basic attributes.

class matching.clusterTools.SMSCluster(smsList=[], dataset=None)

Bases: object

An instance of this class represents a cluster of SMS, which holds the averageSMS. This class is used to store the relevant information about a cluster of SMS and to manipulate this information.

computeAverageSMS()

Computes the average SMS for the cluster. The average SMS has generic ParticleNodes with the attributes set to the average values of self.smsList. It can only be defined if all SMS share the same canonical name and the same txname. Otherwise, returns None

Returns

AverageSMS object or None (if it can not be defined)

distanceTo(sms)

Defines the relative distance between the cluster and SMS object or another cluster. The distance is computed using the upper limits for the averageSMS (for cluster objects) or the SMS upper limit. The distance is defined as d = 2*|ul1-ul2|/(ul1+ul2).

Parameters

sms – SMS object or SMSCluster object

Returns

relative distance

getTotalXSec()

Return the sum over the cross sections of all SMS belonging to the cluster.

Returns

sum of weights of all the SMS in the cluster (XSectionList object)

isValid(maxDist)

Checks if the SMSCluster is a valid cluster, i.e. if its AverageSMS has a well defined UL and the distance between any SMS in the cluster and the cluster AverageSMS is smaller than maxDist.

Parameters

• dataset – Dataset object used to check the UL

• maxDist – maximum distance between the averageSMS and all the SMS in the cluster

Returns

True/False

matching.clusterTools.clusterSMS(smsList, maxDist, dataset)

Cluster the original SMS according to their distance in upper limit space.

Parameters

• smsList – list of sms (TheorySMS objects)

• dataset – Dataset object to be used when computing distances in upper limit space

• maxDist – maximum distance for clustering two SMS

Returns

list of clusters (SMSCluster objects)

matching.clusterTools.doCluster(smsList, dataset, maxDist)

Cluster algorithm to cluster SMS using a modified minimal spanning tree method.

Parameters

• smsList – list of all SMS to be clustered

• dataset – Dataset object to be used when computing distances in upper limit space

• maxDist – maximum distance for clustering two SMS

Returns

a list of SMSCluster objects containing the SMS belonging to the cluster

matching.clusterTools.groupSMS(smsList, dataset)

Group SMS into clusters where the average SMS is identical to all the SMS in cluster. Each cluster contains all SMS which share the same mass,width and upper limit and can be replaced by their average SMS.

Parameters

smsList – list of all SMS to be grouped

Returns

a list of SMSCluster objects which represents a group of SMS with same mass, width and upper limit.

matching.clusterTools.mergeClusters(clusterList, useAverage=False)

Merge a list of SMSCluster objects using the averageSMS of each cluster if useAverage is True. Otherwise cluster the list of all SMS from all clusters.

Parameters

• clusterList – List of SMSCluster objects

• useAverage – True/False. If True, will cluster the averageSMS in each cluster.

matching.exceptions module

exception matching.exceptions.SModelSMatcherError(value=None)

Bases: Exception

Class to define SModelS specific errors

matching.matcherAuxiliaryFuncs module

matching.matcherAuxiliaryFuncs.average(values, weights=None, nround=-1)

Compute the weighted average of a list of objects. All the objects must be of the same type. If all objects are equal returns the first entry of the list. Only the average of ints, floats and Unum objects or nested lists of these can be computed. If the average can not be computed returns None.

Parameters

• values – List of objects of the same type

• weights – Weights for computing the weighted average. If None it will assume unit weights.

• nround – If greater than zero and the returning attibute is numeric, will round it to this number of significant digits.

matching.matcherAuxiliaryFuncs.roundValue(value, nround=-1)

Round a value to nround significant digits. If the input value is not a float or Unum object, it is zero or infinity, nothing is done.

Parameters

nround – number of significant digits

Returns

rounded value

matching.modelTester module

matching.modelTester.checkForSemicolon(strng, section, var)

matching.modelTester.getAllInputFiles(inFile)

Given inFile, return list of all input files

Parameters

inFile – Path to input file or directory containing input files

Returns

List of all input files, and the directory name

matching.modelTester.getCombiner(inputFile, parameterFile)

Facility for running SModelS, computing the theory predictions and returning the combination of analyses (defined in the parameterFile). Useful for plotting likelihoods!. Extracts and returns the TheoryPredictionsCombiner object from the master printer, if the object is found. Return None otherwise.

Parameters

• inputFile – path to the input SLHA file

• parameterFile – path to parameters.ini file

Returns

TheoryPredictionsCombiner object generated by running SModelS.

matching.modelTester.getParameters(parameterFile)

Read parameter file, exit in case of errors

Parameters

parameterFile – Path to parameter File

Returns

ConfigParser read from parameterFile

matching.modelTester.loadDatabase(parser, db)

Load database

Parameters

• parser – ConfigParser with path to database

• db – binary database object. If None, then database is loaded, according to databasePath. If True, then database is loaded, and text mode is forced.

Returns

database object

matching.modelTester.loadDatabaseResults(parser, database)

Restrict the (active) database results to the ones specified in parser

Parameters

• parser – ConfigParser, containing analysis and txnames selection

• database – Database object

matching.modelTester.runSetOfFiles(inputFiles, outputDir, parser, database, timeout, development, parameterFile, return_dict)

Loop over all input files in inputFiles with testPoint

Parameters

• inputFiles – list of input files to be tested

• outputDir – path to directory where output is be stored

• parser – ConfigParser storing information from parameter.ini file

• database – Database with selected experimental results

• development – turn on development mode (e.g. no crash report)

• parameterFile – parameter file, for crash reports

Returns

printers output

matching.modelTester.runSingleFile(inputFile, outputDir, parser, database, timeout, development, parameterFile)

Call testPoint on inputFile, write crash report in case of problems

Parameters

• inputFile – path to input file

• outputDir – path to directory where output is be stored

• parser – ConfigParser storing information from parameter.ini file

• datbase – Database holding the list of selected results

• crashReport – if True, write crash report in case of problems

• timeout – set a timeout for one model point (0 means no timeout)

Returns

output of printers

matching.modelTester.setExperimentalFeatures(featuresDict)

set the experimental features flats, if experimentalFeatures:* = True

matching.modelTester.testPoint(inputFile, outputDir, parser, database)

Test model point defined in input file (running decomposition, check results, test coverage)

Parameters

• inputFile – path to input file

• outputDir – path to directory where output is be stored

• parser – ConfigParser storing information from parameters file

• database – Database holding the list of experiment results

Returns

dictionary with input filename as key and the MasterPrinter object as value

matching.modelTester.testPoints(fileList, inDir, outputDir, parser, database, timeout, development, parameterFile)

Loop over all input files in fileList with testPoint, using ncpus CPUs defined in parser

Parameters

• fileList – list of input files to be tested

• inDir – path to directory where input files are stored

• outputDir – path to directory where output is stored

• parser – ConfigParser storing information from parameter.ini file

• database – Database with selected experimental results

• timeout – set a timeout for one model point (0 means no timeout)

• development – turn on development mode (e.g. no crash report)

• parameterFile – parameter file, for crash reports

Returns

printer(s) output, if not run in parallel mode

matching.theoryPrediction module

class matching.theoryPrediction.TheoryPrediction(deltas_rel=None)

Bases: object

An instance of this class represents the results of the theory prediction for an analysis.

Initialize the theory prediction object. deltas_rel is meant to be a constant.

Parameters

deltas_rel – relative uncertainty in signal (float). Default value is 20%.

CLs(*args, **kwargs)

analysisId()

Return experimental analysis ID

computeConditions()

computeStatistics(*args, **kwargs)

computeXSection()

dataId()

Return ID of dataset

dataType(short=False)

Return the type of dataset :param: short, if True, return abbreviation (ul,em,comb)

getRValue(expected=False)

Get the r value = theory prediction / experimental upper limit

getUpperLimit(expected=False)

Get the upper limit on sigma*eff. For UL-type results, use the UL map. For EM-Type returns the corresponding dataset (signal region) upper limit. For combined results, returns the upper limit on the total sigma*eff (for all signal regions/datasets).

Parameters

expected – return expected Upper Limit, instead of observed.

Returns

upper limit (Unum object)

getUpperLimitOnMu(expected=False)

Get upper limit on signal strength multiplier, using the theory prediction value and the corresponding upper limit (i.e. mu_UL = upper limit/theory xsec)

Parameters

expected – if True, compute expected upper limit, else observed

Returns

upper limit on signal strength multiplier mu

getmaxCondition()

Returns the maximum xsection from the list conditions

Returns

maximum condition xsection (float)

likelihood(*args, **kwargs)

lmax(*args, **kwargs)

lsm(*args, **kwargs)

muhat(*args, **kwargs)

nllToLikelihood(nll: Union[None, float], return_nll: bool)

if not return_nll, then compute likelihood from nll

setStatsComputer()

Creates and instance of StatsComputer depending on the type of TheoryPrediction/dataset. In case it is not possible to define a statistical computer (upper limit result or no expected upper limits), set the computer to ‘N/A’.

sigma_mu(*args, **kwargs)

property statsComputer

totalXsection()

whenDefined()

Returns the function whenever the statistical calculation is possible (i.e. when it is possible to define self.StatsComputer)

class matching.theoryPrediction.TheoryPredictionsCombiner(theoryPredictions: list, slhafile=None, deltas_rel=None)

Bases: TheoryPrediction

Facility used to combine theory predictions from different analyes. If a list with a single TheoryPrediction is given, return the TheoryPrediction object.

Constructor.

Parameters

• theoryPredictions – the List of theory predictions

• slhafile – optionally, the slhafile can be given, for debugging

• deltas_rel – relative uncertainty in signal (float). Default value is 20%.

analysisId()

Return a string with the IDs of all the experimental results used in the combination.

dataId()

Return a string with the IDs of all the datasets used in the combination.

dataType(short=False)

Return its type (combined) :param: short, if True, return abbreviation (anacomb)

describe()

returns a string containing a list of all analysisId and dataIds

getLlhds(muvals, expected=False, normalize=True)

Facility to access the likelihoods for the individual analyses and the combined likelihood. Returns a dictionary with the analysis IDs as keys and the likelihood values as values. Mostly used for plotting the likelihoods.

Parameters

• muvals – List with values for the signal strenth for which the likelihoods must be evaluated.

• expected – If True returns the expected likelihood values.

• normalize – If True normalizes the likelihood by its integral over muvals.

getmaxCondition()

Returns the maximum xsection from the list conditions

Returns

maximum condition xsection (float)

classmethod selectResultsFrom(theoryPredictions, anaIDs)

Select the results from theoryPrediction list which match one of the IDs in anaIDs. If there are multiple predictions for the same ID for which a likelihood is available, it gives priority to the ones with largest expected r-values.

Parameters

• theoryPredictions – list of TheoryPrediction objects

• anaIDs – list with the analyses IDs (in string format) to be combined

Returns

a TheoryPredictionsCombiner object for the selected predictions. If no theory prediction was selected, return None.

setStatsComputer()

Creates and instance of StatsComputer depending on the type of TheoryPrediction/dataset. In case it is not possible to define a statistical computer (upper limit result or no expected upper limits), set the computer to ‘N/A’.

totalXsection()

matching.theoryPrediction.theoryPredictionsFor(database: Database, smsTopDict: Dict, maxMassDist: float = 0.2, useBestDataset: bool = True, combinedResults: bool = True, deltas_rel: Union[None, float] = None)

Compute theory predictions for the given experimental result, using the list of SMS in smsTopDict. For each Txname appearing in expResult, it collects the SMS and efficiencies, combine the SMS and compute the conditions (if exist).

Parameters

• database – the database with the selected experimental results

• smsTopDict – dictionary of SMS, where the canonical names are keys and the TheorySMS objects are values. (TopologyDict object)

• maxMassDist – maximum mass distance for clustering SMS (float)

• useBestDataset – If True, uses only the best dataset (signal region). If False, returns predictions for all datasets (if combinedResults is False), or only the combinedResults (if combinedResults is True).

• combinedResults – add theory predictions that result from combining datasets.

• deltas_rel – relative uncertainty in signal (float). Default value is 20%.

Returns

a TheoryPredictionList object containing a list of TheoryPrediction objects

Module contents