nodes: 0, module; 1, function_definition; 2, function_name:union_categoricals; 3, parameters; 4, block; 5, identifier:to_union; 6, default_parameter; 7, default_parameter; 8, expression_statement; 9, import_from_statement; 10, import_from_statement; 11, if_statement; 12, function_definition; 13, expression_statement; 14, expression_statement; 15, if_statement; 16, expression_statement; 17, if_statement; 18, if_statement; 19, return_statement; 20, identifier:sort_categories; 21, False; 22, identifier:ignore_order; 23, False; 24, comment:"""
      Combine list-like of Categorical-like, unioning categories. All
      categories must have the same dtype.
  
      .. versionadded:: 0.19.0
  
      Parameters
      ----------
      to_union : list-like of Categorical, CategoricalIndex,
                 or Series with dtype='category'
      sort_categories : boolean, default 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, the ordered attribute of the Categoricals will be ignored.
          Results in an unordered categorical.
  
          .. versionadded:: 0.20.0
  
      Returns
      -------
      result : 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
      <http://pandas.pydata.org/pandas-docs/stable/categorical.html#unioning>`__
  
      Examples
      --------
  
      >>> from pandas.api.types import union_categoricals
  
      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"])
      >>> 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.
  
      >>> 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)
      >>> 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)
      >>> union_categoricals([a, b])
      TypeError: to union ordered Categoricals, all categories must be the same
  
      New in version 0.20.0
  
      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)
      >>> 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')
      >>> union_categoricals([a, b])
      [b, c, a, b]
      Categories (3, object): [b, c, a]
      """; 25, dotted_name; 26, dotted_name; 27, dotted_name; 28, dotted_name; 29, dotted_name; 30, dotted_name; 31, dotted_name; 32, comparison_operator:len(to_union) == 0; 33, block; 34, function_name:_maybe_unwrap; 35, parameters; 36, block; 37, assignment; 38, assignment; 39, not_operator; 40, block; 41, assignment; 42, call; 43, comment:# identical categories - fastpath; 44, block; 45, elif_clause; 46, else_clause; 47, identifier:ignore_order; 48, block; 49, call; 50, identifier:pandas; 51, identifier:Index; 52, identifier:Categorical; 53, identifier:CategoricalIndex; 54, identifier:Series; 55, identifier:pandas; 56, identifier:core; 57, identifier:arrays; 58, identifier:categorical; 59, identifier:_recode_for_categories; 60, call; 61, integer:0; 62, raise_statement; 63, identifier:x; 64, if_statement; 65, identifier:to_union; 66, list_comprehension; 67, identifier:first; 68, subscript; 69, call; 70, raise_statement; 71, identifier:ordered; 72, False; 73, identifier:all; 74, generator_expression; 75, expression_statement; 76, expression_statement; 77, if_statement; 78, if_statement; 79, if_statement; 80, boolean_operator; 81, comment:# different categories - union and recode; 82, block; 83, comment:# ordered - to show a proper error message; 84, block; 85, expression_statement; 86, identifier:Categorical; 87, argument_list; 88, identifier:len; 89, argument_list; 90, call; 91, call; 92, block; 93, elif_clause; 94, else_clause; 95, call; 96, for_in_clause; 97, identifier:to_union; 98, integer:0; 99, identifier:all; 100, generator_expression; 101, call; 102, call; 103, for_in_clause; 104, assignment; 105, assignment; 106, call; 107, block; 108, else_clause; 109, boolean_operator; 110, block; 111, boolean_operator; 112, block; 113, identifier:ignore_order; 114, call; 115, expression_statement; 116, expression_statement; 117, if_statement; 118, expression_statement; 119, expression_statement; 120, if_statement; 121, assignment; 122, identifier:new_codes; 123, keyword_argument; 124, keyword_argument; 125, keyword_argument; 126, identifier:to_union; 127, identifier:ValueError; 128, argument_list; 129, identifier:isinstance; 130, argument_list; 131, return_statement; 132, call; 133, block; 134, block; 135, identifier:_maybe_unwrap; 136, argument_list; 137, identifier:x; 138, identifier:to_union; 139, call; 140, for_in_clause; 141, identifier:TypeError; 142, argument_list; 143, attribute; 144, argument_list; 145, identifier:other; 146, subscript; 147, identifier:categories; 148, attribute; 149, identifier:ordered; 150, attribute; 151, identifier:all; 152, generator_expression; 153, expression_statement; 154, block; 155, boolean_operator; 156, identifier:ordered; 157, raise_statement; 158, identifier:sort_categories; 159, not_operator; 160, expression_statement; 161, expression_statement; 162, import_from_statement; 163, expression_statement; 164, identifier:all; 165, generator_expression; 166, assignment; 167, assignment; 168, identifier:sort_categories; 169, block; 170, assignment; 171, assignment; 172, call; 173, block; 174, else_clause; 175, identifier:ordered; 176, False; 177, identifier:categories; 178, identifier:categories; 179, identifier:ordered; 180, identifier:ordered; 181, identifier:fastpath; 182, True; 183, string; 184, identifier:x; 185, tuple; 186, attribute; 187, identifier:isinstance; 188, argument_list; 189, return_statement; 190, raise_statement; 191, identifier:x; 192, identifier:is_dtype_equal; 193, argument_list; 194, identifier:other; 195, subscript; 196, string:"dtype of categories must be the same"; 197, identifier:first; 198, identifier:is_dtype_equal; 199, identifier:other; 200, identifier:to_union; 201, slice; 202, identifier:first; 203, identifier:categories; 204, identifier:first; 205, identifier:ordered; 206, call; 207, for_in_clause; 208, assignment; 209, expression_statement; 210, expression_statement; 211, identifier:sort_categories; 212, not_operator; 213, call; 214, attribute; 215, assignment; 216, assignment; 217, dotted_name; 218, dotted_name; 219, assignment; 220, not_operator; 221, for_in_clause; 222, identifier:cats; 223, call; 224, identifier:categories; 225, call; 226, expression_statement; 227, identifier:new_codes; 228, list_comprehension; 229, identifier:new_codes; 230, call; 231, identifier:all; 232, generator_expression; 233, expression_statement; 234, raise_statement; 235, block; 236, string_content:No Categoricals to union; 237, identifier:CategoricalIndex; 238, identifier:Series; 239, identifier:x; 240, identifier:values; 241, identifier:x; 242, identifier:Categorical; 243, identifier:x; 244, call; 245, attribute; 246, attribute; 247, identifier:to_union; 248, slice; 249, integer:1; 250, attribute; 251, argument_list; 252, identifier:other; 253, subscript; 254, identifier:new_codes; 255, call; 256, assignment; 257, assignment; 258, identifier:ignore_order; 259, identifier:TypeError; 260, argument_list; 261, identifier:categories; 262, identifier:is_monotonic_increasing; 263, identifier:categories; 264, call; 265, identifier:indexer; 266, call; 267, identifier:pandas; 268, identifier:core; 269, identifier:algorithms; 270, identifier:take_1d; 271, identifier:new_codes; 272, call; 273, attribute; 274, identifier:c; 275, identifier:to_union; 276, attribute; 277, argument_list; 278, identifier:Index; 279, argument_list; 280, assignment; 281, call; 282, for_in_clause; 283, attribute; 284, argument_list; 285, attribute; 286, for_in_clause; 287, assignment; 288, call; 289, raise_statement; 290, identifier:TypeError; 291, argument_list; 292, attribute; 293, identifier:dtype; 294, attribute; 295, identifier:dtype; 296, integer:1; 297, attribute; 298, identifier:equals; 299, attribute; 300, identifier:to_union; 301, slice; 302, attribute; 303, argument_list; 304, identifier:codes; 305, binary_operator:[first.codes] + [_recode_for_categories(other.codes,
                                                              other.categories,
                                                              first.categories)
                                       for other in to_union[1:]]; 306, identifier:new_codes; 307, call; 308, concatenated_string; 309, attribute; 310, argument_list; 311, attribute; 312, argument_list; 313, identifier:take_1d; 314, argument_list; 315, identifier:c; 316, identifier:ordered; 317, attribute; 318, identifier:append; 319, list_comprehension; 320, call; 321, identifier:categories; 322, call; 323, identifier:_recode_for_categories; 324, argument_list; 325, identifier:c; 326, identifier:to_union; 327, identifier:np; 328, identifier:concatenate; 329, identifier:new_codes; 330, identifier:c; 331, identifier:ordered; 332, identifier:c; 333, identifier:to_union; 334, identifier:msg; 335, parenthesized_expression; 336, identifier:TypeError; 337, argument_list; 338, call; 339, string:"all components to combine must be Categorical"; 340, identifier:other; 341, identifier:categories; 342, identifier:first; 343, identifier:categories; 344, identifier:first; 345, identifier:categories; 346, identifier:other; 347, identifier:categories; 348, integer:1; 349, identifier:np; 350, identifier:concatenate; 351, list_comprehension; 352, list; 353, list_comprehension; 354, attribute; 355, argument_list; 356, string:"Cannot use sort_categories=True with "; 357, string:"ordered Categoricals"; 358, identifier:categories; 359, identifier:sort_values; 360, identifier:categories; 361, identifier:get_indexer; 362, attribute; 363, identifier:indexer; 364, identifier:new_codes; 365, keyword_argument; 366, identifier:first; 367, identifier:categories; 368, attribute; 369, for_in_clause; 370, attribute; 371, argument_list; 372, attribute; 373, argument_list; 374, attribute; 375, attribute; 376, identifier:categories; 377, concatenated_string; 378, identifier:msg; 379, identifier:TypeError; 380, argument_list; 381, attribute; 382, for_in_clause; 383, attribute; 384, call; 385, for_in_clause; 386, identifier:np; 387, identifier:concatenate; 388, identifier:codes; 389, identifier:first; 390, identifier:categories; 391, identifier:fill_value; 392, unary_operator; 393, identifier:c; 394, identifier:categories; 395, identifier:c; 396, subscript; 397, identifier:cats; 398, identifier:unique; 399, identifier:categories; 400, identifier:sort_values; 401, identifier:c; 402, identifier:codes; 403, identifier:c; 404, identifier:categories; 405, string:"to union ordered Categoricals, "; 406, string:"all categories must be the same"; 407, string; 408, identifier:c; 409, identifier:codes; 410, identifier:c; 411, identifier:to_union; 412, identifier:first; 413, identifier:codes; 414, identifier:_recode_for_categories; 415, argument_list; 416, identifier:other; 417, subscript; 418, integer:1; 419, identifier:to_union; 420, slice; 421, string_content:Categorical.ordered must be the same; 422, attribute; 423, attribute; 424, attribute; 425, identifier:to_union; 426, slice; 427, integer:1; 428, identifier:other; 429, identifier:codes; 430, identifier:other; 431, identifier:categories; 432, identifier:first; 433, identifier:categories; 434, integer:1
