Skip to content

Commit

Permalink
API: deprecate Index.sym_diff in favor of symmetric_difference
Browse files Browse the repository at this point in the history
closes #12591
closes #12594
  • Loading branch information
xflr6 authored and jreback committed Mar 17, 2016
1 parent e4df1ac commit 1893ffd
Show file tree
Hide file tree
Showing 6 changed files with 28 additions and 20 deletions.
2 changes: 1 addition & 1 deletion doc/source/api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1374,7 +1374,7 @@ Combining / joining / set operations
Index.intersection
Index.union
Index.difference
Index.sym_diff
Index.symmetric_difference

Selecting
~~~~~~~~~
Expand Down
4 changes: 2 additions & 2 deletions doc/source/indexing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1359,7 +1359,7 @@ operators. Difference is provided via the ``.difference()`` method.
a & b
a.difference(b)
Also available is the ``sym_diff (^)`` operation, which returns elements
Also available is the ``symmetric_difference (^)`` operation, which returns elements
that appear in either ``idx1`` or ``idx2`` but not both. This is
equivalent to the Index created by ``idx1.difference(idx2).union(idx2.difference(idx1))``,
with duplicates dropped.
Expand All @@ -1368,7 +1368,7 @@ with duplicates dropped.
idx1 = pd.Index([1, 2, 3, 4])
idx2 = pd.Index([2, 3, 4, 5])
idx1.sym_diff(idx2)
idx1.symmetric_difference(idx2)
idx1 ^ idx2
Missing values
Expand Down
2 changes: 2 additions & 0 deletions doc/source/whatsnew/v0.18.1.txt
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,8 @@ API changes
Deprecations
^^^^^^^^^^^^

- The method name ``Index.sym_diff()`` is deprecated and can be replaced by ``Index.symmetric_difference()`` (:issue:`12591`)




Expand Down
12 changes: 7 additions & 5 deletions pandas/indexes/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -1619,7 +1619,7 @@ def __or__(self, other):
return self.union(other)

def __xor__(self, other):
return self.sym_diff(other)
return self.symmetric_difference(other)

def union(self, other):
"""
Expand Down Expand Up @@ -1796,7 +1796,7 @@ def difference(self, other):

diff = deprecate('diff', difference)

def sym_diff(self, other, result_name=None):
def symmetric_difference(self, other, result_name=None):
"""
Compute the sorted symmetric difference of two Index objects.
Expand All @@ -1807,11 +1807,11 @@ def sym_diff(self, other, result_name=None):
Returns
-------
sym_diff : Index
symmetric_difference : Index
Notes
-----
``sym_diff`` contains elements that appear in either ``idx1`` or
``symmetric_difference`` contains elements that appear in either ``idx1`` or
``idx2`` but not both. Equivalent to the Index created by
``(idx1 - idx2) + (idx2 - idx1)`` with duplicates dropped.
Expand All @@ -1822,7 +1822,7 @@ def sym_diff(self, other, result_name=None):
--------
>>> idx1 = Index([1, 2, 3, 4])
>>> idx2 = Index([2, 3, 4, 5])
>>> idx1.sym_diff(idx2)
>>> idx1.symmetric_difference(idx2)
Int64Index([1, 5], dtype='int64')
You can also use the ``^`` operator:
Expand All @@ -1843,6 +1843,8 @@ def sym_diff(self, other, result_name=None):
attribs['freq'] = None
return self._shallow_copy_with_infer(the_diff, **attribs)

sym_diff = deprecate('sym_diff', symmetric_difference)

