columnflow.selection#

Object and event selection tools.

Selector#

class Selector(*args, **kwargs)[source]#

Bases: TaskArrayFunction

Base class for all selectors.

__init__(*args, **kwargs)[source]#
classmethod selector(func=None, bases=(), mc_only=False, data_only=False, nominal_only=False, shifts_only=None, **kwargs)[source]#

Decorator for creating a new Selector subclass with additional, optional bases and attaching the decorated function to it as call_func.

When mc_only (data_only) is True, the calibrator is skipped and not considered by other calibrators, selectors and producers in case they are evalauted on a order.Dataset (using the dataset_inst attribute) whose is_mc (is_data) attribute is False.

When nominal_only is True or shifts_only is set, the calibrator is skipped and not considered by other calibrators, selectors and producers in case they are evalauted on a order.Shift (using the global_shift_inst attribute) whose name does not match.

All additional kwargs are added as class members of the new subclasses.

Parameters:

  • func (Callable | None, default: None) – Callable that is used to perform the selections

  • bases (default: ()) – Additional bases for new subclass

  • mc_only (bool, default: False) – Flag to indicate that this Selector should only run on Monte Carlo Simulation

  • data_only (bool, default: False) – Flag to indicate that this Selector should only run on observed data

Return type:

DerivableMeta | Callable

Returns:

New Selector instance

SelectionResult#

class SelectionResult(main=None, steps=None, objects=None, aux=None)[source]#

Bases: AuxDataMixin

Lightweight class that wraps selection decisions (e.g. event and object selection steps).

Additionally, this class provides convenience methods to merge them or to dump them into an awkward array. Arbitrary, auxiliary information (additional arrays, or other objects) that should not be stored in dumped akward arrays can be placed in the aux dictionary (see AuxDataMixin).

The resulting structure looks like the following example:

results = {
    # arbitrary, top-level main fields
    ...

    "steps": {
        # event selection decisions from certain steps
        "jet": array_of_event_masks,
        "muon": array_of_event_masks,
        ...,
    },

    "objects": {
        # object selection decisions or indices
        # define type of this field here, define that `jet` is of
        # type `Jet`
        "Jet": {
            "jet": array_of_jet_indices,
        },
        "Muon": {
            "muon": array_of_muon_indices,
        },
        ...,
    },
    # additionally, you can also save auxiliary data, e.g.
    "aux": {
        # save the per-object jet selection masks
        "jet": array_of_jet_object_masks,
        # save number of jets
        "n_passed_jets": ak.num(array_of_jet_indices, axis=1),
        ...,
    },
    ...
}

The fields can be configured through the main, steps and objects keyword arguments. The following example creates the structure above.

# combined event selection after all steps
event_sel = reduce(and_, results.steps.values())
res = SelectionResult(
    main={
        "event": event_sel,
    },
    steps={
        "jet": array_of_event_masks,
        "muon": array_of_event_masks,
        ...
    },
    objects={
        "Jet": {
            "jet": array_of_jet_indices
        },
        "Muon": {
            "muon": array, ...
        }
    }
)
res.to_ak()
__init__(main=None, steps=None, objects=None, aux=None)[source]#
__iadd__(other)[source]#

Adds the field of an other instance in-place.

When None, this instance is returned unchanged.

Parameters:

other (SelectionResult | None) – Instance of SelectionResult to be added to current instance

Raises:

TypeError – if other is not a SelectionResult instance

Return type:

SelectionResult

Returns:

This instance after adding operation

__add__(other)[source]#

Returns a new instance with all fields of this and an other instance merged.

When None, a copy of this instance is returned.

Parameters:

other (SelectionResult | None) – Instance of SelectionResult to be added to current instance

Raises:

TypeError – if other is not a SelectionResult instance

Return type:

SelectionResult

Returns:

This instance after adding operation

to_ak()[source]#

Converts the contained fields into a nested awkward array and returns it.

The conversion is performed with multiple calls of .

Return type:

Array

Returns:

Transformed SelectionResult

Submodules#