class_docstr: Index based on an underlying `Categorical`.
  
  CategoricalIndex can only take on a limited,
  and usually fixed, number of possible values (`categories`). Also,
  it might have an order, but numerical operations
  (additions, divisions, ...) are not possible.
  
  Parameters
  ----------
  data : array-like (1-dimensional)
      The values of the categorical. If `categories` are given, values not in
      `categories` will be replaced with NaN.
  categories : index-like, optional
      The categories for the categorical. Items need to be unique.
      If the categories are not given here (and also not in `dtype`), they
      will be inferred from the `data`.
  ordered : bool, optional
      Whether or not this categorical is treated as an ordered
      categorical. If not given here or in `dtype`, the resulting
      categorical will be unordered.
  dtype : CategoricalDtype or "category", optional
      If :class:`CategoricalDtype`, cannot be used together with
      `categories` or `ordered`.
  copy : bool, default False
      Make a copy of input ndarray.
  name : object, optional
      Name to be stored in the index.
  
  See Also
  --------
  Index : The base pandas-on-Spark Index type.
  
  Examples
  --------
  >>> ps.CategoricalIndex(["a", "b", "c", "a", "b", "c"])  # doctest: +NORMALIZE_WHITESPACE
  CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
                   categories=['a', 'b', 'c'], ordered=False, dtype='category')
  
  ``CategoricalIndex`` can also be instantiated from a ``Categorical``:
  
  >>> c = pd.Categorical(["a", "b", "c", "a", "b", "c"])
  >>> ps.CategoricalIndex(c)  # doctest: +NORMALIZE_WHITESPACE
  CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
                   categories=['a', 'b', 'c'], ordered=False, dtype='category')
  
  Ordered ``CategoricalIndex`` can have a min and max value.
  
  >>> ci = ps.CategoricalIndex(
  ...     ["a", "b", "c", "a", "b", "c"], ordered=True, categories=["c", "b", "a"]
  ... )
  >>> ci  # doctest: +NORMALIZE_WHITESPACE
  CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
                   categories=['c', 'b', 'a'], ordered=True, dtype='category')
  
  From a Series:
  
  >>> s = ps.Series(["a", "b", "c", "a", "b", "c"], index=[10, 20, 30, 40, 50, 60])
  >>> ps.CategoricalIndex(s)  # doctest: +NORMALIZE_WHITESPACE
  CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
                   categories=['a', 'b', 'c'], ordered=False, dtype='category')
  
  From an Index:
  
  >>> idx = ps.Index(["a", "b", "c", "a", "b", "c"])
  >>> ps.CategoricalIndex(idx)  # doctest: +NORMALIZE_WHITESPACE
  CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
                   categories=['a', 'b', 'c'], ordered=False, dtype='category')
