stats.trigger_rate module

class stats.trigger_rate.ratebin(arg0=None, arg1=None, count=None)

Bases: segment

A version of the segment class (see ligo.segments) that carries a count of things. Arithmetic operations update the count by interpreting the count as a uniform density of things throughout the interval spanned by the segment. For example, the intersection of two ratebins is the interval they have in common, and the intersection’s count is given by the sum of the densities of the two multiplied by the size of the intersection.

The implementation does not enforce the use of numeric values for boundaries and counts, but is unlikely to behave sensibly unless numeric values are used. One will also encounter problems with (semi-)open intervals due to the mean density being 0 for all finite counts in such intervals, and undefined otherwise.

Negative counts are allowed, and in particular the subtraction operation can yield a ratebin with a negative count if the density in the ratebin being subtracted is sufficiently high. If this is a concern, it is left as an excercise for the calling code to check for this condition.

Some behaviour has been selected to accomodate the specific needs of the intended application, and might not be sensible for general use outside of that application. For example, if the count is None then the density reported is 0, not None.

Like the segment class from which it is derived, ratebin objects are immutable: neither the boundaries, nor the count, can be modified after creation.

Example:

>>> # initialize from two boundary values without count
>>> x = ratebin(0, 10)
>>> x
None@[0,10)
>>> print(x.count)
None
>>> x.density   # count of None --> density = 0, not None
0.0
>>> # initialize from two boundary values with count
>>> x = ratebin(0, 10, count = 5)
>>> x
5@[0,10)
>>> x.density
0.5
>>> # intialize from a sequence without count
>>> y = ratebin((5, 15))
>>> y
None@[5,15)
>>> # intialize from a sequence with count
>>> y = ratebin((5, 15), count = 2.5)
>>> y.density
0.25
>>> # initialize from a ratebin without count
>>> ratebin(y)
2.5@[5,15)
>>> # initialize from a ratebin with count
>>> ratebin(y, count = 5)
5@[5,15)
>>> # arithmetic examples
>>> x | y
7.5@[0,15)
>>> x + y
7.5@[0,15)
>>> (x + y).density
0.5
>>> x - y
3.75@[0,5)
>>> (x - y).density
0.75
>>> x & y
3.75@[5,10)
>>> (x & y).density
0.75
>>> x & x
10@[0,10)
>>> x
5@[0,10)

BUGS: comparisons and hash behaviour are inherited from the segment class, specifically this means the count attribute is ignored for the purpose of comparisons. For example, a set will believe a ratebin object is already in the set if its boundaries match those of a ratebin in the set, regardless of what their counts are. A dictionary will do key look-up using the ratebin boundaries, only.

Example:

>>> x = ratebin(0, 10, count = 5)
>>> s = set([x])
>>> y = ratebin(0, 10, count = 10)
>>> y in s
True
>>> y == x
True
>>> x
5@[0,10)
>>> y
10@[0,10)
>>> # x and y compare as equal, so d gets only one entry
>>> d = {x: "a", y: "b"}
>>> d
{5@[0,10): 'b'}

contract(x)

Return a new segment whose bounds are given by adding x to the segment’s lower bound and subtracting x from the segment’s upper bound.

property count

property density

protract(x)

Return a new segment whose bounds are given by subtracting x from the segment’s lower bound and adding x to the segment’s upper bound.

shift(x)

Return a new segment whose bounds are given by adding x to the segment’s upper and lower bounds.

class stats.trigger_rate.ratebinlist

Bases: segmentlist

Modified version of the segmentlist type (see ligo.segments) whose arithmetic operations implement the segment-and-count arithmetic operations defined by the ratebin type.

This implemention has only been optimized for performance for the specific use cases for which it has been designed. It will likely be found to have unacceptable performance if used as a general-purpose segmentlist implementation.

Example:

