Merge pull request pandas-dev#10977 from Winterflower/pandas-series-apply

DOC: Examples for Series.apply docstring

Author: jreback

pandas/core/series.py

@@ -2064,13 +2064,84 @@ def apply(self, func, convert_dtype=True, args=(), **kwds):
             Positional arguments to pass to function in addition to the value
         Additional keyword arguments will be passed as keywords to the function
 
+        Returns
+        -------
+        y : Series or DataFrame if func returns a Series
+
         See also
         --------
         Series.map: For element-wise operations
 
-        Returns
-        -------
-        y : Series or DataFrame if func returns a Series
+        Examples
+        --------
+
+        Create a series with typical summer temperatures for each city.
+
+        >>> import pandas as pd
+        >>> import numpy as np
+        >>> series = pd.Series([20, 21, 12], index=['London', 
+        ... 'New York','Helsinki'])
+        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
+        >>> series.apply(square)
+        London      400
+        New York    441
+        Helsinki    144
+        dtype: int64
+
+        Square the values by passing an anonymous function as an
+        argument to ``apply()``.
+
+        >>> series.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
+
+        >>> series.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
+
+        >>> series.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. 
+
+        >>> series.apply(np.log)
+        London      2.995732
+        New York    3.044522
+        Helsinki    2.484907
+        dtype: float64
+
+
         """
         if len(self) == 0:
             return self._constructor(dtype=self.dtype,