order.category

order.category #

Classes to describe object that help distinguishing events.

Class Channel#

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

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 and id to the UniqueObject constructor.

Copy behavior

copy()

All attributes are copied.

copy_shallow()

All attributs are copied except for child categories which is set to a default value instead.

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(
    name="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)[source]#: Adds a child category to the categories index and returns it. 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. See UniqueObjectIndex.add() for more info.

clear_categories()#: Removes all child categories from the categories index.

clear_channels()#: Removes all child channels from the channels index. Also removes this channel instance from the parent_channels index of all removed channels.

clear_parent_channels()#: Removes all parent channels from the parent_channels index. Also removes this channel instance from the channels index of all removed channel.

extend_categories(objs)#: Adds multiple child categories to the categories index and returns the added objects in a list.

extend_channels(objs)#: Adds multiple child channels to the channels index 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.

extend_parent_channels(objs)#: Adds multiple parent channels to the parent_channels index 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.

get_category(obj, deep=True, default=no_default)#: Returns a child category given by obj, which might be a name, id, or an instance from the categories index. If deep is True, the lookup is recursive through potentially nested child categories. When no category is found, default is returned when set. Otherwise, an error is raised.

get_channel(obj, deep=True, default=no_default)#: Returns a child channel given by obj, which might be a name, id, or an instance from the channels index. If deep is True, the lookup is recursive through potentially nested child channels. When no channel is found, default is returned when set. Otherwise, an error is raised.

get_leaf_categories()#: Returns all child categories from the categories index that have no child categories themselves in a recursive fashion. Possible duplicates due to nested structures are removed.

get_leaf_channels()#: Returns all child channels from the channels index that have no child channels themselves in a recursive fashion. Possible duplicates due to nested structures are removed.

get_parent_channel(obj, deep=True, default=no_default)#: Returns a parent channel given by obj, which might be a name, id, or an instance from the parent_channels index. If deep is True, the lookup is recursive through potentially nested parent channels. When no channel is found, default is returned when set. Otherwise, an error is raised.

get_root_channels()#: Returns all parent channels from the parent_channels index that have no parent channels themselves in a recursive fashion. Possible duplicates due to nested structures are removed.

property has_categories#: Returns True when this category has child categories, False otherwise.

has_category(obj, deep=True)#: Checks if the categories index contains an obj which might be a name, id, or an instance. If deep is True, the lookup is recursive through potentially nested child categories.

has_channel(obj, deep=True)#: Checks if the channels index contains an obj which might be a name, id, or an instance. If deep is True, the lookup is recursive through potentially nested child channels.

property has_channels#: Returns True when this channel has child channels, False otherwise.

has_parent_channel(obj, deep=True)#: Checks if the parent_channels index contains an obj, which might be a name, id, or an instance. If deep is True, the lookup is recursive through potentially nested parent channels.

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, silent=False)#: Removes a child channel given by obj, which might be a name, id, or an instance from the channels index and returns the removed object. Also removes this channel from the parent_channels index of the removed channel. 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, silent=False)#: Removes the parent channel obj the parent_channels index. 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. Unless silent is True, an error is raised if the object was not found. See UniqueObjectIndex.remove() for more info.

walk_categories(algo='bfs', depth_first=False, include_self=False)#

Walks through the categories index 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.

The traversal order is defined by algo which allows different values (more info):

"bfs": Breadth-first search.

"dfs_preorder": Pre-order depth-first search.

"dfs_postorder": Post-order depth-first search.

"dfs": Alias for "dfs_preorder".

"dfs_pre": Alias for "dfs_preorder".

"dfs_post": Alias for "dfs_postorder".

When include_self is True, this category instance is yielded as well with a depth of 0.

walk_channels(algo='bfs', depth_first=False, include_self=False)#

Walks through the channels index 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.

The traversal order is defined by algo which allows different values (more info):

"bfs": Breadth-first search.

"dfs_preorder": Pre-order depth-first search.

"dfs_postorder": Post-order depth-first search.

"dfs": Alias for "dfs_preorder".

"dfs_pre": Alias for "dfs_preorder".

"dfs_post": Alias for "dfs_postorder".

When include_self is True, this channel instance is yielded as well with a depth of 0.

walk_parent_channels(algo='bfs', depth_first=False, include_self=False)#

Walks through the parent_channels index 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.

The traversal order is defined by algo which allows different values (more info):

"bfs": Breadth-first search.

"dfs_preorder": Pre-order depth-first search.

"dfs_postorder": Post-order depth-first search.

"dfs": Alias for "dfs_preorder".

"dfs_pre": Alias for "dfs_preorder".

"dfs_post": Alias for "dfs_postorder".

