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

All attributes are copied.

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. 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. 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.

get_leaf_channels()

Returns all child channels from the channels index that have no child channels themselves in a recursive fashion.

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. 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.

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.

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.

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.

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(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. 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(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. 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(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. 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)[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, 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 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

The channel attribute is carried over as a reference, all remaining attributes are copied. Note that the copied dataset is also registered in the channel.

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(
    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. 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.

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. 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.

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.

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.

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(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. 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(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. 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.