added agg, transform and filter

Author: arthurlw

doc/source/user_guide/user_defined_functions.rst

@@ -13,10 +13,6 @@ flexibility when built-in methods are not sufficient. These functions can be
 applied at different levels: element-wise, row-wise, column-wise, or group-wise,
 depending on the method used.
 
-.. .. note:: 
-    
-..     User-Defined Functions will be abbreviated to UDFs throughout this guide.
-
 Why Use User-Defined Functions?
 -------------------------------
 
@@ -36,7 +32,7 @@ needs go beyond standard aggregation, transformation, or filtering. UDFs allow y
 What functions support User-Defined Functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-UDFs can be applied across various pandas methods that work with Series and DataFrames:
+User-Defined Functions can be applied across various pandas methods that work with Series and DataFrames:
 
 * :meth:`DataFrame.apply` - A flexible method that allows applying a function to Series,
   DataFrames, or groups of data.
@@ -60,7 +56,6 @@ ways to apply user-defined functions across different pandas data structures.
 The :meth:`DataFrame.apply` allows applying a user-defined functions along either axis (rows or columns):
 
 .. ipython:: python
-
     import pandas as pd
     
     # Sample DataFrame
@@ -71,8 +66,8 @@ The :meth:`DataFrame.apply` allows applying a user-defined functions along eithe
         return x + 1
     
     # Apply function
-    df_transformed = df.apply(add_one)
-    print(df_transformed)
+    df_applied = df.apply(add_one)
+    print(df_applied)
 
     # This works with lambda functions too
     df_lambda = df.apply(lambda x : x + 1)
@@ -82,9 +77,6 @@ The :meth:`DataFrame.apply` allows applying a user-defined functions along eithe
 :meth:`DataFrame.apply` also accepts dictionaries of multiple user-defined functions:
 
 .. ipython:: python
-
-    import pandas as pd
-    
     # Sample DataFrame
     df = pd.DataFrame({'A': [1, 2, 3], 'B': [1, 2, 3]})
     
@@ -96,8 +88,8 @@ The :meth:`DataFrame.apply` allows applying a user-defined functions along eithe
         return x + 2
     
     # Apply function
-    df_transformed = df.apply({"A": add_one, "B": add_two})
-    print(df_transformed)
+    df_applied = df.apply({"A": add_one, "B": add_two})
+    print(df_applied)
 
     # This works with lambda functions too
     df_lambda = df.apply({"A": lambda x : x + 1, "B": lambda x : x + 2})
@@ -106,9 +98,6 @@ The :meth:`DataFrame.apply` allows applying a user-defined functions along eithe
 :meth:`DataFrame.apply` works with Series objects as well:
 
 .. ipython:: python
-
-    import pandas as pd
-    
     # Sample Series
     s = pd.Series([1, 2, 3])
     
@@ -117,8 +106,8 @@ The :meth:`DataFrame.apply` allows applying a user-defined functions along eithe
         return x + 1
     
     # Apply function
-    s_transformed = s.apply(add_one)
-    print(df_transformed)
+    s_applied = s.apply(add_one)
+    print(s_applied)
 
     # This works with lambda functions too
     s_lambda = s.apply(lambda x : x + 1)
@@ -127,10 +116,9 @@ The :meth:`DataFrame.apply` allows applying a user-defined functions along eithe
 :meth:`DataFrame.agg`
 ---------------------
 
-When working with grouped data, user-defined functions can be used within :meth:`DataFrame.agg`:
+The :meth:`DataFrame.agg` allows aggregation with a user-defined function along either axis (rows or columns):
 
 .. ipython:: python
-
     # Sample DataFrame
     df = pd.DataFrame({
         'Category': ['A', 'A', 'B', 'B'],
@@ -145,6 +133,78 @@ When working with grouped data, user-defined functions can be used within :meth:
     grouped_result = df.groupby('Category')['Values'].agg(group_mean)
     print(grouped_result)
 
+In terms of the API, :meth:`DataFrame.agg` has similar usage to :meth:`DataFrame.apply`,
+but it is primarily used for **aggregation**, applying functions that summarize or reduce data.
+Typically, the result of :meth:`DataFrame.agg` reduces the dimensions of data as shown
+in the above example. Conversely, :meth:`DataFrame.apply` is more general and allows for both
+transformations and custom row-wise or element-wise operations.
+
+:meth:`DataFrame.transform`
+---------------------------
+
+The :meth:`DataFrame.transform` allows transforms a Dataframe, Series or Grouped object
+while preserving the original shape of the object.
+
+.. ipython:: python 
+    # Sample DataFrame  
+    df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})  
+
+    # User-Defined Function  
+    def double(x):  
+        return x * 2  
+
+    # Apply transform  
+    df_transformed = df.transform(double)  
+    print(df_transformed)  
+
+    # This works with lambda functions too  
+    df_lambda = df.transform(lambda x: x * 2)  
+    print(df_lambda)  
+
+Attempting to use common aggregation functions such as `mean` or `sum` will result in
+values being broadcasted to the original dimensions:
+
+.. ipython:: python 
+    # Sample DataFrame
+    df = pd.DataFrame({
+        'Category': ['A', 'A', 'B', 'B', 'B'],
+        'Values': [10, 20, 30, 40, 50]
+    })
+
+    # Using transform with mean
+    df['Mean_Transformed'] = df.groupby('Category')['Values'].transform('mean')
+
+    # Using transform with sum
+    df['Sum_Transformed'] = df.groupby('Category')['Values'].transform('sum')
+
+    # Result broadcasted to DataFrame
+    print(df)
+
+:meth:`DataFrame.filter`
+------------------------
+
+The :meth:`DataFrame.filter` method is used to select subsets of the DataFrame’s
+columns or rows and accepts user-defined functions. Specifically, these functions
+return boolean values to filter columns or rows. It is useful when you want to 
+extract specific columns or rows that match particular conditions.
+
+.. ipython:: python 
+    # Sample DataFrame
+    df = pd.DataFrame({
+        'A': [1, 2, 3],
+        'B': [4, 5, 6],
+        'C': [7, 8, 9],
+        'D': [10, 11, 12]
+    })
+
+    # Define a function that filters out columns where the name is longer than 1 character
+    df_filtered_func = df.filter(items=lambda x: len(x) > 1)
+    print(df_filtered_func)
+
+Unlike the methods discussed earlier, :meth:`DataFrame.filter` does not accept
+functions that do not return boolean values, such as `mean` or `sum`.
+
+
 Performance Considerations
 --------------------------