DOC: update the aggregate 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"
- [ ] 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>`
- [ ] 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.aggregate) ####################
################################################################################

Aggregate using one or multiple operations along the specified axis.

.. versionadded:: 0.20.0

Parameters
----------
func : function, string, dictionary, or list of string/functions
    Function to use for aggregating the data. If a function, must either
    work when passed a DataFrame or when passed to DataFrame.apply. For
    a DataFrame, can pass a dict, if the keys are DataFrame column names.

    Accepted combinations are:

    - string function name.
    - function.
    - list of functions.
    - dict of column names -> functions (or list of functions).
axis : {0 or 'index', 1 or 'columns'}, default 0
    - 0 or 'index': apply function to each column.
    - 1 or 'columns': apply function to each row.
args
    Optional positional arguments to pass to the function.
kwargs
    Optional keyword arguments to pass to the function.

Returns
-------
aggregated : DataFrame

Notes
-----
`agg` is an alias for `aggregate`. Use the alias.

Notes
-----
The default behavior of aggregating over the axis 0 is different from
`numpy` functions `mean`/`median`/`prod`/`sum`/`std`/`var`, where the
default is to compute the aggregation of the flattened array (e.g.,
`numpy.mean(arr_2d)` as opposed to `numpy.mean(arr_2d, axis=0)`).

`agg` is an alias for `aggregate`. Use the alias.

Examples
--------

>>> df = df = pd.DataFrame([[1,2,3],
...                         [4,5,6],
...                         [7,8,9],
...                         [np.nan, np.nan, np.nan]],
...                        columns=['A', 'B', 'C'])

Aggregate these functions across all columns

>>> df.aggregate(['sum', 'min'])
        A     B     C
sum  12.0  15.0  18.0
min   1.0   2.0   3.0

Different aggregations per column

>>> df.aggregate({'A' : ['sum', 'min'], 'B' : ['min', 'max']})
        A    B
max   NaN  8.0
min   1.0  2.0
sum  12.0  NaN

See also
--------
pandas.DataFrame.apply : Perform any type of operations.
pandas.DataFrame.transform : Perform transformation type operations.
pandas.DataFrame.groupby.aggregate : Perform aggregation type operations
    over groups.
pandas.DataFrame.resample.aggregate : Perform aggregation type operations
    over resampled bins.
pandas.DataFrame.rolling.aggregate : Perform aggregation type operations
    over rolling window.

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameter "axis" description should start with capital letter
		Parameter "args" has no type
		Parameter "kwargs" 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.

- args and kwargs have no type
- axis : {0 or 'index', 1 or 'columns'}, default 0

This PR has been made in collaboration with @rochamatcomp

Question to reviewers: we have added to the docstring the parameter `axis` because this is appropriate for DataFrame. However this dosctring is generic (shared with Series, groupby, window and resample) and the parameter `axis` is wrong for them (for Series the parameter has only one possible value). What should be the right way to fix this?


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

Comments:
I have read that there has been a change to the convention during the sprint, and `args` and `kwargs` should be in the same line and a common description in the next line. Should we implement this?
Sure

On Sun, Mar 11, 2018 at 11:12 AM, Albert Villanova del Moral <
notifications@github.com> wrote:

> *@albertvillanova* commented on this pull request.
> ------------------------------
>
> In pandas/core/frame.py
> <https://github.com/pandas-dev/pandas/pull/20276#discussion_r173660102>:
>
> >
>      See also
>      --------
> -    pandas.DataFrame.apply
> -    pandas.DataFrame.transform
> -    pandas.DataFrame.groupby.aggregate
> -    pandas.DataFrame.resample.aggregate
> -    pandas.DataFrame.rolling.aggregate
> -
> +    pandas.DataFrame.apply : Perform any type of operations.
> +    pandas.DataFrame.transform : Perform transformation type operations.
> +    pandas.DataFrame.groupby.aggregate : Perform aggregation type operations
>
> @TomAugspurger <https://github.com/tomaugspurger> Also
> pandas.core.window.EWM?
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/pull/20276#discussion_r173660102>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABQHIiBdNMGBt9kq94jiJQAED8qPomMrks5tdUzbgaJpZM4Slo-D>
> .
>

Looks like there's a merge conflict @albertvillanova. Can you update? LMK if you need help with the git stuff.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20276?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@51765d0`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff            @@
##             master   #20276   +/-   ##
=========================================
  Coverage          ?    91.7%           
=========================================
  Files             ?      150           
  Lines             ?    49165           
  Branches          ?        0           
=========================================
  Hits              ?    45087           
  Misses            ?     4078           
  Partials          ?        0
```

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

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20276?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/window.py](https://codecov.io/gh/pandas-dev/pandas/pull/20276/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvd2luZG93LnB5) | `96.31% <ø> (ø)` | |
| [pandas/core/groupby.py](https://codecov.io/gh/pandas-dev/pandas/pull/20276/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS5weQ==) | `92.14% <ø> (ø)` | |
| [pandas/core/resample.py](https://codecov.io/gh/pandas-dev/pandas/pull/20276/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzYW1wbGUucHk=) | `96.43% <ø> (ø)` | |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/20276/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.18% <ø> (ø)` | |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/20276/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.84% <ø> (ø)` | |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/20276/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `95.85% <ø> (ø)` | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20276?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/20276?src=pr&el=footer). Last update [51765d0...e1a0c27](https://codecov.io/gh/pandas-dev/pandas/pull/20276?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Please, note that this PR has been made in collaboration with @rochamatcomp