DOC: update the DataFrame.mode method 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.mode)  ######################
################################################################################

Get the mode(s) of each element along the axis selected.

Adds a row for each mode per label, filling gaps with NaN.

Parameters
----------
axis : {0 or 'index', 1 or 'columns'}, default 0
    The axis to iterate over while searching for the mode.
    To find the mode for each column, iterate over rows (``axis=0``
    default behaviour).
    To find the mode for each row, iterate over columns (``axis=1``).
numeric_only : boolean, default False
    If True, only apply to numeric dimensions.

Returns
-------
modes : DataFrame (sorted)
    A DataFrame containing the modes
    If ``axis=0``, there will be one column per column in the original
    DataFrame, with as many rows as there are modes.
    If ``axis=1``, there will be one row per row in the original
    DataFrame, with as many columns as there are modes.

Notes
-----
There may be multiple values returned for the selected
axis (when more than one item share the maximum frequency), which is
the reason why a dataframe is returned. If you want to impute missing
values with the mode in a dataframe ``df``, you can just do this:
``df.fillna(df.mode().iloc[0])``.

See Also
--------
Series.mode : Return the highest frequency value in a Series.
Series.value_counts : Returns a Series with all occuring values as
    indices and the number of occurences as values.

Examples
--------

``mode`` returns a DataFrame with multiple rows if there is more than
one mode. Missing entries are imputed with NaN.

>>> grades = pd.DataFrame({
...     'Science': [80, 70, 80, 75, 80, 75, 85, 90, 80, 70],
...     'Math': [70, 70, 75, 75, 80, 80, 85, 85, 90, 90]
... })
>>> grades.apply(lambda x: x.value_counts())
    Science  Math
70        2     2
75        2     2
80        4     2
85        1     2
90        1     2
>>> grades.mode()
   Science  Math
0     80.0    70
1      NaN    75
2      NaN    80
3      NaN    85
4      NaN    90

Use ``axis=1`` to apply mode over columns (get the mode of each row).

>>> student_grades = pd.DataFrame.from_dict({
...     'Alice': [80, 85, 90, 85, 95],
...     'Bob': [70, 80, 80, 75, 90]
... }, 'index')
>>> student_grades
        0   1   2   3   4
Alice  80  85  90  85  95
Bob    70  80  80  75  90
>>> student_grades.mode(axis=1)
        0
Alice  85
Bob    80

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.mode" correct. :)

```

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
name: Numeric Operations
description: Arithmetic, Comparison, and Logical operations

Comments:
Hello @mkoo21! Thanks for updating the PR.

 - In the file [`pandas/core/frame.py`](https://github.com/pandas-dev/pandas/blob/e476c551319b64a46e4fb8b83305cadc6b70098f/pandas/core/frame.py), following are the PEP8 issues :

> [Line 5950:1](https://github.com/pandas-dev/pandas/blob/e476c551319b64a46e4fb8b83305cadc6b70098f/pandas/core/frame.py#L5950): [W293](https://duckduckgo.com/?q=pep8%20W293) blank line contains whitespace



##### Comment last updated on March 11, 2018 at 21:14 Hours UTC
@mkoo21 Can you try to follow the guidelines please? Check for PEP8, paste the output of the validation script
Sorry, I thought I ran the PEP8 check but it wasn't outputting anything when I ran it earlier. 
Output of validation script: 
```
################################################################################
###################### Docstring (pandas.DataFrame.mode)  ######################
################################################################################

Get the mode(s) of each element along the axis selected.

Adds a row for each mode per label, filling gaps with NaN.

Parameters
----------
axis : {0 or 'index', 1 or 'columns'}, default 0
    The axis to iterate over while searching for the mode.
    To find the mode for each column, iterate over rows (``axis=0``
    default behaviour).
    To find the mode for each row, iterate over columns (``axis=1``).
numeric_only : boolean, default False
    If True, only apply to numeric dimensions.

Returns
-------
modes : DataFrame (sorted)
    A DataFrame containing the modes
    If ``axis=0``, there will be one column per column in the original
    DataFrame, with as many rows as there are modes.
    If ``axis=1``, there will be one row per row in the original
    DataFrame, with as many columns as there are modes.

Notes
-----
There may be multiple values returned for the selected
axis (when more than one item share the maximum frequency), which is
the reason why a dataframe is returned. If you want to impute missing
values with the mode in a dataframe ``df``, you can just do this:
``df.fillna(df.mode().iloc[0])``.

See Also
--------
Series.mode : Return the highest frequency value in a Series.
Series.value_counts : Returns a Series with all occuring values as
    indices and the number of occurences as values.

Examples
--------

``mode`` returns a DataFrame with multiple rows if there is more than
one mode. Missing entries are imputed with NaN.

>>> grades = pd.DataFrame({
...     'Science': [80, 70, 80, 75, 80, 75, 85, 90, 80, 70],
...     'Math': [70, 70, 75, 75, 80, 80, 85, 85, 90, 90]
... })
>>> grades.apply(lambda x: x.value_counts())
    Science  Math
70        2     2
75        2     2
80        4     2
85        1     2
90        1     2
>>> grades.mode()
   Science  Math
0     80.0    70
1      NaN    75
2      NaN    80
3      NaN    85
4      NaN    90

Use ``axis=1`` to apply mode over columns (get the mode of each row).

>>> student_grades = pd.DataFrame.from_dict({
...     'Alice': [80, 85, 90, 85, 95],
...     'Bob': [70, 80, 80, 75, 90]
... }, 'index')
>>> student_grades
        0   1   2   3   4
Alice  80  85  90  85  95
Bob    70  80  80  75  90
>>> student_grades.mode(axis=1)
        0
Alice  85
Bob    80

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.mode" correct. :)
```
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20241?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@c3d491a`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `92.1%`.

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

```diff
@@            Coverage Diff            @@
##             master   #20241   +/-   ##
=========================================
  Coverage          ?   91.72%           
=========================================
  Files             ?      150           
  Lines             ?    49162           
  Branches          ?        0           
=========================================
  Hits              ?    45096           
  Misses            ?     4066           
  Partials          ?        0
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.11% <92.1%> (?)` | |
| #single | `41.86% <23.68%> (?)` | |

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

------

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

I've made the requested changes to the text. The validation and PEP8 scripts passed. I'm not sure how to address the CI failures on my end. Is there anything else I need to do?
Superseded by #22404 (discontinued PR, and the source branch does not exist anymore).