Skip to main content
`Ctrl`+`K`

# pandas.api.typing.DataFrameGroupBy.transform

DataFrameGroupBy.transform(func=None, *args, engine=None, engine_kwargs=None, **kwargs)

  Call function producing a same-indexed DataFrame on each group.

  Returns a DataFrame having the same indexes as the original object filled with the transformed values.

  When `func` is a user-defined function, by default it operates on each column of each group separately (each column is passed as a `Series`); see the Notes section below.

  Parameters:
    func function, str, list, or dict

      Function to apply to each group. See the Notes section below for requirements.

      Accepted inputs are:

      - String

      - Python function

      - Numba JIT function with `engine='numba'` specified.

      - List of strings/functions: applied to every non-key column, returning a MultiIndex-column DataFrame `(column, func)`.

      - Dict `{column: func}` or `{name: NamedFunc(column, func)}`: applied per-column as specified.

      Changed in version 3.1.0: Added support for list-like, dict, and `NamedFunc` arguments.

      Only passing a single function is supported with the numba 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.

      If a string is chosen, then it needs to be the name of the groupby method you want to use.

    *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 the global 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 `nogil` and `parallel` dictionary keys. The values must either be `True` or `False`. The default `engine_kwargs` for the `'numba'` engine is `{'nogil': False, 'parallel': False}` and will be applied to the function

    **kwargs

      Keyword arguments to be passed into func. When `func=None`, `**kwargs` should be pairs of `output_name=NamedFunc(column, func)`.

  Returns:
    DataFrame

      DataFrame with the same indexes as the original object filled with transformed values.

  See also

  `DataFrame.groupby.apply`

    Apply function `func` group-wise and combine the results together.

  `DataFrame.groupby.aggregate`

    Aggregate using one or more operations.

  `DataFrame.transform`

    Call `func` on self producing a DataFrame with the same axis shape as self.

  Notes

  See Transformation in the User Guide for more details and examples.

  Each group is endowed the attribute ‘name’ in case you need to know which group you are working on.

  The current implementation imposes three requirements on `func`:

  - `func` must return a value that either has the same shape as the input subframe or can be broadcast to the shape of the input subframe. For example, if `func` returns a scalar it will be broadcast to have the same shape as the input subframe.

  - `func` is applied to each column of the group separately (each column is passed as a `Series`). If `func` also supports application to the entire group `DataFrame` and returns the same result, a faster path operating on the whole group is used starting from the second group.

  - `func` must not mutate groups. Mutation is not supported and may produce unexpected results. See Mutating with User Defined Function (UDF) methods for more details.

  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.

  The resulting dtype will reflect the return value of the passed `func`, see the examples below.

  Changed in version 2.0.0: When using `.transform` on a grouped DataFrame and the transformation function returns a DataFrame, pandas now aligns the result’s index with the input’s index. You can call `.to_numpy()` on the result of the transformation function to avoid alignment.

  Examples

      >>> df = pd.DataFrame(
      ...     {
      ...         "A": ["foo", "bar", "foo", "bar", "foo", "bar"],
      ...         "B": ["one", "one", "two", "three", "two", "two"],
      ...         "C": [1, 5, 5, 2, 5, 5],
      ...         "D": [2.0, 5.0, 8.0, 1.0, 2.0, 9.0],
      ...     }
      ... )
      >>> grouped = df.groupby("A")[["C", "D"]]
      >>> grouped.transform(lambda x: (x - x.mean()) / x.std())
                C         D
      0 -1.154701 -0.577350
      1  0.577350  0.000000
      2  0.577350  1.154701
      3 -1.154701 -1.000000
      4  0.577350 -0.577350
      5  0.577350  1.000000

  Broadcast result of the transformation

      >>> grouped.transform(lambda x: x.max() - x.min())
           C    D
      0  4.0  6.0
      1  3.0  8.0
      2  4.0  6.0
      3  3.0  8.0
      4  4.0  6.0
      5  3.0  8.0

      >>> grouped.transform("mean")
                C    D
      0  3.666667  4.0
      1  4.000000  5.0
      2  3.666667  4.0
      3  4.000000  5.0
      4  3.666667  4.0
      5  4.000000  5.0

  The resulting dtype will reflect the return value of the passed `func`, for example:

      >>> grouped.transform(lambda x: x.astype(int).max())
         C  D
      0  5  8
      1  5  9
      2  5  8
      3  5  9
      4  5  8
      5  5  9

  List-like arguments

      >>> df2 = pd.DataFrame({"col": list("aab"), "val": range(3), "other": range(3)})
      >>> df2.groupby("col").transform(["sum", "min"])
         val       other
         sum min   sum min
      0    1   0     1   0
      1    1   0     1   0
      2    2   2     2   2

  Dictionary arguments

      >>> df2.groupby("col").transform({"val": "sum", "other": "min"})
         val  other
      0    1      0
      1    1      0
      2    2      2

  Named aggregation

      >>> df2.groupby("col").transform(
      ...     val_sum=pd.NamedAgg(column="val", aggfunc="sum"),
      ...     other_min=pd.NamedAgg(column="other", aggfunc="min"),
      ... )
         val_sum  other_min
      0        1          0
      1        1          0
      2        2          2