`columnflow.selection`#

Object and event selection tools.

Classes:

`Selector`(args, *kwargs)	Base class for all selectors.
`SelectionResult`([event, steps, objects, aux])	Lightweight class that wraps selection decisions (e.g.

Functions:

selector([func, bases, mc_only, data_only, ...])

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

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

Bases: TaskArrayFunction

Base class for all selectors.

Attributes:

exposed

Methods:

selector([func, bases, mc_only, data_only, ...])

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

exposed = False#

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 selector is skipped and not considered by other calibrators, selectors and producers in case they are evaluated 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 selector is skipped and not considered by other calibrators, selectors and producers in case they are evaluated 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) – Function to be wrapped and integrated into new Selector class.
bases (default: ()) – Additional bases for the new Selector.
mc_only (bool, default: False) – Boolean flag indicating that this Selector should only run on Monte Carlo simulation and skipped for real data.
data_only (bool, default: False) – Boolean flag indicating that this Selector should only run on real data and skipped for Monte Carlo simulation.
nominal_only (bool, default: False) – Boolean flag indicating that this Selector should only run on the nominal shift and skipped on any other shifts.
shifts_only (Sequence[str] | set[str] | None, default: None) – Shift names that this Selector should only run on, skipping all other shifts.

Return type:

DerivableMeta | Callable

Returns:

New Selector subclass.

selector(func=None, bases=(), mc_only=False, data_only=False, nominal_only=False, shifts_only=None, **kwargs)#

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

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

Parameters:

func (Callable | None, default: None) – Function to be wrapped and integrated into new Selector class.
bases (default: ()) – Additional bases for the new Selector.
mc_only (bool, default: False) – Boolean flag indicating that this Selector should only run on Monte Carlo simulation and skipped for real data.
data_only (bool, default: False) – Boolean flag indicating that this Selector should only run on real data and skipped for Monte Carlo simulation.
nominal_only (bool, default: False) – Boolean flag indicating that this Selector should only run on the nominal shift and skipped on any other shifts.
shifts_only (Sequence[str] | set[str] | None, default: None) – Shift names that this Selector should only run on, skipping all other shifts.

Return type:

DerivableMeta | Callable

Returns:

New Selector subclass.

class SelectionResult(event=None, steps=None, objects=None, aux=None, **other)[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 = {
    # boolean selection mask for events
    "event": selected_events_mask,

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

    "objects": {
        # object selection decisions or indices
        "Jet": {
            "jet": array_of_jet_indices,
            "bjet": array_of_bjet_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),
        ...,
    },

    # other arbitrary top-level fields
    ...
}

Specific fields can be configured through event, steps, objects and aux keyword arguments. All additional keyword arguments are stored as top-level fields.

The following example creates the structure above.

# combined event selection after all steps
event_sel = reduce(and_, results.steps.values())
res = SelectionResult(
    event=selected_event_mask,
    steps={
        "jet": array_of_event_masks,
        "muon": array_of_event_masks,
        ...
    },
    # nested mappings of source collections to target collections with different indices
    objects={
        # collections to be created from the initial "Jet" collection: "jet" and "bjet"
        # define name of new field and provide indices of the corresponding objects
        "Jet": {
            "jet": array_of_jet_indices
            "bjet": list_of_bjet_indices,
        },
        # collections to be created from the initial "Muon" collection: "muon"
        "Muon": {
            "muon": array_of_selected_muon_indices,
        },
    },
    # others
    ...
)
res.to_ak()

Methods:

to_ak()

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

to_ak()[source]#

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

The conversion is performed with multiple calls of ak.zip().

Raises:

ValueError – If the main events mask contains a type other than bool.
KeyError – If the additional top-level fields in other have a field “event”, “step” or “objects” that might overwrite existing special fields.

Return type:

Array

Returns:

SelectionResult transformed into an awkward array.

columnflow.selection

Contents

columnflow.selection#

`columnflow.selection`#