diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 433118e648827..a82ba18d6798e 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -172,16 +172,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.Period.asfreq \ pandas.Period.now \ pandas.arrays.PeriodArray \ - pandas.Interval.closed \ - pandas.Interval.left \ - pandas.Interval.length \ - pandas.Interval.right \ - pandas.arrays.IntervalArray.left \ - pandas.arrays.IntervalArray.right \ - pandas.arrays.IntervalArray.closed \ - pandas.arrays.IntervalArray.mid \ - pandas.arrays.IntervalArray.length \ - pandas.arrays.IntervalArray.is_non_overlapping_monotonic \ pandas.arrays.IntervalArray.from_arrays \ pandas.arrays.IntervalArray.to_tuples \ pandas.Int8Dtype \ @@ -310,9 +300,7 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.CategoricalIndex.as_ordered \ pandas.CategoricalIndex.as_unordered \ pandas.CategoricalIndex.equals \ - pandas.IntervalIndex.closed \ pandas.IntervalIndex.values \ - pandas.IntervalIndex.is_non_overlapping_monotonic \ pandas.IntervalIndex.to_tuples \ pandas.MultiIndex.dtypes \ pandas.MultiIndex.drop \ diff --git a/pandas/_libs/interval.pyx b/pandas/_libs/interval.pyx index fe405b98f218c..074e9b19eaf72 100644 --- a/pandas/_libs/interval.pyx +++ b/pandas/_libs/interval.pyx @@ -188,6 +188,14 @@ cdef class IntervalMixin: See Also -------- Interval.is_empty : Indicates if an interval contains no points. + + Examples + -------- + >>> interval = pd.Interval(left=1, right=2, closed='left') + >>> interval + Interval(1, 2, closed='left') + >>> interval.length + 1 """ return self.right - self.left @@ -369,11 +377,27 @@ cdef class Interval(IntervalMixin): cdef readonly object left """ Left bound for the interval. + + Examples + -------- + >>> interval = pd.Interval(left=1, right=2, closed='left') + >>> interval + Interval(1, 2, closed='left') + >>> interval.left + 1 """ cdef readonly object right """ Right bound for the interval. + + Examples + -------- + >>> interval = pd.Interval(left=1, right=2, closed='left') + >>> interval + Interval(1, 2, closed='left') + >>> interval.right + 2 """ cdef readonly str closed @@ -381,6 +405,14 @@ cdef class Interval(IntervalMixin): String describing the inclusive side the intervals. Either ``left``, ``right``, ``both`` or ``neither``. + + Examples + -------- + >>> interval = pd.Interval(left=1, right=2, closed='left') + >>> interval + Interval(1, 2, closed='left') + >>> interval.closed + 'left' """ def __init__(self, left, right, str closed="right"): diff --git a/pandas/core/arrays/interval.py b/pandas/core/arrays/interval.py index 48540113e8766..2303f8334c07c 100644 --- a/pandas/core/arrays/interval.py +++ b/pandas/core/arrays/interval.py @@ -1266,6 +1266,17 @@ def _format_space(self) -> str: def left(self): """ Return the left endpoints of each Interval in the IntervalArray as an Index. + + Examples + -------- + + >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(2, 5)]) + >>> interv_arr + + [(0, 1], (2, 5]] + Length: 2, dtype: interval[int64, right] + >>> interv_arr.left + Index([0, 2], dtype='int64') """ from pandas import Index @@ -1275,6 +1286,17 @@ def left(self): def right(self): """ Return the right endpoints of each Interval in the IntervalArray as an Index. + + Examples + -------- + + >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(2, 5)]) + >>> interv_arr + + [(0, 1], (2, 5]] + Length: 2, dtype: interval[int64, right] + >>> interv_arr.right + Index([1, 5], dtype='int64') """ from pandas import Index @@ -1284,6 +1306,17 @@ def right(self): def length(self) -> Index: """ Return an Index with entries denoting the length of each Interval. + + Examples + -------- + + >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(1, 5)]) + >>> interv_arr + + [(0, 1], (1, 5]] + Length: 2, dtype: interval[int64, right] + >>> interv_arr.length + Index([1, 4], dtype='int64') """ return self.right - self.left @@ -1291,6 +1324,17 @@ def length(self) -> Index: def mid(self) -> Index: """ Return the midpoint of each Interval in the IntervalArray as an Index. + + Examples + -------- + + >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(1, 5)]) + >>> interv_arr + + [(0, 1], (1, 5]] + Length: 2, dtype: interval[int64, right] + >>> interv_arr.mid + Index([0.5, 3.0], dtype='float64') """ try: return 0.5 * (self.left + self.right) @@ -1378,6 +1422,27 @@ def closed(self) -> IntervalClosedType: String describing the inclusive side the intervals. Either ``left``, ``right``, ``both`` or ``neither``. + + Examples + -------- + + For arrays: + + >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(1, 5)]) + >>> interv_arr + + [(0, 1], (1, 5]] + Length: 2, dtype: interval[int64, right] + >>> interv_arr.closed + 'right' + + For Interval Index: + + >>> interv_idx = pd.interval_range(start=0, end=2) + >>> interv_idx + IntervalIndex([(0, 1], (1, 2]], dtype='interval[int64, right]') + >>> interv_idx.closed + 'right' """ return self.dtype.closed @@ -1436,6 +1501,41 @@ def set_closed(self, closed: IntervalClosedType) -> Self: Non-overlapping means (no Intervals share points), and monotonic means either monotonic increasing or monotonic decreasing. + + Examples + -------- + For arrays: + + >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(1, 5)]) + >>> interv_arr + + [(0, 1], (1, 5]] + Length: 2, dtype: interval[int64, right] + >>> interv_arr.is_non_overlapping_monotonic + True + + >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1), + ... pd.Interval(-1, 0.1)]) + >>> interv_arr + + [(0.0, 1.0], (-1.0, 0.1]] + Length: 2, dtype: interval[float64, right] + >>> interv_arr.is_non_overlapping_monotonic + False + + For Interval Index: + + >>> interv_idx = pd.interval_range(start=0, end=2) + >>> interv_idx + IntervalIndex([(0, 1], (1, 2]], dtype='interval[int64, right]') + >>> interv_idx.is_non_overlapping_monotonic + True + + >>> interv_idx = pd.interval_range(start=0, end=2, closed='both') + >>> interv_idx + IntervalIndex([[0, 1], [1, 2]], dtype='interval[int64, both]') + >>> interv_idx.is_non_overlapping_monotonic + False """ @property