ENH union_categoricals supports ignore_order GH13410

Author: Justin Solinsky

doc/source/categorical.rst

@@ -693,6 +693,17 @@ The below raises ``TypeError`` because the categories are ordered and not identi
    Out[3]:
    TypeError: to union ordered Categoricals, all categories must be the same
 
+.. versionadded:: 0.20.0
+
+Ordered categoricals with different categories or orderings can be combined by
+using the ``ignore_ordered=True`` argument.
+
+.. ipython:: python
+
+    a = pd.Categorical(["a", "b", "c"], ordered=True)
+    b = pd.Categorical(["c", "b", "a"], ordered=True)
+    union_categoricals([a, b], ignore_order=True)
+
 ``union_categoricals`` also works with a ``CategoricalIndex``, or ``Series`` containing
 categorical data, but note that the resulting array will always be a plain ``Categorical``
 

doc/source/whatsnew/v0.20.0.txt

@@ -137,7 +137,7 @@ Other enhancements
 
 - ``.select_dtypes()`` now allows the string 'datetimetz' to generically select datetimes with tz (:issue:`14910`)
 - ``pd.merge_asof()`` gained the option ``direction='backward'|'forward'|'nearest'`` (:issue:`14887`)
-
+- ``ignore_ordered`` argument added to ``pd.types.concat.union_categoricals``; setting the argument to true will ignore the ordered attribute of unioned categoricals (:issue:`13410`)
 
 .. _whatsnew_0200.api_breaking:
 

pandas/tools/tests/test_concat.py

@@ -1675,14 +1675,14 @@ def test_union_categoricals_ignore_order(self):
         tm.assert_categorical_equal(res, exp)
 
         res = union_categoricals([c1, c1], ignore_order=True)
-        exp = Categorical([1, 2, 3, 1, 2, 3], ordered=False)
+        exp = Categorical([1, 2, 3, 1, 2, 3])
         tm.assert_categorical_equal(res, exp)
 
         c1 = Categorical([1, 2, 3, np.nan], ordered=True)
         c2 = Categorical([3, 2], categories=[1, 2, 3], ordered=True)
 
         res = union_categoricals([c1, c2], ignore_order=True)
-        exp = Categorical([1, 2, 3, np.nan, 3, 2], ordered=False)
+        exp = Categorical([1, 2, 3, np.nan, 3, 2])
         tm.assert_categorical_equal(res, exp)
 
         c1 = Categorical([1, 2, 3], ordered=True)
@@ -1692,13 +1692,16 @@ def test_union_categoricals_ignore_order(self):
         exp = Categorical([1, 2, 3, 1, 2, 3])
         tm.assert_categorical_equal(res, exp)
 
-        c1 = Categorical([1, 2, 3], categories=[3, 2, 1], ordered=True)
-        c2 = Categorical([1, 2, 3], ordered=True)
-
-        res = union_categoricals([c1, c2], ignore_order=True, sort_categories=True)
+        res = union_categoricals([c2, c1], ignore_order=True, sort_categories=True)
         exp = Categorical([1, 2, 3, 1, 2, 3], categories=[1, 2, 3])
         tm.assert_categorical_equal(res, exp)
 
+        c1 = Categorical([1, 2, 3], ordered=True)
+        c2 = Categorical([4, 5, 6], ordered=True)
+        result = union_categoricals([c1, c2], ignore_order=True)
+        expected = Categorical([1, 2, 3, 4, 5, 6])
+        tm.assert_categorical_equal(result, expected)
+
     def test_union_categoricals_sort(self):
         # GH 13846
         c1 = Categorical(['x', 'y', 'z'])

pandas/types/concat.py

@@ -223,8 +223,8 @@ def union_categoricals(to_union, sort_categories=False, ignore_order=False):
         If true, resulting categories will be lexsorted, otherwise
         they will be ordered as they appear in the data.
     ignore_order: boolean, default False
-        If true, ordered categories will be ignored.  Results in
-        an unordered categorical.
+        If true, the ordered attribute of the Categoricals will be ignored.
+        Results in an unordered categorical.
 
     Returns
     -------
@@ -238,7 +238,7 @@ def union_categoricals(to_union, sort_categories=False, ignore_order=False):
         - all inputs are ordered and their categories are not identical
         - sort_categories=True and Categoricals are ordered
     ValueError
-        Emmpty list of categoricals passed
+        Empty list of categoricals passed
     """
     from pandas import Index, Categorical, CategoricalIndex, Series
 
@@ -275,7 +275,7 @@ def _maybe_unwrap(x):
             categories = categories.sort_values()
             indexer = categories.get_indexer(first.categories)
             new_codes = take_1d(indexer, new_codes, fill_value=-1)
-    elif ignore_order | all(not c.ordered for c in to_union):
+    elif ignore_order or all(not c.ordered for c in to_union):
         # different categories - union and recode
         cats = first.categories.append([c.categories for c in to_union[1:]])
         categories = Index(cats.unique())