order.category

Classes to describe object that help distinguishing events.

Class Channel

class Channel(*args, **kwargs)

Bases: UniqueObject, CopyMixin, AuxDataMixin, TagMixin, LabelMixin

An object that descibes an analysis channel, often defined by a particular decay channel that results in distinct final state objects. A channel can have parent-child relations to other channels with one parent per child, and child relations to categories.

Arguments

References to contained categories are initialized with categories. label and label_short are passed to the LabelMixin, tags to the TagMixin, aux to the AuxDataMixin, and name, id and context to the UniqueObject constructor.

Copy behavior

All attributes are copied except for references to child channels and the parent channel as well as categories. Also note the copy behavior of UniqueObject’s.

Example

import order as od

# create a channel
SL_channel = od.Channel("SL", 1, label="lepton+jets")

# add child channels
e_channel  = SL_channel.add_channel("e", 1, label="e+jets")
mu_channel = SL_channel.add_channel("mu", 2)

len(SL_channel.channels)
# -> 2

len(e_channel.parent_channels)
# -> 1

e_channel.parent_channel
# -> SL_channel

# add categories
cat_e_2j = e_channel.add_category("e_2j",
    label="2 jets",
    selection="nJets == 2",
)

# print the category label
cat_e_2j.full_label
# -> "e+jets, 2 jets"

Members

categories
type: UniqueObjectIndex
read-only

The UniqueObjectIndex of child categories.

channels
type: UniqueObjectIndex
read-only

The UniqueObjectIndex of child channels.

parent_channels
type: UniqueObjectIndex
read-only

The UniqueObjectIndex of parent channels.

add_category(*args, **kwargs)

Adds a child category. See UniqueObjectIndex.add() for more info. Also sets the channel of the added category to this instance.

add_channel(*args, **kwargs)

Adds a child channel to the channels index and returns it. Also adds this channel to the parent_channels index of the added channel. An exception is raised when the number of allowed parents of a child channel is exceeded. See UniqueObjectIndex.add() for more info.

add_parent_channel(*args, **kwargs)

Adds a parent channel to the parent_channels index and returns it. Also adds this channel to the channels index of the added channel. An exception is raised when the number of allowed parents is exceeded. When context is None, the default_context of the channels index is used. See UniqueObjectIndex.add() for more info.

clear_categories(context=None)

Removes all child categories from the categories index for context. When context is None, the default_context of the categories index is used.

clear_channels(context=None)

Removes all child channels from the channels index for context. Also removes this channel instance from the parent_channels index of all removed channels. When context is None, the default_context of the channels index is used

clear_parent_channels(context=None)

Removes all parent channels from the parent_channels index for context. Also removes this channel instance from the channels index of all removed channel.

extend_categories(objs, context=None)

Adds multiple child categories to the categories index for context and returns the added objects in a list. When context is None, the default_context of the categories index is used.

extend_channels(objs, context=None)

Adds multiple child channels to the channels index for context and returns the added objects in a list. Also adds this channel to the parent_channels index of the added channel. An exception is raised when the number of allowed parents of a child channel is exceeded. When context is None, the default_context of the channels index is used.

extend_parent_channels(objs, context=None)

Adds multiple parent channels to the parent_channels index for context and returns the added objects in a list. Also adds this channel to the channels index of the added channel. An exception is raised when the number of allowed parent channels is exceeded. When context is None, the default_context of the channels index is used.

get_category(obj, deep=True, default=no_default, context=None)

Returns a child category given by obj, which might be a name, id, or an instance from the categories index for context. If deep is True, the lookup is recursive. When no category is found, default is returned when set. Otherwise, an error is raised. When context is None, the default_context of the categories index is used.

get_channel(obj, deep=True, default=no_default, context=None)

Returns a child channel given by obj, which might be a name, id, or an instance from the channels index for context. If deep is True, the lookup is recursive. When no channel is found, default is returned when set. Otherwise, an error is raised. When context is None, the default_context of the channels index is used.

get_leaf_categories(context=None)

Returns all child categories from the categories index for context that have no child categories themselves in a recursive fashion. When context is None, the default_context of the categories index is used.

get_leaf_channels(context=None)

Returns all child channels from the channels index for context that have no child channels themselves in a recursive fashion. When context is None, the default_context of the channels index is used.

get_parent_channel(obj, deep=True, default=no_default, context=None)

Returns a parent channel given by obj, which might be a name, id, or an instance from the parent_channels index for context. If deep is True, the lookup is recursive. When no channel is found, default is returned when set. Otherwise, an error is raised. When context is None, the default_context of the parent_channels index is used.

get_root_channels(context=None)

Returns all parent channels from the parent_channels index for context that have no parent channels themselves in a recursive fashion. When context is None, the default_context of the parent_channels index is used.

property has_categories

Returns True when this category has child categories, False otherwise.

has_category(obj, deep=True, context=None)

Checks if the categories index for context contains an obj which might be a name, id, or an instance. If deep is True, the lookup is recursive. When context is None, the default_context of the categories index is used.

