DOC: DataFrame.agg and Series.agg documentation is unclear on which function we can use

[arnaudlegout]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.agg.html
https://pandas.pydata.org/docs/reference/api/pandas.Series.agg.html

Documentation problem

During discussion for issue #49352 we found that the documentation of the agg function for both DataFrame and Series is unclear on

• which function will work
• what will be passed to the function
• how function names are looked up (and so which optional parameter can be used if we use function names)

Suggested fix for documentation

For DataFrame.agg, it must be explained that:

The passed function must accept either a Series and return a scalar, or a DataFrame and returns a Series. If the axis is 0 and the function accept a Series, the passed Series will be a column, otherwise, it will be a row. If function names are passed, the called function will be the first function found according to the MRO from a DataFrame object (that is, the result of getattr(df, 'func_name')). For instance, passing mean will match DataFrame.mean.

For Series.agg, it must be explained that:

The passed function must accept either a Series and return a scalar. If function names are passed, the called function will be the first function found according to the MRO from a Series object (that is, the result of getattr(s, 'func_name')).

[arnaudlegout]

I can propose a PR for this issue, but I need someone to check the behavior I described is correct because I am not sure. What I described correspond to my understanding of core.appy._try_aggregate_string_function that I believed is called to convert a function name to a function object.

[arnaudlegout]

I missed that after searching the DataFrame MRO, it falls back to numpy MRO. So updating the documentation.

For DataFrame.agg, it must be explained that:

The passed function must accept either a Series and return a scalar, or a DataFrame and returns a Series. If the axis is 0 and the function accept a Series, the passed Series will be a column, otherwise, it will be a row. If function names are passed, the called function will be the first function found according to the MRO from a DataFrame object (that is, the result of getattr(df, 'func_name')). For instance, passing mean will match DataFrame.mean. If no function is found with this name, then it will be searched according to the MRO of numpy.

For Series.agg, it must be explained that:

The passed function must accept either a Series and return a scalar. If function names are passed, the called function will be the first function found according to the MRO from a Series object (that is, the result of getattr(s, 'func_name')). If no function is found with this name, then it will be searched according to the MRO of numpy.