piso.coverage#
- piso.coverage(interval_array, domain=None, bins=False, how='fraction')#
Calculates the fraction of a domain (or possibly multiple domains) covered by a collection of intervals.
Calculation over multiple domains is only possible when bins = True.
- Parameters
- interval_array
pandas.IntervalIndex
orpandas.arrays.IntervalArray
Contains the (possibly overlapping) intervals which partially, or wholly cover the domain. May be left-closed, right-closed, both, or neither.
- domain
tuple
,pandas.Interval
,pandas.IntervalIndex
orpandas.arrays.IntervalArray
, optional Specifies the domain over which to calculate the “coverage”. 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 apandas.IntervalIndex
orpandas.arrays.IntervalArray
then the intervals it contains define a possibly disconnected domain. If bins = True then domain must bepandas.IntervalIndex
orpandas.arrays.IntervalArray
with disjoint intervals.- binsboolean, default False
If False, then the domain is interpreted as a single domain and returns one value. If True, then domain is interpreted as disjoint bins over which coverage is calculated for each.
- how{“fraction”, “sum”}, default “fraction”
If how = “fraction” then the result is a fraction of the size of the domain. If how = “sum” then the result is the length of the domain covered.
New in version 0.8.0.
- interval_array
- Returns
- float or
pandas.Series
- float or
Examples
>>> import pandas as pd >>> import piso
>>> arr1 = pd.arrays.IntervalArray.from_tuples( ... [(0, 4), (3, 5), (7, 8)], ... )
>>> piso.coverage(arr1) 0.75
>>> piso.coverage(arr1, (0, 10)) 0.6
>>> piso.coverage(arr1, pd.Interval(-10, 10)) 0.3
>>> piso.coverage(arr1, pd.Interval(-10, 10), how="sum") 6
>>> domain = pd.arrays.IntervalArray.from_tuples( ... [(4,6), (7, 10)], ... ) >>> piso.coverage(arr1, domain) 0.4
>>> piso.coverage(arr1, domain, bins=True) (4, 6] 0.500000 (7, 10] 0.333333 dtype: float64
>>> piso.coverage(arr1, domain, bins=True, how="sum") (4, 6] 1.0 (7, 10] 1.0 dtype: float64