DOC: Document behaviour of head(n), tail(n) for negative values of n except on GroupBy (#30556)

* DOC: Document negative values on head(n), tail(n) except for GroupBy

Author: bharatr21

pandas/core/generic.py

@@ -4652,14 +4652,17 @@ def head(self: FrameOrSeries, n: int = 5) -> FrameOrSeries:
  on position. It is useful for quickly testing if your object
  has the right type of data in it.
 
+ For negative values of `n`, this function returns all rows except
+ the last `n` rows, equivalent to ``df[:-n]``.
+
  Parameters
  ----------
  n : int, default 5
  Number of rows to select.
 
  Returns
  -------
- obj_head : same type as caller
+ same type as caller
  The first `n` rows of the caller object.
 
  See Also
@@ -4699,6 +4702,17 @@ def head(self: FrameOrSeries, n: int = 5) -> FrameOrSeries:
  0 alligator
  1 bee
  2 falcon
+
+ For negative values of `n`
+
+ >>> df.head(-3)
+ animal
+ 0 alligator
+ 1 bee
+ 2 falcon
+ 3 lion
+ 4 monkey
+ 5 parrot
  """
 
  return self.iloc[:n]
@@ -4711,6 +4725,9 @@ def tail(self: FrameOrSeries, n: int = 5) -> FrameOrSeries:
  position. It is useful for quickly verifying data, for example,
  after sorting or appending rows.
 
+ For negative values of `n`, this function returns all rows except
+ the first `n` rows, equivalent to ``df[n:]``.
+
  Parameters
  ----------
  n : int, default 5
@@ -4758,6 +4775,17 @@ def tail(self: FrameOrSeries, n: int = 5) -> FrameOrSeries:
  6 shark
  7 whale
  8 zebra
+
+ For negative values of `n`
+
+ >>> df.tail(-3)
+ animal
+ 3 lion
+ 4 monkey
+ 5 parrot
+ 6 shark
+ 7 whale
+ 8 zebra
  """
 
  if n == 0:

pandas/core/groupby/groupby.py

@@ -2377,6 +2377,8 @@ def head(self, n=5):
  from the original DataFrame with original index and order preserved
  (``as_index`` flag is ignored).
 
+ Does not work for negative values of `n`.
+
  Returns
  -------
  Series or DataFrame
@@ -2390,6 +2392,10 @@ def head(self, n=5):
  A B
  0 1 2
  2 5 6
+ >>> df.groupby('A').head(-1)
+ Empty DataFrame
+ Columns: [A, B]
+ Index: []
  """
  self._reset_group_selection()
  mask = self._cumcount_array() < n
@@ -2405,6 +2411,8 @@ def tail(self, n=5):
  from the original DataFrame with original index and order preserved
  (``as_index`` flag is ignored).
 
+ Does not work for negative values of `n`.
+
  Returns
  -------
  Series or DataFrame
@@ -2418,6 +2426,10 @@ def tail(self, n=5):
  A B
  1 a 2
  3 b 2
+ >>> df.groupby('A').tail(-1)
+ Empty DataFrame
+ Columns: [A, B]
+ Index: []
  """
  self._reset_group_selection()
  mask = self._cumcount_array(ascending=False) < n