contur package

Subpackages

Module contents

The Contur package for model interpretation of collider-physics measurements

The Contur package contains the following submodules, which should be imported by hand as needed.

  • contur.config - Global configuration options

  • contur.data - Database and associated functions parsing data/covariance info from Rivet/YODA

  • contur.export - Utiluty for exporting map files to csv

  • contur.factories - Main worker classes for contur functionality

  • contur.oracle - Driver for scans using active learning

  • contur.plot - Plotting engine and styling

  • contur.run - Defines logic used in python executables

  • contur.scan - Utilities for steering/running creation of MC grids

  • contur.util - Misc helper functions

Executables

contur

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

This is the main analysis executable for Contur: Constraints on new theories using Rivet

usage: contur [-h] [-v] [-d] [-q] [-l LOG] [--offline] [--nomultip]
              [--nopyscripts] [-p PARAM_FILE] [-g GRID] [-r RESULTS]
              [--runname RUNNAME] [--tag TAG] [--map MAPFILE] [--csv CSVFILE]
              [--remerge] [--addtoDB] [--keep-hepmc] [-b BEAMS] [-o OUTPUTDIR]
              [--db DBFILE] [--model MODEL] [-P [PI]] [-M [ME]] [--slha SLHA]
              [--BW BINWIDTH] [--BO BINOFFSET] [--ns]
              [--ana-match ANAPATTERNS] [--ana-unmatch ANAUNPATTERNS] [--all]
              [--xr] [--tracks-only] [--soft-physics] [--xhg] [--whw] [--wbv]
              [--awz] [-s] [--wn WEIGHTNAME] [-f FINDPARAMS] [-u] [--tc]
              [--min-num-sys MNS] [--split-pools POOLPATTERNS]
              [--ana-split ANASPLIT] [--spb] [--lle]
              [yodafiles ...]

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, --log

Specify logfile name.

Default: “contur.log”

--offline

Run in offline mode (no querying of inspire).

Default: False

--nomultip

Do not use multiprocessing.

Default: False

--nopyscripts

Disable writing of Python scripts for individualhistograms in grid mode.

Default: False

-b, --beams
Select beams to run on. Default is to run on 13TeV.

Known beams are [‘13TeV’, ‘2_76TeV’, ‘7TeV’, ‘8TeV’, ‘all’]. NOTE: em_ep_91_2 is currently beta, see https://gitlab.com/hepcedar/rivet/-/issues/293.

Default: “all”

--ana-match

only run on analyses whose name matches this regex

Default: []

--ana-unmatch

exclude analyses whose name matches this regex

Default: []

-f, --find-point

identify points consistent with these parameters and make histograms for them

Default: []

Options relating to grid of results

-p, --param-steering-file

File specifying parameter space scanned.

Default: “param_file.dat”

-g, --grid

Run in grid mode on a folder containing a structured grid of points.

-r, --results

Name of the file for the results database.

--runname

Identifier for grid run

Default: “my_run”

--tag

Identifier for merged yoda files.

Default: “runpoint”

--map

Name of map (pickle) file output if desired (in grid mode).

--csv

Name of csv file output if desired (in grid mode).

--remerge

Do not use any existing merges of yoda files: merge yoda files anew.

Default: False

--addtoDB

add results to an existing results file.

Default: False

--keep-hepmc

preserve the HepMC files if they are being generated (in grid mode).

Default: False

I/O

-o, --outputdir

Output path.

Default: “ANALYSIS”

yodafiles

List of indiviudal yoda files to process.

--db, --dbfile

Name of file for results DB.

Default: “contur_run.db”

Dressing options to embellish outputs

--model

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

-P, --particleinfo

Comma-separated list of particles for which mass, width, branchings will be stored. If flag is present with no list, info will be saved for all particles found.

-M, --matrix_element

Comma-separated list of matrix elements for which cross sections will be stored.If flag is present with no list, info will be saved for all non-zero processes found.

--slha

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

Default: “MASS”

--BW, --binwidth

optional binning of SLHA paramters

--BO, --binoffset

optional bin offset for SLHA parameters

--ns, --nostack

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

Default: False

Options to exclude/include subsets of data

--all

Convenience option to use all data. Overrides any other selections.

Default: False

--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

--tracks-only

Only use plots which are based on tracking informationUseful for models where calorimeter jet calibration may be suspect (e.g. dark showers).

Default: False

--soft-physics

Include plots which are very sensitive to soft QCD.Not reliable unless you really know what you are doing.

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: “”

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

-u, --diagonalise-cov

Use diagonal version of covariance matrix (ie no systematic correlations).

Default: False

--tc, --theorycorr

Assume SM theory uncertainties are correlated

Default: False

--min-num-sys

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

Default: 5

--split-pools

write out histograms from analyses in given pools separately

Default: []

--ana-split

write out histograms from given analyses separately

Default: []

--spb, --signal-plus-background

Tell contur that the input histos are signal-plus-background, not just signal

Default: False

--lle, --look-elsewhere

