order.category
Contents
order.category#
Classes to describe object that help distinguishing events.
Contents
Class Channel#
- class Channel(*args, **kwargs)[source]#
Bases:
order.unique.UniqueObject
,order.mixins.CopyMixin
,order.mixins.AuxDataMixin
,order.mixins.TagMixin
,order.mixins.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 theTagMixin
, aux to theAuxDataMixin
, and name and id to theUniqueObject
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. SeeUniqueObjectIndex.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 theparent_channels
index of the added channel. An exception is raised when the number of allowed parents of a child channel is exceeded. SeeUniqueObjectIndex.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 thechannels
index of the added channel. An exception is raised when the number of allowed parents is exceeded. SeeUniqueObjectIndex.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 theparent_channels
index of all removed channels.
- clear_parent_channels()#
Removes all parent channels from the
parent_channels
index. Also removes this channel instance from thechannels
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 theparent_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 thechannels
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 theparent_channels
index of the removed channel. Unless silent is True, an error is raised if the object was not found. SeeUniqueObjectIndex.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 thechannels
index of the removed parent channel. Returns the removed object. Unless silent is True, an error is raised if the object was not found. SeeUniqueObjectIndex.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. SeeUniqueObjectIndex.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:
order.unique.UniqueObject
,order.mixins.CopyMixin
,order.mixins.AuxDataMixin
,order.mixins.TagMixin
,order.mixins.SelectionMixin
,order.mixins.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 theSelectionMixin
, tags to theTagMixin
, aux to theAuxDataMixin
, and name and id (defaulting to an auto id) to theUniqueObject
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
andparent_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
- 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 theparent_categories
index of the added category. SeeUniqueObjectIndex.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 thecategories
index of the added category. SeeUniqueObjectIndex.add()
for more info.
- clear_categories()#
Removes all child categories from the
categories
index. Also removes this category instance from theparent_categories
index of all removed categories.
- clear_parent_categories()#
Removes all parent categories from the
parent_categories
index. Also removes this category instance from thecategories
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 theparent_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 thecategories
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 theparent_categories
index of the removed category. Unless silent is True, an error is raised if the object was not found. SeeUniqueObjectIndex.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 thecategories
index of the removed parent category. Returns the removed object. Unless silent is True, an error is raised if the object was not found. SeeUniqueObjectIndex.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.