order.mixins#

Mixin classes providing common functionality.

Class CopyMixin#

class CopyMixin[source]#

Bases: object

Mixin-class that adds copy features to inheriting classes.

Inheriting classes can define a copy_specs class member, which is supposed to be a list containing specifications per attribute to be copied. See CopySpec and CopySpec.new() for information about possible copy specifications.

Note

At the moment, custom specs are only required for attributes that should not be copied but either carried over to the copied instance as a reference, or skipped in case only a shallow copy is requested via copy_shallow().

Example

import order as od

some_object = object()

class MyClass(od.CopyMixin):

    copy_specs = [
        {"attr": "obj", "ref": True},
        {"attr": "complex_obj", "ref": True, "skip_shallow": True},
    ]

    def __init__(self, name, obj, complex_obj=None):
        super(MyClass, self).__init__()
        self.name = name
        self.obj = obj
        self.complex_obj = complex_obj

a = MyClass("foo", some_object, "some_other_complex_object")
a.name
# -> "foo"

# normal copy

b = a.copy()
b.name
# -> "foo"

b.obj is a.obj
# -> True

b.complex_obj is a.complext_obj
# -> True

# shallow copy (skipping certain attributes)

c = a.copy_shallow()
c.name
# -> "foo"

c.obj is a.obj
# -> True

c.complex_obj is None  # note the None here
# -> True

Members

classattribute copy_specs#

type: list

List of copy specifications per attribute.

Methods:

copy(*args, **kwargs[, _specs, _skip])

Creates a copy of this instance and returns it.

copy_shallow(*args, **kwargs[, _specs, _skip])

Just like copy(), creates a copy of this instance and returns it, however with all attributes that were declared as skip_shallow skipped (see CopySpec).

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.

copy_shallow(*args, **kwargs, _specs=None, _skip=None)[source]#

Just like copy(), creates a copy of this instance and returns it, however with all attributes that were declared as skip_shallow skipped (see CopySpec).

Class CopySpec#

class CopySpec(dst, src=None, ref=False, ref_placeholder=None, skip=False, skip_shallow=False, skip_value=None)[source]#

Bases: object

Class holding attribute copy specifications. Instances of this class are used in CopyMixin to optionally describe the copy behavior individually per attribute. At the moment, copy specs only need to be created in case attributes should not be copied but carried over the the copied objects as a reference.

Arguments

dst is the destination attribute name, src is the source attribute. When ref is True, the attribute is not copied but a reference is passed to the newly created instance. Internally, this is done be temporarily setting the attribute to a ref_placeholder value, performing the deep copy, and then (re)setting the attribute to the original object.

When skip (skip_shallow) is True, the attribute is not copied when the source objects is copied through CopyMixin.copy() (CopyMixin.copy_shallow()). When skipped, the attribute of the copied object will be skip_value.

Members

dst#

type: string

The destination attribute.

src#

type: string

The source attribute.

ref#

type: bool

Whether or not the attribute should be passed as a reference instead of being copied.

ref_placeholder#

type: any

Placeholder value for attributes carried over as a reference that is used during the copying process.

skip#

type: bool

Whether or not the attribute is skipped when copied with CopyMixin.copy().

skip_shallow#

type: bool

Whether or not the attribute is skipped when copyied with CopyMixin.copy_shallow().

skip_value#

type: any

Value to be used for attributes that are skipped in the copy process.

Class AuxDataMixin#

class AuxDataMixin(aux=None)[source]#

Bases: object

Mixin-class that provides storage of auxiliary data via a simple interface.

Arguments

aux can be a dictionary or a list of 2-tuples to initialize the auxiliary data container. For convenient access via attributes, each instance of this mixin-class has a proxy object x which can be used to obtain auxiliary information. See example below.

Example

import order as od

class MyClass(od.AuxDataMixin):
    pass

c = MyClass(aux={"foo": "bar"})

# "foo" in c.aux
# same as c.has_aux("foo")
# -> True

c.set_aux("test", "some_value")
c.get_aux("test")
# -> "some_value"

c.get_aux("notthere")
# -> KeyError

c.get_aux("notthere", default=123)
# -> 123

c.x.test
# -> "some_value"

c.x("test")  # same as c.get_aux
# -> "some_value"

c.x.notthere
# -> AttributeError

Members

aux#

type: OrderedDict

The dictionary of auxiliary data.

x#

type: DotAccessProxy (read-only)

An object that provides simple attribute access to auxiliary data.

Methods:

set_aux(key, value)

Stores auxiliary value for a specific key.

has_aux(key)

Returns True when an auxiliary data entry for a specific key exists, False otherwise.

get_aux(key, [default])

Returns the auxiliary data for a specific key.

remove_aux(key[, silent])

Removes the auxiliary data for a specific key.

clear_aux()

Clears the auxiliary data container.

set_aux(key, value)[source]#

Stores auxiliary value for a specific key. Returns value.

has_aux(key)[source]#

Returns True when an auxiliary data entry for a specific key exists, False otherwise.