def get_loc(self, key, method=None, tolerance=None):
"""
Get integer location for requested label
Expand Down
16 changes: 10 additions & 6 deletions pandas/tests/indexes/common.py
Original file line number Diff line number Diff line change
Expand Up @@ -305,7 +305,7 @@ def test_setops_errorcases(self):
# # non-iterable input
cases = [0.5, 'xxx']
methods = [idx.intersection, idx.union, idx.difference,
idx.sym_diff]
idx.symmetric_difference]

for method in methods:
for case in cases:
Expand Down Expand Up @@ -404,15 +404,15 @@ def test_difference_base(self):
with tm.assertRaisesRegexp(TypeError, msg):
result = first.difference([1, 2, 3])

def test_symmetric_diff(self):
def test_symmetric_difference(self):
for name, idx in compat.iteritems(self.indices):
first = idx[1:]
second = idx[:-1]
if isinstance(idx, CategoricalIndex):
pass
else:
answer = idx[[0, -1]]
result = first.sym_diff(second)
result = first.symmetric_difference(second)
self.assertTrue(tm.equalContents(result, answer))

# GH 10149
Expand All @@ -422,17 +422,21 @@ def test_symmetric_diff(self):
if isinstance(idx, PeriodIndex):
msg = "can only call with other PeriodIndex-ed objects"
with tm.assertRaisesRegexp(ValueError, msg):
result = first.sym_diff(case)
result = first.symmetric_difference(case)
elif isinstance(idx, CategoricalIndex):
pass
else:
result = first.sym_diff(case)
result = first.symmetric_difference(case)
self.assertTrue(tm.equalContents(result, answer))

if isinstance(idx, MultiIndex):
msg = "other must be a MultiIndex or a list of tuples"
with tm.assertRaisesRegexp(TypeError, msg):
result = first.sym_diff([1, 2, 3])
result = first.symmetric_difference([1, 2, 3])

# 12591 deprecated
with tm.assert_produces_warning(FutureWarning):
first.sym_diff(second)

def test_insert_base(self):

Expand Down
12 changes: 6 additions & 6 deletions pandas/tests/indexes/test_base.py
Original file line number Diff line number Diff line change
Expand Up @@ -641,11 +641,11 @@ def test_difference(self):
self.assertEqual(len(result), 0)
self.assertEqual(result.name, first.name)

def test_symmetric_diff(self):
def test_symmetric_difference(self):
# smoke
idx1 = Index([1, 2, 3, 4], name='idx1')
idx2 = Index([2, 3, 4, 5])
result = idx1.sym_diff(idx2)
result = idx1.symmetric_difference(idx2)
expected = Index([1, 5])
self.assertTrue(tm.equalContents(result, expected))
self.assertIsNone(result.name)
Expand All @@ -658,7 +658,7 @@ def test_symmetric_diff(self):
# multiIndex
idx1 = MultiIndex.from_tuples(self.tuples)
idx2 = MultiIndex.from_tuples([('foo', 1), ('bar', 3)])
result = idx1.sym_diff(idx2)
result = idx1.symmetric_difference(idx2)
expected = MultiIndex.from_tuples([('bar', 2), ('baz', 3), ('bar', 3)])
self.assertTrue(tm.equalContents(result, expected))

Expand All @@ -667,7 +667,7 @@ def test_symmetric_diff(self):
# and the correct non-nan values are there. punt on sorting.
idx1 = Index([1, 2, 3, np.nan])
idx2 = Index([0, 1, np.nan])
result = idx1.sym_diff(idx2)
result = idx1.symmetric_difference(idx2)
# expected = Index([0.0, np.nan, 2.0, 3.0, np.nan])

nans = pd.isnull(result)
Expand All @@ -679,11 +679,11 @@ def test_symmetric_diff(self):
idx1 = Index([1, 2, 3, 4], name='idx1')
idx2 = np.array([2, 3, 4, 5])
expected = Index([1, 5])
result = idx1.sym_diff(idx2)
result = idx1.symmetric_difference(idx2)
self.assertTrue(tm.equalContents(result, expected))
self.assertEqual(result.name, 'idx1')

result = idx1.sym_diff(idx2, result_name='new_name')
result = idx1.symmetric_difference(idx2, result_name='new_name')
self.assertTrue(tm.equalContents(result, expected))
self.assertEqual(result.name, 'new_name')

Expand Down

0 comments on commit 1893ffd

Please sign in to comment.