Configuration schema

The configuration schema for cabinetry is given below. It is defined via a json schema that can be found at src/cabinetry/schemas/config.json.

The General block holds general settings, followed by blocks that take lists of objects: regions, samples, normalization factors, and systematics. The Regions, Samples and NormFactors blocks are required, while Systematics is optional. Settings shown in bold are required.

General

general settings

General settings

Regions

list of regions
type	array
items	a region
	Region
minItems	1
uniqueItems	True

Samples

list of samples
type	array
items	a sample
	Sample
minItems	1
uniqueItems	True

NormFactors

list of normalization factors
type	array
items	a normalization factor
	NormFactor
minItems	1
uniqueItems	True

Systematics

list of systematics
type	array
items	a systematic uncertainty
	Systematic
minItems	0
uniqueItems	True

Details about the setting blocks:

General settings

general settings
type	object
properties
Measurement	name of measurement
	type	string
POI	name of parameter of interest, defaults to empty string
	type	string
InputPath	path to input files
	type	string
HistogramFolder	folder to save histograms to and read histograms from
	type	string
Fixed	list of parameters to treat as constant in fits
	type	array
	items	a fixed parameter
		type	object
		properties
		Name	name of fixed parameter
			type	string
		Value	value to fix parameter to
			type	number
		additionalProperties	False
	minItems	1
	uniqueItems	True
VariationPath	(part of) path to file containing variation (for histogram inputs), defaults to empty string
	type	string
additionalProperties	False

Region

a region of phase space
required: Name + Variable + Binning (for ntuple inputs), Name (for histogram inputs)
type	object
properties
Name	name of the region
	type	string
Variable	variable to bin in
	type	string
Binning	binning to use in histograms
	type	array
	items	bins
		type	number
	minItems	2
	uniqueItems	True
Filter	selection criteria to apply
	type	string
RegionPath	(part of) path to file containing region
	type	string
additionalProperties	False

Sample

a sample of a specific process or data
required: Name + Tree (for ntuple inputs), Name (for histogram inputs)
type	object
properties
Name	name of the sample
	type	string
Tree	name of tree
	type	string
Filter	selection criteria to apply (override for region setting)
	type	string
Weight	weight to apply to events
	type	string
SamplePath	(part of) path(s) to input file(s)
	SamplePath setting
Data	if it is a data sample
	type	boolean
DisableStaterror	whether to disable the automatic inclusion of staterror modifiers for this sample, defaults to False
	type	boolean
Regions	region(s) that contain the sample, defaults to all regions
	Regions setting
additionalProperties	False

NormFactor

a normalization factor affecting one or more samples
type	object
properties
Name	name of the normalization factor
	type	string
Regions	region(s) that contain the normfactor, defaults to all regions
	Regions setting
Samples	affected sample(s), defaults to all samples
	Sample setting
Nominal	nominal value
	type	number
Bounds	lower and upper bound
	type	array
	items	bounds
		type	number
	maxItems	2
	minItems	2
	uniqueItems	True
additionalProperties	False

Systematic

a systematic uncertainty
type	object
properties
Name	name of the systematic uncertainty
	type	string
Type	type of systematic uncertainty
	type	string
	enum	Normalization, NormPlusShape
Up	template for “up” variation
	Template
Down	template for “down” variation
	Template
Regions	region(s) that contain the systematic, defaults to all regions
	Regions setting
Samples	affected sample(s), defaults to all samples
	Sample setting
Smoothing	smoothing to apply
	Smoothing setting
ModifierName	name of modifier in workspace, defaults to value set by Name
	type	string
additionalProperties	False

Common options:

Template

a systematic template (up/down)
type	object
properties
Tree	name of tree (override for nominal setting)
	type	string
Weight	weight to apply (override for nominal setting)
	type	string
Variable	variable to bin in (override for nominal setting)
	type	string
Filter	selection criteria to apply (override for region / sample setting)
	type	string
RegionPath	(part of) path to file containing region (override for nominal setting)
	type	string
SamplePath	(part of) path(s) to input file(s) (override for nominal setting)
	SamplePath setting
Normalization	normalization uncertainty to apply
	type	number
Symmetrize	whether to apply symmetrization
	type	boolean
VariationPath	(part of) path to file containing variation (for histogram inputs, override for general setting)
	type	string
additionalProperties	False

Sample setting

name(s) of affected sample(s)
oneOf	single affected sample
	type	string
	multiple affected samples
	type	array
	items	single affected sample
		type	string
	minItems	1
	uniqueItems	True

SamplePath setting

path(s) to input file(s) for histogram production
a list of paths is only supported for ntuple inputs
oneOf	path to single file
	type	string
	list of paths
	type	array
	items	path to single file
		type	string
	minItems	1
	uniqueItems	True

Regions setting

name(s) of region(s)
oneOf	single region
	type	string
	list of regions
	type	array
	items	single region
		type	string
	minItems	1
	uniqueItems	True

Smoothing setting

smoothing settings for template histograms
type	object
properties
Algorithm	name of smoothing algorithm to use
	type	string
	enum	353QH, twice
Regions	regions to apply smoothing in
	Regions setting
Samples	sample(s) to apply smoothing to, defaults to all samples
	Sample setting
additionalProperties	False