class_docstr_tok: ["Index","based","on","an","underlying","`","Categorical","`",".","CategoricalIndex","can","only","take","on","a","limited",",","and","usually","fixed",",","number","of","possible","values","(","`","categories","`",")",".","Also",",","it","might","have","an","order",",","but","numerical","operations","(","additions",",","divisions",",","...",")","are","not","possible",".","Parameters","--","--","--","--","--","data",":","array-like","(","1-dimensional",")","The","values","of","the","categorical",".","If","`","categories","`","are","given",",","values","not","in","`","categories","`","will","be","replaced","with","NaN",".","categories",":","index-like",",","optional","The","categories","for","the","categorical",".","Items","need","to","be","unique",".","If","the","categories","are","not","given","here","(","and","also","not","in","`","dtype","`",")",",","they","will","be","inferred","from","the","`","data","`",".","ordered",":","bool",",","optional","Whether","or","not","this","categorical","is","treated","as","an","ordered","categorical",".","If","not","given","here","or","in","`","dtype","`",",","the","resulting","categorical","will","be","unordered",".","dtype",":","CategoricalDtype","or","``","category","''",",","optional","If",":","class",":","`","CategoricalDtype","`",",","can","not","be","used","together","with","`","categories","`","or","`","ordered","`",".","copy",":","bool",",","default","False","Make","a","copy","of","input","ndarray",".","name",":","object",",","optional","Name","to","be","stored","in","the","index",".","See","Also","--","--","--","--","Index",":","The","base","pandas-on-Spark","Index","type",".","Examples","--","--","--","--",">",">",">","ps.CategoricalIndex","(","[","``","a","''",",","``","b","''",",","``","c","''",",","``","a","''",",","``","b","''",",","``","c","''","]",")","#","doctest",":","+NORMALIZE_WHITESPACE","CategoricalIndex","(","[","'","a","'",",","'","b","'",",","'","c","'",",","'","a","'",",","'","b","'",",","'","c","'","]",",","categories=","[","'","a","'",",","'","b","'",",","'","c","'","]",",","ordered=False",",","dtype='category","'",")","``","CategoricalIndex","``","can","also","be","instantiated","from","a","``","Categorical","``",":",">",">",">","c","=","pd.Categorical","(","[","``","a","''",",","``","b","''",",","``","c","''",",","``","a","''",",","``","b","''",",","``","c","''","]",")",">",">",">","ps.CategoricalIndex","(","c",")","#","doctest",":","+NORMALIZE_WHITESPACE","CategoricalIndex","(","[","'","a","'",",","'","b","'",",","'","c","'",",","'","a","'",",","'","b","'",",","'","c","'","]",",","categories=","[","'","a","'",",","'","b","'",",","'","c","'","]",",","ordered=False",",","dtype='category","'",")","Ordered","``","CategoricalIndex","``","can","have","a","min","and","max","value",".",">",">",">","ci","=","ps.CategoricalIndex","(","...","[","``","a","''",",","``","b","''",",","``","c","''",",","``","a","''",",","``","b","''",",","``","c","''","]",",","ordered=True",",","categories=","[","``","c","''",",","``","b","''",",","``","a","''","]","...",")",">",">",">","ci","#","doctest",":","+NORMALIZE_WHITESPACE","CategoricalIndex","(","[","'","a","'",",","'","b","'",",","'","c","'",",","'","a","'",",","'","b","'",",","'","c","'","]",",","categories=","[","'","c","'",",","'","b","'",",","'","a","'","]",",","ordered=True",",","dtype='category","'",")","From","a","Series",":",">",">",">","s","=","ps.Series","(","[","``","a","''",",","``","b","''",",","``","c","''",",","``","a","''",",","``","b","''",",","``","c","''","]",",","index=","[","10",",","20",",","30",",","40",",","50",",","60","]",")",">",">",">","ps.CategoricalIndex","(","s",")","#","doctest",":","+NORMALIZE_WHITESPACE","CategoricalIndex","(","[","'","a","'",",","'","b","'",",","'","c","'",",","'","a","'",",","'","b","'",",","'","c","'","]",",","categories=","[","'","a","'",",","'","b","'",",","'","c","'","]",",","ordered=False",",","dtype='category","'",")","From","an","Index",":",">",">",">","idx","=","ps.Index","(","[","``","a","''",",","``","b","''",",","``","c","''",",","``","a","''",",","``","b","''",",","``","c","''","]",")",">",">",">","ps.CategoricalIndex","(","idx",")","#","doctest",":","+NORMALIZE_WHITESPACE","CategoricalIndex","(","[","'","a","'",",","'","b","'",",","'","c","'",",","'","a","'",",","'","b","'",",","'","c","'","]",",","categories=","[","'","a","'",",","'","b","'",",","'","c","'","]",",","ordered=False",",","dtype='category","'",")"]
docstr: Set the categories to the specified new_categories.
  
  `new_categories` can include new categories (which will result in
  unused categories) or remove old categories (which results in values
  set to NaN). If `rename==True`, the categories will simply be renamed
  (less or more items than in old categories will result in values set to
  NaN or in unused categories respectively).
  
  This method can be used to perform more than one action of adding,
  removing, and reordering simultaneously and is therefore faster than
  performing the individual steps via the more specialised methods.
  
  On the other hand this methods does not do checks (e.g., whether the
  old categories are included in the new categories on a reorder), which
  can result in surprising changes, for example when using special string
  dtypes, which does not consider a S1 string equal to a single char
  python string.
  
  Parameters
  ----------
  new_categories : Index-like
     The categories in new order.
  ordered : bool, default False
     Whether or not the categorical is treated as an ordered categorical.
     If not given, do not change the ordered information.
  rename : bool, default False
     Whether or not the new_categories should be considered as a rename
     of the old categories or as reordered categories.
  
  Returns
  -------
  CategoricalIndex with reordered categories
  
  Raises
  ------
  ValueError
      If new_categories does not validate as categories
  
  See Also
  --------
  rename_categories : Rename categories.
  reorder_categories : Reorder categories.
  add_categories : Add new categories.
  remove_categories : Remove the specified categories.
  remove_unused_categories : Remove categories which are not used.
  
  Examples
  --------
  >>> idx = ps.CategoricalIndex(list("abbccc"))
  >>> idx  # doctest: +NORMALIZE_WHITESPACE
  CategoricalIndex(['a', 'b', 'b', 'c', 'c', 'c'],
                   categories=['a', 'b', 'c'], ordered=False, dtype='category')
  
  >>> idx.set_categories(['b', 'c'])  # doctest: +NORMALIZE_WHITESPACE
  CategoricalIndex([nan, 'b', 'b', 'c', 'c', 'c'],
                   categories=['b', 'c'], ordered=False, dtype='category')
  
  >>> idx.set_categories([1, 2, 3], rename=True)
  CategoricalIndex([1, 2, 2, 3, 3, 3], categories=[1, 2, 3], ordered=False, dtype='category')
  
  >>> idx.set_categories([1, 2, 3], rename=True, ordered=True)
  CategoricalIndex([1, 2, 2, 3, 3, 3], categories=[1, 2, 3], ordered=True, dtype='category')
