From cc58b84f423db58de9edca762f0abbe10c638efb Mon Sep 17 00:00:00 2001 From: topper-123 Date: Thu, 28 Sep 2017 21:26:38 +0200 Subject: [PATCH] DOC: Improved doc string for IntervalIndex + related changes (#17706) --- pandas/_libs/interval.pyx | 4 ++ pandas/core/indexes/interval.py | 110 ++++++++++++++++++++++++++------ 2 files changed, 96 insertions(+), 18 deletions(-) diff --git a/pandas/_libs/interval.pyx b/pandas/_libs/interval.pyx index bfbda9696ff2b..306597031817d 100644 --- a/pandas/_libs/interval.pyx +++ b/pandas/_libs/interval.pyx @@ -58,6 +58,10 @@ cdef class Interval(IntervalMixin): closed : {'left', 'right', 'both', 'neither'} Whether the interval is closed on the left-side, right-side, both or neither. Defaults to 'right'. + + See Also + -------- + IntervalIndex : an Index of intervals that are all closed on the same side. """ cdef readonly object left, right diff --git a/pandas/core/indexes/interval.py b/pandas/core/indexes/interval.py index 55ed2342571ab..a697ed7888f90 100644 --- a/pandas/core/indexes/interval.py +++ b/pandas/core/indexes/interval.py @@ -120,9 +120,42 @@ class IntervalIndex(IntervalMixin, Index): copy : boolean, default False Copy the meta-data + Examples + --------- + A new ``IntervalIndex`` is typically constructed using + :func:`interval_range`: + + >>> pd.interval_range(start=0, end=5) + IntervalIndex([(0, 1], (1, 2], (2, 3], (3, 4], (4, 5]] + closed='right', dtype='interval[int64]') + + It may also be constructed using one of the constructor + methods :meth:`IntervalIndex.from_arrays`, + :meth:`IntervalIndex.from_breaks`, :meth:`IntervalIndex.from_intervals` + and :meth:`IntervalIndex.from_tuples`. + + See further examples in the doc strings of ``interval_range`` and the + mentioned constructor methods. + + Notes + ------ + See the `user guide + `_ + for more. + See Also -------- Index + Interval : A bounded slice-like interval + interval_range : Function to create a fixed frequency IntervalIndex + IntervalIndex.from_arrays : Construct an IntervalIndex from a left and + right array + IntervalIndex.from_breaks : Construct an IntervalIndex from an array of + splits + IntervalIndex.from_intervals : Construct an IntervalIndex from an array of + Interval objects + IntervalIndex.from_tuples : Construct an IntervalIndex from a list/array of + tuples """ _typ = 'intervalindex' _comparables = ['name'] @@ -319,11 +352,20 @@ def from_breaks(cls, breaks, closed='right', name=None, copy=False): Examples -------- + >>> pd.IntervalIndex.from_breaks([0, 1, 2, 3]) + IntervalIndex([(0, 1], (1, 2], (2, 3]] + closed='right', + dtype='interval[int64]') - >>> IntervalIndex.from_breaks([0, 1, 2, 3]) - IntervalIndex(left=[0, 1, 2], - right=[1, 2, 3], - closed='right') + See Also + -------- + interval_range : Function to create a fixed frequency IntervalIndex + IntervalIndex.from_arrays : Construct an IntervalIndex from a left and + right array + IntervalIndex.from_intervals : Construct an IntervalIndex from an array + of Interval objects + IntervalIndex.from_tuples : Construct an IntervalIndex from a + list/array of tuples """ breaks = np.asarray(breaks) return cls.from_arrays(breaks[:-1], breaks[1:], closed, @@ -350,11 +392,20 @@ def from_arrays(cls, left, right, closed='right', name=None, copy=False): Examples -------- + >>> pd.IntervalIndex.from_arrays([0, 1, 2], [1, 2, 3]) + IntervalIndex([(0, 1], (1, 2], (2, 3]] + closed='right', + dtype='interval[int64]') - >>> IntervalIndex.from_arrays([0, 1, 2], [1, 2, 3]) - IntervalIndex(left=[0, 1, 2], - right=[1, 2, 3], - closed='right') + See Also + -------- + interval_range : Function to create a fixed frequency IntervalIndex + IntervalIndex.from_breaks : Construct an IntervalIndex from an array of + splits + IntervalIndex.from_intervals : Construct an IntervalIndex from an array + of Interval objects + IntervalIndex.from_tuples : Construct an IntervalIndex from a + list/array of tuples """ left = np.asarray(left) right = np.asarray(right) @@ -378,19 +429,27 @@ def from_intervals(cls, data, name=None, copy=False): Examples -------- - - >>> IntervalIndex.from_intervals([Interval(0, 1), Interval(1, 2)]) - IntervalIndex(left=[0, 1], - right=[1, 2], - closed='right') + >>> pd.IntervalIndex.from_intervals([pd.Interval(0, 1), + ... pd.Interval(1, 2)]) + IntervalIndex([(0, 1], (1, 2]] + closed='right', dtype='interval[int64]') The generic Index constructor work identically when it infers an array of all intervals: - >>> Index([Interval(0, 1), Interval(1, 2)]) - IntervalIndex(left=[0, 1], - right=[1, 2], - closed='right') + >>> pd.Index([pd.Interval(0, 1), pd.Interval(1, 2)]) + IntervalIndex([(0, 1], (1, 2]] + closed='right', dtype='interval[int64]') + + See Also + -------- + interval_range : Function to create a fixed frequency IntervalIndex + IntervalIndex.from_arrays : Construct an IntervalIndex from a left and + right array + IntervalIndex.from_breaks : Construct an IntervalIndex from an array of + splits + IntervalIndex.from_tuples : Construct an IntervalIndex from a + list/array of tuples """ data = np.asarray(data) left, right, closed = intervals_to_interval_bounds(data) @@ -415,7 +474,19 @@ def from_tuples(cls, data, closed='right', name=None, copy=False): Examples -------- + >>> pd.IntervalIndex.from_tuples([(0, 1), (1,2)]) + IntervalIndex([(0, 1], (1, 2]], + closed='right', dtype='interval[int64]') + See Also + -------- + interval_range : Function to create a fixed frequency IntervalIndex + IntervalIndex.from_arrays : Construct an IntervalIndex from a left and + right array + IntervalIndex.from_breaks : Construct an IntervalIndex from an array of + splits + IntervalIndex.from_intervals : Construct an IntervalIndex from an array + of Interval objects """ left = [] right = [] @@ -1121,7 +1192,6 @@ def interval_range(start=None, end=None, periods=None, freq=None, Examples -------- - Numeric ``start`` and ``end`` is supported. >>> pd.interval_range(start=0, end=5) @@ -1159,6 +1229,10 @@ def interval_range(start=None, end=None, periods=None, freq=None, >>> pd.interval_range(end=5, periods=4, closed='both') IntervalIndex([[1, 2], [2, 3], [3, 4], [4, 5]] closed='both', dtype='interval[int64]') + + See Also + -------- + IntervalIndex : an Index of intervals that are all closed on the same side. """ if com._count_not_none(start, end, periods) != 2: raise ValueError('Of the three parameters: start, end, and periods, '