piso.complement

piso.complement(interval_array, domain=None)

Calculates the complement of a collection of intervals (in an array) over some domain.

Equivalent to the set difference of the domain and the intervals in the array.

Parameters

interval_arraypandas.IntervalIndex or pandas.arrays.IntervalArray

Contains the (possibly overlapping) intervals. Must be left-closed or right-closed.

domaintuple, pandas.Interval, pandas.IntervalIndex or pandas.arrays.IntervalArray, optional

Specifies the domain over which to calculate the “complement”. If domain is None, then the domain is considered to be the extremities of the intervals contained in interval_array If domain is a tuple then it should specify lower and upper bounds, and be equivalent to a pandas.Interval. If domain is a pandas.IntervalIndex or pandas.arrays.IntervalArray then the intervals it contains define a possibly disconnected domain.

Returns

pandas.IntervalIndex or pandas.arrays.IntervalArray

The return type will be the same as interval_array.

Examples

>>> import pandas as pd
>>> import piso

>>> arr1 = pd.arrays.IntervalArray.from_tuples(
...     [(0, 4), (3, 5), (7, 8)],
... )

>>> piso.complement(arr1)
<IntervalArray>
[(5, 7]]
Length: 1, closed: right, dtype: interval[int64]

>>> piso.complement(arr1, (-5, 10))
<IntervalArray>
[(-5, 0], (5, 7], (8, 10]]
Length: 3, closed: right, dtype: interval[int64]

>>> piso.complement(arr1, pd.Interval(-5, 6))
<IntervalArray>
[(-5, 0], (5, 6]]
Length: 2, closed: right, dtype: interval[int64]

>>> domain = pd.arrays.IntervalArray.from_tuples(
...     [(-5,-2), (7,10)],
... )

>>> piso.complement(arr1, domain)
<IntervalArray>
[(-5, -2], (8, 10]]
Length: 2, closed: right, dtype: interval[int64]