Skip to content

Commit 65baa5b

Browse files
rhshadrachrhshadrach
authored
DOC: Add groupby-specific docstrings for take (#50526)
* DOC: Add groupby-specific docs for grouby.take * Add Series/DataFrame.take
1 parent 5574109 commit 65baa5b

File tree

1 file changed

+160
-2
lines changed

1 file changed

+160
-2
lines changed

‎pandas/core/groupby/generic.py

+160-2
Original file line numberDiff line numberDiff line change
@@ -891,13 +891,85 @@ def fillna(
891891
)
892892
return result
893893

894-
@doc(Series.take.__doc__)
895894
def take(
896895
self,
897896
indices: TakeIndexer,
898897
axis: Axis = 0,
899898
**kwargs,
900899
) -> Series:
900+
"""
901+
Return the elements in the given *positional* indices in each group.
902+
903+
This means that we are not indexing according to actual values in
904+
the index attribute of the object. We are indexing according to the
905+
actual position of the element in the object.
906+
907+
If a requested index does not exist for some group, this method will raise.
908+
To get similar behavior that ignores indices that don't exist, see
909+
:meth:`.SeriesGroupBy.nth`.
910+
911+
Parameters
912+
----------
913+
indices : array-like
914+
An array of ints indicating which positions to take in each group.
915+
axis : {0 or 'index', 1 or 'columns', None}, default 0
916+
The axis on which to select elements. ``0`` means that we are
917+
selecting rows, ``1`` means that we are selecting columns.
918+
For `SeriesGroupBy` this parameter is unused and defaults to 0.
919+
**kwargs
920+
For compatibility with :meth:`numpy.take`. Has no effect on the
921+
output.
922+
923+
Returns
924+
-------
925+
Series
926+
A Series containing the elements taken from each group.
927+
928+
See Also
929+
--------
930+
Series.take : Take elements from a Series along an axis.
931+
Series.loc : Select a subset of a DataFrame by labels.
932+
Series.iloc : Select a subset of a DataFrame by positions.
933+
numpy.take : Take elements from an array along an axis.
934+
SeriesGroupBy.nth : Similar to take, won't raise if indices don't exist.
935+
936+
Examples
937+
--------
938+
>>> df = DataFrame([('falcon', 'bird', 389.0),
939+
... ('parrot', 'bird', 24.0),
940+
... ('lion', 'mammal', 80.5),
941+
... ('monkey', 'mammal', np.nan),
942+
... ('rabbit', 'mammal', 15.0)],
943+
... columns=['name', 'class', 'max_speed'],
944+
... index=[4, 3, 2, 1, 0])
945+
>>> df
946+
name class max_speed
947+
4 falcon bird 389.0
948+
3 parrot bird 24.0
949+
2 lion mammal 80.5
950+
1 monkey mammal NaN
951+
0 rabbit mammal 15.0
952+
>>> gb = df["name"].groupby([1, 1, 2, 2, 2])
953+
954+
Take elements at positions 0 and 1 along the axis 0 in each group (default).
955+
956+
>>> gb.take([0, 1])
957+
1 4 falcon
958+
3 parrot
959+
2 2 lion
960+
1 monkey
961+
Name: name, dtype: object
962+
963+
We may take elements using negative integers for positive indices,
964+
starting from the end of the object, just like with Python lists.
965+
966+
>>> gb.take([-1, -2])
967+
1 3 parrot
968+
4 falcon
969+
2 0 rabbit
970+
1 monkey
971+
Name: name, dtype: object
972+
"""
901973
result = self._op_via_apply("take", indices=indices, axis=axis, **kwargs)
902974
return result
903975

@@ -2400,13 +2472,99 @@ def fillna(
24002472
)
24012473
return result
24022474

2403-
@doc(DataFrame.take.__doc__)
24042475
def take(
24052476
self,
24062477
indices: TakeIndexer,
24072478
axis: Axis | None = 0,
24082479
**kwargs,
24092480
) -> DataFrame:
2481+
"""
2482+
Return the elements in the given *positional* indices in each group.
2483+
2484+
This means that we are not indexing according to actual values in
2485+
the index attribute of the object. We are indexing according to the
2486+
actual position of the element in the object.
2487+
2488+
If a requested index does not exist for some group, this method will raise.
2489+
To get similar behavior that ignores indices that don't exist, see
2490+
:meth:`.DataFrameGroupBy.nth`.
2491+
2492+
Parameters
2493+
----------
2494+
indices : array-like
2495+
An array of ints indicating which positions to take.
2496+
axis : {0 or 'index', 1 or 'columns', None}, default 0
2497+
The axis on which to select elements. ``0`` means that we are
2498+
selecting rows, ``1`` means that we are selecting columns.
2499+
**kwargs
2500+
For compatibility with :meth:`numpy.take`. Has no effect on the
2501+
output.
2502+
2503+
Returns
2504+
-------
2505+
DataFrame
2506+
An DataFrame containing the elements taken from each group.
2507+
2508+
See Also
2509+
--------
2510+
DataFrame.take : Take elements from a Series along an axis.
2511+
DataFrame.loc : Select a subset of a DataFrame by labels.
2512+
DataFrame.iloc : Select a subset of a DataFrame by positions.
2513+
numpy.take : Take elements from an array along an axis.
2514+
2515+
Examples
2516+
--------
2517+
>>> df = DataFrame([('falcon', 'bird', 389.0),
2518+
... ('parrot', 'bird', 24.0),
2519+
... ('lion', 'mammal', 80.5),
2520+
... ('monkey', 'mammal', np.nan),
2521+
... ('rabbit', 'mammal', 15.0)],
2522+
... columns=['name', 'class', 'max_speed'],
2523+
... index=[4, 3, 2, 1, 0])
2524+
>>> df
2525+
name class max_speed
2526+
4 falcon bird 389.0
2527+
3 parrot bird 24.0
2528+
2 lion mammal 80.5
2529+
1 monkey mammal NaN
2530+
0 rabbit mammal 15.0
2531+
>>> gb = df.groupby([1, 1, 2, 2, 2])
2532+
2533+
Take elements at positions 0 and 1 along the axis 0 (default).
2534+
2535+
Note how the indices selected in the result do not correspond to
2536+
our input indices 0 and 1. That's because we are selecting the 0th
2537+
and 1st rows, not rows whose indices equal 0 and 1.
2538+
2539+
>>> gb.take([0, 1])
2540+
name class max_speed
2541+
1 4 falcon bird 389.0
2542+
3 parrot bird 24.0
2543+
2 2 lion mammal 80.5
2544+
1 monkey mammal NaN
2545+
2546+
The order of the specified indices influnces the order in the result.
2547+
Here, the order is swapped from the previous example.
2548+
2549+
>>> gb.take([0, 1])
2550+
name class max_speed
2551+
1 4 falcon bird 389.0
2552+
3 parrot bird 24.0
2553+
2 2 lion mammal 80.5
2554+
1 monkey mammal NaN
2555+
2556+
Take elements at indices 1 and 2 along the axis 1 (column selection).
2557+
2558+
We may take elements using negative integers for positive indices,
2559+
starting from the end of the object, just like with Python lists.
2560+
2561+
>>> gb.take([-1, -2])
2562+
name class max_speed
2563+
1 3 parrot bird 24.0
2564+
4 falcon bird 389.0
2565+
2 0 rabbit mammal 15.0
2566+
1 monkey mammal NaN
2567+
"""
24102568
result = self._op_via_apply("take", indices=indices, axis=axis, **kwargs)
24112569
return result
24122570

0 commit comments

Comments
 (0)