Skip to main content
`Ctrl`+`K`

# pandas.Series.apply

Series.apply(func, convert_dtype=<no_default>, args=(), *, by_row='compat', **kwargs)

  Invoke function on values of Series.

  Can be ufunc (a NumPy function that applies to the entire Series) or a Python function that only works on single values.

  Parameters:
    funcfunction

      Python function or NumPy ufunc to apply.

    convert_dtypebool, default True

      Try to find better dtype for elementwise function results. If False, leave as dtype=object. Note that the dtype is always preserved for some extension array dtypes, such as Categorical.

      Deprecated since version 2.1.0: `convert_dtype` has been deprecated. Do `ser.astype(object).apply()` instead if you want `convert_dtype=False`.

    argstuple

      Positional arguments passed to func after the series value.

    by_rowFalse or “compat”, default “compat”

      If `"compat"` and func is a callable, func will be passed each element of the Series, like `Series.map`. If func is a list or dict of callables, will first try to translate each func into pandas methods. If that doesn’t work, will try call to apply again with `by_row="compat"` and if that fails, will call apply again with `by_row=False` (backward compatible). If False, the func will be passed the whole Series at once.

      `by_row` has no effect when `func` is a string.

      Added in version 2.1.0.

    **kwargs

      Additional keyword arguments passed to func.

  Returns:
    Series or DataFrame

      If func returns a Series object the result will be a DataFrame.

  See also

  `Series.map`

    For element-wise operations.

  `Series.agg`

    Only perform aggregating type operations.

  `Series.transform`

    Only perform transforming type operations.

  Notes

  Functions that mutate the passed object can produce unexpected behavior or errors and are not supported. See Mutating with User Defined Function (UDF) methods for more details.

  Examples

  Create a series with typical summer temperatures for each city.

      >>> s = pd.Series([20, 21, 12],
      ...               index=['London', 'New York', 'Helsinki'])
      >>> s
      London      20
      New York    21
      Helsinki    12
      dtype: int64

  Square the values by defining a function and passing it as an argument to `apply()`.

      >>> def square(x):
      ...     return x ** 2
      >>> s.apply(square)
      London      400
      New York    441
      Helsinki    144
      dtype: int64

  Square the values by passing an anonymous function as an argument to `apply()`.

      >>> s.apply(lambda x: x ** 2)
      London      400
      New York    441
      Helsinki    144
      dtype: int64

  Define a custom function that needs additional positional arguments and pass these additional arguments using the `args` keyword.

      >>> def subtract_custom_value(x, custom_value):
      ...     return x - custom_value

      >>> s.apply(subtract_custom_value, args=(5,))
      London      15
      New York    16
      Helsinki     7
      dtype: int64

  Define a custom function that takes keyword arguments and pass these arguments to `apply`.

      >>> def add_custom_values(x, **kwargs):
      ...     for month in kwargs:
      ...         x += kwargs[month]
      ...     return x

      >>> s.apply(add_custom_values, june=30, july=20, august=25)
      London      95
      New York    96
      Helsinki    87
      dtype: int64

  Use a function from the Numpy library.

      >>> s.apply(np.log)
      London      2.995732
      New York    3.044522
      Helsinki    2.484907
      dtype: float64