# ivalutils 0.8.1

Basic interval arithmetic, sequences of intervals and mappings on intervals

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
False
False
>>> ival4 = UpperClosedInterval(100)
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.

Version Changes