Skip to content

Commit 541c9a8

Browse files
author
Chang She
committed
DOC tweaks and better deprecation message for DataFrame #2304 #2337
1 parent 1c0169d commit 541c9a8

File tree

3 files changed

+26
-11
lines changed

3 files changed

+26
-11
lines changed

RELEASE.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ pandas 0.10.0
3838
`header` argument will be respected. If there is an existing header column,
3939
this can rename the columns. To fix legacy code, put ``header=None`` when
4040
passing ``names``
41+
- DataFrame selection using a boolean frame now preserves input shape
4142

4243
**Improvements to existing features**
4344

doc/source/indexing.rst

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -234,8 +234,9 @@ indexing expressions.
234234
Where and Masking
235235
~~~~~~~~~~~~~~~~~
236236

237-
Selecting values from a Series with a boolean vector in the *[]*, returns a subset of the rows.
238-
The method `where` allows selection that preserves the original data shape (and is a copy).
237+
Selecting values from a Series with a boolean vector generally returns a subset of the data.
238+
To guarantee that selection output has the same shape as the original data, you can use the
239+
``where`` method in ``Series`` and ``DataFrame``.
239240

240241
.. ipython:: python
241242
@@ -245,16 +246,16 @@ The method `where` allows selection that preserves the original data shape (and
245246
# return a Series of the same shape as the original
246247
s.where(s > 0)
247248
248-
Selecting values from a DataFrame with a boolean critierion in the *[]*, that is the same shape as
249-
the original DataFrame, returns a similary sized DataFrame (and is a copy). `where` is used under the hood as the implementation.
249+
Selecting values from a DataFrame with a boolean critierion now also preserves input data shape.
250+
``where`` is used under the hood as the implementation.
250251

251252
.. ipython:: python
252253
253254
# return a DataFrame of the same shape as the original
254-
# this is equiavalent to `df.where(df < 0)`
255+
# this is equiavalent to ``df.where(df < 0)``
255256
df[df < 0]
256257
257-
In addition, `where` takes an optional `other` argument for replacement of values where the
258+
In addition, ``where`` takes an optional ``other`` argument for replacement of values where the
258259
condition is False, in the returned copy.
259260

260261
.. ipython:: python
@@ -274,20 +275,32 @@ This can be done intuitively like so:
274275
df2[df2 < 0] = 0
275276
df2
276277
277-
Furthermore, `where` aligns the input boolean condition (ndarray or DataFrame), such that partial selection
278-
with setting is possible. This is analagous to partial setting via `.ix` (but on the contents rather than the axis labels)
278+
Furthermore, ``where`` aligns the input boolean condition (ndarray or DataFrame), such that partial selection
279+
with setting is possible. This is analagous to partial setting via ``.ix`` (but on the contents rather than the axis labels)
279280

280281
.. ipython:: python
281282
282283
df2 = df.copy()
283284
df2[ df2[1:4] > 0 ] = 3
284285
df2
285286
286-
`mask` is the inverse boolean operation of `where`.
287+
By default, ``where`` returns a modified copy of the data. There is an optional parameter ``inplace``
288+
so that the original data can be modified without creating a copy:
289+
290+
.. ipython:: python
291+
292+
df_orig = df.copy()
293+
294+
df_orig.where(df > 0, -df, inplace=True);
295+
296+
df_orig
297+
298+
``mask`` is the inverse boolean operation of ``where``.
287299

288300
.. ipython:: python
289301
290302
s.mask(s >= 0)
303+
291304
df.mask(df >= 0)
292305
293306

pandas/core/frame.py

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3453,9 +3453,10 @@ def _combine_series_infer(self, other, func, fill_value=None):
34533453
# teeny hack because one does DataFrame + TimeSeries all the time
34543454
if self.index.is_all_dates and other.index.is_all_dates:
34553455
import warnings
3456-
warnings.warn(("TimeSeries broadcasting across DataFrame index "
3456+
warnings.warn(("TimeSeries broadcasting along DataFrame index "
34573457
"by default is deprecated. Please use "
3458-
"DataFrame.sub"),
3458+
"DataFrame.<op> to explicitly broadcast arithmetic "
3459+
"operations along the index"),
34593460
FutureWarning)
34603461
return self._combine_match_index(other, func, fill_value)
34613462
else:

0 commit comments

Comments
 (0)