contur package

Module contents

The Contur package for model interpretation of collider-physics measurements

Importing the Contur package pulls in the following submodules:

One additional submodule can be manually imported

  • contur.run - Defines logic used in python executables

Executables

contur

Main executable for running contur analysis on a grid of yoda files, a single yoda file, or a yoda stream

usage: contur [-h] [-v] [-d] [-q] [-l LOG] [-o OUTPUTDIR] [-y] [--ns]
              [-g GRID] [-T TAG] [-m MAPFILE] [--new] [-p PARAM_FILE]
              [--model MODEL] [--bf BF] [--me ME] [-w WIDTH] [-S SLHA]
              [-M MASS] [--BW BINWIDTH] [--BO BINOFFSET] [--xr] [--xhg]
              [--whw] [--wbv] [--awz] [-s] [--wn WEIGHTNAME] [--th] [--to]
              [--ana-match ANAPATTERNS] [--ana-unmatch ANAUNPATTERNS]
              [--split-pools POOLPATTERNS] [--ana-split ANASPLIT] [-b BEAMS]
              [-f FINDPARAMS] [--el] [-u] [--xtc] [--mnp]
              [--min_syst MIN_SYST] [--error_precision ERR_PREC]
              [--ll_precision LL_PREC] [--n_iter N_ITER] [--min_num_sys MNS]
              [yoda_files [yoda_files ...]]

Named Arguments

-v, --version

print version number and exit.

Default: False

-d, --debug

Switch on Debug to all, written to log file

Default: False

-q, --quiet

Suppress info messages

Default: False

-l, --logfile

Specify logfile name.

Default: “contur.log”

Input/Output control options

yoda_files

.yoda files to process.

-o, --outputdir

Top level output directory.

Default: “ANALYSIS”

-y, --yodamerge

only do the yodamerge step, then exit

Default: False

--ns, --nostack

in single run mode, do not stack the histograms in dat file output

Default: False

-g, --grid

specify a folder containing a structured grid of points to analyse. Usually ‘myscan’.

-T, --tag

Identifier for merged yoda files.

Default: “runpoint_

-m, --map

Name of map file output in grid running.

Default: “contur.map”

--new

Force Contur to not use possibly available merges of yoda files but merge yoda files anew.

Default: False

Dressing options to embelish outputs

-p, --param_file

Optionally specify a parameter file. Only used for documentation, and ignored for grid running.

Default: “params.dat”

--model

Optionally give name for model used. Only used for documentation.

--bf, --branchingfraction

Optionally give a comma-separated list of branching fractions for which cross sections will be stored in the map file

--me, --matrixelement

Optionally give a comma-separated list of matrix elements for which cross sections will be stored in the map file

-w, --width

Optionally give a comma-separated list of particle widths for which values will be stored in the map file

-S, --slha

read parameters from a comma-seperated list of blocks in an SLHA file

Default: “MASS”

-M, --mass

Optionally give a comma-separated list of particle masses for which values will be stored in the map file

--BW, --binwidth

optional binning of SLHA paramters

--BO, --binoffset

optional bin offset for SLHA parameters

Options to exclude/include subsets of data

--xr, --nometratio

Exclude plots where exclusion would be based on a ratio to the SM dileptonsUse this when you have ehnanced Z production in your model.

Default: False

--xhg, --nohiggsgamma

Exclude plots where Higgs to photons signal is background-subtracted by fitting continuum.Do this when you have large non-Higgs diphoton production from your model.

Default: False

--whw, --withhiggsww

Include plots where Higgs to WW signal is background-subtracted using data.Only try this when you have large Higgs WW from your model and not much top or other source of WW.

Default: False

--wbv, --withbvetos

Include plots where a b-jet veto was applied in the measurement but not in the fiducial definition.Only try this when you have large W+jets enhancements and no extra top or other source of W+b.

Default: False

--awz, --atlas-wz

Include the ATLAS WZ analysis with dodgy SM assumptions.Might be useful for enhanced WZ cross sections but be careful.

Default: False

-s, --use-searches

Use reco-level search analyses in the sensitivity evaluation (beta).

Default: False

--wn, --weight-name

for weighted events/histos, select the name of the weight to use.

Default: “”

--th, --theory

Use SM theory as the background model, where available.

Default: False

--to, --theoryonly

Only use those data where the SM theory prediction is available.

Default: False

--ana-match

only run on analyses whose name matches any of these regexes

Default: []

--ana-unmatch

exclude analyses whose name matches any of these regexes

Default: []

--split-pools

write out histograms from analyses in given pools separately

Default: []

--ana-split

write out histograms from given analyses separately

Default: []

-b, --beams

in grid mode, only run on these beams

