NminusOne#

class coffea.analysis_tools.NminusOne(names, nev, masks, delayed_mode, commonmask=None, wgtev=None, weights=None, weightsmodifier=None)[source]#

Bases: object

Object to be returned by PackedSelection.nminusone()

Methods Summary

plot_vars(vars[, axes, bins, start, stop, ...])

Plot the histograms of variables for each step of the N-1 selection

print([weighted, scale])

Prints the statistics of the N-1 selection

result([includeweights])

Returns the results of the N-1 selection as a namedtuple

to_npz(file[, compressed, compute, ...])

Saves the results of the N-1 selection to a .npz file

yieldhist([weighted, scale, categorical])

Returns the N-1 selection yields as a hist.Hist object

Methods Documentation

plot_vars(vars, axes=None, bins=None, start=None, stop=None, edges=None, transform=None, weighted=None, scale=None, categorical=None)[source]#

Plot the histograms of variables for each step of the N-1 selection

Parameters:

  • vars (dict) – A dictionary in the form {name: array} where name is the name of the variable, and array is the corresponding array of values. The arrays must be the same length as each mask of the N-1 selection.

  • axes (list of hist.axis objects, optional) – The axes objects to histogram the variables on. This will override all the following arguments that define axes. Must be the same length as vars.

  • bins (iterable of integers or Nones, optional) – The number of bins for each variable histogram. If not specified, it defaults to 20. Must be the same length as vars.

  • start (iterable of floats or integers or Nones, optional) – The lower edge of the first bin for each variable histogram. If not specified, it defaults to the minimum value of the variable array. Must be the same length as vars.

  • stop (iterable of floats or integers or Nones, optional) – The upper edge of the last bin for each variable histogram. If not specified, it defaults to the maximum value of the variable array. Must be the same length as vars.

  • edges (list of iterables of floats or integers, optional) – The bin edges for each variable histogram. This overrides bins, start, and stop if specified. Must be the same length as vars.

  • transform (iterable of hist.axis.transform objects or Nones, optional) – The transforms to apply to each variable histogram axis. If not specified, it defaults to None. Must be the same length as vars.

  • weighted (bool, optional) – Whether to fill the histograms with weights. Default is None, which applies the weights if the nminusone was instantiated with weights and unweighted distributions otherwise.

  • scale (float, optional) – A scalar value by which all weights will be scaled, works with both weighted and unweighted methods.

  • categorical (dict, optional) –

    A dictionary with the following keys:

    axishist.axis object

    The axis to be used as a categorical axis

    valueslist

    The array to be filled in the categorical axis, must be the same length as the masks

    labelslist

    The labels corresponding to the values in the categorical axis

    Default is None, which does not apply any categorical axis.

Returns:

  • hists (list of hist.Hist or hist.dask.Hist objects) – A list of 2D histograms of the variables for each step of the N-1 selection. The first axis is the variable, the second axis is the N-1 selection step.

  • labels (list of strings) – The bin labels of y axis of the histogram.

  • catlabels (list of strings, optional) – The labels of the categorical axis

print(weighted=None, scale=None)[source]#

Prints the statistics of the N-1 selection

Parameters:

  • weighted (bool, optional) – Whether to print the weighted statistics. Default is None, which prints the weighted statistics if the nminusone was instantiated with weights and unweighted statistics otherwise.

  • scale (float, optional) – A scale factor to apply to the nminusone statistics. Default is None, which does not apply any scaling.

result(includeweights=None)[source]#

Returns the results of the N-1 selection as a namedtuple

Parameters:

includeweights (bool, optional) – Whether to include the weights in the result. Default is None, which includes the weights if the Cutflow was instantiated with weights and excludes them otherwise.

Returns:

result – A namedtuple with the following attributes. If includeweights is False or weights were not provided, returns NminusOneResult. If includeweights is True and weights were provided, returns ExtendedNminusOneResult.

NminusOneResult attributes:

  • nevlist of integers or dask_awkward.lib.core.Scalar objects

    The number of events in each step of the N-1 selection as a list of integers or delayed integers

  • maskslist of boolean numpy.ndarray or dask_awkward.lib.core.Array objects

    The boolean mask vectors of which events pass the N-1 selection each time as a list of materialized or delayed boolean arrays

ExtendedNminusOneResult additional attributes:

  • commonmask : boolean numpy.ndarray or dask_awkward.lib.core.Array object, or None if no common mask was provided

  • wgtevlist of floats or dask_awkward.lib.core.Scalar objects, or None if no weights were provided

    The weighted number of events in each step of the N-1 selection as a list of floats or delayed floats

  • weightsfloat numpy.ndarray or dask_awkward.lib.core.Array object, or None if no weights were provided

    The Weights.weight(modifier) array provided as input. Must be masked by masks elements to get the corresponding weights

  • weightsmodifierstr or None

    The modifier passed to Weights.weight([modifier]) if weights were provided

Return type:

NminusOneResult or ExtendedNminusOneResult

to_npz(file, compressed=False, compute=False, includeweights=None)[source]#

Saves the results of the N-1 selection to a .npz file

Parameters:

  • file (str or file) – Either the filename (string) or an open file (file-like object) where the data will be saved. If file is a string or a Path, the .npz extension will be appended to the filename if it is not already there.

  • compressed (bool, optional) – If True, the data will be compressed in the .npz file. Default is False.

  • compute (bool, optional) – Whether to immediately start writing or to return an object that the user can choose when to start writing by calling compute(). Default is False.

  • includeweights (bool, optional) – Whether to save the weights in the npz file. Default is None, which saves the weights if the NminusOne was instantiated with weights

Returns:

out – If compute=True, returns None. Otherwise, returns an object that can be used to start writing the data by calling compute().

Return type:

NminusOneToNpz or None

yieldhist(weighted=None, scale=None, categorical=None)[source]#

Returns the N-1 selection yields as a hist.Hist object

Parameters:

  • weighted (bool, optional) – Whether to fill the histograms with weights. Default is None, which applies the weights if the nminusone was instantiated with weights and unweighted statistics otherwise.

  • categorical (dict, optional) –

    A dictionary with the following keys:

    axishist.axis object

    The axis to be used as a categorical axis

    valueslist

    The array to be filled in the categorical axis, must be the same length as the masks

    labelslist

    The labels corresponding to the values in the categorical axis

    Default is None, which does not apply any categorical axis.

Returns:

  • h (hist.Hist or hist.dask.Hist) – Histogram of the number of events surviving the N-1 selection

  • labels (list of strings) – The bin labels of the histogram

  • catlabels (list of strings) – The labels of the categorical axis