Treat plots with no signal as agreeing well. Otherwise (default) they are ignored.

Default: False

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. (if –single, just make one example directory)

usage: contur-batch [-h] [-v] [-d] [-q] [-l LOG] [--offline] [--nomultip]
                    [--nopyscripts] [-p PARAM_FILE] [-g GRID] [-r RESULTS]
                    [--runname RUNNAME] [--tag TAG] [--map MAPFILE]
                    [--csv CSVFILE] [--remerge] [--addtoDB] [--keep-hepmc]
                    [-b BEAMS] [-o OUTPUTDIR] [--template TEMPLATE_FILE]
                    [--runinfo RUN_INFO] [-n NUM_EVENTS] [--seed SEED]
                    [-Q QUEUE] [-s] [-P] [-w WALLTIME] [--memory MEMORY]
                    [-B BATCH_SYSTEM] [-V] [--single] [-N NUM_POINTS]
                    [-a ANALYSIS_FLAGS] [--setup SETUP_SCRIPT]
                    [--main-program MAIN_PROGRAM] [-m MCEG]

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, --log

Specify logfile name.

Default: “contur.log”

--offline

Run in offline mode (no querying of inspire).

Default: False

--nomultip

Do not use multiprocessing.

Default: False

--nopyscripts

Disable writing of Python scripts for individualhistograms in grid mode.

Default: False

-b, --beams
Select beams to run on. Default is to run on 13TeV.

Known beams are [‘13TeV’, ‘2_76TeV’, ‘7TeV’, ‘8TeV’, ‘all’]. NOTE: em_ep_91_2 is currently beta, see https://gitlab.com/hepcedar/rivet/-/issues/293.

Default: “13TeV”

-o, --outputdir

Output path.

Default: “myscan00”

-m, --mceg

MC event generator.

Default: “herwig”

Options relating to grid of results

-p, --param-steering-file

File specifying parameter space scanned.

Default: “param_file.dat”

-g, --grid

Run in grid mode on a folder containing a structured grid of points.

-r, --results

Name of the file for the results database.

--runname

Identifier for grid run

Default: “my_run”

--tag

Identifier for merged yoda files.

Default: “runpoint”

--map

Name of map (pickle) file output if desired (in grid mode).

--csv

Name of csv file output if desired (in grid mode).

--remerge

Do not use any existing merges of yoda files: merge yoda files anew.

Default: False

--addtoDB

add results to an existing results file.

Default: False

--keep-hepmc

preserve the HepMC files if they are being generated (in grid mode).

Default: False

Batch system control

--template

Template Herwig .in file.

Default: “herwig.in”

--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

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

Rivet reading from pipe.

Default: False

-w, --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”

-V, --variable-precision

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

Default: False

--single

just generate one example directory, no job submission

Default: False

-N, --numpoints

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.

--main-program

Specify whether to use the main93 or main89 program for pythia8. Number of events for main89 presently have to be specified within your command file.

Default: “main93”

contur-export

Export a map file as a csv file.

contur-extract-xs-bf

Extract the cross sections and branching ratios from a single event generator log

contur-gridtool

Collection of utilities for operating on grids of yoda files

Various manipulations on a grid.

usage: contur-gridtool [-h] [-v] [-d] [-q] [-l LOG] [--offline] [--nomultip]
                       [--nopyscripts] [-p PARAM_FILE] [-g GRID] [-r RESULTS]
                       [--runname RUNNAME] [--tag TAG] [--map MAPFILE]
                       [--csv CSVFILE] [--remerge] [--addtoDB] [--keep-hepmc]
                       [--ana-match ANAPATTERNS] [--ana-unmatch ANAUNPATTERNS]
                       [-f FINDPARAMS] [--merge] [--remove-merged]
                       [--no-clean] [--archive] [-c] [--ca] [-S] [--detail]
                       [--plot] [-m MCEG]

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, --log

Specify logfile name.

Default: “contur.log”

--offline

Run in offline mode (no querying of inspire).

Default: False

--nomultip

Do not use multiprocessing.

Default: False

--nopyscripts

Disable writing of Python scripts for individualhistograms in grid mode.

Default: False

--ana-match

only run on analyses whose name matches this regex

Default: []

--ana-unmatch

exclude analyses whose name matches this regex

Default: []

-f, --find-point

identify points consistent with these parameters and make histograms for them

Default: []

-m, --mceg

MC event generator.

Default: “herwig”

Options relating to grid of results

-p, --param-steering-file

File specifying parameter space scanned.

Default: “param_file.dat”

-g, --grid

Run in grid mode on a folder containing a structured grid of points.

-r, --results

Name of the file for the results database.

--runname

Identifier for grid run

Default: “my_run”

--tag

Identifier for merged yoda files.

Default: “runpoint”

--map

Name of map (pickle) file output if desired (in grid mode).

--csv

Name of csv file output if desired (in grid mode).

--remerge

Do not use any existing merges of yoda files: merge yoda files anew.

Default: False

--addtoDB

add results to an existing results file.

Default: False

--keep-hepmc

