contur.util package


contur.util.file_readers module


Get histograms from a YODA file. Loops over all yoda objects in the input file looking for valid signal histograms.

Ignores REF and THY (which are read elsewhere) and RAW histograms.

Param filename

(`string`) name of yoda input file.


  • mchistos = dictionary containing {path, ao} pairs for candidate signal histograms.

  • xsec = yoda analysis object containing the generated xsec and its uncertainty

  • Nev = yoda analysis object containing sum of weights, sum of squared weight, number of events


read the SM vs measurement test statistics from the archived (.stat) file.


path – YODA path of the relevant histogram.


the test statistic (float)

contur.util.file_readers.read_herwig_log_file(root, files, branching_fractions, widths, masses)[source]

Find the Herwig .log file and read various values from it

  • root (string) – Top directory from which to searching for .out files began

  • files – List of files being searches

  • branching_fractions – list of branching fractions to look for

  • widths – list of branching widths to look for

  • masses – list of branching masses to look for


dictionary of (name, value) pairs for the extracted parameters.

contur.util.file_readers.read_herwig_out_file(root, files, matrix_elements)[source]

Find the Herwig .out file and read cross sections for requested matrix element values from it.

  • root (string) – Top directory from which to searching for .out files began

  • files – List of files being searches

  • matrix_elements – list of matrix elements to look for


dictionary of matrix element (name, value) pairs


Read a parameter file and return dictionary of (strings of) contents


file_path (string) – full path the the parameter file


dictionary of parameter (parameter_name, value) pairs

contur.util.file_readers.read_slha_file(root, slha_file, block_list)[source]

read requested blocks from an SLHA1 file (if found)

returns a dictionary blocks_dict{ block: {name: value} } for each block in block_list.

the name of the block is prepended to each parameter, for disambiguation when written to the map file.

for the MASS block the binwidth and binoffset will be applied, if provided. @TODO that would be better handled at the visualisation/plotting step?

  • root – path to SLHA file

  • slha_file – name of SLHA file

  • block_list – list of SLHA blocks to read


dictionary (blockname, (name, value))

contur.util.utils module

Miscellaneous helper functions that may be used by more than one contur submodule

class contur.util.utils.Plot[source]

Bases: dict

A tiny Plot object to help writing out the head in the .dat file

contur.util.utils.build_full_likelihood(sorted_blocks, omittedPool='')[source]

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


Function to query InspireHEP database and return a dictionary containing the metadata

extracted/adapted from rivet-findid


inspire_id (string) – the ID of the publication on Inspire


pub_data dictionary – selected metadata as a dictionary of bytes


Function that finds the chi-square test statistic that gives the maximum confidence level for each likelihood block for which we don’t have a valid covariance matrix (either the matrix has no invserse or has not been succesfully built)


Function that calculates the confidence level for each likelihood block extracted from the YODA file using the signal and background test statistic for the block


Make a Scatter2D from a Scatter1D by treating the points as y values and adding dummy x bins.


Function to make an output directory if it does not already exist. Also tests if an existing directory is write-accessible.

contur.util.utils.newlogspace(start, stop, num=50, endpoint=True, base=10.0, dtype=None)[source]

Numpy logspace returns base^start to base^stop, we modify this here so it returns logspaced between start and stop


Get permission to continue program

contur.util.utils.sort_blocks(likelihood_blocks, omitted_pools='')[source]

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

contur.util.utils.walklevel(some_dir, level=1)[source]

Like os.walk but can specify a level to walk to useful for managing directories a bit better


Write an Ascii banner giving the version and pointing to the documenation

contur.util.utils.write_histo_dat(mcpath, plotparser, nostack, histo)[source]

Write a YODA .dat file (plot formatting) for the histogram in the output directory, for later display.

  • mcpath – (string) the yoda path of the histogram

  • plotparser – (rivet.PlotParser) a standard rivet plot parser object.

  • outdir – (string) Absolute path to the top level directory for the output. The dat files will be written in a directory structure below this as POOL/ANALYSIS/HISTOGRAM.dat

  • histo (contur.factories.HistFactory) – dressed YODA ao

the output directort is detemined by contur.config.plot_dir

contur.util.utils.write_sm_test(outdir, histo)[source]

Write a short text file archiving the result of comparing SM prediction vs measurement (no signal prediction) for this histo.

  • outdir – (string) Absolute path to the top level directory for the output. The .stat files will be written in a directory structure below this as POOL/ANALYSIS/HISTOGRAM.stat

  • histo (contur.factories.HistFactory) – dressed YODA ao

contur.util.utils.write_summary_file(message, conturDepot)[source]

Write a brief text summary of a conturDepot, describing the run conditions and results. If contur.config.gridMode is False, will also write info about the most sensitive histograms in each pool, for parsing by contur-mkhtml

  • message – text (string) message containing the run conditions for this depot

  • conturDepot – the processed depot of results

the name of the directory to write the file into will be determined by contur.config.output_dir

Module contents