>>> x0 = ratebinlist([ratebin(0, 10, count = 5)])
>>> x1 = ratebinlist([ratebin(5, 15, count = 2.5)])
>>> x2 = ratebinlist([ratebin(15, 25, count = 2.5)])
>>> x3 = ratebinlist([ratebin(20, 30, count = 5)])
>>> x0 | x1
[7.5@[0,15)]
>>> x0 | x1 | x2 | x3
[15@[0,30)]
>>> x0 - x1
[3.75@[0,5)]
>>> x0 | x2
[5@[0,10), 2.5@[15,25)]
>>> (x0 | x2).density
0.375
>>> x0 - x1
[3.75@[0,5)]
>>> x0.density
0.5
>>> (x0 - x1).density
0.75
>>> x0 - x2
[5@[0,10)]
>>> y = ratebinlist(x0)
>>> y.extend(x1)
>>> y.extend(x2)
>>> y.extend(x3)
>>> y
[5@[0,10), 2.5@[5,15), 2.5@[15,25), 5@[20,30)]
>>> y.coalesce()
[15@[0,30)]
>>> # slices are ratebinlist objects
>>> (x0 | x3)[1:].density
0.5
>>> # density is 0 at times with no segments
>>> x0.density_at(15)
0.0
>>> # and empty lists have a mean density of 0 (not NaN)
>>> (x0 & x2).density
0.0

NOTE: the XML I/O feature of this class will only work correctly for float-valued boundaries and integer counts.

add_ratebin(seg, count)

Convenience method. Equivalent to

self |= type(self)([ratebin(seg, count = count)])

Example:

>>> x = ratebinlist()
>>> x.add_ratebin((0, 10), 5)
>>> x.add_ratebin((10, 20), 5)
>>> x
[10@[0,20)]

coalesce()

Sort the elements of the list into ascending order, and merge continuous segments into single segments. Segmentlist is modified in place. This operation is O(n log n).

property count

property density

density_at(x)

find(item)

Return the smallest i such that i is the index of an element that wholly contains item. Raises ValueError if no such element exists.

NOTE: unlike the segmentlist class from which ratebinlist is derived, this implementation requires the ratebinlist to be coalesced.

Example:

>>> x = ratebinlist([ratebin(0, 10, count = 5), ratebin(15, 25, count = 2.5)])
>>> x.find(-1)
Traceback (most recent call last):
        ...
IndexError: -1
>>> x.find(0)
0
>>> x.find(5)
0
>>> # upper bounds of segments not included in span
>>> x.find(10)
Traceback (most recent call last):
        ...
IndexError: 10
>>> x.find(12)
Traceback (most recent call last):
        ...
IndexError: 12
>>> x.find(15)
1
>>> x.find(20)
1
>>> x.find(26)
Traceback (most recent call last):
        ...
IndexError: 26

classmethod from_xml(xml, name)

segmentlist()

Construct and return a segments.segmentlist of segments.segment objects by type-casting the contents.

to_xml(name)

class stats.trigger_rate.triggerrates(*args)

Bases: segmentlistdict

Example:

>>> x = triggerrates({
...             "H1": ratebinlist([
...                     ratebin((0, 10), count = 5),
...                     ratebin((20, 30), count = 5)
...             ]),
...             "V1": ratebinlist([
...                     ratebin((0, 15), count = 7),
...                     ratebin((25, 35), count = 7)
...             ])
...     })
...
>>> x
{'H1': [5@[0,10), 5@[20,30)], 'V1': [7@[0,15), 7@[25,35)]}
>>> y = x.copy()
>>> y
{'H1': [5@[0,10), 5@[20,30)], 'V1': [7@[0,15), 7@[25,35)]}
>>> y == x
True
>>> y is x
False
>>> y = triggerrates.from_xml(x.to_xml("test"), "test")
>>> y
{'H1': [5@[0.0,10.0), 5@[20.0,30.0)], 'V1': [7@[0.0,15.0), 7@[25.0,35.0)]}
>>> y == x
True
>>> y is x
False

property counts

property densities

density_at(x)

classmethod from_xml(xml, name)

intersection(keys)

Return the intersection of the segmentlists associated with the keys in keys.

See also .vote(). This method is equivalent to .vote(keys, len(keys)) with keys uniquified.

random_uniform()

segmentlistdict()

to_xml(name)

union(keys)

Return the union of the segmentlists associated with the keys in keys.