DOC: update the pandas.Series.where docstring

[simobasso]

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

• PR title is "DOC: update the docstring"
• The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
• The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
• 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.where) ######################
################################################################################

Replace values that don't respect a `cond` condition.

Return an object of same shape as self with entries that
not satisfy a `cond` is True are replaced by `other`.

Parameters
----------
cond : boolean NDFrame, array-like, or callable
    Where `cond` is True, keep the original value. Where
    False, replace with corresponding value from `other`.
    If `cond` is callable, it is computed on the NDFrame and
    should return boolean NDFrame or array. The callable must
    not change input NDFrame (though pandas doesn't check it).

    .. versionadded:: 0.18.1
        A callable can be used as cond.

other : scalar, NDFrame, or callable
    Entries where `cond` is False are replaced with
    corresponding value from `other`.
    If other is callable, it is computed on the NDFrame and
    should return scalar or NDFrame. The callable must not
    change input NDFrame (though pandas doesn't check it).

    .. versionadded:: 0.18.1
        A callable can be used as other.

inplace : boolean, default False
    Whether to perform the operation in place on the data.
axis : int, default None
    Alignment axis if needed.
level : int, default None
    Alignment level if needed.
errors : str, {'raise', 'ignore'}, default `raise`
    Note that currently this parameter won't affect
    the results and will always coerce to a suitable dtype.

    - `raise` : allow exceptions to be raised.
    - `ignore` : suppress exceptions. On error return original object.

try_cast : boolean, default False
    Try to cast the result back to the input type (if possible).
raise_on_error : boolean, default True
    Whether to raise on invalid data types (e.g. trying to where on
    strings).

    .. deprecated:: 0.21.0
    Use `error`.

Returns
-------
wh : same type as caller

Notes
-----
The where method is an application of the if-then idiom. For each
element in the calling DataFrame, if ``cond`` is ``True`` the
element is used; otherwise the corresponding element from the DataFrame
``other`` is used.

The signature for :func:`DataFrame.where` differs from
:func:`numpy.where`. Roughly ``df1.where(m, df2)`` is equivalent to
``np.where(m, df1, df2)``.

For further details and examples see the ``where`` documentation in
:ref:`indexing <indexing.where_mask>`.

See Also
--------
:func:`DataFrame.mask` : Return an object of same shape as self

Examples
--------
>>> s = pd.Series(range(5))
>>> s.where(s > 0)
0    NaN
1    1.0
2    2.0
3    3.0
4    4.0
dtype: float64

>>> s.mask(s > 0)
0    0.0
1    NaN
2    NaN
3    NaN
4    NaN
dtype: float64

>>> s.where(s > 1, 10)
0    10
1    10
2    2
3    3
4    4
dtype: int64

>>> df = pd.DataFrame(np.arange(10).reshape(-1, 2), columns=['A', 'B'])
>>> m = df % 3 == 0
>>> df.where(m, -df)
   A  B
0  0 -1
1 -2  3
2 -4 -5
3  6 -7
4 -8  9
>>> df.where(m, -df) == np.where(m, df, -df)
      A     B
0  True  True
1  True  True
2  True  True
3  True  True
4  True  True
>>> df.where(m, -df) == df.mask(~m, -df)
      A     B
0  True  True
1  True  True
2  True  True
3  True  True
4  True  True

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        Private classes (['NDFrame']) should not be mentioned in public docstring.

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.

Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

• closes #xxxx
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

[pep8speaks]

Hello @simobasso! Thanks for updating the PR.

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

Comment last updated on July 08, 2018 at 16:01 Hours UTC

[jbigatti]

Please, change PR's title to: "DOC: update the pandas.Series.where docstring"

[simobasso]

@jbigatti done but FYI

[jorisvandenbossche]

Thanks a lot for the PR!

Added some inline comments. One additional comment: in the Examples section, can you add a bit of explanation between the current examples? (explaining what the following example will do or how it is different from the previous one, to give readers some context when looking at it)

[jorisvandenbossche]

"don't respect" is too specific for where I think. Can you make this Replace values where the condition is %(cond)s .

[jorisvandenbossche]

Ideally we should try to avoid using "self", as not necessarily all our users know this concept. You can for example change it to "the calling object"

[jorisvandenbossche]

Can you add an extra indentation level to this line? (so sphinx knows it is part of the deprecated directive

and 'error' -> 'errors'

[codecov]

Codecov Report

❗ No coverage uploaded for pull request base (master@b058e37). Click here to learn what that means.
The diff coverage is 88.88%.

@@            Coverage Diff            @@
##             master   #20165   +/-   ##
=========================================
  Coverage          ?   91.72%           
=========================================
  Files             ?      150           
  Lines             ?    49152           
  Branches          ?        0           
=========================================
  Hits              ?    45086           
  Misses            ?     4066           
  Partials          ?        0

Flag	Coverage Δ
#multiple	90.11% <88.88%> (?)
#single	41.84% <0%> (?)

Impacted Files	Coverage Δ
pandas/core/generic.py	95.84% <88.88%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update b058e37...3bae8ec. Read the comment docs.

[WillAyd]

Thanks @simobasso !