piso.accessor.ArrayAccessor.union

ArrayAccessor.union(*interval_arrays, squeeze=False, return_type='infer')

Performs a set union operation.

What is considered a set is determined by the number of positional arguments used, that is, determined by the size of interval_arrays.

If interval_arrays is empty then the sets are considered to be the intervals contained in the array object the accessor belongs to (an instance of pandas.IntervalIndex, pandas.arrays.IntervalArray).

If interval_arrays is not empty then the sets are considered to be the elements in interval_arrays, in addition to the intervals in the array object the accessor belongs to. Each of these arrays is assumed to contain disjoint intervals (and satisfy the definition of a set). Any array containing overlaps between intervals will be mapped to one with disjoint intervals via a union operation.

Parameters

*interval_arraysargument list of pandas.IntervalIndex or pandas.arrays.IntervalArray

May contain zero or more arguments.

squeezeboolean, default False

If True, will try to coerce the return value to a single pandas.Interval. If supplied, must be done so as a keyword argument.

return_type{“infer”, pandas.IntervalIndex, pandas.arrays.IntervalArray}, default “infer”

If “infer” the return type will be the same as interval_array. If supplied, must be done so as a keyword argument.

Returns

pandas.IntervalIndex or pandas.arrays.IntervalArray

Examples

>>> import pandas as pd
>>> import piso
>>> piso.register_accessors()

Examples with interval_arrays empty:

>>> arr = pd.arrays.IntervalArray.from_tuples(
...     [(0, 4), (2, 5), (3, 6), (7, 8), (8, 9), (10, 12)],
... )

>>> arr.piso.union()
<IntervalArray>
[(0.0, 6.0], (7.0, 9.0], (10.0, 12.0]]
Length: 3, closed: right, dtype: interval[float64]

>>> arr.set_closed("left").piso.union()
<IntervalArray>
[[0, 4), [2, 5), [3, 6), [7, 8), [8, 9), [10, 12)]
Length: 6, closed: left, dtype: interval[int64]

>>> pd.IntervalIndex(arr).piso.union()
IntervalIndex([(0.0, 6.0], (7.0, 9.0], (10.0, 12.0]],
              closed='right',
              dtype='interval[float64]')

>>> arr.piso.union(return_type=pd.IntervalIndex)
IntervalIndex([(0.0, 6.0], (7.0, 9.0], (10.0, 12.0]],
              closed='right',
              dtype='interval[float64]')

Examples with interval_arrays non empty:

>>> arr1 = pd.arrays.IntervalArray.from_tuples(
...     [(0, 4), (5, 6), (7, 8), (10, 12)],
... )
>>> arr2 = pd.arrays.IntervalArray.from_tuples(
...     [(3, 5), (8, 9)],
... )
>>> arr3 = pd.arrays.IntervalArray.from_tuples(
...     [(6, 8), (9, 11)],
... )

>>> arr1.piso.union(arr2)
<IntervalArray>
[(0.0, 6.0], (7.0, 9.0], (10.0, 12.0]]
Length: 3, closed: right, dtype: interval[float64]

>>> arr2.piso.union(arr3, return_type=pd.IntervalIndex)
IntervalIndex([(3.0, 5.0], (6.0, 11.0]],
              closed='right',
              dtype='interval[float64]')

>>> arr1.piso.union(arr2, arr3)
<IntervalArray>
[(0.0, 12.0]]
Length: 1, closed: right, dtype: interval[float64]

>>> arr1.piso.union(arr2, arr3, squeeze=True)
Interval(0.0, 12.0, closed='right')