Default: []

-f, --findPoint

identify points consistent with these parameters and make histograms for them

Default: []

--el, --expected_limits

Ignore the data, and calculate the expected limits where SM theory is available.

Default: False

Options to Manipulate the constructed test statistic. They dont apply if correlations are switched off

-u, --uncorrelate_errors

Master switch for turning off treatment of correlations.

Default: False

--xtc, --notheorycorr

Assume SM theory uncertainties are uncorrelated

Default: False

--mnp, --minimize_np

If using correlations, perform nuisance parameter minimization (slow)

Default: False

--min_syst

If using correlations, correlated systematic errors with a maximum fractional contribution below this will be ignored (saves time!)

Default: 0.001

--error_precision

precision cut off in nuisance parameters when minimizing LL

Default: 0.0001

--ll_precision

precision cut off in LL when minimizing it

Default: 0.0001

--n_iter

minimize cuts off after n_iter*n_variables iterations

Default: 200

--min_num_sys

minimum number of systematic nuisance parameters for them to be treated as correlated

Default: 2

contur-smtest

Run contur analysis on data vs SM theory

usage: contur-smtest [-h] [-v] [-d] [-q] [-l LOG] [-o OUTPUTDIR] [--xr]
                     [--xhg] [--whw] [--wbv] [--awz] [-s] [--wn WEIGHTNAME]
                     [--th] [--to] [--ana-match ANAPATTERNS]
                     [--ana-unmatch ANAUNPATTERNS]
                     [--split-pools POOLPATTERNS] [--ana-split ANASPLIT]
                     [-b BEAMS] [-f FINDPARAMS] [--el] [-u] [--xtc] [--mnp]
                     [--min_syst MIN_SYST] [--error_precision ERR_PREC]
                     [--ll_precision LL_PREC] [--n_iter N_ITER]
                     [--min_num_sys MNS]

Named Arguments

-v, --version

print version number and exit.

Default: False

-d, --debug

Switch on Debug to all, written to log file

Default: False

-q, --quiet

Suppress info messages

Default: False

-l, --logfile

Specify logfile name.

Default: “contur.log”

-o, --outputdir

Specify output directory for SM plot files.

Default: “sm_plots”

Options to exclude/include subsets of data

--xr, --nometratio

Exclude plots where exclusion would be based on a ratio to the SM dileptonsUse this when you have ehnanced Z production in your model.

Default: False

--xhg, --nohiggsgamma

Exclude plots where Higgs to photons signal is background-subtracted by fitting continuum.Do this when you have large non-Higgs diphoton production from your model.

Default: False

--whw, --withhiggsww

Include plots where Higgs to WW signal is background-subtracted using data.Only try this when you have large Higgs WW from your model and not much top or other source of WW.

Default: False

--wbv, --withbvetos

Include plots where a b-jet veto was applied in the measurement but not in the fiducial definition.Only try this when you have large W+jets enhancements and no extra top or other source of W+b.

Default: False

--awz, --atlas-wz

Include the ATLAS WZ analysis with dodgy SM assumptions.Might be useful for enhanced WZ cross sections but be careful.

Default: False

-s, --use-searches

Use reco-level search analyses in the sensitivity evaluation (beta).

Default: False

--wn, --weight-name

for weighted events/histos, select the name of the weight to use.

Default: “”

--th, --theory

Use SM theory as the background model, where available.

Default: False

--to, --theoryonly

Only use those data where the SM theory prediction is available.

Default: False

--ana-match

only run on analyses whose name matches any of these regexes

Default: []

--ana-unmatch

exclude analyses whose name matches any of these regexes

Default: []

--split-pools

write out histograms from analyses in given pools separately

Default: []

--ana-split

write out histograms from given analyses separately

Default: []

-b, --beams

in grid mode, only run on these beams

Default: []

-f, --findPoint

identify points consistent with these parameters and make histograms for them

Default: []

--el, --expected_limits

Ignore the data, and calculate the expected limits where SM theory is available.

Default: False

Options to Manipulate the constructed test statistic. They dont apply if correlations are switched off

-u, --uncorrelate_errors

Master switch for turning off treatment of correlations.

Default: False

--xtc, --notheorycorr

Assume SM theory uncertainties are uncorrelated

Default: False

--mnp, --minimize_np

If using correlations, perform nuisance parameter minimization (slow)

Default: False

--min_syst

If using correlations, correlated systematic errors with a maximum fractional contribution below this will be ignored (saves time!)

Default: 0.001

--error_precision

precision cut off in nuisance parameters when minimizing LL

Default: 0.0001

--ll_precision

precision cut off in LL when minimizing it

Default: 0.0001

