title: What does the group_keys argument to pandas.groupby actually do?
body: <p>In <a href="http://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.groupby.html" rel="noreferrer"><code>pandas.DataFrame.groupby</code></a>, there is an argument <code>group_keys</code>, which I gather is supposed to do something relating to how group keys are included in the dataframe subsets. According to the documentation:</p>
  
  <blockquote>
    <p><strong>group_keys</strong> : <em>boolean, default True</em></p>
    
    <blockquote>
      <p>When calling apply, add group keys to index to identify pieces</p>
    </blockquote>
  </blockquote>
  
  <p>However, I can't really find any examples where <code>group_keys</code> makes an actual difference:</p>
  
  <pre><code>import pandas as pd
  
  df = pd.DataFrame([[0, 1, 3],
                     [3, 1, 1],
                     [3, 0, 0],
                     [2, 3, 3],
                     [2, 1, 0]], columns=list('xyz'))
  
  gby = df.groupby('x')
  gby_k = df.groupby('x', group_keys=False)
  </code></pre>
  
  <p>It doesn't make a difference in the output of <code>apply</code>:</p>
  
  <pre><code>ap = gby.apply(pd.DataFrame.sum)
  #    x  y  z
  # x         
  # 0  0  1  3
  # 2  4  4  3
  # 3  6  1  1
  
  ap_k = gby_k.apply(pd.DataFrame.sum)
  #    x  y  z
  # x         
  # 0  0  1  3
  # 2  4  4  3
  # 3  6  1  1
  </code></pre>
  
  <p>And even if you print out the grouped subsets as you go, the results are still identical:</p>
  
  <pre><code>def printer_func(x):
      print(x)
      return x
  
  print('gby')
  print('--------------')
  gby.apply(printer_func)
  print('--------------')
  
  print('gby_k')
  print('--------------')
  gby_k.apply(printer_func)
  print('--------------')
  
  # gby
  # --------------
  #    x  y  z
  # 0  0  1  3
  #    x  y  z
  # 0  0  1  3
  #    x  y  z
  # 3  2  3  3
  # 4  2  1  0
  #    x  y  z
  # 1  3  1  1
  # 2  3  0  0
  # --------------
  # gby_k
  # --------------
  #    x  y  z
  # 0  0  1  3
  #    x  y  z
  # 0  0  1  3
  #    x  y  z
  # 3  2  3  3
  # 4  2  1  0
  #    x  y  z
  # 1  3  1  1
  # 2  3  0  0
  # --------------
  </code></pre>
  
  <p>I considered the possibility that the default argument is actually <code>True</code>, but switching <code>group_keys</code> to explicitly <code>False</code> doesn't make a difference either.  What exactly is this argument for?</p>
  
  <p>(Run on <code>pandas</code> version <code>0.18.1</code>)</p>
  
  <p><strong>Edit:</strong>
  I did find a way where <code>group_keys</code> changes behavior, based on <a href="https://stackoverflow.com/a/34282449/467366">this answer</a>:</p>
  
  <pre><code>import pandas as pd
  import numpy as np
  
  row_idx = pd.MultiIndex.from_product(((0, 1), (2, 3, 4)))
  d = pd.DataFrame([[4, 3], [1, 3], [1, 1], [2, 4], [0, 1], [4, 2]], index=row_idx)
  
  df_n = d.groupby(level=0).apply(lambda x: x.nlargest(2, [0]))
  #        0  1
  # 0 0 2  4  3
  #     3  1  3
  # 1 1 4  4  2
  #     2  2  4
  
  df_k = d.groupby(level=0, group_keys=False).apply(lambda x: x.nlargest(2, [0]))
  
  #      0  1
  # 0 2  4  3
  #   3  1  3
  # 1 4  4  2
  #   2  2  4
  </code></pre>
  
  <p>However, I'm still not clear on the intelligible principle behind what <code>group_keys</code> is <em>supposed to do</em>. This behavior does not seem intuitive based on <strong>@piRSquared</strong>'s answer.</p>