docstr_tok: ["Set","the","categories","to","the","specified","new_categories",".","`","new_categories","`","can","include","new","categories","(","which","will","result","in","unused","categories",")","or","remove","old","categories","(","which","results","in","values","set","to","NaN",")",".","If","`","rename==True","`",",","the","categories","will","simply","be","renamed","(","less","or","more","items","than","in","old","categories","will","result","in","values","set","to","NaN","or","in","unused","categories","respectively",")",".","This","method","can","be","used","to","perform","more","than","one","action","of","adding",",","removing",",","and","reordering","simultaneously","and","is","therefore","faster","than","performing","the","individual","steps","via","the","more","specialised","methods",".","On","the","other","hand","this","methods","does","not","do","checks","(","e.g.",",","whether","the","old","categories","are","included","in","the","new","categories","on","a","reorder",")",",","which","can","result","in","surprising","changes",",","for","example","when","using","special","string","dtypes",",","which","does","not","consider","a","S1","string","equal","to","a","single","char","python","string",".","Parameters","--","--","--","--","--","new_categories",":","Index-like","The","categories","in","new","order",".","ordered",":","bool",",","default","False","Whether","or","not","the","categorical","is","treated","as","an","ordered","categorical",".","If","not","given",",","do","not","change","the","ordered","information",".","rename",":","bool",",","default","False","Whether","or","not","the","new_categories","should","be","considered","as","a","rename","of","the","old","categories","or","as","reordered","categories",".","Returns","--","--","--","-","CategoricalIndex","with","reordered","categories","Raises","--","--","--","ValueError","If","new_categories","does","not","validate","as","categories","See","Also","--","--","--","--","rename_categories",":","Rename","categories",".","reorder_categories",":","Reorder","categories",".","add_categories",":","Add","new","categories",".","remove_categories",":","Remove","the","specified","categories",".","remove_unused_categories",":","Remove","categories","which","are","not","used",".","Examples","--","--","--","--",">",">",">","idx","=","ps.CategoricalIndex","(","list","(","``","abbccc","''",")",")",">",">",">","idx","#","doctest",":","+NORMALIZE_WHITESPACE","CategoricalIndex","(","[","'","a","'",",","'","b","'",",","'","b","'",",","'","c","'",",","'","c","'",",","'","c","'","]",",","categories=","[","'","a","'",",","'","b","'",",","'","c","'","]",",","ordered=False",",","dtype='category","'",")",">",">",">","idx.set_categories","(","[","'","b","'",",","'","c","'","]",")","#","doctest",":","+NORMALIZE_WHITESPACE","CategoricalIndex","(","[","nan",",","'","b","'",",","'","b","'",",","'","c","'",",","'","c","'",",","'","c","'","]",",","categories=","[","'","b","'",",","'","c","'","]",",","ordered=False",",","dtype='category","'",")",">",">",">","idx.set_categories","(","[","1",",","2",",","3","]",",","rename=True",")","CategoricalIndex","(","[","1",",","2",",","2",",","3",",","3",",","3","]",",","categories=","[","1",",","2",",","3","]",",","ordered=False",",","dtype='category","'",")",">",">",">","idx.set_categories","(","[","1",",","2",",","3","]",",","rename=True",",","ordered=True",")","CategoricalIndex","(","[","1",",","2",",","2",",","3",",","3",",","3","]",",","categories=","[","1",",","2",",","3","]",",","ordered=True",",","dtype='category","'",")"]
code: def set_categories(
      self,
      new_categories: Union[pd.Index, List],
      ordered: Optional[bool] = None,
      rename: bool = False,
  ) -> Optional["CategoricalIndex"]:
      """
      Set the categories to the specified new_categories.
  
      `new_categories` can include new categories (which will result in
      unused categories) or remove old categories (which results in values
      set to NaN). If `rename==True`, the categories will simply be renamed
      (less or more items than in old categories will result in values set to
      NaN or in unused categories respectively).
  
      This method can be used to perform more than one action of adding,
      removing, and reordering simultaneously and is therefore faster than
      performing the individual steps via the more specialised methods.
  
      On the other hand this methods does not do checks (e.g., whether the
      old categories are included in the new categories on a reorder), which
      can result in surprising changes, for example when using special string
      dtypes, which does not consider a S1 string equal to a single char
      python string.
  
      Parameters
      ----------
      new_categories : Index-like
         The categories in new order.
      ordered : bool, default False
         Whether or not the categorical is treated as an ordered categorical.
         If not given, do not change the ordered information.
      rename : bool, default False
         Whether or not the new_categories should be considered as a rename
         of the old categories or as reordered categories.
  
      Returns
      -------
      CategoricalIndex with reordered categories
  
      Raises
      ------
      ValueError
          If new_categories does not validate as categories
  
      See Also
      --------
      rename_categories : Rename categories.
      reorder_categories : Reorder categories.
      add_categories : Add new categories.
      remove_categories : Remove the specified categories.
      remove_unused_categories : Remove categories which are not used.
  
      Examples
      --------
      >>> idx = ps.CategoricalIndex(list("abbccc"))
      >>> idx  # doctest: +NORMALIZE_WHITESPACE
      CategoricalIndex(['a', 'b', 'b', 'c', 'c', 'c'],
                       categories=['a', 'b', 'c'], ordered=False, dtype='category')
  
      >>> idx.set_categories(['b', 'c'])  # doctest: +NORMALIZE_WHITESPACE
      CategoricalIndex([nan, 'b', 'b', 'c', 'c', 'c'],
                       categories=['b', 'c'], ordered=False, dtype='category')
  
      >>> idx.set_categories([1, 2, 3], rename=True)
      CategoricalIndex([1, 2, 2, 3, 3, 3], categories=[1, 2, 3], ordered=False, dtype='category')
  
      >>> idx.set_categories([1, 2, 3], rename=True, ordered=True)
      CategoricalIndex([1, 2, 2, 3, 3, 3], categories=[1, 2, 3], ordered=True, dtype='category')
      """
      return CategoricalIndex(
          self.to_series().cat.set_categories(
              new_categories, ordered=ordered, rename=rename
          )
      ).rename(self.name)
  
imports: from typing import Any, Callable, List, Optional, Union, cast, no_type_check
  import pandas
  from pandas.api.types import is_hashable, CategoricalDtype
  from pyspark import pandas
  from pyspark.pandas.indexes.base import Index
  from pyspark.pandas.internal import InternalField
  from pyspark.pandas.series import Series
  from pyspark.sql.types import StructField
label_desc: Use image node_id 14 for calling the CategoricalIndex obj's underlying member method code with example usage: obj.set_categories(new_categories, ordered, rename) and returns: CategoricalIndex