Skip to content

Commit 9407518

Browse files
DeaMariaLeonDeaMariaLeon
authored
DOC: Fixing EX01 - Added more examples (#53540)
* Added examples groupby * Removed decorator & added 'See Also' inside docstring * Added @substitution instead of repeating 'see_also'
1 parent a6ad8ab commit 9407518

File tree

2 files changed

+195
-14
lines changed

2 files changed

+195
-14
lines changed

‎ci/code_checks.sh

-12
Original file line numberDiff line numberDiff line change
@@ -263,16 +263,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
263263
pandas.core.window.ewm.ExponentialMovingWindow.cov \
264264
pandas.api.indexers.BaseIndexer \
265265
pandas.api.indexers.VariableOffsetWindowIndexer \
266-
pandas.core.groupby.DataFrameGroupBy.__iter__ \
267-
pandas.core.groupby.SeriesGroupBy.__iter__ \
268-
pandas.core.groupby.DataFrameGroupBy.groups \
269-
pandas.core.groupby.SeriesGroupBy.groups \
270-
pandas.core.groupby.DataFrameGroupBy.indices \
271-
pandas.core.groupby.SeriesGroupBy.indices \
272-
pandas.core.groupby.DataFrameGroupBy.get_group \
273-
pandas.core.groupby.SeriesGroupBy.get_group \
274-
pandas.core.groupby.DataFrameGroupBy.all \
275-
pandas.core.groupby.DataFrameGroupBy.any \
276266
pandas.core.groupby.DataFrameGroupBy.count \
277267
pandas.core.groupby.DataFrameGroupBy.cummax \
278268
pandas.core.groupby.DataFrameGroupBy.cummin \
@@ -293,8 +283,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
293283
pandas.core.groupby.DataFrameGroupBy.std \
294284
pandas.core.groupby.DataFrameGroupBy.sum \
295285
pandas.core.groupby.DataFrameGroupBy.var \
296-
pandas.core.groupby.SeriesGroupBy.all \
297-
pandas.core.groupby.SeriesGroupBy.any \
298286
pandas.core.groupby.SeriesGroupBy.count \
299287
pandas.core.groupby.SeriesGroupBy.cummax \
300288
pandas.core.groupby.SeriesGroupBy.cummin \

‎pandas/core/groupby/groupby.py

+195-2
Original file line numberDiff line numberDiff line change
@@ -720,6 +720,33 @@ def __repr__(self) -> str:
720720
def groups(self) -> dict[Hashable, np.ndarray]:
721721
"""
722722
Dict {group name -> group labels}.
723+
724+
Examples
725+
--------
726+
727+
For SeriesGroupBy:
728+
729+
>>> lst = ['a', 'a', 'b']
730+
>>> ser = pd.Series([1, 2, 3], index=lst)
731+
>>> ser
732+
a 1
733+
a 2
734+
b 3
735+
dtype: int64
736+
>>> ser.groupby(level=0).groups
737+
{'a': ['a', 'a'], 'b': ['b']}
738+
739+
For DataFrameGroupBy:
740+
741+
>>> data = [[1, 2, 3], [1, 5, 6], [7, 8, 9]]
742+
>>> df = pd.DataFrame(data, columns=["a", "b", "c"])
743+
>>> df
744+
a b c
745+
0 1 2 3
746+
1 1 5 6
747+
2 7 8 9
748+
>>> df.groupby(by=["a"]).groups
749+
{1: [0, 1], 7: [2]}
723750
"""
724751
return self.grouper.groups
725752

@@ -733,6 +760,34 @@ def ngroups(self) -> int:
733760
def indices(self) -> dict[Hashable, npt.NDArray[np.intp]]:
734761
"""
735762
Dict {group name -> group indices}.
763+
764+
Examples
765+
--------
766+
767+
For SeriesGroupBy:
768+
769+
>>> lst = ['a', 'a', 'b']
770+
>>> ser = pd.Series([1, 2, 3], index=lst)
771+
>>> ser
772+
a 1
773+
a 2
774+
b 3
775+
dtype: int64
776+
>>> ser.groupby(level=0).indices
777+
{'a': array([0, 1]), 'b': array([2])}
778+
779+
For DataFrameGroupBy:
780+
781+
>>> data = [[1, 2, 3], [1, 5, 6], [7, 8, 9]]
782+
>>> df = pd.DataFrame(data, columns=["a", "b", "c"],
783+
... index=["owl", "toucan", "eagle"])
784+
>>> df
785+
a b c
786+
owl 1 2 3
787+
toucan 1 5 6
788+
eagle 7 8 9
789+
>>> df.groupby(by=["a"]).indices
790+
{1: array([0, 1]), 7: array([2])}
736791
"""
737792
return self.grouper.indices
738793

@@ -867,6 +922,38 @@ def get_group(self, name, obj=None) -> DataFrame | Series:
867922
Returns
868923
-------
869924
same type as obj
925+
926+
Examples
927+
--------
928+
929+
For SeriesGroupBy:
930+
931+
>>> lst = ['a', 'a', 'b']
932+
>>> ser = pd.Series([1, 2, 3], index=lst)
933+
>>> ser
934+
a 1
935+
a 2
936+
b 3
937+
dtype: int64
938+
>>> ser.groupby(level=0).get_group("a")
939+
a 1
940+
a 2
941+
dtype: int64
942+
943+
For DataFrameGroupBy:
944+
945+
>>> data = [[1, 2, 3], [1, 5, 6], [7, 8, 9]]
946+
>>> df = pd.DataFrame(data, columns=["a", "b", "c"],
947+
... index=["owl", "toucan", "eagle"])
948+
>>> df
949+
a b c
950+
owl 1 2 3
951+
toucan 1 5 6
952+
eagle 7 8 9
953+
>>> df.groupby(by=["a"]).get_group(1)
954+
a b c
955+
owl 1 2 3
956+
toucan 1 5 6
870957
"""
871958
if obj is None:
872959
obj = self._selected_obj
@@ -886,6 +973,47 @@ def __iter__(self) -> Iterator[tuple[Hashable, NDFrameT]]:
886973
-------
887974
Generator yielding sequence of (name, subsetted object)
888975
for each group
976+
977+
Examples
978+
--------
979+
980+
For SeriesGroupBy:
981+
982+
>>> lst = ['a', 'a', 'b']
983+
>>> ser = pd.Series([1, 2, 3], index=lst)
984+
>>> ser
985+
a 1
986+
a 2
987+
b 3
988+
dtype: int64
989+
>>> for x, y in ser.groupby(level=0):
990+
... print(f'{x}\\n{y}\\n')
991+
a
992+
a 1
993+
a 2
994+
dtype: int64
995+
b
996+
b 3
997+
dtype: int64
998+
999+
For DataFrameGroupBy:
1000+
1001+
>>> data = [[1, 2, 3], [1, 5, 6], [7, 8, 9]]
1002+
>>> df = pd.DataFrame(data, columns=["a", "b", "c"])
1003+
>>> df
1004+
a b c
1005+
0 1 2 3
1006+
1 1 5 6
1007+
2 7 8 9
1008+
>>> for x, y in df.groupby(by=["a"]):
1009+
... print(f'{x}\\n{y}\\n')
1010+
(1,)
1011+
a b c
1012+
0 1 2 3
1013+
1 1 5 6
1014+
(7,)
1015+
a b c
1016+
2 7 8 9
8891017
"""
8901018
keys = self.keys
8911019
level = self.level
@@ -1787,7 +1915,7 @@ def _obj_1d_constructor(self) -> Callable:
17871915

17881916
@final
17891917
@Substitution(name="groupby")
1790-
@Appender(_common_see_also)
1918+
@Substitution(see_also=_common_see_also)
17911919
def any(self, skipna: bool = True):
17921920
"""
17931921
Return True if any value in the group is truthful, else False.
@@ -1802,6 +1930,38 @@ def any(self, skipna: bool = True):
18021930
Series or DataFrame
18031931
DataFrame or Series of boolean values, where a value is True if any element
18041932
is True within its respective group, False otherwise.
1933+
%(see_also)s
1934+
Examples
1935+
--------
1936+
For SeriesGroupBy:
1937+
1938+
>>> lst = ['a', 'a', 'b']
1939+
>>> ser = pd.Series([1, 2, 0], index=lst)
1940+
>>> ser
1941+
a 1
1942+
a 2
1943+
b 0
1944+
dtype: int64
1945+
>>> ser.groupby(level=0).any()
1946+
a True
1947+
b False
1948+
dtype: bool
1949+
1950+
For DataFrameGroupBy:
1951+
1952+
>>> data = [[1, 0, 3], [1, 0, 6], [7, 1, 9]]
1953+
>>> df = pd.DataFrame(data, columns=["a", "b", "c"],
1954+
... index=["ostrich", "penguin", "parrot"])
1955+
>>> df
1956+
a b c
1957+
ostrich 1 0 3
1958+
penguin 1 0 6
1959+
parrot 7 1 9
1960+
>>> df.groupby(by=["a"]).any()
1961+
b c
1962+
a
1963+
1 False True
1964+
7 True True
18051965
"""
18061966
return self._cython_agg_general(
18071967
"any",
@@ -1811,7 +1971,7 @@ def any(self, skipna: bool = True):
18111971

18121972
@final
18131973
@Substitution(name="groupby")
1814-
@Appender(_common_see_also)
1974+
@Substitution(see_also=_common_see_also)
18151975
def all(self, skipna: bool = True):
18161976
"""
18171977
Return True if all values in the group are truthful, else False.
@@ -1826,6 +1986,39 @@ def all(self, skipna: bool = True):
18261986
Series or DataFrame
18271987
DataFrame or Series of boolean values, where a value is True if all elements
18281988
are True within its respective group, False otherwise.
1989+
%(see_also)s
1990+
Examples
1991+
--------
1992+
1993+
For SeriesGroupBy:
1994+
1995+
>>> lst = ['a', 'a', 'b']
1996+
>>> ser = pd.Series([1, 2, 0], index=lst)
1997+
>>> ser
1998+
a 1
1999+
a 2
2000+
b 0
2001+
dtype: int64
2002+
>>> ser.groupby(level=0).all()
2003+
a True
2004+
b False
2005+
dtype: bool
2006+
2007+
For DataFrameGroupBy:
2008+
2009+
>>> data = [[1, 0, 3], [1, 5, 6], [7, 8, 9]]
2010+
>>> df = pd.DataFrame(data, columns=["a", "b", "c"],
2011+
... index=["ostrich", "penguin", "parrot"])
2012+
>>> df
2013+
a b c
2014+
ostrich 1 0 3
2015+
penguin 1 5 6
2016+
parrot 7 8 9
2017+
>>> df.groupby(by=["a"]).all()
2018+
b c
2019+
a
2020+
1 False True
2021+
7 True True
18292022
"""
18302023
return self._cython_agg_general(
18312024
"all",

0 commit comments

Comments
 (0)