preserve the HepMC files if they are being generated (in grid mode).

Default: False

Control options

--merge

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

Default: False

--remove-merged

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

Default: False

--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

--detail

output detailed information for certain parameter point

Default: False

--plot

make histograms for specified parameters (much slower!)

Default: False

contur-init

Make the contents of the user area (compile DB, new rivet routines etc)

contur-mapmerge

Merge a list of map files

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.

contur-oracle

Run the oracle

contur-plot

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

Plot contur maps from a results file.

usage: contur-plot [-h] [-v] [-d] [-q] [-l LOG] [--offline] [--nomultip]
                   [--nopyscripts] [-o OUTPUTDIR] [-i INPUTDIR]
                   [-ef EXTERNALFUNCTION] [-eg EXTERNALGRID] [-xl] [-yl]
                   [--pools] [-O OMIT] [-x XLABEL] [-y YLABEL] [-sp]
                   [-t TITLE] [--ilevel ILEVEL] [--iorder IORDER]
                   [--style {DRAFT,FINAL}] [--isigma ISIGMA]
                   [--num-dpools NDPOOLS] [--clstxt] [--no-clsdpool]
                   [-f PLOT_FORMAT] [--databg] [--secondary-contours]
                   [--interactive] [--cls CLS]
                   file [variables ...]

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, --log

Specify logfile name.

Default: “contur.log”

--offline

Run in offline mode (no querying of inspire).

Default: False

--nomultip

Do not use multiprocessing.

Default: False

--nopyscripts

Disable writing of Python scripts for individualhistograms in grid mode.

Default: False

-o, --outputdir

Output path.

Default: “conturPlot”

Map file plotting arguments

file

Path to result database file or map file that containing the info of model points .

variables

x, y [and z] variables to plot.

-i, --indir

the directory to look in for results.

Default: “ANALYSIS”

-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: “”

--ilevel, --iLevel

interpolation zoom level

Default: 3

--iorder, --iOrder

interpolation zoom spline order (1 to 5)

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

-f, --format

format for plots (pdf, png…)

Default: “pdf”

--databg

Make data-as-background the primary exclusion.

Default: False

--secondary-contours

Add contour(s) for stats other than the default.

Default: False

--interactive

Show figure in interactive mode

Default: False

--cls, --CLs

Minimum level of exclusion in order for citation to be printed in FINAL style.

Default: 0.68

contur-scan-xs-bf

Extract the cross sections and branching ratios from generator log files in a grid

contur-smtest

Run contur analysis on data vs SM theory

Running Standard Model comparisons.

usage: contur-smtest [-h] [-v] [-d] [-q] [-l LOG] [--offline] [--nomultip]
                     [--nopyscripts] [-o OUTPUTDIR] [-b BEAMS]
                     [--ana-match ANAPATTERNS] [--ana-unmatch ANAUNPATTERNS]
                     [--all] [--xr] [--tracks-only] [--soft-physics] [--xhg]
                     [--whw] [--wbv] [--awz] [-s] [--wn WEIGHTNAME] [-u]
                     [--tc] [--min-num-sys MNS] [--split-pools POOLPATTERNS]
                     [--ana-split ANASPLIT] [--spb] [--lle]
                     [--graphics GRAPHICS]

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, --log

Specify logfile name.

Default: “contur.log”

--offline

Run in offline mode (no querying of inspire).

Default: False

--nomultip

Do not use multiprocessing.

Default: False

--nopyscripts

Disable writing of Python scripts for individualhistograms in grid mode.

Default: False

-o, --outputdir

Output path.

-b, --beams
Select beams to run on. Default is to run on 13TeV.

Known beams are [‘13TeV’, ‘2_76TeV’, ‘7TeV’, ‘8TeV’, ‘all’]. NOTE: em_ep_91_2 is currently beta, see https://gitlab.com/hepcedar/rivet/-/issues/293.

Default: “all”

--ana-match

only run on analyses whose name matches this regex

Default: []

--ana-unmatch

exclude analyses whose name matches this regex

Default: []

--graphics

Generate rivet plot graphics.

Options to exclude/include subsets of data

--all

Convenience option to use all data. Overrides any other selections.

Default: False

--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

--tracks-only

Only use plots which are based on tracking informationUseful for models where calorimeter jet calibration may be suspect (e.g. dark showers).

Default: False

--soft-physics

Include plots which are very sensitive to soft QCD.Not reliable unless you really know what you are doing.

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: “”

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

-u, --diagonalise-cov

Use diagonal version of covariance matrix (ie no systematic correlations).

Default: False

--tc, --theorycorr

Assume SM theory uncertainties are correlated

Default: False

--min-num-sys

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

Default: 5

--split-pools

write out histograms from analyses in given pools separately

Default: []

--ana-split

write out histograms from given analyses separately

Default: []

--spb, --signal-plus-background

Tell contur that the input histos are signal-plus-background, not just signal

Default: False

--lle, --look-elsewhere

Treat plots with no signal as agreeing well. Otherwise (default) they are ignored.

Default: False