Doc/df filter
 Updates doc comments for `DataFrame.filter` and adds usage examples.

<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>

I've never understood exactly what the role of this method is - it seems to do a lot of stuff not very well, particularly when `select` (also not well documented) is available. 

Is it worth looking at `filter` + `select` + `query`, and thinking about whether they all need to be in the API?

( @cswarth thanks for the docs, they look much better imo)
 > Is it worth looking at filter + select + query, and thinking about whether they all need to be in the API?

Yes, this is definitely worth considering -- maybe open another issue for this? My inclination would be to drop `filter` and `select` in favor of just using indexing operations.
 Bummer, all CI tests have failed on account of a failure in lint.sh

https://travis-ci.org/pydata/pandas/jobs/110452254#L1231

It's failing on generic.py so this is probably my fault.  I'm looking into this.
 you can run `git diff upstream/master | flake8 --diff` to just lint your section.
 darn it, ignore this PR for now - I merged instead of rebasing. There really aren't 900+ changes here.
 I'll  fix it.  
 A previous attempt that didn't get merged to clear up the sky on `filter` / `select` is here: https://github.com/pydata/pandas/pull/6599 
Probably worth a look for such a discussion
 @cswarth for future reference, you don't need to close a PR if you screwed up a rebase. Just clean-up the branch (or make the branch again with the same name) and force push it again 
 ah ok, thank you.  I apologize for making such a simple task difficult. 
I deleted the branch before pushing and that automatically nuked the PR.  
I'm assuming my only option now it to create a new PR?  
 Yes, I think so. Also if you force pushed while the PR was closed, you cannot open it again (I find that a quite annoying thing of github)
 note we had quite a bit of discussion w.r.t. deprecateing filter/select [here](https://github.com/pydata/pandas/pull/6599)