get_aux(key[, default])[source]#

Returns the auxiliary data for a specific key. If a default is given, it is returned in case key is not found.

remove_aux(key, silent=False)[source]#

Removes the auxiliary data for a specific key. Unless silent is True, an exception is raised if the key to remove is not found.

clear_aux()[source]#

Clears the auxiliary data container.

Class TagMixin#

class TagMixin(tags=None)[source]#

Bases: object

Mixin-class that allows inheriting objects to be attribute one or more tags. See the example below for more infos.

Arguments

tags initializes the internal set of stored tags.

Example

import order as od

class MyClass(od.TagMixin):
    pass

c = MyClass(tags={"foo", "bar"})

c.has_tag("foo")
# -> True

c.has_tag("baz")
# -> False

c.has_tag(("foo", "baz"), mode=any)  # the default mode
# -> True

c.has_tag(("foo", "baz"), mode=all)
# -> False

c.has_tag(("foo", "ba*"), mode=all)
# -> True

c.has_tag(("foo", "ba(r|z)"), mode=all, func="re")
# -> True

Members

tags#

type: set

The set of tags of this object. See has_tag() for information about how to evaluate them with patterns or regular expressions.

Methods:

add_tag(tag)

Adds a new tag to the set of tags.

remove_tag(tag)

Removes a previously added tag from the set if tags.

has_tag(tag[, mode])

Returns True when this object is tagged with tag, False otherwise.

add_tag(tag)[source]#

Adds a new tag to the set of tags.

remove_tag(tag)[source]#

Removes a previously added tag from the set if tags.

has_tag(tag, mode=any, **kwargs)[source]#

Returns True when this object is tagged with tag, False otherwise. When tag is a sequence of tags, the behavior is defined by mode. For any, the object is considered tagged when at least one of the provided tags matches. When all, all provided tags have to match. Each tag can be a fnmatch or re pattern. All kwargs are passed to util.multi_match().

Class DataSourceMixin#

class DataSourceMixin(is_data=False)[source]#

Bases: object

Mixin-class that provides convenience attributes for distinguishing between MC and real data.

Arguments

is_data initializes the same-named attribute.

Example

import order as od

class MyClass(od.DataSourceMixin):
    pass

c = MyClass(is_data=False)

c.is_data
# -> False

c.data_source
# -> "mc"

c.is_data = True
c.data_source
# -> "data"

Members

classattribute DATA_SOURCE_DATA#

type: string

The data source string for data ("data").

classattribute DATA_SOURCE_MC#

type: string

The data source string for mc ("mc").

classattribute allow_undefined_data_source#

type: boolean

A configuration flag for this class that decides whether empty (None) data sources are allowed. False by default.

is_data#

type: boolean

True if this object contains information on real data.

is_mc#

type: boolean

True if this object contains information on MC data.

data_source#

type: string

Either DATA_SOURCE_DATA or DATA_SOURCE_MC, depending on the source of contained data.

Class SelectionMixin#

class SelectionMixin(selection=None, str_selection_mode=None)[source]#

Bases: object

Mixin-class that adds attibutes and methods to describe a selection rule, either as strings, bare callables, or sequences of the two. When rules are defined as strings, ROOT- or numexpr-style expression syntax are supported with convenient logical concatenation.

Arguments

selection and str_selection_mode initialize the same-named attributes.

Example

import order as od

class MyClass(od.SelectionMixin):
    pass

# ROOT-style string expressions
c = MyClass(selection="branchA > 0", str_selection_mode=MyClass.MODE_ROOT)

c.selection
# -> "branchA > 0"

c.add_selection("myBranchB < 100")
c.selection
# -> "(myBranchA > 0) && (myBranchB < 100)"

c.add_selection("myWeight", op="*")
c.selection
# -> "((myBranchA > 0) && (myBranchB < 100)) * (myWeight)"

# numexpr-style string expressions
c = MyClass(selection="branchA > 0", str_selection_mode=MyClass.MODE_NUMEXPR)

c.add_selection("myBranchB < 100")
c.selection
# -> "(myBranchA > 0) & (myBranchB < 100)"

def my_selection(*args, **kwargs):
    ...

c.selection = my_selection
c.selection
# -> <function my_selection()>
c.str_selection_mode
# -> None
c.add_selection("myBranchB < 100")
# -> TypeError

Members

classattribute MODE_ROOT#

type: string

Flag denoting the ROOT-style selection mode ("root").

classattribute MODE_NUMEXP#

type: string

Flag denoting the numexpr-style selection mode ("numexpr").

classattribute default_str_selection_mode#

type: string

The default str_selection_mode when none is given in the instance constructor. It is initially set to MODE_NUMEXPR if order.util.ROOT_DEFAULT is false, or to MODE_ROOT otherwise.

selection#

type: string, callable, list

The selection string, callable or a sequence of them. When a string, str_selection_mode decides how the string is treated.

str_selection_mode#

type: string, None

