Merge pull request #8227 from jreback/index_api

API: raise on setops for + and - for Indexes (GH8226)

Author: jreback

doc/source/indexing.rst

@@ -1616,28 +1616,33 @@ display:
    df
    df['A']
 
+.. _indexing.setops:
 
 Set operations on Index objects
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. warning::
+
+   In 0.15.0. the set operations ``+`` and ``-`` were deprecated in order to provide these for numeric type operations on certain
+   index types. ``+`` can be replace by ``.union()`` or ``|``, and ``-`` by ``.difference()``.
+
 .. _indexing.set_ops:
 
-The three main operations are ``union (|)``, ``intersection (&)``, and ``diff
-(-)``. These can be directly called as instance methods or used via overloaded
-operators:
+The two main operations are ``union (|)``, ``intersection (&)``
+These can be directly called as instance methods or used via overloaded
+operators. Difference is provided via the ``.difference()`` method.
 
 .. ipython:: python
 
    a = Index(['c', 'b', 'a'])
    b = Index(['c', 'e', 'd'])
-   a.union(b)
    a | b
    a & b
-   a - b
+   a.difference(b)
 
 Also available is the ``sym_diff (^)`` operation, which returns elements
 that appear in either ``idx1`` or ``idx2`` but not both. This is
-equivalent to the Index created by ``(idx1 - idx2) + (idx2 - idx1)``,
+equivalent to the Index created by ``(idx1.difference(idx2)).union(idx2.difference(idx1))``,
 with duplicates dropped.
 
 .. ipython:: python

doc/source/v0.15.0.txt

@@ -19,6 +19,7 @@ users upgrade to this version.
   - Internal refactoring of the ``Index`` class to no longer sub-class ``ndarray``, see :ref:`Internal Refactoring <whatsnew_0150.refactoring>`
   - New datetimelike properties accessor ``.dt`` for Series, see :ref:`Datetimelike Properties <whatsnew_0150.dt>`
   - dropping support for ``PyTables`` less than version 3.0.0, and ``numexpr`` less than version 2.1 (:issue:`7990`)
+  - API change in using Indexs set operations, see :ref:`here <whatsnew_0150.index_set_ops>`
 
 - :ref:`Other Enhancements <whatsnew_0150.enhancements>`
 
@@ -343,6 +344,11 @@ API changes
 - ``Series.to_csv()`` now returns a string when ``path=None``, matching the behaviour of
     ``DataFrame.to_csv()`` (:issue:`8215`).
 
+
+.. _whatsnew_0150.index_set_ops:
+
+- The Index set operations ``+`` and ``-`` were deprecated in order to provide these for numeric type operations on certain index types. ``+`` can be replace by ``.union()`` or ``|``, and ``-`` by ``.difference()``. Further the method name ``Index.diff()`` is deprecated and can be replaced by ``Index.difference()``
+
 .. _whatsnew_0150.dt:
 
 .dt accessor

pandas/core/base.py

@@ -711,8 +711,10 @@ def __add__(self, other):
         from pandas.core.index import Index
         from pandas.tseries.offsets import DateOffset
         if isinstance(other, Index):
+            warnings.warn("using '+' to provide set union with Indexes is deprecated, "
+                          "use .union()",FutureWarning)
             return self.union(other)
-        elif isinstance(other, (DateOffset, datetime.timedelta, np.timedelta64)):
+        if isinstance(other, (DateOffset, datetime.timedelta, np.timedelta64)):
             return self._add_delta(other)
         elif com.is_integer(other):
             return self.shift(other)
@@ -723,8 +725,10 @@ def __sub__(self, other):
         from pandas.core.index import Index
         from pandas.tseries.offsets import DateOffset
         if isinstance(other, Index):
-            return self.diff(other)
-        elif isinstance(other, (DateOffset, datetime.timedelta, np.timedelta64)):
+            warnings.warn("using '-' to provide set differences with Indexes is deprecated, "
+                          "use .difference()",FutureWarning)
+            return self.difference(other)
+        if isinstance(other, (DateOffset, datetime.timedelta, np.timedelta64)):
             return self._add_delta(-other)
         elif com.is_integer(other):
             return self.shift(-other)

pandas/core/categorical.py