has_channel(obj, deep=True, context=None)

Checks if the channels index for context contains an obj which might be a name, id, or an instance. If deep is True, the lookup is recursive. When context is None, the default_context of the channels index is used.

property has_channels

Returns True when this channel has child channels, False otherwise.

has_parent_channel(obj, deep=True, context=None)

Checks if the parent_channels index for context contains an obj, which might be a name, id, or an instance. If deep is True, the lookup is recursive. When context is None, the default_context of the parent_channels index is used.

property has_parent_channels

Returns True when this channel has parent channels, False otherwise.

property is_leaf_category

Returns True when this category has no child categories, False otherwise.

property is_leaf_channel

Returns True when this channel has no child channels, False otherwise.

property is_root_channel

Returns True when this channel has no parent channels, False otherwise.

remove_channel(obj, context=None, silent=False)

Removes a child channel given by obj, which might be a name, id, or an instance from the channels index for context and returns the removed object. Also removes this channel from the parent_channels index of the removed channel. When context is None, the default_context of the channels index is used. Unless silent is True, an error is raised if the object was not found. See UniqueObjectIndex.remove() for more info.

remove_parent_channel(obj=None, context=None, silent=False)

Removes the parent channel obj the parent_channels index for context. When obj is not None, it can be a name, id, or an instance referring to the parent channel for validation purposes. Also removes this instance from the channels index of the removed parent channel. Returns the removed object. When context is None, the default_context of the parent_channels index is used. Unless silent is True, an error is raised if the object was not found. See UniqueObjectIndex.remove() for more info.

walk_categories(context=None, depth_first=False, include_self=False)

Walks through the categories index for context and per iteration, yields a child category, its depth relative to this category, and its child categories in a list that can be modified to alter the walking. When context is None, the default_context of the categories index is used. When context is all, all indices are traversed. When depth_first is True, iterate depth-first instead of the default breadth-first. When include_self is True, also yield this category instance with a depth of 0.

walk_channels(context=None, depth_first=False, include_self=False)

Walks through the channels index for context and per iteration, yields a child channel, its depth relative to this channel, and its child channels in a list that can be modified to alter the walking. When context is None, the default_context of the channels index is used. When context is all, all indices are traversed. When depth_first is True, iterate depth-first instead of the default breadth-first. When include_self is True, also yield this channel instance with a depth of 0.

walk_parent_channels(context=None, depth_first=False, include_self=False)

Walks through the parent_channels index for context and per iteration, yields a parent channel, its depth relative to this channel, and its parent channels in a list that can be modified to alter the walking. When context is None, the default_context of the parent_channels index is used. When context is all, all indices are traversed. When depth_first is True, iterate depth-first instead of the default breadth-first. When include_self is True, also yield this channel instance with a depth of 0.

remove_category(*args, **kwargs)

Removes a child category. See UniqueObjectIndex.remove() for more info. Also resets the channel of the added category.

Class Category

class Category(name, id='+', channel=None, categories=None, label=None, label_short=None, selection=None, selection_mode=None, tags=None, aux=None, context=None)

Bases: UniqueObject, CopyMixin, AuxDataMixin, TagMixin, SelectionMixin, LabelMixin

Class that describes an analysis category. This is not to be confused with an analysis Channel. While the definition of a channel can be understood as being fixed by e.g. the final state of an event, a category describes an arbitrary sub phase-space. Therefore, a category can be (optionally) uniquely assigned to a channel - it has a channel.

Also, categories can be nested, i.e., they can have child and parent categories.

Arguments

channel should be a reference to a Channel instance or None. Child categories are initialized with categories.

label and label_short are forwarded to the LabelMixin, selection and selection_mode to the SelectionMixin, tags to the TagMixin, aux to the AuxDataMixin, and name, id (defaulting to an auto id) and context to the UniqueObject constructor.

Copy behavior

All attributes are copied except for references to child and parent categories. If set, the channel reference is kept. Also note the copy behavior of UniqueObject’s.

Example

import order as od

# toggle the default selection mode to Root-style selection string concatenation
od.Category.default_selection_mode = "root"

cat = od.Category("4j",
    label="4 jets",
    label_short="4j",
    selection="nJets == 4",
)

# note that no id needs to be passed to the Category constructor
# its id is set automatically based on the maximum id of currently existing category
# instances plus one (which is - of course - one in this example)
cat.id
# -> 1

cat.label
# -> "4 jets"

# add a channel
ch = od.Channel("dilepton", 1,
    label="Dilepton",
    label_short="DL"
)
cat.channel = ch

# the category is also assigned to the channel now
cat in ch.categories
# -> True

# and we can create the full category label
cat.full_label
# -> "Dilepton, 4 jets"

# and the short version of it
cat.full_label_short
# -> "DL, 4j"

# add a sub category
cat2 = cat.add_category("4j_2b",
    label=cat.label + ", 2 b-tags",
)

# set the selection string (could also be set in add_category above)
cat2.selection = [cat.selection, "nBTags == 2"]

