ftag.utils.metrics#

Tools for metrics module.

Functions#

save_divide(numerator, denominator[, default])

Save divide for denominator equal to 0.

weighted_percentile(arr, percentile[, weights])

Calculate weighted percentile.

calculate_efficiency(sig_disc, bkg_disc, target_eff[, ...])

Calculate efficiency.

calculate_rejection(sig_disc, bkg_disc, target_eff[, ...])

Calculate rejection.

calculate_efficiency_error(→ numpy.ndarray)

Calculate statistical efficiency uncertainty.

calculate_rejection_error(→ numpy.ndarray)

Calculate the rejection uncertainties.

get_discriminant(→ numpy.ndarray)

Calculate the tagging discriminant for a given tagger.

Module Contents#

ftag.utils.metrics.save_divide(numerator: numpy.ndarray | float, denominator: numpy.ndarray | float, default: float = 1.0)#

Save divide for denominator equal to 0.

Division using numpy divide function returning default value in cases where denominator is 0.

Parameters:

  • numerator (np.ndarray | float,) – Numerator in the ratio calculation.

  • denominator (np.ndarray | float,) – Denominator in the ratio calculation.

  • default (float) – Default value which is returned if denominator is 0.

Returns:

ratio – Result of the division

Return type:

np.ndarray | float

ftag.utils.metrics.weighted_percentile(arr: numpy.ndarray, percentile: numpy.ndarray, weights: numpy.ndarray = None)#

Calculate weighted percentile.

Implementation according to https://stackoverflow.com/a/29677616/11509698 (https://en.wikipedia.org/wiki/Percentile#The_weighted_percentile_method)

Parameters:

  • arr (np.ndarray) – Data array

  • percentile (np.ndarray) – Percentile array

  • weights (np.ndarray) – Weights array, by default None

Returns:

Weighted percentile array

Return type:

np.ndarray

ftag.utils.metrics.calculate_efficiency(sig_disc: numpy.ndarray, bkg_disc: numpy.ndarray, target_eff: float | list | numpy.ndarray, return_cuts: bool = False, sig_weights: numpy.ndarray = None, bkg_weights: numpy.ndarray = None)#

Calculate efficiency.

Parameters:

  • sig_disc (np.ndarray) – Signal discriminant

  • bkg_disc (np.ndarray) – Background discriminant

  • target_eff (float or list or np.ndarray) – Working point which is used for discriminant calculation

  • return_cuts (bool) – Specifies if the cut values corresponding to the provided WPs are returned. If target_eff is a float, only one cut value will be returned. If target_eff is an array, target_eff is an array as well.

  • sig_weights (np.ndarray) – Weights for signal events

  • bkg_weights (np.ndarray) – Weights for background events

Returns:

  • eff (float or np.ndarray) – Efficiency. Return float if target_eff is a float, else np.ndarray

  • cutvalue (float or np.ndarray) – Cutvalue if return_cuts is True. Return float if target_eff is a float, else np.ndarray

ftag.utils.metrics.calculate_rejection(sig_disc: numpy.ndarray, bkg_disc: numpy.ndarray, target_eff, return_cuts: bool = False, sig_weights: numpy.ndarray = None, bkg_weights: numpy.ndarray = None, smooth: bool = False)#

Calculate rejection.

Parameters:

  • sig_disc (np.ndarray) – Signal discriminant

  • bkg_disc (np.ndarray) – Background discriminant

  • target_eff (float or list) – Working point which is used for discriminant calculation

  • return_cuts (bool) – Specifies if the cut values corresponding to the provided WPs are returned. If target_eff is a float, only one cut value will be returned. If target_eff is an array, target_eff is an array as well.

  • sig_weights (np.ndarray) – Weights for signal events, by default None

  • bkg_weights (np.ndarray) – Weights for background events, by default None

Returns:

  • rej (float or np.ndarray) – Rejection. If target_eff is a float, a float is returned if it’s a list a np.ndarray

  • cut_value (float or np.ndarray) – Cutvalue if return_cuts is True. If target_eff is a float, a float is returned if it’s a list a np.ndarray

ftag.utils.metrics.calculate_efficiency_error(arr: numpy.ndarray, n_counts: int, suppress_zero_divison_error: bool = False, norm: bool = False) → numpy.ndarray#

Calculate statistical efficiency uncertainty.

Parameters:

  • arr (numpy.array) – Efficiency values

  • n_counts (int) – Number of used statistics to calculate efficiency

  • suppress_zero_divison_error (bool) – Not raising Error for zero division

  • norm (bool, optional) – If True, normed (relative) error is being calculated, by default False

Returns:

Efficiency uncertainties

Return type:

numpy.array

Raises:

ValueError – If n_counts <=0

Notes

This method uses binomial errors as described in section 2.2 of https://inspirehep.net/files/57287ac8e45a976ab423f3dd456af694

ftag.utils.metrics.calculate_rejection_error(arr: numpy.ndarray, n_counts: int, norm: bool = False) → numpy.ndarray#

Calculate the rejection uncertainties.

Parameters:

  • arr (numpy.array) – Rejection values

  • n_counts (int) – Number of used statistics to calculate rejection

  • norm (bool, optional) – If True, normed (relative) error is being calculated, by default False

Returns:

Rejection uncertainties

Return type:

numpy.array

Raises:

  • ValueError – If n_counts <=0

  • ValueError – If any rejection value is 0

Notes

Special case of eff_err()

ftag.utils.metrics.get_discriminant(jets: numpy.ndarray, tagger: str, signal: ftag.labels.Label, flavours: ftag.labels.LabelContainer, fraction_values: dict[str, float], epsilon: float = 1e-10) → numpy.ndarray#

Calculate the tagging discriminant for a given tagger.

Calculated as the logarithm of the ratio of a specified signal probability to a weighted sum ofbackground probabilities.

Parameters:

  • jets (np.ndarray) – Structured array of jets containing tagger outputs

  • tagger (str) – Name of the tagger

  • signal (Label) – Signal flavour (bjets/cjets or hbb/hcc)

  • fraction_values (dict) – Dict with the fraction values for the background classes for the given tagger

  • epsilon (float, optional) – Small number to avoid division by zero, by default 1e-10

Returns:

Array of discriminant values.

Return type:

np.ndarray

Raises:

ValueError – If the signal flavour is not recognised.