piso.intersection#

piso.intersection(interval_array, *interval_arrays, min_overlaps='all', squeeze=False, return_type='infer')#

Performs a set intersection 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 interval_array.

If interval_arrays is not empty then the sets are considered to be interval_array and the elements in interval_arrays. 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_arraypandas.IntervalIndex or pandas.arrays.IntervalArray: The first (and possibly only) operand to the intersection operation.
*interval_arraysargument list of pandas.IntervalIndex or pandas.arrays.IntervalArray: May contain zero or more arguments.
min_overlapsint or “all”, default “all”: Specifies the minimum number of intervals which overlap in order to define an intersection. If min_overlaps is an int then it must be no smaller than 2. If min_overlaps is all then an intersection is only defined where every interval overlaps. If supplied, must be done so as a keyword argument.
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

Examples with interval_arrays empty:

>>> arr = pd.arrays.IntervalArray.from_tuples(
...     [(0, 4), (2, 5), (3, 6)],
... )

>>> piso.intersection(arr)
<IntervalArray>
[(3.0, 4.0]]
Length: 1, closed: right, dtype: interval[float64]

>>> piso.intersection(pd.IntervalIndex(arr))
IntervalIndex([(3.0, 4.0]],
              closed='right',
              dtype='interval[float64]')

>>> piso.intersection(arr, return_type=pd.IntervalIndex)
IntervalIndex([(3.0, 4.0]],
              closed='right',
              dtype='interval[float64]')

>>> piso.intersection(arr)
<IntervalArray>
[]
Length: 0, closed: right, dtype: interval[int64]

>>> piso.intersection(arr, min_overlaps=2)
<IntervalArray>
[(2.0, 5.0]]
Length: 1, closed: right, dtype: interval[float64]

Examples with interval_arrays not 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)],
... )

>>> piso.intersection(arr1, arr2)
<IntervalArray>
[(3.0, 4.0]]
Length: 1, closed: right, dtype: interval[float64]

>>> piso.intersection(arr1, arr2, squeeze=True)
Interval(3.0, 4.0, closed='right')

>>> piso.intersection(arr1, arr2, arr3)
<IntervalArray>
[]
Length: 0, closed: right, dtype: interval[float64]

>>> piso.intersection(arr1, arr2, arr3, min_overlaps=2)
<IntervalArray>
[(3.0, 4.0], (10.0, 11.0]]
Length: 2, closed: right, dtype: interval[float64]