cat2.selection
# -> "(nJets == 4) && (nBTags == 2)"

Members

channel
type: Channel, None

The channel instance of this category, or None when not set.

full_label
type: string
read-only

The label of this category, prefix with the channel label if a channel is set.

full_label_short
type: string
read-only

The short label of this category, prefix with the short channel label if a channel is set.

full_label_root
type: string
read-only

The label of this category, prefix with the channel label if a channel is set, converted to ROOT-style latex.

full_label_short_root
type: string
read-only

The short label of this category, prefix with the short channel label if a channel is set, converted to ROOT-style latex.

categories
type: UniqueObjectIndex
read-only

The UniqueObjectIndex of child categories.

parent_categories
type: UniqueObjectIndex
read-only

The UniqueObjectIndex of parent categories.

add_category(*args, **kwargs)

Adds a child category to the categories index and returns it. Also adds this category to the parent_categories index of the added category. See UniqueObjectIndex.add() for more info.

add_parent_category(*args, **kwargs)

Adds a parent category to the parent_categories index and returns it. Also adds this category to the categories index of the added category. When context is None, the default_context of the categories index is used. See UniqueObjectIndex.add() for more info.

clear_categories(context=None)

Removes all child categories from the categories index for context. Also removes this category instance from the parent_categories index of all removed categories. When context is None, the default_context of the categories index is used

clear_parent_categories(context=None)

Removes all parent categories from the parent_categories index for context. Also removes this category instance from the categories index of all removed category.

extend_categories(objs, context=None)

Adds multiple child categories to the categories index for context and returns the added objects in a list. Also adds this category to the parent_categories index of the added category. When context is None, the default_context of the categories index is used.

extend_parent_categories(objs, context=None)

Adds multiple parent categories to the parent_categories index for context and returns the added objects in a list. Also adds this category to the categories index of the added category. When context is None, the default_context of the categories index is used.

get_category(obj, deep=True, default=no_default, context=None)

Returns a child category given by obj, which might be a name, id, or an instance from the categories index for context. If deep is True, the lookup is recursive. When no category is found, default is returned when set. Otherwise, an error is raised. When context is None, the default_context of the categories index is used.

get_leaf_categories(context=None)

Returns all child categories from the categories index for context that have no child categories themselves in a recursive fashion. When context is None, the default_context of the categories index is used.

get_parent_category(obj, deep=True, default=no_default, context=None)

Returns a parent category given by obj, which might be a name, id, or an instance from the parent_categories index for context. If deep is True, the lookup is recursive. When no category is found, default is returned when set. Otherwise, an error is raised. When context is None, the default_context of the parent_categories index is used.

get_root_categories(context=None)

Returns all parent categories from the parent_categories index for context that have no parent categories themselves in a recursive fashion. When context is None, the default_context of the parent_categories index is used.

property has_categories

Returns True when this category has child categories, False otherwise.

has_category(obj, deep=True, context=None)

Checks if the categories index for context contains an obj which might be a name, id, or an instance. If deep is True, the lookup is recursive. When context is None, the default_context of the categories index is used.

property has_parent_categories

Returns True when this category has parent categories, False otherwise.

has_parent_category(obj, deep=True, context=None)

Checks if the parent_categories index for context contains an obj, which might be a name, id, or an instance. If deep is True, the lookup is recursive. When context is None, the default_context of the parent_categories index is used.

property is_leaf_category

Returns True when this category has no child categories, False otherwise.

property is_root_category

Returns True when this category has no parent categories, False otherwise.

remove_category(obj, context=None, silent=False)

Removes a child category given by obj, which might be a name, id, or an instance from the categories index for context and returns the removed object. Also removes this category from the parent_categories index of the removed category. When context is None, the default_context of the categories index is used. Unless silent is True, an error is raised if the object was not found. See UniqueObjectIndex.remove() for more info.

remove_parent_category(obj, context=None, silent=False)

Removes a parent category obj which might be a name, id, or an instance from the parent_categories index for context. Also removes this instance from the categories index of the removed parent category. Returns the removed object. When context is None, the default_context of the parent_categories index is used. Unless silent is True, an error is raised if the object was not found. See UniqueObjectIndex.remove() for more info.

walk_categories(context=None, depth_first=False, include_self=False)

Walks through the categories index for context and per iteration, yields a child category, its depth relative to this category, and its child categories in a list that can be modified to alter the walking. When context is None, the default_context of the categories index is used. When context is all, all indices are traversed. When depth_first is True, iterate depth-first instead of the default breadth-first. When include_self is True, also yield this category instance with a depth of 0.

walk_parent_categories(context=None, depth_first=False, include_self=False)

Walks through the parent_categories index for context and per iteration, yields a parent category, its depth relative to this category, and its parent categories in a list that can be modified to alter the walking. When context is None, the default_context of the parent_categories index is used. When context is all, all indices are traversed. When depth_first is True, iterate depth-first instead of the default breadth-first. When include_self is True, also yield this category instance with a depth of 0.