--n_iter

minimize cuts off after n_iter*n_variables iterations

Default: 200

--min_num_sys

minimum number of systematic nuisance parameters for them to be treated as correlated

Default: 2

contur-batch

Run a series of batch jobs to either 1) build a grid of yoda files or 2) analyse a grid of yoda files

Run a parameter space scan and submit batch jobs. Produces a directory for each beam containing generator config file detailing the parameters used at that run point and a shell script to run the generator that is then submitted to batch.

usage: contur-batch [-h] [-v] [-d] [-q] [-l LOG] [-o output_dir]
                    [-p param_file.dat] [-t template_file] [-r run_info]
                    [-n num_events] [--seed seed] [-Q queue] [-s] [-b BEAMS]
                    [-P] [-w WALLTIME] [--memory MEMORY] [-B batch_system]
                    [-m mceg] [-V] [-g ANALYSE_GRID] [-N NUM_POINTS]
                    [-a ANALYSIS_FLAGS] [--setup SETUP_SCRIPT]

Named Arguments

-v, --version

print version number and exit.

Default: False

-d, --debug

Switch on Debug to all, written to log file

Default: False

-q, --quiet

Suppress info messages

Default: False

-l, --logfile

Specify logfile name.

Default: “contur.log”

-o, --out_dir

Specify the output directory name.

Default: “myscan00”

-p, --param_file

File specifying parameter space.

Default: “param_file.dat”

-t, --template

Template Herwig .in file.

Default: “LHC.in”

-r, --runinfo

Directory with required run information. Set to ‘none’ to not use one.

Default: “RunInfo”

-n, --numevents

Number of events to generate.

Default: 30000

--seed

Seed for random number generator.

Default: 101

-Q, --queue

batch queue.

Default: “”

-s, --scan_only, --scan-only

Only perform scan and do not submit batch job.

Default: False

-b, --beams

beam.

Default: “all”

-P, --pipe_hepmc, --pipe-hepmc

Rivet reading from pipe.

Default: False

-w, --wallTime, --walltime

Set maximum wall time for jobs (HH:MM).

--memory

Set maximum memory consumption for jobs (e.g. 2G).

-B, --batch

Specify which batch system is using, support: qsub, condor or slurm

Default: “qsub”

-m, --mceg

MC event generator.

Default: “herwig”

-V, --variablePrecision

Use this flag to make number of events for each point variable

Default: False

-g, --analyse_grid

run analysis and make map files from an existing grid.

-N, --num_points

break an analysis run down into jobs/maps with N parameter points in each

Default: 50

-a, --analysis_flags

flags to pass to the contur analysis step (separate with commas)

Default: “”

--setup

specify a setup script to be sourced at start of analysis batch job.

contur-gridtool

Collection of utilities for operating on grids of yoda files

usage: contur-gridtool [-h] [-v] [-d] [-q] [-l LOG] [--merge] [--rm]
                       [-x ANAPATTERNS] [--nc] [--archive] [-c] [--ca] [-S]
                       [-f FINDPARAMS] [-o output_dir] [-p param_file.dat]
                       [-t template_file] [-r run_info] [-n num_events]
                       [--seed seed] [-Q queue] [-s] [-b BEAMS] [-P]
                       [-w WALLTIME] [--memory MEMORY] [-B batch_system]
                       [-m mceg] [-V] [-g ANALYSE_GRID] [-N NUM_POINTS]
                       [-a ANALYSIS_FLAGS] [--setup SETUP_SCRIPT]
                       [scan_dirs [scan_dirs ...]]

Positional Arguments

scan_dirs

scan directories to process.

Named Arguments

-v, --version

print version number and exit.

Default: False

-d, --debug

Switch on Debug to all, written to log file

Default: False

-q, --quiet

Suppress info messages

Default: False

-l, --logfile

Specify logfile name.

Default: “contur.log”

-o, --out_dir

Specify the output directory name.

Default: “myscan00”

-p, --param_file

File specifying parameter space.

Default: “param_file.dat”

-t, --template

Template Herwig .in file.

Default: “LHC.in”

-r, --runinfo

Directory with required run information. Set to ‘none’ to not use one.

Default: “RunInfo”

-n, --numevents

Number of events to generate.

Default: 30000

--seed

Seed for random number generator.

Default: 101

-Q, --queue

batch queue.

Default: “”

-s, --scan_only, --scan-only

Only perform scan and do not submit batch job.

Default: False

-b, --beams

beam.

Default: “all”

-P, --pipe_hepmc, --pipe-hepmc

Rivet reading from pipe.

Default: False

-w, --wallTime, --walltime

Set maximum wall time for jobs (HH:MM).

--memory

