fast_carpenter.selection.stage module¶

Stages to remove events from subsequent stages

Provides two stages:

CutFlow – Prevent subsequent stages from seeing certain events,

SelectPhaseSpace – Create a new variable which can be used as a mask

Both stages are configured very similarly, and both stages produce an output table describing how many events pass each subsequent cut to make it into the final mask.

class fast_carpenter.selection.stage.CutFlow(name, out_dir, selection_file=None, keep_unique_id=False, selection=None, counter=True, weights=None)[source]¶

Bases: object

Prevents subsequent stages seeing certain events.

The two most important parameters to understand are the selection and weights parameters.

Parameters:

selection (str or dict) – The criteria for selecting events, formed by a nested set of “cuts”. Each cut must either be a valid Expressions or a single-length dictionary, with one of Any or All as the key, and a list of cuts as the value.
weights (str or list[str], dict[str, str]) – How to weight events in the output summary table. Must be either a single variable, a list of variables, or a dictionary where the values are variables in the data and keys are the column names that these weights should be called in the output tables.

Example

Mask events using a single cut based on the nJet variable being greater than 2 and weight events in the summary table by the EventWeight variable:

cut_flow_1:
    selection:
        nJet > 2
    weights: EventWeight

Mask events by requiring both the nMuon variable being greater than 2 and the first Muon_energy value in each event being above 20. Don’t weight events in the summary table:

cut_flow_2:
    selection:
        All:
          - nMuon > 2
          - {reduce: 0, formula: Muon_energy > 20}

Mask events by requiring the nMuon variable be greater than 2 and either the first Muon_energy value in each event is above 20 or the total_energy is greater than 100. The summary table will weight events by both the EventWeight variable (called weight_nominal in the table) and the SystUp variable (called weight_syst_up in the summary):

cut_flow_3:
    selection:
        All:
          - nMuon > 2
          - Any:
            - {reduce: 0, formula: Muon_energy > 20}
            - total_energy > 100
    weights: {weight_nominal: EventWeight, weight_syst_up: SystUp}

Other Parameters:

name (str) – The name of this stage (handled automatically by fast-flow)
out_dir (str) – Where to put the summary table (handled automatically by fast-flow)
selection_file (str) – Deprecated
keep_unique_id (bool) – If True, the summary table will contain a column that gives each cut a unique id. This is used internally to maintain the cut order, and often will not be useful in subsequent manipulation of the output table, so by default this is removed.
counter (bool) – Currently unused

Raises:

BadCutflowConfig – If neither or both of selection and selection_file are provided, or if a bad selection or weight configuration is given.

See also

SelectPhaseSpace: Adds the resulting event-mask as a new variable to the data.

selection.filters.build_selection(): Handles the actual creation of the event selection, based on the configuration.

numexpr: which is used for the internal expression handling.

collector()[source]¶

event(chunk)[source]¶

merge(rhs)[source]¶

class fast_carpenter.selection.stage.SelectPhaseSpace(name, out_dir, region_name, **kwargs)[source]¶

Bases: fast_carpenter.selection.stage.CutFlow

Creates an event-mask and adds it to the data-space.

This is identical to the CutFlow class, except that the resulting mask is added to the list of variables in the data-space, rather than being used directly to remove events. This allows multiple “regions” to be defined using different CutFlows in a single configuration.

Parameters:	region_name – The name given to the resulting mask when added to back to the data-space.