The selection mode. Should either be MODE_ROOT or MODE_NUMEXPR. Only considered when selection is a string.

Methods:

add_selection(selection, **kwargs)

Adds a selection string to the current one if it is also a string.

add_selection(selection, **kwargs)[source]#

Adds a selection string to the current one if it is also a string. The new string will be logically connected via AND by default, which can be configured through kwargs. All kwargs are forwarded to util.join_root_selection() or util.join_numexpr_selection().

Class LabelMixin#

class LabelMixin(label=None, label_short=None)[source]#

Bases: object

Mixin-class that provides a label, a short version of that label, and some convenience attributes.

Arguments

label and label_short initialize the same-named attributes.

Example

import order as od

l = od.LabelMixin(label="Muon")

l.label
# -> "Muon"

# when not set, the short label returns the normal label
l.label_short
# -> "Muon"

l.label_short = r"$\mu$"
l.label_short
# -> "$\mu$"

# conversion to ROOT-style latex
l.label_short_root
# -> "#mu"

Members

label#

type: string

The label. When this object has a name (configurable via _label_fallback_attr) attribute, the label defaults to that value when not set.

label_root#

type: string (read-only)

The label, converted to ROOT-style latex.

label_short#

type: string

A short label, which defaults to the normal label when not set.

label_short_root#

type: string (read-only)

Short version of the label, converted to ROOT-style latex.

Class ColorMixin#

class ColorMixin(color=None, color1=None, color2=None, color3=None)[source]#

Bases: object

Mixin-class that provides a color in terms of RGB values as well as some convenience methods. Internally, up to three different color values are stored, accessible through attributes such as color1, color2 and color3. For convenience (and backwards compatibility), omitting the number will forward to the primary color (1).

Arguments

Each color arguments can be a tuple of 3 or 4 numbers that are interpreted as red, green and blue color values, and optinally an alpha value. Internally, all values are stored as floats, so when integers are passed, they are divided by 255. Similar to the access, when color1 is not set but color is, the latter is interpreted as the former.

Example

import order as od

c = od.ColorMixin(color=(255, 0.5, 100), color2="#00f")

c.color
# -> (1.0, 0.5, 0.392)

c.color_int
# -> (255, 128, 100)

c.color_alpha
# -> 1.0

c.color2_int
# -> (0, 0, 255)

Members

color1_r#

type: float

Red component of the primary color.

color1_g#

type: float

Green component of the primary color.

color1_b#

type: float

Blue component of the primary color.

color1_r_int#

type: int

Red component of the primary color, converted to an integer in the [0, 255] range.

color1_g_int#

type: int

Green component of the primary color, converted to an integer in the [0, 255] range.

color1_b_int#

type: int

Blue component of the primary color, converted to an integer in the [0, 255] range.

color1_alpha#

type: float

The alpha value of the primary color, defaults to 1.0.

color1#

type: tuple (float)

The RGB values of the primary color in a 3-tuple.

color1_int#

type: tuple (int)

The RGB int values of the primary color in a 3-tuple.

color2_r#

type: float

Red component of the secondary color.

color2_g#

type: float

Green component of the secondary color.

color2_b#

type: float

Blue component of the secondary color.

color2_r_int#

type: int

Red component of the secondary color, converted to an integer in the [0, 255] range.

color2_g_int#

type: int

Green component of the secondary color, converted to an integer in the [0, 255] range.

color2_b_int#

type: int

Blue component of the secondary color, converted to an integer in the [0, 255] range.

color2_alpha#

type: float

The alpha value of the secondary color, defaults to 1.0.

color2#

type: tuple (float)

The RGB values of the secondary color in a 3-tuple.

color2_int#

type: tuple (int)

The RGB int values of the secondary color in a 3-tuple.

color3_r#

type: float

Red component of the tertiary color.

color3_g#

type: float

Green component of the tertiary color.

color3_b#

type: float

Blue component of the tertiary color.

color3_r_int#

type: int

Red component of the tertiary color, converted to an integer in the [0, 255] range.

color3_g_int#

type: int

Green component of the tertiary color, converted to an integer in the [0, 255] range.

color3_b_int#

type: int

Blue component of the tertiary color, converted to an integer in the [0, 255] range.

color3_alpha#

type: float

The alpha value of the tertiary color, defaults to 1.0.

color3#

type: tuple (float)

The RGB values of the tertiary color in a 3-tuple.

color3_int#

type: tuple (int)

The RGB int values of the tertiary color in a 3-tuple.

color_r#

type: float

Shorthand for color1_r.

color_g#

type: float

Shorthand for color1_g.

color_b#

type: float

Shorthand for color1_b.

color_r_int#

type: int

Shorthand for color1_r_int.

color_g_int#

type: int

Shorthand for color1_g_int.

color_b_int#

type: int

Shorthand for color1_b_int.

color_alpha#

type: float

Shorthand for color1_alpha.

color#

type: tuple (float)

Shorthand for color1.

color_int#

type: tuple (int)

Shorthand for color1_int.