Doc improvements for IntervalIndex and Interval (#17714)

Author: topper-123

doc/source/advanced.rst

@@ -833,12 +833,21 @@ Of course if you need integer based selection, then use ``iloc``
 IntervalIndex
 ~~~~~~~~~~~~~
 
+:class:`IntervalIndex` together with its own dtype, ``interval`` as well as the
+:class:`Interval` scalar type, allow first-class support in pandas for interval
+notation.
+
+The ``IntervalIndex`` allows some unique indexing and is also used as a
+return type for the categories in :func:`cut` and :func:`qcut`.
+
 .. versionadded:: 0.20.0
 
 .. warning::
 
  These indexing behaviors are provisional and may change in a future version of pandas.
 
+An ``IntervalIndex`` can be used in ``Series`` and in ``DataFrame`` as the index.
+
 .. ipython:: python
 
  df = pd.DataFrame({'A': [1, 2, 3, 4]},
@@ -860,6 +869,20 @@ If you select a lable *contained* within an interval, this will also select the
  df.loc[2.5]
  df.loc[[2.5, 3.5]]
 
+``Interval`` and ``IntervalIndex`` are used by ``cut`` and ``qcut``:
+
+.. ipython:: python
+
+ c = pd.cut(range(4), bins=2)
+ c
+ c.categories
+
+Furthermore, ``IntervalIndex`` allows one to bin *other* data with these same
+bins, with ``NaN`` representing a missing value similar to other dtypes.
+
+.. ipython:: python
+
+ pd.cut([0, 3, 5, 1], bins=c.categories)
 
 Miscellaneous indexing FAQ
 --------------------------

pandas/_libs/interval.pyx

@@ -51,17 +51,35 @@ cdef class Interval(IntervalMixin):
 
  .. versionadded:: 0.20.0
 
- Attributes
+ Parameters
  ----------
- left, right : values
- Left and right bounds for each interval.
+ left : value
+ Left bound for interval.
+ right : value
+ Right bound for interval.
  closed : {'left', 'right', 'both', 'neither'}
  Whether the interval is closed on the left-side, right-side, both or
  neither. Defaults to 'right'.
 
+ Examples
+ --------
+ >>> iv = pd.Interval(left=0, right=5)
+ >>> iv
+ Interval(0, 5, closed='right')
+ >>> 2.5 in iv
+ True
+
+ >>> year_2017 = pd.Interval(pd.Timestamp('2017-01-01'),
+ ... pd.Timestamp('2017-12-31'), closed='both')
+ >>> pd.Timestamp('2017-01-01 00:00') in year_2017
+ True
+
  See Also
  --------
- IntervalIndex : an Index of intervals that are all closed on the same side.
+ IntervalIndex : an Index of ``interval`` s that are all closed on the same
+ side.
+ cut, qcut : convert arrays of continuous data into categoricals/series of
+ ``Interval``.
  """
 
  cdef readonly object left, right

pandas/core/indexes/interval.py

@@ -105,8 +105,10 @@ class IntervalIndex(IntervalMixin, Index):
 
  .. versionadded:: 0.20.0
 
- Warning: the indexing behaviors are provisional and may change in
- a future version of pandas.
+ .. warning::
+
+ The indexing behaviors are provisional and may change in
+ a future version of pandas.
 
  Attributes
  ----------
@@ -147,15 +149,11 @@ class IntervalIndex(IntervalMixin, Index):
  --------
  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
+ interval_range : Function to create a fixed frequency
+ IntervalIndex, IntervalIndex.from_arrays, IntervalIndex.from_breaks,
+ IntervalIndex.from_intervals, IntervalIndex.from_tuples
+ cut, qcut : convert arrays of continuous data into categoricals/series of
+ ``Interval``.
  """
  _typ = 'intervalindex'
  _comparables = ['name']