Weights#

class coffea.analysis_tools.Weights(size, storeIndividual=False)[source]#

Bases: object

Container for event weights and associated systematic shifts

This container keeps track of correction factors and systematic effects that can be encoded as multiplicative modifiers to the event weight. All weights are stored in vector form.

Parameters:

  • size (int or None) – size of the weight arrays to be handled (i.e. the number of events / instances). If None then we expect to operate in delayed mode.

  • storeIndividual (bool, optional) – store not only the total weight + variations, but also each individual weight. Default is false.

Attributes Summary

variations

List of available modifiers

weightStatistics

Statistics about the weight, including the sum of squared weights and number of entries.

Methods Summary

add(name, weight[, weightUp, weightDown, shift])

Add a new weight

add_multivariation(name, weight, ...[, shift])

Add a new weight with multiple variations

partial_weight([include, exclude, modifier])

Partial event weight vector

weight([modifier])

Returns the current event weight vector

Attributes Documentation

variations#

List of available modifiers

weightStatistics#

Statistics about the weight, including the sum of squared weights and number of entries.

Methods Documentation

add(name, weight, weightUp=None, weightDown=None, shift=False)[source]#

Add a new weight

Adds a named correction to the event weight, and optionally also associated systematic uncertainties.

Parameters:

  • name (str) – name of correction

  • weight (numpy.ndarray) – the nominal event weight associated with the correction

  • weightUp (numpy.ndarray, optional) – weight with correction uncertainty shifted up (if available)

  • weightDown (numpy.ndarray, optional) – weight with correction uncertainty shifted down. If weightUp is supplied, and the correction uncertainty is symmetric, this can be set to None to auto-calculate the down shift as 1 / weightUp.

  • shift (bool, optional) – if True, interpret weightUp and weightDown as a relative difference (additive) to the nominal value

Note

weightUp and weightDown are assumed to be rvalue-like and may be modified in-place by this function

add_multivariation(name, weight, modifierNames, weightsUp, weightsDown, shift=False)[source]#

Add a new weight with multiple variations

Each variation of a single weight is given a different modifier name. This is particularly useful e.g. for btag SF variations.

Parameters:

  • name (str) – name of correction

  • weight (numpy.ndarray) – the nominal event weight associated with the correction

  • modifierNames (list of str) – list of modifiers for each set of weights variation

  • weightsUp (list of numpy.ndarray) – weight with correction uncertainty shifted up (if available)

  • weightsDown (list of numpy.ndarray) – weight with correction uncertainty shifted down. If weightUp is supplied, and the correction uncertainty is symmetric, this can be set to None to auto-calculate the down shift as 1 / weightUp.

  • shift (bool, optional) – if True, interpret weightUp and weightDown as a relative difference (additive) to the nominal value

Note

weightUp and weightDown are assumed to be rvalue-like and may be modified in-place by this function

partial_weight(include=[], exclude=[], modifier=None)[source]#

Partial event weight vector

Return a partial weight by multiplying a subset of all weights. Can be operated either by specifying weights to include or weights to exclude, but not both at the same time. The method can only be used if the individual weights are stored via the storeIndividual argument in the Weights initializer.

Parameters:

  • include (list) – Weight names to include, defaults to []

  • exclude (list) – Weight names to exclude, defaults to []

  • modifier (str, optional) – if supplied, provide event weight corresponding to a particular systematic uncertainty shift, of form str(name + 'Up') or (Down)

Returns:

weight – The weight vector, corresponding to only the effect of the corrections specified.

Return type:

numpy.ndarray

weight(modifier=None)[source]#

Returns the current event weight vector

Parameters:

modifier (str, optional) – if supplied, provide event weight corresponding to a particular systematic uncertainty shift, of form str(name + 'Up') or (Down)

Returns:

weight – The weight vector, possibly modified by the effect of a given systematic variation.

Return type:

numpy.ndarray