Add example usage to DataFrame.filter
State: closed

Updates doc comments for `DataFrame.filter` and adds usage examples.
Fixed errors identified by `flake8` and correctly rebase my branch before issuing PR.

<dl class="method">
<dt id="pandas.DataFrame.filter">
<code class="descclassname">DataFrame.</code><code class="descname">filter</code><span class="sig-paren">(</span><em>items=None</em>, <em>like=None</em>, <em>regex=None</em>, <em>axis=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pandas.DataFrame.filter" title="Permalink to this definition">¶</a></dt>
<dd><p>Subset rows or columns of dataframe according to  labels in the index.</p>
<p>Note that this routine does not filter a dataframe on its contents. The filter is 
applied to the labels of the index.
This method is a thin veneer on top of <span class="xref std std-ref">DateFrame Select</span></p>
<table class="docutils field-list" frame="void" rules="none">
<colgroup><col class="field-name">
<col class="field-body">
</colgroup><tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><p class="first"><strong>items</strong> : list-like</p>
<blockquote>
<div><p>List of info axis to restrict to (must not all be present)</p>
</div></blockquote>
<p><strong>like</strong> : string</p>
<blockquote>
<div><p>Keep info axis where “arg in col == True”</p>
</div></blockquote>
<p><strong>regex</strong> : string (regular expression)</p>
<blockquote>
<div><p>Keep info axis with re.search(regex, col) == True</p>
</div></blockquote>
<p><strong>axis</strong> : int or None</p>
<blockquote>
<div><p>The axis to filter on.</p>
</div></blockquote>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">same type as input object with filtered info axis</p>
</td>
</tr>
</tbody>
</table>
<p class="rubric">Notes</p>
<p>The <code class="docutils literal"><span class="pre">items</span></code>, <code class="docutils literal"><span class="pre">like</span></code>, and <code class="docutils literal"><span class="pre">regex</span></code> parameters should be mutually exclusive, but this is not checked.</p>
<p><code class="docutils literal"><span class="pre">axis</span></code> defaults to the info axis that is used when indexing with <code class="docutils literal"><span class="pre">[]</span></code>.</p>
<p class="rubric">Examples</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">df</span>
<span class="go">        one  two  three</span>
<span class="go">mouse     1    2      3</span>
<span class="go">rabbit    4    5      6</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="c1"># select columns by name</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">df</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">items</span><span class="o">=</span><span class="p">[</span><span class="s1">'one'</span><span class="p">,</span> <span class="s1">'three'</span><span class="p">])</span>  
<span class="go">        one  three</span>
<span class="go">mouse     1      3</span>
<span class="go">rabbit    4      6</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="c1"># select columns by regular expression</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">df</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">regex</span><span class="o">=</span><span class="s1">'e$'</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
<span class="go">        one  three</span>
<span class="go">mouse     1      3</span>
<span class="go">rabbit    4      6</span>
</pre></div>
</div>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="c1"># select rows containing 'bbi'</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">df</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">like</span><span class="o">=</span><span class="s1">'bbi'</span><span class="p">,</span> <span class="n">axis</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
<span class="go">        one  two  three</span>
<span class="go">rabbit    4    5      6</span>
</pre></div>
</div>
</dd></dl>


Labels:
name: Docs
name: Indexing
description: Related to indexing on series/frames, not to indexes themselves

Comments:
Removed the "thin veneer" comment and added a See Also referring to `pandas.DataFrame.select`.
The point is to demonstrate that this routine does not filter on the contents of the dataframe, but on the index.  Hopefully this will help those coming from R who might be expecting `DataFrame.filter` to act like `dplyr::filter`

can you update

Sorry for being a newbie, but update in what way?  Do you want me to rebase my `doc/df_filter` development branch to `upstream/master` and push that to github?  It looks like that will be push 201 commits so I want to make sure that is the right thing to do.

you need to rebase on master first

I updated my branch, but 24hrs later the CI builds are still not complete.  Is that unusual or expected?

Also the CI build for python 3.5 failed but I don't see how it has anything to do with changes I created.
https://travis-ci.org/pydata/pandas/jobs/124031500

Travis was having some issues ok now

ithe 3.5 build on. numpy master is currently failing but that is ok

can you rebase / update according to comments

can you rebase / update

can you update

## [Current coverage](https://codecov.io/gh/pydata/pandas/pull/12399?src=pr) is **83.76%**

> Merging [#12399](https://codecov.io/gh/pydata/pandas/pull/12399?src=pr) into [master](https://codecov.io/gh/pydata/pandas/branch/master?src=pr) will decrease coverage by **0.47%**

``` diff
@@             master   #12399   diff @@
========================================
  Files           138      135      -3   
  Lines         50721    49640   -1081   
  Methods           0        0           
  Branches          0        0           
========================================
- Hits          42723    41583   -1140   
- Misses         7998     8057     +59   
  Partials          0        0           
```

> Powered by [Codecov](https://codecov.io?src=pr). Last updated by [2061e9e...5e492cd](https://codecov.io/gh/pydata/pandas/compare/2061e9e5fbbd890c484b53232b0747e08d7d1739...5e492cd2132c4e907be5165a32f0f9fd76114595)

As requested, added test for mutually exclusive arguments in DataFrame.filter and added unit tests for same.

Enforcing mutually exclusive arguments in frame.filter() is an incompatible change that is going to break some code, somewhere.  Should this be called out in the release notes?

I would like to make a case that this API should be deprecated at this time.   It adds little value over reindex and select at the expense of an API that is different than just about anything else. 

@cswarth yes pls add a whatsnew note about the mutually exclusive args.

already slated to deprecate in 0.19.0: https://github.com/pydata/pandas/issues/12401

thanks @cswarth