Skip to content

Commit

Permalink
DOC: fix RT03, ES01 for pandas.core.groupby.SeriesGroupBy.agg and pan…
Browse files Browse the repository at this point in the history 
…das.core.groupby.SeriesGroupBy.aggregate (#59898)

* DOC: fix RT03, ES01 for pandas.core.groupby.SeriesGroupBy.agg

* DOC: remove _agg_template_series

Co-authored-by: mroeschke <mroeschke@users.noreply.github.com>
Co-authored-by: rhshadrach <rhshadrach@users.noreply.github.com>

* DOC: remove _agg_template_series

Co-authored-by: mroeschke <mroeschke@users.noreply.github.com>
Co-authored-by: rhshadrach <rhshadrach@users.noreply.github.com>

* DOC: remove _agg_template_seris

---------

Co-authored-by: mroeschke <mroeschke@users.noreply.github.com>
Co-authored-by: rhshadrach <rhshadrach@users.noreply.github.com>
  • Loading branch information
@tuhinsharma121 @mroeschke @rhshadrach
3 people authored Sep 28, 2024
1 parent cf12e67 commit d538a1c
Show file tree
Hide file tree
Showing 4 changed files with 134 additions and 86 deletions.
2 changes: 0 additions & 2 deletions ci/code_checks.sh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -137,8 +137,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
-i "pandas.core.groupby.DataFrameGroupBy.plot PR02" \
-i "pandas.core.groupby.DataFrameGroupBy.sem SA01" \
-i "pandas.core.groupby.SeriesGroupBy.__iter__ RT03,SA01" \
-i "pandas.core.groupby.SeriesGroupBy.agg RT03" \
-i "pandas.core.groupby.SeriesGroupBy.aggregate RT03" \
-i "pandas.core.groupby.SeriesGroupBy.get_group RT03,SA01" \
-i "pandas.core.groupby.SeriesGroupBy.groups SA01" \
-i "pandas.core.groupby.SeriesGroupBy.indices SA01" \
Expand Down
136 changes: 134 additions & 2 deletions pandas/core/groupby/generic.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,6 @@
from pandas.core.groupby.groupby import (
GroupBy,
GroupByPlot,
_agg_template_series,
_transform_template,
)
from pandas.core.indexes.api import (
Expand Down Expand Up @@ -323,8 +322,141 @@ def apply(self, func, *args, **kwargs) -> Series:
"""
return super().apply(func, *args, **kwargs)

@doc(_agg_template_series, examples=_agg_examples_doc, klass="Series")
def aggregate(self, func=None, *args, engine=None, engine_kwargs=None, **kwargs):
"""
Aggregate using one or more operations.
The ``aggregate`` method enables flexible and efficient aggregation of grouped
data using a variety of functions, including built-in, user-defined, and
optimized JIT-compiled functions.
Parameters
----------
func : function, str, list, dict or None
Function to use for aggregating the data. If a function, must either
work when passed a Series or when passed to Series.apply.
Accepted combinations are:
- function
- string function name
- list of functions and/or function names, e.g. ``[np.sum, 'mean']``
- None, in which case ``**kwargs`` are used with Named Aggregation. Here
the output has one column for each element in ``**kwargs``. The name of
the column is keyword, whereas the value determines the aggregation
used to compute the values in the column.
Can also accept a Numba JIT function with
``engine='numba'`` specified. Only passing a single function is supported
with this engine.
If the ``'numba'`` engine is chosen, the function must be
a user defined function with ``values`` and ``index`` as the
first and second arguments respectively in the function signature.
Each group's index will be passed to the user defined function
and optionally available for use.
.. deprecated:: 2.1.0
Passing a dictionary is deprecated and will raise in a future version
of pandas. Pass a list of aggregations instead.
*args
Positional arguments to pass to func.
engine : str, default None
* ``'cython'`` : Runs the function through C-extensions from cython.
* ``'numba'`` : Runs the function through JIT compiled code from numba.
* ``None`` : Defaults to ``'cython'`` or globally setting
``compute.use_numba``
engine_kwargs : dict, default None
* For ``'cython'`` engine, there are no accepted ``engine_kwargs``
* For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil``
and ``parallel`` dictionary keys. The values must either be ``True`` or
``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is
``{'nopython': True, 'nogil': False, 'parallel': False}`` and will be
applied to the function
**kwargs
* If ``func`` is None, ``**kwargs`` are used to define the output names and
aggregations via Named Aggregation. See ``func`` entry.
* Otherwise, keyword arguments to be passed into func.
Returns
-------
Series
Aggregated Series based on the grouping and the applied aggregation
functions.
See Also
--------
SeriesGroupBy.apply : Apply function func group-wise
and combine the results together.
SeriesGroupBy.transform : Transforms the Series on each group
based on the given function.
Series.aggregate : Aggregate using one or more operations.
Notes
-----
When using ``engine='numba'``, there will be no "fall back" behavior internally.
The group data and group index will be passed as numpy arrays to the JITed
user defined function, and no alternative execution attempts will be tried.
Functions that mutate the passed object can produce unexpected
behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
for more details.
.. versionchanged:: 1.3.0
The resulting dtype will reflect the return value of the passed ``func``,
see the examples below.
Examples
--------
>>> s = pd.Series([1, 2, 3, 4])
>>> s
0 1
1 2
2 3
3 4
dtype: int64
>>> s.groupby([1, 1, 2, 2]).min()
1 1
2 3
dtype: int64
>>> s.groupby([1, 1, 2, 2]).agg("min")
1 1
2 3
dtype: int64
>>> s.groupby([1, 1, 2, 2]).agg(["min", "max"])
min max
1 1 2
2 3 4
The output column names can be controlled by passing
the desired column names and aggregations as keyword arguments.
>>> s.groupby([1, 1, 2, 2]).agg(
... minimum="min",
... maximum="max",
... )
minimum maximum
1 1 2
2 3 4
.. versionchanged:: 1.3.0
The resulting dtype will reflect the return value of the aggregating
function.
>>> s.groupby([1, 1, 2, 2]).agg(lambda x: x.astype(float).min())
1 1.0
2 3.0
dtype: float64
"""
relabeling = func is None
columns = None
if relabeling:
Expand Down
81 changes: 0 additions & 81 deletions pandas/core/groupby/groupby.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -364,87 +364,6 @@ class providing the base-class of operations.
--------
%(example)s"""

_agg_template_series = """
Aggregate using one or more operations.
Parameters
----------
func : function, str, list, dict or None
Function to use for aggregating the data. If a function, must either
work when passed a {klass} or when passed to {klass}.apply.
Accepted combinations are:
- function
- string function name
- list of functions and/or function names, e.g. ``[np.sum, 'mean']``
- None, in which case ``**kwargs`` are used with Named Aggregation. Here the
output has one column for each element in ``**kwargs``. The name of the
column is keyword, whereas the value determines the aggregation used to compute
the values in the column.
Can also accept a Numba JIT function with
``engine='numba'`` specified. Only passing a single function is supported
with this engine.
If the ``'numba'`` engine is chosen, the function must be
a user defined function with ``values`` and ``index`` as the
first and second arguments respectively in the function signature.
Each group's index will be passed to the user defined function
and optionally available for use.
.. deprecated:: 2.1.0
Passing a dictionary is deprecated and will raise in a future version
of pandas. Pass a list of aggregations instead.
*args
Positional arguments to pass to func.
engine : str, default None
* ``'cython'`` : Runs the function through C-extensions from cython.
* ``'numba'`` : Runs the function through JIT compiled code from numba.
* ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba``
engine_kwargs : dict, default None
* For ``'cython'`` engine, there are no accepted ``engine_kwargs``
* For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil``
and ``parallel`` dictionary keys. The values must either be ``True`` or
``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is
``{{'nopython': True, 'nogil': False, 'parallel': False}}`` and will be
applied to the function
**kwargs
* If ``func`` is None, ``**kwargs`` are used to define the output names and
aggregations via Named Aggregation. See ``func`` entry.
* Otherwise, keyword arguments to be passed into func.
Returns
-------
{klass}
See Also
--------
{klass}GroupBy.apply : Apply function func group-wise
and combine the results together.
{klass}GroupBy.transform : Transforms the Series on each group
based on the given function.
{klass}.aggregate : Aggregate using one or more operations.
Notes
-----
When using ``engine='numba'``, there will be no "fall back" behavior internally.
The group data and group index will be passed as numpy arrays to the JITed
user defined function, and no alternative execution attempts will be tried.
Functions that mutate the passed object can produce unexpected
behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
for more details.
.. versionchanged:: 1.3.0
The resulting dtype will reflect the return value of the passed ``func``,
see the examples below.
{examples}"""


@final
class GroupByPlot(PandasObject):
Expand Down
1 change: 0 additions & 1 deletion scripts/validate_unwanted_patterns.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@
"_shared_docs",
"_new_Index",
"_new_PeriodIndex",
"_agg_template_series",
"_pipe_template",
"_apply_groupings_depr",
"__main__",
Expand Down

0 comments on commit d538a1c

Please sign in to comment.