GitLocker: The Coding Marketplace

Description:

ivalutils 0.8.1

The package ivalutils provides classes for basic interval arithmetics as
well as classes for building sequences of adjacent intervals and for building
mappings of intervals to arbitrary values.
An Interval defines a subset of a set of values by optionally giving a lower
and / or an upper limit.
The base set of values - and therefore the given limits - must have a
common base type which defines a total order on the values.

Creating intervals
The simplest way is calling the class Interval without arguments, resulting
in both endpoints to be infinite:

>>> ival = Interval()
>>> ival
Interval()
>>> str(ival)
'(-inf .. +inf)'

For getting a more useful interval, it’s neccessary to specify atleast one
endpoint:

>>> ival = Interval(LowerClosedLimit(0))
>>> ival
Interval(lower_limit=Limit(True, 0, True))
>>> str(ival)
'[0 .. +inf)'

>>> ival = Interval(upper_limit=UpperClosedLimit(100.))
>>> ival
Interval(upper_limit=Limit(False, 100.0, True))
>>> str(ival)
'(-inf .. 100.0]'

>>> ival = Interval(LowerClosedLimit(0), UpperOpenLimit(27))
>>> ival
Interval(lower_limit=Limit(True, 0, True), upper_limit=Limit(False, 27, False))
>>> str(ival)
'[0 .. 27)'

Any type which defines a total ordering can be used for the limits:

>>> ClosedInterval('a', 'zzz')
Interval(lower_limit=Limit(True, 'a', True), upper_limit=Limit(False, 'zzz', True))

Several factory functions can be used as shortcut. For example:

>>> LowerClosedInterval(30)
Interval(lower_limit=Limit(True, 30, True))
>>> UpperOpenInterval(0)
Interval(upper_limit=Limit(False, 0, False))
>>> ClosedInterval(1, 3)
Interval(lower_limit=Limit(True, 1, True), upper_limit=Limit(False, 3, True))
>>> ChainableInterval(0, 5)
Interval(lower_limit=Limit(True, 0, True), upper_limit=Limit(False, 5, False))

Operations on intervals
The limits of an interval can be retrieved via properties:

>>> ival = ClosedInterval(0, 100)
>>> ival.lower_limit
Limit(True, 0, True)
>>> ival.upper_limit
Limit(False, 100, True)
>>> ival.limits
(Limit(True, 0, True), Limit(False, 100, True))

Several methods can be used to test for specifics of an interval. For example:

>>> ival.is_bounded()
True
>>> ival.is_finite()
True
>>> ival.is_left_open()
False

Intervals can be tested for including a value:

>>> 74 in ival
True
>>> -4 in ival
False

Intervals can be compared:

>>> ival2 = LowerOpenInterval(100)
>>> ival3 = LowerClosedInterval(100)
>>> ival < ival2
True
>>> ival < ival3
True
>>> ival2 < ival3
False
>>> ival2 == ival3
False
>>> ival3 < ival2
True
>>> ival2.is_adjacent(ival3)
False
>>> ival3.is_adjacent(ival2)
False
>>> ival4 = UpperClosedInterval(100)
>>> ival4.is_adjacent(ival2)
True
>>> ival.is_overlapping(ival3)
True
>>> ival.is_subset(ival4)
True

Creating sequences of adjacent intervals
The class IntervalChain is used to create sequences of adjacent intervals:

>>> ic = IntervalChain(('a', 'd', 'g', 'z'))
>>> ic
IntervalChain(('a', 'd', 'g', 'z'))

The default is to create an interval sequence which is lower-bound and
upper-infinite and containing lower-closed intervals:

>>> str(ic)
"[['a' .. 'd'), ['d' .. 'g'), ['g' .. 'z'), ['z' .. +inf)]"

By specifying additional parameters, you can determine which endpoints will be
closed and whether a lower and / or upper infinite endpoint will be added:

>>> ic = IntervalChain(('a', 'd', 'g', 'z'), lower_closed = False, add_lower_inf=True, add_upper_inf=False)
>>> str(ic)
"[(-inf .. 'a'], ('a' .. 'd'], ('d' .. 'g'], ('g' .. 'z']]"

Operations on interval chains
Interval chains can be indexed and iterated like lists …:

>>> ic[2]
Interval(lower_limit=Limit(True, 'd', False), upper_limit=Limit(False, 'g', True))
>>> [ival.upper_limit.value for ival in ic]
['a', 'd', 'g', 'z']

… and can be searched for the index of the interval holding a specified
value:

>>> ic.map2idx('b')
1
>>> ic.map2idx('a')
0
>>> ic.map2idx('aa')
1

Creating interval mappings
The class IntervalMapping is used to create a mapping from intervals to
arbitrary values.
Instances can be created by giving an IntervalChain and a sequence of
associated values …:

>>> im1 = IntervalMapping(IntervalChain((0, 300, 500, 1000)), (0., .10, .15, .20))

… or a sequence of limiting values and a sequence of associated values …:

>>> im2 = IntervalMapping((0, 300, 500, 1000), (0., .10, .15, .20))

… or a sequence of tuples, each holding a limiting value and an associated
value:

>>> im3 = IntervalMapping(((0, 0.), (300, .10), (500, .15), (1000, .20)))
>>> im1 == im2 == im3
True

Operations on IntervalMappings
Interval mappings behave like ordinary mappings:

>>> list(im3.keys())
[Interval(lower_limit=Limit(True, 0, True), upper_limit=Limit(False, 300, False)),
Interval(lower_limit=Limit(True, 300, True), upper_limit=Limit(False, 500, False)),
Interval(lower_limit=Limit(True, 500, True), upper_limit=Limit(False, 1000, False)),
Interval(lower_limit=Limit(True, 1000, True))]
>>> list(im3.values())
[0.0, 0.1, 0.15, 0.2]
>>> im3[Interval(lower_limit=Limit(True, 300, True), upper_limit=Limit(False, 500, False))]
0.1

In addition they can be looked-up for the value associated with the interval
which contains a given value:

>>> im3.map(583)
0.15

As a short-cut, the interval mapping can be used like a function:

>>> im3(412)
0.1

Use cases for interval mappings are for example:

determine the discount to be applied depending on an order value,
rating customers depending on their sales turnover,
classifying cities based on the number of inhabitants,
mapping booking dates to accounting periods,
grouping of measured values in discrete ranges.

For more details see the documentation on GitHub or at http://ivalutils.readthedocs.io.

History

Version
Changes

0.8.1
Additional tests (enhanced coverage).

0.8.0
First public release.