Systematic-uncertainty tools

Heppy provides tools to explore and treat the systematic variations of histograms. This notably means combining multiple systematic variations into a single combined systematic. Some examples include:

• Combining the members of a PDF set into the PDF uncertainty
• Adding several uncorrelated uncertainties in quadrature to get a resulting net uncertainty
• Combining a set of bootstrap replicas into a final uncertainty
• Taking the envelope of perturbative QCD scale variations to get an estimate of the fixed-order calculation uncertainty
• etc.

The basic usage is:

1. Create any number of heppy.uncertainty.model instances that specify which variations should be combined and how.
2. Call heppy.uncertainty.combine_copy, taking as arguments a histogram and a list of uncertainty models, to return a copy of the histogram where the combination models have been applied to the variations.

heppy.uncertainty.combine_add_quad(array, nominal)

heppy.uncertainty.combine_add_lin(array, nominal)

heppy.uncertainty.combine_symm_rms(array, nominal)

heppy.uncertainty.combine_asym_rms(array, nominal)

heppy.uncertainty.combine_envelope(array, nominal)

heppy.uncertainty.combine_asym_hessian(array, nominal)

heppy.uncertainty.combine_symm_hessian(array, nominal)

heppy.uncertainty.combine_asym_hessian_pairwise(array, nominal)

heppy.uncertainty.combine_symm_hessian_pairwise(array, nominal)

class heppy.uncertainty.model(name, keys, strategy, reference=None, postprocess=None, suffixes=('__hi', '__lo'), controlplot=None, matches_required=None)

Model for combining multiple variations into one uncertainty.

Contains information of which variations to combine how and what to call the result.

apply(histogram, controlplot_location=None)

WARNING: SIDE EFFECTS - this method will change the @histogram.corr_variations dictionary. @controlplots: if a directory (end with ‘/’) or prefix is given, control plots will be stored there for models that have them enabled (model.controlplot != None)

heppy.uncertainty.remove_same_sign_shifts(histogram, suffixes=['_1up', '_1down', '_up', '_down'])

Drop smaller same-sign correlated variation shifts from the nominal for any group of variations whose names differ only by (any number of occurrences of) any of the strings in matches

heppy.uncertainty.combine_copy(histogram, models, ignore_missing=False, controlplot_location=None, drop_same_sign_shifts=False, suffixes=['_1up', '_1down', '_up', '_down'])

@histogram: the input histogram. The return value will be a copy of this histogram, with the desired variation combinations applied. @models: iterable of the models to be applied @ignore_missing: if True, do not throw an exception if the input variations specified in a model are missing, but simply ignore the model @controlplot_location: if a directory (end with ‘/’) or prefix is given, control plots will be stored there for models that have them enabled (model.controlplot != None) :param drop_same_sign_shifts: if True, _correlated_ variation names that differ only by any suffix given in argument suffixes are grouped together. If more than one of these grouped variations has a shift with respect to the nominal in a given bin, only the largest shift in that bin is kept. The other shifts are set to zero (i.e. the variation is set to equal the nominal in the bin). A common case where this is useful is to avoid double-counting the same source of systematic uncertainty in bins where the “up” and “down” variation point in the same direction with respect to the nominal in some bin(s). Uncorrelated variations are not affected by this option. :type drop_same_sign_shifts: bool :param suffixes: see argument drop_same_sign_shifts for explanation :type suffixes: list of str

IMPORTANT NOTE: it is possible to apply combination models whose input variations are only produced in the same call of combine_copy. In other words,

the variations don’t yet need to exist in the @histogram.corr_variations when passing @histogram to combine_copy.