REF: IntervalIndex[IntervalArray]

Closes pandas-dev#19209

Author: TomAugspurger

doc/source/basics.rst

@@ -1925,11 +1925,23 @@ untouched. If the data is modified, it is because you did so explicitly.
 dtypes
 ------
 
-The main types stored in pandas objects are ``float``, ``int``, ``bool``,
-``datetime64[ns]`` and ``datetime64[ns, tz]``, ``timedelta[ns]``,
-``category`` and ``object``. In addition these dtypes have item sizes, e.g.
-``int64`` and ``int32``. See :ref:`Series with TZ <timeseries.timezone_series>`
-for more detail on ``datetime64[ns, tz]`` dtypes.
+For the most part, pandas uses NumPy arrays and dtypes for Series or individual
+columns of a DataFrame. The main types allowed in pandas objects are ``float``,
+``int``, ``bool``, and ``datetime64[ns]`` (note that NumPy does not support
+timezone-aware datetimes).
+
+In addition to NumPy's types, pandas :ref:`extends <extending.extension-types>`
+NumPy's type-system for a few cases.
+
+* :ref:`Categorical <categorical>`
+* :ref:`Datetime with Timezone <timeseries.timezone_series>`
+* Interval
+
+Pandas uses the ``object`` dtype for storing strings.
+
+Finally, arbitrary objects may be stored using the ``object`` dtype, but should
+be avoided to the extent possible (for performance and interoperability with
+other libraries and methods. See :ref:`basics.object_conversion`).
 
 A convenient :attr:`~DataFrame.dtypes` attribute for DataFrame returns a Series
 with the data type of each column.

doc/source/whatsnew/v0.23.0.txt

@@ -299,6 +299,41 @@ Supplying a ``CategoricalDtype`` will make the categories in each column consist
     df['A'].dtype
     df['B'].dtype
 
+.. _whatsnew_023.enhancements.interval:
+
+Storing Interval Data in Series and DataFrame
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Interval data may now be stored in a Series or DataFrame, in addition to an
+:class:`IntervalIndex` like before.
+
+.. ipython:: python
+
+   ser = pd.Series(pd.interval_range(0, 5))
+   ser
+   ser.dtype
+
+Previously, these would be cast to a NumPy array of Interval objects. In general,
+this should result in better performance when storing an array of intervals in
+a Series.
+
+Note that the ``.values`` of a Series containing intervals is no longer a NumPy
+array. Rather, it's an ``ExtensionArray``, composed of two arrays ``left`` and
+``right``.
+
+.. ipython:: python
+
+   ser.values
+
+To recover the NumPy array of Interval objects, use :func:`numpy.asarray`:
+
+.. ipython:: python
+
+   np.asarray(ser.values)
+
+This is the same behavior as ``Series.values`` for categorical data. See
+:ref:`whatsnew_0230.api_breaking.interval_values` for more.
+
 .. _whatsnew_023.enhancements.extension:
 
 Extending Pandas with Custom Types
@@ -479,6 +514,42 @@ If you wish to retain the old behavior while using Python >= 3.6, you can use
                'Taxes': -200,
                'Net result': 300}).sort_index()
 
+.. _whatsnew_0230.api_breaking.interval_values:
+
+``IntervalIndex.values`` is now an ``IntervalArray``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``.values`` attribute of an :class:`IntervalIndex` now returns an
+``IntervalArray``, rather than a NumPy array of :class:`Interval` objects.
+
+Previous Behavior:
+
+.. code-block:: ipython
+
+   In [1]: idx = pd.interval_range(0, 4)
+
+   In [2]: idx.values
+   Out[2]:
+   array([Interval(0, 1, closed='right'), Interval(1, 2, closed='right'),
+          Interval(2, 3, closed='right'), Interval(3, 4, closed='right')],
+         dtype=object)
+
+New Behavior:
+
+.. ipython:: python
+
+   idx = pd.interval_range(0, 4)
+   idx.values
+
+This mirrors ``CateogricalIndex.values``, which returns a ``Categorical``.             
+
+For situations where you need an ``ndarray`` of Interval objects, use
+:meth:`numpy.asarray` or ``idx.astype(object)``.
+
+.. ipython:: python
+
+   idx.values.astype(object)
+
 .. _whatsnew_0230.api_breaking.deprecate_panel:
 
 Deprecate Panel

pandas/core/arrays/__init__.py

@@ -1,2 +1,10 @@
-from .base import ExtensionArray  # noqa
-from .categorical import Categorical  # noqa
+from .base import ExtensionArray
+from .categorical import Categorical
+from .interval import IntervalArray
+
+
+__all__ = [
+    'Categorical',
+    'ExtensionArray',
+    'IntervalArray',
+]

pandas/core/arrays/categorical.py

@@ -19,6 +19,7 @@
     _ensure_int64,
     _ensure_object,
     _ensure_platform_int,
+    is_extension_array_dtype,
     is_dtype_equal,
     is_datetimelike,
     is_datetime64_dtype,
@@ -1218,6 +1219,8 @@ def __array__(self, dtype=None):
         ret = take_1d(self.categories.values, self._codes)
         if dtype and not is_dtype_equal(dtype, self.categories.dtype):
             return np.asarray(ret, dtype)
+        if is_extension_array_dtype(ret):
+            ret = np.asarray(ret)
         return ret
 
     def __setstate__(self, state):