Set maximum memory consumption for jobs (e.g. 2G).

-B, --batch

Specify which batch system is using, support: qsub, condor or slurm

Default: “qsub”

-m, --mceg

MC event generator.

Default: “herwig”

-V, --variablePrecision

Use this flag to make number of events for each point variable

Default: False

-g, --analyse_grid

run analysis and make map files from an existing grid.

-N, --num_points

break an analysis run down into jobs/maps with N parameter points in each

Default: 50

-a, --analysis_flags

flags to pass to the contur analysis step (separate with commas)

Default: “”

--setup

specify a setup script to be sourced at start of analysis batch job.

Control options

--merge

merge two or more grids using symbolic links. Excludes other options

Default: False

--rm, --remove-merged

if unmerged yodas exist, unzip them, and remove merged ones

Default: False

-x

create a new grid containing output of only these analyses

Default: []

--nc, --no-clean

do not remove unnecessary files.

Default: False

--archive

remove intermediate and unncessary files, and compress others.

Default: False

-c, --check

check whether all grid points have valid yodas

Default: False

--ca, --check-all

include grid points without logfiles when checking for yodas

Default: False

-S, --submit

(re)submit any jobs which are found to have failed.

Default: False

-f, --findPoint

identify points consistent with these parameters and make histograms for them

Default: []

contur-plot

Main executuble for making heatmap and contour plots from a map file

Plot contur data from a .map file.

usage: contur-plot [-h] [-v] [-d] [-q] [-l LOG] [-o OUTPUTDIR]
                   [-ef EXTERNALFUNCTION] [-eg EXTERNALGRID] [-xl] [-yl]
                   [--pools] [-O OMIT] [-x XLABEL] [-y YLABEL] [-sp]
                   [-T TITLE] [-L ILEVEL] [--style {DRAFT,FINAL}]
                   [--isigma ISIGMA] [--num-dpools NDPOOLS] [--clstxt]
                   [--no-clsdpool] [-c CONTOUR_COLOUR]
                   map_file [variables [variables ...]]

Positional Arguments

map_file

Path to .map file containing list of depot objects.

variables

x, y [and z] variables to plot.

Named Arguments

-v, --version

print version number and exit.

Default: False

-d, --debug

Switch on Debug to all, written to log file

Default: False

-q, --quiet

Suppress info messages

Default: False

-l, --logfile

Specify logfile name.

Default: “contur.log”

-o, --output_path

Path to output plot(s) to.

Default: “conturPlot”

-ef, --externalFunction

Python file with external functions to load and plot

-eg, --externalGrid

Python file loading alternative external grids

-xl, --xlog

Set the xaxis to be displayed on a log scale

Default: False

-yl, --ylog

Set the yaxis to be displayed on a log scale

Default: False

--pools

Turn on plotting of individual analysis pools (much slower!)

Default: False

-O, --omit

Name of pool to omit (will slow things down!)

Default: “”

-x, --xlabel

x-axis label. Accepts latex formatting but special characters must be input with a slash, e.g. $M_{z’}$~[GeV]

-y, --ylabel

y-axis label. Accepts latex formatting but special characters must be input with a slash, e.g. $M_{z’}$~[GeV]

-sp, --save_plots

Save the raw matplotlib axes to a file for graphical manipulation

Default: False

-T, --title

Title for plot.

Default: “”

-L, --ilevel, --iLevel

interpolation zoom level

Default: 3

--style

Possible choices: DRAFT, FINAL

Global flag for plot-styling variations: ‘final’ will have no title or cmap key and will produce a .tex file containing a colour legend for the dominant pools plot

Default: DRAFT

--isigma, --iSigma

interpolation smoothing radius, in mesh cells

Default: 0.75

--num-dpools

Number of levels of (sub)dominant pool plots to make.

Default: 1

--clstxt

Write CLs values on top of the mesh in the detailed dominant-pool plots.

Default: False

--no-clsdpool

Skip the detailed dominant-pool plot with lead/sub/diff CLs meshes.

Default: False

-c, -contour_colour

Colour for the 68/95 contours

Default: “white”

contur-export

Export a map file as a csv file.

contur-extract-herwig-xs-br

Extract the cross sections and branching ratios from a single herwig log

contur-scan-herwig-xs-br

Extract the cross sections and branching ratios from a grid of herwig logs

contur-mapmerge

Merge a list of map files

contur-mkana

Make the analysis lists for herwig/rivet, and optionall the web pages for them

contur-mkbib

Make the contur webpage bibliography

contur-mkhtml

Make an html summary, with links to plots, for a single yoda file on which contur has been run

contur-mkthy

Make theory reference yodas (/THY/) from raw theory archives.