Added documentation for Named aggregation in groupby.agg (Issue #18220)

doc/source/user_guide/groupby.rst

@@ -722,16 +722,45 @@ accepts the special syntax in :meth:`.DataFrameGroupBy.agg` and :meth:`.SeriesGr
   to make it clearer what the arguments are. As usual, the aggregation can
   be a callable or a string alias.
 
+Example:
+-------
+
+Consider the following DataFrame `animals`:
+
 .. ipython:: python
 
-   animals
+    import pandas as pd
 
-   animals.groupby("kind").agg(
-       min_height=pd.NamedAgg(column="height", aggfunc="min"),
-       max_height=pd.NamedAgg(column="height", aggfunc="max"),
-       average_weight=pd.NamedAgg(column="weight", aggfunc="mean"),
-   )
+    animals = pd.DataFrame({
+        'kind': ['cat', 'dog', 'cat', 'dog'],
+        'height': [9.1, 6.0, 9.5, 34.0],
+        'weight': [7.9, 7.5, 9.9, 198.0]
+    })
+
+To demonstrate "named aggregation," let's group the DataFrame by the 'kind' column and apply different aggregations to the 'height' and 'weight' columns:
+
+.. ipython:: python
+
+   result = animals.groupby('kind').agg(
+        min_height=pd.NamedAgg(column='height', aggfunc='min'),
+        max_height=pd.NamedAgg(column='height', aggfunc='max'),
+        average_weight=pd.NamedAgg(column='weight', aggfunc='mean')
+    )
+
+In the above example, we used "named aggregation" to specify custom output column names (`min_height`, `max_height`, and `average_weight`) for each aggregation. The result will be a new DataFrame with the aggregated values, and the output column names will be as specified.
+
+The resulting DataFrame will look like this:
+
+.. code-block:: bash
 
+       min_height  max_height  average_weight
+    kind
+    cat          9.1         9.5            8.90
+    dog          6.0        34.0          102.75
+
+In this example, the 'min_height' column contains the minimum height for each group, the 'max_height' column contains the maximum height, and the 'average_weight' column contains the average weight for each group.
+
+By using "named aggregation," you can easily control the output column names and have more descriptive results when performing aggregations with `groupby.agg`.
 
 :class:`NamedAgg` is just a ``namedtuple``. Plain tuples are allowed as well.
 
@@ -770,6 +799,77 @@ no column selection, so the values are just the functions.
        max_height="max",
    )
 
+Passing a List of Tuples
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Instead of a dictionary, you can also pass a list of tuples to the `agg` method to achieve similar results. Each tuple contains the output column name as the first element and the aggregation function as the second element. This approach is particularly useful for applying multiple aggregations on the same column.
+
+Example:
+--------
+
+Consider the following DataFrame `df`:
+
+.. ipython:: python
+    import pandas as pd
+    import numpy as np
+    df = pd.DataFrame({'key': ['a', 'a', 'b', 'b', 'a'],
+                       'data': np.random.randn(5)})
+Suppose we want to group the DataFrame by the 'key' column and apply different aggregations to the 'data' column:
+
+.. ipython:: python
+   result = df.groupby('key')['data'].agg([('foo', 'mean')])
+In this example, the output column 'foo' contains the mean value of the 'data' column for each group.
+
+To apply multiple aggregations to the same column, you can pass a list of tuples:
+
+.. ipython:: python
+   result = df.groupby('key')['data'].agg([('col1', 'mean'), ('col2', 'std')])
+In this case, the resulting DataFrame will have two columns: 'col1' containing the mean and 'col2' containing the standard deviation of the 'data' column for each group.
+
+Similarly, you can extend this approach to include more aggregations:
+
+.. ipython:: python
+   result = df.groupby('key')['data'].agg([('col1', 'mean'), ('col2', 'std'), ('col3', 'min')])
+Here, the resulting DataFrame will have three columns: 'col1', 'col2', and 'col3', each containing the respective aggregation result for the 'data' column.
+
+In addition to the examples above, let's consider a scenario where we want to calculate both the mean and the median of the 'data' column for each group:
+
+.. ipython:: python
+   result = df.groupby('key')['data'].agg([('mean_value', 'mean'), ('median_value', 'median')])
+The resulting DataFrame will have two columns: 'mean_value' and 'median_value', each containing the corresponding aggregation results.
+
+Using a list of tuples provides a concise way to apply multiple aggregations to the same column while controlling the output column names. This approach is especially handy when you need to calculate various statistics on the same data within each group.
+
+For a copy-pastable example, consider the following DataFrame `df`:
+<<<<<<< HEAD
+
+.. ipython:: python
+
+    import pandas as pd
+    import numpy as np
+
+    df = pd.DataFrame({'key': ['a', 'a', 'b', 'b', 'a'],
+                       'data': np.random.randn(5)})
+
+You can then use the `agg` function with a list of tuples for aggregations:
+
+.. ipython:: python
+
+    result = df.groupby('key')['data'].agg([('foo', 'mean')])
+
+This will create a DataFrame with the mean values for each group under the 'foo' column.
+
+.. ipython:: python
+    import pandas as pd
+    import numpy as np
+    df = pd.DataFrame({'key': ['a', 'a', 'b', 'b', 'a'],
+                       'data': np.random.randn(5)})
+You can then use the `agg` function with a list of tuples for aggregations:
+
+.. ipython:: python
+    result = df.groupby('key')['data'].agg([('foo', 'mean')])
+This will create a DataFrame with the mean values for each group under the 'foo' column.
+
 Applying different functions to DataFrame columns
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~