@@ -435,7 +435,7 @@ def reorder_levels(self, new_levels, ordered=None):
         """
         new_levels = self._validate_levels(new_levels)
 
-        if len(new_levels) < len(self._levels) or len(self._levels-new_levels):
+        if len(new_levels) < len(self._levels) or len(self._levels.difference(new_levels)):
             raise ValueError('Reordered levels must include all original levels')
         values = self.__array__()
         self._codes = _get_codes_for_values(values, new_levels)
@@ -887,7 +887,7 @@ def __setitem__(self, key, value):
                 raise ValueError("cannot set a Categorical with another, without identical levels")
 
         rvalue = value if com.is_list_like(value) else [value]
-        to_add = Index(rvalue)-self.levels
+        to_add = Index(rvalue).difference(self.levels)
         # no assignments of values not in levels, but it's always ok to set something to np.nan
         if len(to_add) and not isnull(to_add).all():
             raise ValueError("cannot setitem on a Categorical with a new level,"

pandas/core/frame.py

@@ -3682,7 +3682,7 @@ def append(self, other, ignore_index=False, verify_integrity=False):
                                 'ignore_index=True')
 
             index = None if other.name is None else [other.name]
-            combined_columns = self.columns.tolist() + ((self.columns | other.index) - self.columns).tolist()
+            combined_columns = self.columns.tolist() + (self.columns | other.index).difference(self.columns).tolist()
             other = other.reindex(combined_columns, copy=False)
             other = DataFrame(other.values.reshape((1, len(other))),
                               index=index, columns=combined_columns).convert_objects()

pandas/core/groupby.py

@@ -473,7 +473,7 @@ def _set_selection_from_grouper(self):
             ax = self.obj._info_axis
             groupers = [ g.name for g in grp.groupings if g.level is None and g.name is not None and g.name in ax ]
             if len(groupers):
-                self._group_selection = (ax-Index(groupers)).tolist()
+                self._group_selection = ax.difference(Index(groupers)).tolist()
 
     def _set_result_index_ordered(self, result):
         # set the result index on the passed values object

pandas/core/index.py

@@ -1128,9 +1128,10 @@ def argsort(self, *args, **kwargs):
 
     def __add__(self, other):
         if isinstance(other, Index):
+            warnings.warn("using '+' to provide set union with Indexes is deprecated, "
+                          "use '|' or .union()",FutureWarning)
             return self.union(other)
-        else:
-            return Index(np.array(self) + other)
+        return Index(np.array(self) + other)
 
     __iadd__ = __add__
     __eq__ = _indexOp('__eq__')
@@ -1141,7 +1142,10 @@ def __add__(self, other):
     __ge__ = _indexOp('__ge__')
 
     def __sub__(self, other):
-        return self.diff(other)
+        if isinstance(other, Index):
+            warnings.warn("using '-' to provide set differences with Indexes is deprecated, "
+                          "use .difference()",FutureWarning)
+        return self.difference(other)
 
     def __and__(self, other):
         return self.intersection(other)
@@ -1273,7 +1277,7 @@ def intersection(self, other):
             taken.name = None
         return taken
 
-    def diff(self, other):
+    def difference(self, other):
         """
         Compute sorted set difference of two Index objects
 
@@ -1289,8 +1293,7 @@ def diff(self, other):
         -----
         One can do either of these and achieve the same result
 
-        >>> index - index2
-        >>> index.diff(index2)
+        >>> index.difference(index2)
         """
 
         if not hasattr(other, '__iter__'):
@@ -1308,6 +1311,8 @@ def diff(self, other):
         theDiff = sorted(set(self) - set(other))
         return Index(theDiff, name=result_name)
 
+    diff = deprecate('diff',difference)
+
     def sym_diff(self, other, result_name=None):
         """
         Compute the sorted symmetric difference of two Index objects.
@@ -1350,7 +1355,7 @@ def sym_diff(self, other, result_name=None):
             other = Index(other)
             result_name = result_name or self.name
 
-        the_diff = sorted(set((self - other) + (other - self)))
+        the_diff = sorted(set((self.difference(other)).union(other.difference(self))))
         return Index(the_diff, name=result_name)
 
     def get_loc(self, key):
@@ -4135,6 +4140,8 @@ def union(self, other):
         Returns
         -------
         Index
+
+        >>> index.union(index2)
         """
         self._assert_can_do_setop(other)
 
@@ -4177,7 +4184,7 @@ def intersection(self, other):
             return MultiIndex.from_arrays(lzip(*uniq_tuples), sortorder=0,
                                           names=result_names)
 
-    def diff(self, other):
+    def difference(self, other):
         """
         Compute sorted set difference of two MultiIndex objects
 

pandas/core/panel.py

@@ -678,9 +678,9 @@ def _combine_frame(self, other, func, axis=0):
                                  self.minor_axis)
 
     def _combine_panel(self, other, func):
-        items = self.items + other.items
-        major = self.major_axis + other.major_axis
-        minor = self.minor_axis + other.minor_axis
+        items = self.items.union(other.items)
+        major = self.major_axis.union(other.major_axis)
+        minor = self.minor_axis.union(other.minor_axis)
 
         # could check that everything's the same size, but forget it
         this = self.reindex(items=items, major=major, minor=minor)

pandas/core/panelnd.py

@@ -82,7 +82,7 @@ def _combine_with_constructor(self, other, func):
         # combine labels to form new axes
         new_axes = []
         for a in self._AXIS_ORDERS:
-            new_axes.append(getattr(self, a) + getattr(other, a))
+            new_axes.append(getattr(self, a).union(getattr(other, a)))
 
         # reindex: could check that everything's the same size, but forget it
         d = dict([(a, ax) for a, ax in zip(self._AXIS_ORDERS, new_axes)])

pandas/core/reshape.py

@@ -848,7 +848,7 @@ def lreshape(data, groups, dropna=True, label=None):
         keys, values = zip(*groups)
 
     all_cols = list(set.union(*[set(x) for x in values]))
-    id_cols = list(data.columns.diff(all_cols))
+    id_cols = list(data.columns.difference(all_cols))
 
     K = len(values[0])