DOC: Add example usage to DataFrame.filter

Author: Chris Warth <[email protected]>

Closes #12399 from cswarth/doc/df_filter and squashes the following commits:

f48e9ff [Chris Warth] DOC: Add example usage to DataFrame.filter

Author: cswarth

doc/source/whatsnew/v0.18.2.txt

@@ -286,6 +286,7 @@ Other API changes
 
 - ``Float64Index.astype(int)`` will now raise ``ValueError`` if ``Float64Index`` contains ``NaN`` values (:issue:`13149`)
 - ``TimedeltaIndex.astype(int)`` and ``DatetimeIndex.astype(int)`` will now return ``Int64Index`` instead of ``np.array`` (:issue:`13209`)
+- ``.filter()`` enforces mutual exclusion of the keyword arguments. (:issue:`12399`)
 
 .. _whatsnew_0182.deprecations:
 

pandas/core/generic.py

@@ -2357,7 +2357,11 @@ def _reindex_axis(self, new_index, fill_method, axis, copy):
 
     def filter(self, items=None, like=None, regex=None, axis=None):
         """
-        Restrict the info axis to set of items or wildcard
+        Subset rows or columns of dataframe according to labels in
+        the specified index.
+
+        Note that this routine does not filter a dataframe on its
+        contents. The filter is applied to the labels of the index.
 
         Parameters
         ----------
@@ -2367,19 +2371,57 @@ def filter(self, items=None, like=None, regex=None, axis=None):
             Keep info axis where "arg in col == True"
         regex : string (regular expression)
             Keep info axis with re.search(regex, col) == True
-        axis : int or None
-            The axis to filter on. By default this is the info axis. The "info
-            axis" is the axis that is used when indexing with ``[]``. For
-            example, ``df = DataFrame({'a': [1, 2, 3, 4]]}); df['a']``. So,
-            the ``DataFrame`` columns are the info axis.
+        axis : int or string axis name
+            The axis to filter on.  By default this is the info axis,
+            'index' for Series, 'columns' for DataFrame
+
+        Returns
+        -------
+        same type as input object
+
+        Examples
+        --------
+        >>> df
+        one  two  three
+        mouse     1    2      3
+        rabbit    4    5      6
+
+        >>> # select columns by name
+        >>> df.filter(items=['one', 'three'])
+        one  three
+        mouse     1      3
+        rabbit    4      6
+
+        >>> # select columns by regular expression
+        >>> df.filter(regex='e$', axis=1)
+        one  three
+        mouse     1      3
+        rabbit    4      6
+
+        >>> # select rows containing 'bbi'
+        >>> df.filter(like='bbi', axis=0)
+        one  two  three
+        rabbit    4    5      6
+
+        See Also
+        --------
+        pandas.DataFrame.select
 
         Notes
         -----
-        Arguments are mutually exclusive, but this is not checked for
+        The ``items``, ``like``, and ``regex`` parameters are
+        enforced to be mutually exclusive.
 
+        ``axis`` defaults to the info axis that is used when indexing
+        with ``[]``.
         """
         import re
 
+        nkw = sum([x is not None for x in [items, like, regex]])
+        if nkw > 1:
+            raise TypeError('Keyword arguments `items`, `like`, or `regex` '
+                            'are mutually exclusive')
+
         if axis is None:
             axis = self._info_axis_name
         axis_name = self._get_axis_name(axis)

pandas/tests/frame/test_axis_select_reindex.py

@@ -661,8 +661,24 @@ def test_filter(self):
         assert_frame_equal(filtered, expected)
 
         # pass in None
+        with assertRaisesRegexp(TypeError, 'Must pass'):
+            self.frame.filter()
         with assertRaisesRegexp(TypeError, 'Must pass'):
             self.frame.filter(items=None)
+        with assertRaisesRegexp(TypeError, 'Must pass'):
+            self.frame.filter(axis=1)
+
+        # test mutually exclusive arguments
+        with assertRaisesRegexp(TypeError, 'mutually exclusive'):
+            self.frame.filter(items=['one', 'three'], regex='e$', like='bbi')
+        with assertRaisesRegexp(TypeError, 'mutually exclusive'):
+            self.frame.filter(items=['one', 'three'], regex='e$', axis=1)
+        with assertRaisesRegexp(TypeError, 'mutually exclusive'):
+            self.frame.filter(items=['one', 'three'], regex='e$')
+        with assertRaisesRegexp(TypeError, 'mutually exclusive'):
+            self.frame.filter(items=['one', 'three'], like='bbi', axis=0)
+        with assertRaisesRegexp(TypeError, 'mutually exclusive'):
+            self.frame.filter(items=['one', 'three'], like='bbi')
 
         # objects
         filtered = self.mixed_frame.filter(like='foo')