DOC: update the pandas.DataFrame.apply docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [x] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
###################### Docstring (pandas.DataFrame.apply) ######################
################################################################################

Apply a function along an axis of the `Series`.

Objects passed to the function are `Series` objects having as index
either the DataFrame's index (`axis=0`)
or the DataFrame's columns (`axis=1`).
If `result_type` is None, the final return type is the return
type of the applied function.
Otherwise, it depends on the `result_type` argument.

Parameters
----------
func : function
    Function to apply to each column or row.
axis : {0 or 'index', 1 or 'columns'}, default 0
    Axis along which the function is applied:

    * 0 or 'index': apply function to each column.
    * 1 or 'columns': apply function to each row.
broadcast : boolean, optional
    Only relevant for aggregation functions:

    * `False` or `None` : returns a `Series` whose length is the length
      of the index or the number of columns (based on the `axis`
      parameter)
    * `True` : results will be broadcast to the original shape
      of the frame, the original index and columns will be retained.

    .. deprecated:: 0.23.0
       This argument will be removed in a future version, replaced
       by result_type='broadcast'.

raw : boolean, default False
    * `False` : passes each row or column into a `Series` to the
      function.
    * `True` : the passed function will receive ndarray objects
      instead.
    If you are just applying a NumPy reduction function this will
    achieve much better performance.
reduce : boolean or None, default None
    Try to apply reduction procedures. If the `DataFrame` is empty,
    :meth:`apply` will use reduce to determine whether the result
    should be a `Series` or a `DataFrame`. If reduce is None (the
    default), :meth:`apply`'s return value will be guessed by calling
    func on an empty `Series`
    (note: while guessing, exceptions raised by `func` will be
    ignored).
    If reduce is True a `Series` will always be returned, and if
    `False` a `DataFrame` will always be returned.

    .. deprecated:: 0.23.0.
       This argument will be removed in a future version, replaced
       by result_type='reduce'.

result_type : {'expand', 'reduce', 'broadcast', None}
    These only act when `axis=1` (columns):

    * 'expand' : list-like results will be turned into columns.
    * 'reduce' : returns a `Series` if possible rather than expanding
      list-like results. This is the opposite of 'expand'.
    * 'broadcast' : results will be broadcast to the original shape
      of the `DataFrame`, the original index and columns will be
      retained.

    The default behaviour (`None`) depends on the return value of the
    applied function: list-like results will be returned as a `Series`
    of those. However if the apply function returns a `Series` these
    are expanded to columns.

    .. versionadded:: 0.23.0.

args : tuple
    Positional arguments to pass to function in addition to the
    array/series.
kwds :
    Additional keyword arguments to pass as keywords to the function.

Notes
-----
In the current implementation apply calls func twice on the
first column/row to decide whether it can take a fast or slow
code path. This can lead to unexpected behavior if func has
side-effects, as they will take effect twice for the first
column/row.

Examples
--------

We use this DataFrame to illustrate

>>> df = pd.DataFrame(np.tile(np.arange(3), 6).reshape(6, -1) + 1,
...                   columns=['A', 'B', 'C'])
>>> df
   A  B  C
0  1  2  3
1  1  2  3
2  1  2  3
3  1  2  3
4  1  2  3
5  1  2  3

Using a numpy universal function (in this case the same as
``np.sqrt(df)``):

>>> df.apply(np.sqrt)
     A         B         C
0  1.0  1.414214  1.732051
1  1.0  1.414214  1.732051
2  1.0  1.414214  1.732051
3  1.0  1.414214  1.732051
4  1.0  1.414214  1.732051
5  1.0  1.414214  1.732051

Using a reducing function on either axis

>>> df.apply(np.sum, axis=0)
A     6
B    12
C    18
dtype: int64

>>> df.apply(np.sum, axis=1)
0    6
1    6
2    6
3    6
4    6
5    6
dtype: int64

Retuning a list-like will result in a Series

>>> df.apply(lambda x: [1, 2], axis=1)
0    [1, 2]
1    [1, 2]
2    [1, 2]
3    [1, 2]
4    [1, 2]
5    [1, 2]
dtype: object

Passing result_type='expand' will expand list-like results
to columns of a Dataframe

>>> df.apply(lambda x: [1, 2], axis=1, result_type='expand')
   0  1
0  1  2
1  1  2
2  1  2
3  1  2
4  1  2
5  1  2

Returning a Series inside the function is similar to passing
``result_type='expand'``. The resulting column names
will be the Series index.

>>> df.apply(lambda x: pd.Series([1, 2], index=['foo', 'bar']), axis=1)
   foo  bar
0    1    2
1    1    2
2    1    2
3    1    2
4    1    2
5    1    2

Passing ``result_type='broadcast'`` will ensure the same shape
result, whether list-like or scalar is returned by the function,
and broadcast it along the axis. The resulting column names will
be the originals.

>>> df.apply(lambda x: [1, 2, 3], axis=1, result_type='broadcast')
   A  B  C
0  1  2  3
1  1  2  3
2  1  2  3
3  1  2  3
4  1  2  3
5  1  2  3

See also
--------
DataFrame.applymap: For elementwise operations
DataFrame.aggregate: only perform aggregating type operations
DataFrame.transform: only perform transformating type operations

Returns
-------
applied : Series or DataFrame

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwds'} not documented
		Unknown parameters {'kwds :'}
		Parameter "raw" description should start with capital letter
		Parameter "kwds :" has no type
```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.


Labels:
name: Docs
name: Reshaping
description: Concat, Merge/Join, Stack/Unstack, Explode

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20202?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@5b0caf4`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/20202/graphs/tree.svg?token=eZ4WkYLtcO&width=650&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/20202?src=pr&el=tree)

```diff
@@            Coverage Diff            @@
##             master   #20202   +/-   ##
=========================================
  Coverage          ?    91.7%           
=========================================
  Files             ?      150           
  Lines             ?    49167           
  Branches          ?        0           
=========================================
  Hits              ?    45089           
  Misses            ?     4078           
  Partials          ?        0
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.09% <100%> (?)` | |
| #single | `41.86% <100%> (?)` | |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20202?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/20202/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.18% <100%> (ø)` | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20202?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20202?src=pr&el=footer). Last update [5b0caf4...c68a012](https://codecov.io/gh/pandas-dev/pandas/pull/20202?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Hello @mdeboc! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on March 12, 2018 at 16:46 Hours UTC
@mdeboc Thanks a lot!