When include_self is True, this channel instance is yielded as well with a depth of 0.

remove_category(*args, **kwargs)[source]#: Removes a child category from the categories index and returns the removed object. See UniqueObjectIndex.remove() for more info. Also resets the channel of the removed category.

Class Category#

class Category(name, id='+', channel=None, categories=None, label=None, label_short=None, selection=None, str_selection_mode=None, tags=None, aux=None)[source]#

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 str_selection_mode to the SelectionMixin, tags to the TagMixin, aux to the AuxDataMixin, and name and id (defaulting to an auto id) to the UniqueObject constructor.

Copy behavior

copy()

The channel attribute is carried over as a reference, all remaining attributes are copied. Note that the copied category is also registered in the channel. Also, please be aware that deep copies of heavily nested category structures might lead to python running into a recursion error (maximum recursion depth exceeded while calling a Python object). If this is the case, you might want to consider increasing the recursion depth.

copy_shallow()

All attributs are copied except for the channel, (child) categories and parent_categories which are set to default values instead.

Example

import order as od

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

cat = od.Category(
    name="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(
    name="dilepton",
    id=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(
    name="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.

copy(*args, **kwargs, _specs=None, _skip=None)[source]#: Creates a copy of this instance and returns it. All args and kwargs are converted to named arguments (based on the init signature) and set as attributes of the created copy. Additional specifications per attribute are taken from copy_specs or _specs if set. _skip can be a sequence of source attribute names that should be skipped.

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. See UniqueObjectIndex.add() for more info.

clear_categories()#: Removes all child categories from the categories index. Also removes this category instance from the parent_categories index of all removed categories.

clear_parent_categories()#: Removes all parent categories from the parent_categories index. Also removes this category instance from the categories index of all removed category.

extend_categories(objs)#: Adds multiple child categories to the categories index and returns the added objects in a list. Also adds this category to the parent_categories index of the added category.

extend_parent_categories(objs)#: Adds multiple parent categories to the parent_categories index and returns the added objects in a list. Also adds this category to the categories index of the added category.

get_category(obj, deep=True, default=no_default)#: Returns a child category given by obj, which might be a name, id, or an instance from the categories index. If deep is True, the lookup is recursive through potentially nested child categories. When no category is found, default is returned when set. Otherwise, an error is raised.

get_leaf_categories()#: Returns all child categories from the categories index that have no child categories themselves in a recursive fashion. Possible duplicates due to nested structures are removed.

get_parent_category(obj, deep=True, default=no_default)#: Returns a parent category given by obj, which might be a name, id, or an instance from the parent_categories index. If deep is True, the lookup is recursive through potentially nested parent categories. When no category is found, default is returned when set. Otherwise, an error is raised.

get_root_categories()#: Returns all parent categories from the parent_categories index that have no parent categories themselves in a recursive fashion. Possible duplicates due to nested structures are removed.

property has_categories#: Returns True when this category has child categories, False otherwise.

has_category(obj, deep=True)#: Checks if the categories index contains an obj which might be a name, id, or an instance. If deep is True, the lookup is recursive through potentially nested child categories.

property has_parent_categories#: Returns True when this category has parent categories, False otherwise.

has_parent_category(obj, deep=True)#: Checks if the parent_categories index contains an obj, which might be a name, id, or an instance. If deep is True, the lookup is recursive through potentially nested parent categories.

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, silent=False)#: Removes a child category given by obj, which might be a name, id, or an instance from the categories index and returns the removed object. Also removes this category from the parent_categories index of the removed category. Unless silent is True, an error is raised if the object was not found. See UniqueObjectIndex.remove() for more info.

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

walk_categories(algo='bfs', depth_first=False, include_self=False)#

Walks through the categories index 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.

The traversal order is defined by algo which allows different values (more info):

"bfs": Breadth-first search.

"dfs_preorder": Pre-order depth-first search.

"dfs_postorder": Post-order depth-first search.

"dfs": Alias for "dfs_preorder".

"dfs_pre": Alias for "dfs_preorder".

"dfs_post": Alias for "dfs_postorder".

When include_self is True, this category instance is yielded as well with a depth of 0.

walk_parent_categories(algo='bfs', depth_first=False, include_self=False)#

Walks through the parent_categories index 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.

The traversal order is defined by algo which allows different values (more info):

"bfs": Breadth-first search.

"dfs_preorder": Pre-order depth-first search.

"dfs_postorder": Post-order depth-first search.

"dfs": Alias for "dfs_preorder".

"dfs_pre": Alias for "dfs_preorder".

"dfs_post": Alias for "dfs_postorder".

When include_self is True, this category instance is yielded as well with a depth of 0.

order.category

Contents

order.category#

Class Channel#

Class Category#

order.category #