columnflow.selection

`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. event and object selection steps).

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: TaskArrayFunctionWithCalibratorRequirements

Base class for all selectors.

Attributes:

`exposed`
`mc_only`
`data_only`
`cache_instances`

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#

mc_only: bool = False#

data_only: bool = False#

classmethod selector(func=None, bases=(), mc_only=<object object>, data_only=<object object>, require_calibrators=<object object>, **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.

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 | UNSET_TYPE, default: <object object at 0x7d22b4d86760>) – Boolean flag indicating that this Selector should only run on Monte Carlo simulation and skipped for real data.
data_only (bool | UNSET_TYPE, default: <object object at 0x7d22b4d86760>) – Boolean flag indicating that this Selector should only run on real data and skipped for Monte Carlo simulation.
require_calibrators (Sequence[str] | set[str] | None | UNSET_TYPE, default: <object object at 0x7d22b4d86760>) – Sequence of names of calibrators to add to the requirements.

Return type:

DerivableMeta | Callable

Returns:

New Selector subclass.

cache_instances = True#

selector(func=None, bases=(), mc_only=<object object>, data_only=<object object>, require_calibrators=<object object>, **kwargs)#

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.

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 | UNSET_TYPE, default: <object object at 0x7d22b4d86760>) – Boolean flag indicating that this Selector should only run on Monte Carlo simulation and skipped for real data.
data_only (bool | UNSET_TYPE, default: <object object at 0x7d22b4d86760>) – Boolean flag indicating that this Selector should only run on real data and skipped for Monte Carlo simulation.
require_calibrators (Sequence[str] | set[str] | None | UNSET_TYPE, default: <object object at 0x7d22b4d86760>) – Sequence of names of calibrators to add to the requirements.

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`#