ENH: .isnull and .notnull have been added as methods to Index to make this more consistent with the Series API

Author: Jeff Reback <[email protected]>

Closes #15300 from jreback/null and squashes the following commits:

8c35656 [Jeff Reback] DOC: move Index.where to shared_docs
e4502bf [Jeff Reback] ENH: .isnull and .notnull have been added as methods to Index to make this more consistent with the Series API

Author: jreback

doc/source/api.rst

@@ -1356,8 +1356,16 @@ Modifying and Computations
    Index.unique
    Index.nunique
    Index.value_counts
+
+Missing Values
+~~~~~~~~~~~~~~
+.. autosummary::
+   :toctree: generated/
+
    Index.fillna
    Index.dropna
+   Index.isnull
+   Index.notnull
 
 Conversion
 ~~~~~~~~~~

doc/source/whatsnew/v0.20.0.txt

@@ -125,7 +125,7 @@ Other enhancements
 
 - ``pd.read_excel`` now preserves sheet order when using ``sheetname=None`` (:issue:`9930`)
 - Multiple offset aliases with decimal points are now supported (e.g. '0.5min' is parsed as '30s') (:issue:`8419`)
-
+- ``.isnull()`` and ``.notnull()`` have been added to ``Index`` object to make them more consistent with the ``Series`` API (:issue:`15300`)
 - ``pd.read_gbq`` method now allows query configuration preferences (:issue:`14742`)
 
 - New ``UnsortedIndexError`` (subclass of ``KeyError``) raised when indexing/slicing into an

pandas/indexes/base.py

@@ -564,8 +564,7 @@ def repeat(self, repeats, *args, **kwargs):
         nv.validate_repeat(args, kwargs)
         return self._shallow_copy(self._values.repeat(repeats))
 
-    def where(self, cond, other=None):
-        """
+    _index_shared_docs['where'] = """
         .. versionadded:: 0.19.0
 
         Return an Index of same shape as self and whose corresponding
@@ -577,6 +576,9 @@ def where(self, cond, other=None):
         cond : boolean same length as self
         other : scalar, or array-like
         """
+
+    @Appender(_index_shared_docs['where'])
+    def where(self, cond, other=None):
         if other is None:
             other = self._na_value
         values = np.where(cond, self.values, other)
@@ -1662,6 +1664,38 @@ def hasnans(self):
         else:
             return False
 
+    def isnull(self):
+        """
+        Detect missing values
+
+        .. versionadded:: 0.20.0
+
+        Returns
+        -------
+        a boolean array of whether my values are null
+
+        See also
+        --------
+        pandas.isnull : pandas version
+        """
+        return self._isnan
+
+    def notnull(self):
+        """
+        Reverse of isnull
+
+        .. versionadded:: 0.20.0
+
+        Returns
+        -------
+        a boolean array of whether my values are not null
+
+        See also
+        --------
+        pandas.notnull : pandas version
+        """
+        return ~self.isnull()
+
     def putmask(self, mask, value):
         """
         return a new Index of the values set with the mask

pandas/indexes/category.py

@@ -332,19 +332,8 @@ def _can_reindex(self, indexer):
         """ always allow reindexing """
         pass
 
+    @Appender(_index_shared_docs['where'])
     def where(self, cond, other=None):
-        """
-        .. versionadded:: 0.19.0
-
-        Return an Index of same shape as self and whose corresponding
-        entries are from self where cond is True and otherwise are from
-        other.
-
-        Parameters
-        ----------
-        cond : boolean same length as self
-        other : scalar, or array-like
-        """
         if other is None:
             other = self._na_value
         values = np.where(cond, self.values, other)

pandas/tests/indexes/common.py

@@ -7,7 +7,7 @@
 
 from pandas import (Series, Index, Float64Index, Int64Index, UInt64Index,
                     RangeIndex, MultiIndex, CategoricalIndex, DatetimeIndex,
-                    TimedeltaIndex, PeriodIndex, notnull)
+                    TimedeltaIndex, PeriodIndex, notnull, isnull)
 from pandas.types.common import needs_i8_conversion
 from pandas.util.testing import assertRaisesRegexp
 
@@ -879,3 +879,28 @@ def test_fillna(self):
                 expected[1] = True
                 self.assert_numpy_array_equal(idx._isnan, expected)
                 self.assertTrue(idx.hasnans)
+
+    def test_nulls(self):
+        # this is really a smoke test for the methods
+        # as these are adequantely tested for function elsewhere
+
+        for name, index in self.indices.items():
+            if len(index) == 0:
+                self.assert_numpy_array_equal(
+                    index.isnull(), np.array([], dtype=bool))
+            elif isinstance(index, MultiIndex):
+                idx = index.copy()
+                msg = "isnull is not defined for MultiIndex"
+                with self.assertRaisesRegexp(NotImplementedError, msg):
+                    idx.isnull()
+            else:
+
+                if not index.hasnans:
+                    self.assert_numpy_array_equal(
+                        index.isnull(), np.zeros(len(index), dtype=bool))
+                    self.assert_numpy_array_equal(
+                        index.notnull(), np.ones(len(index), dtype=bool))
+                else:
+                    result = isnull(index)
+                    self.assert_numpy_array_equal(index.isnull(), result)
+                    self.assert_numpy_array_equal(index.notnull(), ~result)

pandas/tseries/base.py

@@ -786,19 +786,8 @@ def repeat(self, repeats, *args, **kwargs):
         return self._shallow_copy(self.asi8.repeat(repeats),
                                   freq=freq)
 
+    @Appender(_index_shared_docs['where'])
     def where(self, cond, other=None):
-        """
-        .. versionadded:: 0.19.0
-
-        Return an Index of same shape as self and whose corresponding
-        entries are from self where cond is True and otherwise are from
-        other.
-
-        Parameters
-        ----------
-        cond : boolean same length as self
-        other : scalar, or array-like
-        """
         other = _ensure_datetimelike_to_i8(other)
         values = _ensure_datetimelike_to_i8(self)
         result = np.where(cond, values, other).astype('i8')