Skip to main content
`Ctrl`+`K`

# pandas.api.types.union_categoricals

pandas.api.types.union_categoricals(to_union, sort_categories=False, ignore_order=False)

  Combine list-like of Categorical-like, unioning categories.

  All categories must have the same dtype.

  Parameters:
    to_union list-like

      Categorical, CategoricalIndex, or Series with dtype=’category’.

    sort_categories bool, default False

      If true, resulting categories will be lexsorted, otherwise they will be ordered as they appear in the data.

    ignore_order bool, default False

      If true, the ordered attribute of the Categoricals will be ignored. Results in an unordered categorical.

  Returns:
    Categorical
  Raises:
    TypeError

      - all inputs do not have the same dtype

      - all inputs do not have the same ordered property

      - all inputs are ordered and their categories are not identical

      - sort_categories=True and Categoricals are ordered

    ValueError

      Empty list of categoricals passed

  Notes

  To learn more about categories, see link

  Examples

  If you want to combine categoricals that do not necessarily have the same categories, union_categoricals will combine a list-like of categoricals. The new categories will be the union of the categories being combined.

      >>> a = pd.Categorical(["b", "c"])
      >>> b = pd.Categorical(["a", "b"])
      >>> pd.api.types.union_categoricals([a, b])
      ['b', 'c', 'a', 'b']
      Categories (3, object): ['b', 'c', 'a']

  By default, the resulting categories will be ordered as they appear in the categories of the data. If you want the categories to be lexsorted, use sort_categories=True argument.

      >>> pd.api.types.union_categoricals([a, b], sort_categories=True)
      ['b', 'c', 'a', 'b']
      Categories (3, object): ['a', 'b', 'c']

  union_categoricals also works with the case of combining two categoricals of the same categories and order information (e.g. what you could also append for).

      >>> a = pd.Categorical(["a", "b"], ordered=True)
      >>> b = pd.Categorical(["a", "b", "a"], ordered=True)
      >>> pd.api.types.union_categoricals([a, b])
      ['a', 'b', 'a', 'b', 'a']
      Categories (2, object): ['a' < 'b']

  Raises TypeError because the categories are ordered and not identical.

      >>> a = pd.Categorical(["a", "b"], ordered=True)
      >>> b = pd.Categorical(["a", "b", "c"], ordered=True)
      >>> pd.api.types.union_categoricals([a, b])
      Traceback (most recent call last):
          ...
      TypeError: to union ordered Categoricals, all categories must be the same

  Ordered categoricals with different categories or orderings can be combined by using the ignore_ordered=True argument.

      >>> a = pd.Categorical(["a", "b", "c"], ordered=True)
      >>> b = pd.Categorical(["c", "b", "a"], ordered=True)
      >>> pd.api.types.union_categoricals([a, b], ignore_order=True)
      ['a', 'b', 'c', 'c', 'b', 'a']
      Categories (3, object): ['a', 'b', 'c']

  union_categoricals also works with a CategoricalIndex, or Series containing categorical data, but note that the resulting array will always be a plain Categorical

      >>> a = pd.Series(["b", "c"], dtype='category')
      >>> b = pd.Series(["a", "b"], dtype='category')
      >>> pd.api.types.union_categoricals([a, b])
      ['b', 'c', 'a', 'b']
      Categories (3, object): ['b', 'c', 'a']