From 9b909e8589b3da150f764e8333c86afa37ec2717 Mon Sep 17 00:00:00 2001 From: Simone Basso Date: Sat, 10 Mar 2018 15:50:37 +0100 Subject: [PATCH 1/2] DOC: Improved the docstring of pandas.Series.where --- pandas/core/generic.py | 50 ++++++++++++++++++++++++------------------ 1 file changed, 29 insertions(+), 21 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index a893b2ba1a189..5246c4b3f1638 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -6596,9 +6596,10 @@ def _where(self, cond, other=np.nan, inplace=False, axis=None, level=None, return self._constructor(new_data).__finalize__(self) _shared_docs['where'] = (""" - Return an object of same shape as self and whose corresponding - entries are from self where `cond` is %(cond)s and otherwise are from - `other`. + 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 %(cond)s are replaced by `other`. Parameters ---------- @@ -6623,23 +6624,26 @@ def _where(self, cond, other=np.nan, inplace=False, axis=None, level=None, A callable can be used as other. inplace : boolean, default False - Whether to perform the operation in place on the data - axis : alignment axis if needed, default None - level : alignment level if needed, default None - errors : str, {'raise', 'ignore'}, default 'raise' - - ``raise`` : allow exceptions to be raised - - ``ignore`` : suppress exceptions. On error return original object - + 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), + 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) + strings). .. deprecated:: 0.21.0 + Use `error`. Returns ------- @@ -6659,6 +6663,11 @@ def _where(self, cond, other=np.nan, inplace=False, axis=None, level=None, For further details and examples see the ``%(name)s`` documentation in :ref:`indexing `. + See Also + -------- + :func:`DataFrame.%(name_other)s` : Return an object of same shape as + self + Examples -------- >>> s = pd.Series(range(5)) @@ -6668,6 +6677,7 @@ def _where(self, cond, other=np.nan, inplace=False, axis=None, level=None, 2 2.0 3 3.0 4 4.0 + dtype: float64 >>> s.mask(s > 0) 0 0.0 @@ -6675,13 +6685,15 @@ def _where(self, cond, other=np.nan, inplace=False, axis=None, level=None, 2 NaN 3 NaN 4 NaN + dtype: float64 >>> s.where(s > 1, 10) - 0 10.0 - 1 10.0 - 2 2.0 - 3 3.0 - 4 4.0 + 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 @@ -6706,10 +6718,6 @@ def _where(self, cond, other=np.nan, inplace=False, axis=None, level=None, 2 True True 3 True True 4 True True - - See Also - -------- - :func:`DataFrame.%(name_other)s` """) @Appender(_shared_docs['where'] % dict(_shared_doc_kwargs, cond="True", From 3bae8ec243c440c42ea3c3f03cce5d60ca678c56 Mon Sep 17 00:00:00 2001 From: Will Ayd Date: Sun, 8 Jul 2018 11:00:07 -0500 Subject: [PATCH 2/2] DOC fixup --- pandas/core/generic.py | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 8fb6d8478d570..8da678e0adec0 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7778,10 +7778,7 @@ def _where(self, cond, other=np.nan, inplace=False, axis=None, level=None, return self._constructor(new_data).__finalize__(self) _shared_docs['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 %(cond)s are replaced by `other`. + Replace values where the condition is %(cond_rev)s. Parameters ---------- @@ -7825,7 +7822,8 @@ def _where(self, cond, other=np.nan, inplace=False, axis=None, level=None, strings). .. deprecated:: 0.21.0 - Use `error`. + + Use `errors`. Returns -------