code: def 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.
  
      .. versionadded:: 0.19.0
  
      Parameters
      ----------
      to_union : list-like of Categorical, CategoricalIndex,
                 or Series with dtype='category'
      sort_categories : boolean, default 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, the ordered attribute of the Categoricals will be ignored.
          Results in an unordered categorical.
  
          .. versionadded:: 0.20.0
  
      Returns
      -------
      result : 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
      <http://pandas.pydata.org/pandas-docs/stable/categorical.html#unioning>`__
  
      Examples
      --------
  
      >>> from pandas.api.types import union_categoricals
  
      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"])
      >>> 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.
  
      >>> 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)
      >>> 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)
      >>> union_categoricals([a, b])
      TypeError: to union ordered Categoricals, all categories must be the same
  
      New in version 0.20.0
  
      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)
      >>> 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')
      >>> union_categoricals([a, b])
      [b, c, a, b]
      Categories (3, object): [b, c, a]
      """
      from pandas import Index, Categorical, CategoricalIndex, Series
      from pandas.core.arrays.categorical import _recode_for_categories
  
      if len(to_union) == 0:
          raise ValueError('No Categoricals to union')
  
      def _maybe_unwrap(x):
          if isinstance(x, (CategoricalIndex, Series)):
              return x.values
          elif isinstance(x, Categorical):
              return x
          else:
              raise TypeError("all components to combine must be Categorical")
  
      to_union = [_maybe_unwrap(x) for x in to_union]
      first = to_union[0]
  
      if not all(is_dtype_equal(other.categories.dtype, first.categories.dtype)
                 for other in to_union[1:]):
          raise TypeError("dtype of categories must be the same")
  
      ordered = False
      if all(first.is_dtype_equal(other) for other in to_union[1:]):
          # identical categories - fastpath
          categories = first.categories
          ordered = first.ordered
  
          if all(first.categories.equals(other.categories)
                 for other in to_union[1:]):
              new_codes = np.concatenate([c.codes for c in to_union])
          else:
              codes = [first.codes] + [_recode_for_categories(other.codes,
                                                              other.categories,
                                                              first.categories)
                                       for other in to_union[1:]]
              new_codes = np.concatenate(codes)
  
          if sort_categories and not ignore_order and ordered:
              raise TypeError("Cannot use sort_categories=True with "
                              "ordered Categoricals")
  
          if sort_categories and not categories.is_monotonic_increasing:
              categories = categories.sort_values()
              indexer = categories.get_indexer(first.categories)
  
              from pandas.core.algorithms import take_1d
              new_codes = take_1d(indexer, new_codes, fill_value=-1)
      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())
          if sort_categories:
              categories = categories.sort_values()
  
          new_codes = [_recode_for_categories(c.codes, c.categories, categories)
                       for c in to_union]
          new_codes = np.concatenate(new_codes)
      else:
          # ordered - to show a proper error message
          if all(c.ordered for c in to_union):
              msg = ("to union ordered Categoricals, "
                     "all categories must be the same")
              raise TypeError(msg)
          else:
              raise TypeError('Categorical.ordered must be the same')
  
      if ignore_order:
          ordered = False
  
      return Categorical(new_codes, categories=categories, ordered=ordered,
                         fastpath=True)