DOC tweaks and better deprecation message for DataFrame #2304 #2337

Author: Chang She

RELEASE.rst

@@ -38,6 +38,7 @@ pandas 0.10.0
     `header` argument will be respected. If there is an existing header column,
     this can rename the columns. To fix legacy code, put ``header=None`` when
     passing ``names``
+  - DataFrame selection using a boolean frame now preserves input shape
 
 **Improvements to existing features**
 

doc/source/indexing.rst

@@ -234,8 +234,9 @@ indexing expressions.
 Where and Masking
 ~~~~~~~~~~~~~~~~~
 
-Selecting values from a Series with a boolean vector in the *[]*, returns a subset of the rows.
-The method `where` allows selection that preserves the original data shape (and is a copy).
+Selecting values from a Series with a boolean vector generally returns a subset of the data.
+To guarantee that selection output has the same shape as the original data, you can use the
+``where`` method in ``Series`` and ``DataFrame``.
 
 .. ipython:: python
 
@@ -245,16 +246,16 @@ The method `where` allows selection that preserves the original data shape (and
    # return a Series of the same shape as the original
    s.where(s > 0)
 
-Selecting values from a DataFrame with a boolean critierion in the *[]*, that is the same shape as
-the original DataFrame, returns a similary sized DataFrame (and is a copy). `where` is used under the hood as the implementation.
+Selecting values from a DataFrame with a boolean critierion now also preserves input data shape.
+``where`` is used under the hood as the implementation.
 
 .. ipython:: python
 
    # return a DataFrame of the same shape as the original
-   # this is equiavalent to `df.where(df < 0)` 
+   # this is equiavalent to ``df.where(df < 0)``
    df[df < 0]
 
-In addition, `where` takes an optional `other` argument for replacement of values where the 
+In addition, ``where`` takes an optional ``other`` argument for replacement of values where the
 condition is False, in the returned copy.
 
 .. ipython:: python
@@ -274,20 +275,32 @@ This can be done intuitively like so:
    df2[df2 < 0] = 0
    df2
 
-Furthermore, `where` aligns the input boolean condition (ndarray or DataFrame), such that partial selection
-with setting is possible. This is analagous to partial setting via `.ix` (but on the contents rather than the axis labels)
+Furthermore, ``where`` aligns the input boolean condition (ndarray or DataFrame), such that partial selection
+with setting is possible. This is analagous to partial setting via ``.ix`` (but on the contents rather than the axis labels)
 
 .. ipython:: python
 
    df2 = df.copy()
    df2[ df2[1:4] > 0 ] = 3
    df2
 
-`mask` is the inverse boolean operation of `where`.
+By default, ``where`` returns a modified copy of the data. There is an optional parameter ``inplace``
+so that the original data can be modified without creating a copy:
+
+.. ipython:: python
+
+   df_orig = df.copy()
+
+   df_orig.where(df > 0, -df, inplace=True);
+
+   df_orig
+
+``mask`` is the inverse boolean operation of ``where``.
 
 .. ipython:: python
 
    s.mask(s >= 0)
+
    df.mask(df >= 0)
 
 

pandas/core/frame.py

@@ -3453,9 +3453,10 @@ def _combine_series_infer(self, other, func, fill_value=None):
         # teeny hack because one does DataFrame + TimeSeries all the time
         if self.index.is_all_dates and other.index.is_all_dates:
             import warnings
-            warnings.warn(("TimeSeries broadcasting across DataFrame index "
+            warnings.warn(("TimeSeries broadcasting along DataFrame index "
                            "by default is deprecated. Please use "
-                           "DataFrame.sub"),
+                           "DataFrame.<op> to explicitly broadcast arithmetic "
+                           "operations along the index"),
                            FutureWarning)
             return self._combine_match_index(other, func, fill_value)
         else: