o
    5c~                    @  s  d dl mZ d dlmZ d dlmZ d dlZd dlmZ d dl	m
Z
mZmZmZmZmZmZmZ d dlmZmZmZ d dlZd dlmZ d d	lmZmZmZ d d
lm Z  d dl!m"Z"m#Z# d dl$m%Z%m&Z&m'Z'm(Z(m)Z)m*Z*m+Z+m,Z, d dl-m.Z/ d dl0m1Z1m2Z2 d dl3m4Z4 d dl5m6Z6 d dl7m8Z8 d dl9m:Z:m;Z;m<Z<m=Z=m>Z>m?Z?m@Z@mAZAmBZBmCZCmDZDmEZEmFZFmGZG d dlHmIZImJZJ d dlKmLZLmMZM d dlNmOZOmPZPmQZQ d dlRmSZSmTZT d dlUmVZVmWZW d dlXmY  mZZZ d dlXm[Z[m\Z\m]Z] d dl^m_Z_m`Z` d dlambZbmcZcmdZd d dlemY  mfZg d dlhmiZimjZj d dlkmlZl d dlmmnZn d dlompZp d dlqmrZr e
r5d d lsmtZtmuZumvZv ed!d"d#Zwd$d% ZxdBd(d)ZyG d*d" d"e_edepZzeWezd+d,gd-d.eWezg d/d0d.G d1d2 d2eVedecZ{dCd5d6Z|	7dDdEd:d;Z}dFd=d>Z~dGd@dAZdS )H    )annotations)QUOTE_NONNUMERIC)partialN)get_terminal_size)TYPE_CHECKINGHashableLiteralSequenceTypeVarUnioncastoverload)catch_warningssimplefilterwarn)
get_option)NaTalgoslib)NDArrayBacked)	NoDefault
no_default)	ArrayLike	AstypeArgDtypeNpDtypeOrderedShapenpttype_t)function)deprecate_kwargdeprecate_nonkeyword_arguments)find_stack_level)validate_bool_kwarg)coerce_indexer_dtype)ensure_int64ensure_platform_intis_categorical_dtypeis_datetime64_dtypeis_dict_likeis_dtype_equalis_extension_array_dtypeis_hashableis_integer_dtypeis_list_like	is_scalaris_timedelta64_dtypeneeds_i8_conversionpandas_dtype)CategoricalDtypeExtensionDtype)ABCIndex	ABCSeries)is_valid_na_for_dtypeisnanotna)	arraylikeops)PandasDelegatedelegate_names)	factorizetake_ndunique1d)NDArrayBackedExtensionArrayravel_compat)ExtensionArrayNoNewAttributesMixinPandasObject)extract_arraysanitize_array)unpack_zerodim_and_defer)nargsort)ObjectStringArrayMixin)console)	DataFrameIndexSeriesCategoricalTCategorical)boundc                   sB   dj  dtju rdnd t fdd}|_ |S )N__TFc                   sp  t |}t|rt|t| kr|std| js!dv r!tdt|trcd}| |s1t|| jsG| j	
|j	sGt|j|j	| j	dd}n|j}| j|}| jdk|dkB }| ra ||< |S |r|| j	v r| |}| j|}dvr| jdk} ||< |S t| |S d	vrtd
 dt| dt|trt|jr|| S tt| t|S )NzLengths must match.)__lt____gt____le____ge__z7Unordered Categoricals can only compare equality or notz?Categoricals can only be compared if 'categories' are the same.Fcopy>   __eq__rW   rU   )r[   __ne__z$Cannot compare a Categorical for op z with type zB.
If you want to compare values, use 'np.asarray(cat) <op> other'.)r-   r/   len
ValueErrorordered	TypeError
isinstancerQ   #_categories_match_up_to_permutation
categoriesequalsrecode_for_categoriescodes_codesany_unbox_scalarr<   invalid_comparisontyperD   r2   dtypegetattrnparray)selfotherhashablemsgother_codesretmaski
fill_valueopopname T/var/www/html/gps/gps/lib/python3.10/site-packages/pandas/core/arrays/categorical.pyfunc   sP   





z_cat_compare_op.<locals>.func)__name__operatornerI   )rz   r~   r|   rx   r}   _cat_compare_op   s   ?r   returnboolc              	     sX   t | z| j|}W n ttfy   Y dS w t|r!| v S t fdd|D S )aO  
    Helper for membership check for ``key`` in ``cat``.

    This is a helper method for :method:`__contains__`
    and :class:`CategoricalIndex.__contains__`.

    Returns True if ``key`` is in ``cat.categories`` and the
    location of ``key`` in ``categories`` is in ``container``.

    Parameters
    ----------
    cat : :class:`Categorical`or :class:`categoricalIndex`
    key : a hashable object
        The key to check membership for.
    container : Container (e.g. list-like or mapping)
        The container to check for membership in.

    Returns
    -------
    is_in : bool
        True if ``key`` is in ``self.categories`` and location of
        ``key`` in ``categories`` is in ``container``, else False.

    Notes
    -----
    This method does not check for NaN values. Do that separately
    before calling this method.
    Fc                 3  s    | ]}| v V  qd S Nr|   ).0loc_	containerr|   r}   	<genexpr>       zcontains.<locals>.<genexpr>)hashrc   get_locKeyErrorr`   r0   rh   )catkeyr   locr|   r   r}   contains   s   r   c                      s  e Zd ZU dZdZejedgB ZdZde	d< 						dd fddZ
edddZedddZed	ddZedddd
ddZeddd!d"Zeddd%d"Zeddd(d"Zdd fd)d"Zd*d+ Ze	dd,d-Ze	ddd.d/Zedd1d2Zejdd3d2Zedd5d6Zedd7d8Zd fd9d:	Zdd;d<Zedd=dd@dAZeddCdAZeddEdAZeddFdGgdHefddJdAZedd=ddKdLZeddMdLZeddFgdHefddNdLZedd=ddOdPZ eddQdPZ eddFgdHefddRdPZ ddefdSdTZ!edd=ddVdWZ"eddXdWZ"eddFdYgdHefddZdWZ"defd[d\Z#edd=dd]d^Z$edd_d^Z$eddFdYgdHefdd`d^Z$efdadbZ%edd=ddcddZ&eddeddZ&eddFgdHefddfddZ&dgdh Z'e(e)j*Z+e(e)j,Z-e(e)j.Z/e(e)j0Z1e(e)j2Z3e(e)j4Z5didj Z6e6Z7dkdl Z8e9dddndoZ:ddtduZ;d fdvdwZ<eddxdyZ=dd d{d|Z>dd}d~Z?e?Z@dddZAeAZBdd!ddZCed"ddZDdd ZEdddZFeddFgdHd# fdd	ZGeddddd$ddZHedddd%ddZHeddFgdH	d&d'ddZHdddd	ddd(ddZIdd ZJdddZKedddZLeLjd)ddZLd*ddZMdddZN	d+d,ddZOdd ZPd-ddZQdd.ddZRd/d0ddZSd1ddZTd2ddĄZUd2ddƄZVd3d4ddʄZWd2dd̄ZXdd΄ ZYd5ddфZZe[dddԍd	d՜ddׄZ\e[dddԍd	d՜ddلZ]dd6ddۄZ^dd6dd݄Z_dd߄ Z`d7ddZad8ddZbe	d9d:ddZcd;ddZdd<ddZed-ddZfd=ddZgd>ddZhedd=d?ddZiedddZieddFdGgdHddddZidd=d@ddZjekjlekdd	fdAd dZmdBddZn  ZoS (C  rQ   a^  
    Represent a categorical variable in classic R / S-plus fashion.

    `Categoricals` can only take on only a limited, and usually fixed, number
    of possible values (`categories`). In contrast to statistical categorical
    variables, a `Categorical` might have an order, but numerical operations
    (additions, divisions, ...) are not possible.

    All values of the `Categorical` are either in `categories` or `np.nan`.
    Assigning values outside of `categories` will raise a `ValueError`. Order
    is defined by the order of the `categories`, not lexical order of the
    values.

    Parameters
    ----------
    values : list-like
        The values of the categorical. If categories are given, values not in
        categories will be replaced with NaN.
    categories : Index-like (unique), optional
        The unique categories for this categorical. If not given, the
        categories are assumed to be the unique values of `values` (sorted, if
        possible, otherwise in the order in which they appear).
    ordered : bool, default False
        Whether or not this categorical is treated as a ordered categorical.
        If True, the resulting categorical will be ordered.
        An ordered categorical respects, when sorted, the order of its
        `categories` attribute (which in turn is the `categories` argument, if
        provided).
    dtype : CategoricalDtype
        An instance of ``CategoricalDtype`` to use for this categorical.

    Attributes
    ----------
    categories : Index
        The categories of this categorical
    codes : ndarray
        The codes (integer positions, which point to the categories) of this
        categorical, read only.
    ordered : bool
        Whether or not this Categorical is ordered.
    dtype : CategoricalDtype
        The instance of ``CategoricalDtype`` storing the ``categories``
        and ``ordered``.

    Methods
    -------
    from_codes
    __array__

    Raises
    ------
    ValueError
        If the categories do not validate.
    TypeError
        If an explicit ``ordered=True`` is given but no `categories` and the
        `values` are not sortable.

    See Also
    --------
    CategoricalDtype : Type for categorical data.
    CategoricalIndex : An Index with an underlying ``Categorical``.

    Notes
    -----
    See the `user guide
    <https://pandas.pydata.org/pandas-docs/stable/user_guide/categorical.html>`__
    for more.

    Examples
    --------
    >>> pd.Categorical([1, 2, 3, 1, 2, 3])
    [1, 2, 3, 1, 2, 3]
    Categories (3, int64): [1, 2, 3]

    >>> pd.Categorical(['a', 'b', 'c', 'a', 'b', 'c'])
    ['a', 'b', 'c', 'a', 'b', 'c']
    Categories (3, object): ['a', 'b', 'c']

    Missing values are not included as a category.

    >>> c = pd.Categorical([1, 2, 3, 1, 2, 3, np.nan])
    >>> c
    [1, 2, 3, 1, 2, 3, NaN]
    Categories (3, int64): [1, 2, 3]

    However, their presence is indicated in the `codes` attribute
    by code `-1`.

    >>> c.codes
    array([ 0,  1,  2,  0,  1,  2, -1], dtype=int8)

    Ordered `Categoricals` can be sorted according to the custom order
    of the categories and can have a min and max value.

    >>> c = pd.Categorical(['a', 'b', 'c', 'a', 'b', 'c'], ordered=True,
    ...                    categories=['c', 'b', 'a'])
    >>> c
    ['a', 'b', 'c', 'a', 'b', 'c']
    Categories (3, object): ['c' < 'b' < 'a']
    >>> c.min()
    'c'
    i  tolistcategoricalr4   _dtypeNFTrl   Dtype | Nonefastpathr   rY   r   Nonec              
     s^  t  |||}|r!t |j}t dd|}t || d S t s0tdt	t
 d  g td}t rF|jd u rEt  j|j}ngt tttfst  t trft dkrftjg td nGt tjr{ jdkrutdt d  n2t d }	t|	}| r fd	d
t| d D }
|
s|	jdkrd }n|	j}t|
d |d}	|	 |jd u rz
t  dd\}}W n" t!y } zt  dd\}}|jrt!d|W Y d }~nd }~ww t ||j}nt jrt" j#}t$| jj|j|d}nt% |j}| rtj&|j'|jd }||| < |}t dd|}t||j}	t |	| d S )NFr_   zxAllowing scalars in the Categorical constructor is deprecated and will raise in a future version.  Use `[value]` instead
stacklevelr   rl      z3> 1 ndim Categorical are not supported at this timec                   s   g | ]} | qS r|   r|   )r   idxvaluesr|   r}   
<listcomp>      z(Categorical.__init__.<locals>.<listcomp>objectT)sortzl'values' is not ordered, please explicitly specify the categories order by passing in a categories argument.rX   )(r4   _from_values_or_dtyper%   rc   update_dtypesuper__init__r/   r   FutureWarningr#   rn   ro   r(   r_   ra   r6   r7   rD   comconvert_to_list_likelistr]   r   ndarrayndimNotImplementedErrorrH   r9   rh   whererl   r?   r`   rG   rg   re   _get_codes_for_valuesonesshape)rp   r   rc   r_   rl   r   rY   rf   	null_maskarrarr_listsanitize_dtypeerr	old_codes
full_codes	__class__r   r}   r   p  s   










zCategorical.__init__c                 C     | j S )zT
        The :class:`~pandas.api.types.CategoricalDtype` for this instance.
        )r   rp   r|   r|   r}   rl     s   zCategorical.dtypeintc                 C  s   | j j}|dS NrZ   )_ndarrayrl   rk   )rp   rl   r|   r|   r}   _internal_fill_value  s   
z Categorical._internal_fill_valuetype[Categorical]c                 C  s   t S r   rQ   r   r|   r|   r}   _constructor     zCategorical._constructorrl   rY   c                C  s   t |||dS )Nr   r   )clsscalarsrl   rY   r|   r|   r}   _from_sequence  s   zCategorical._from_sequence.npt.DTypeLike
np.ndarrayc                 C     d S r   r|   rp   rl   rY   r|   r|   r}   astype  r   zCategorical.astyper5   rD   c                 C  r   r   r|   r   r|   r|   r}   r     r   r   r   c                 C  r   r   r|   r   r|   r|   r}   r     r   c              	     sZ  t |}| j|u r|r|  }|S | }|S t|r3td|}| j|}|r*|  n| } | |}|S t|tr@t	 j
||dS t|rN|   rNtdt| jdks\t| jdkrftj| ||d}|S | jj}z|j
||d}| jj}t||stt| jj
|}W n ttfy   d| jj d| }t|w t|t| j|d}|S )	aZ  
        Coerce this type to another dtype

        Parameters
        ----------
        dtype : numpy dtype or pandas type
        copy : bool, default True
            By default, astype always returns a newly allocated object.
            If copy is set to False and dtype is categorical, the original
            object is returned.
        zUnion[str, CategoricalDtype]rX   z#Cannot convert float NaN to integerr   r   zCannot cast z
 dtype to ry   )r3   rl   rY   r(   r   r   
_set_dtypera   r5   r   r   r.   r9   rh   r^   r]   rf   rc   rn   ro   _values	_na_valuer8   r   item_from_zerodimr`   r@   r'   rg   )rp   rl   rY   resultnew_catsry   rs   r   r|   r}   r     sV   
--

%


c                 C  s   |   S )z#
        Alias for tolist.
        )r   r   r|   r|   r}   to_list:  s   zCategorical.to_listc                 C  s
  ddl m}m}m}m} ||}	t|to|jdu}
|
rR|j r(||dd}	n*t	|jr4||dd}	nt
|jr@||dd}	n|j rR|du rMg d}|	|}	|
r^|j}t||	|}n |	jsv|	 }|	 }t|||}t|dd}nt|	dd}|}| ||d	d
S )aA  
        Construct a Categorical from inferred values.

        For inferred categories (`dtype` is None) the categories are sorted.
        For explicit `dtype`, the `inferred_categories` are cast to the
        appropriate type.

        Parameters
        ----------
        inferred_categories : Index
        inferred_codes : Index
        dtype : CategoricalDtype or 'category'
        true_values : list, optional
            If none are provided, the default ones are
            "True", "TRUE", and "true."

        Returns
        -------
        Categorical
        r   )rN   to_datetime
to_numericto_timedeltaNcoerce)errors)TrueTRUEtrueFr   Trl   r   )pandasrN   r   r   r   ra   r4   rc   
is_numericr)   r1   
is_booleanisinre   is_monotonic_increasingrY   sort_values)r   inferred_categoriesinferred_codesrl   true_valuesrN   r   r   r   catsknown_categoriesrc   rf   unsortedr|   r|   r}   _from_inferred_categories@  s4   




z%Categorical._from_inferred_categoriesc                 C  s   t j|||d}|jdu rd}t|t|r-t|r-t| r%td|jt	j
d}nt	|}t|r>t|s>tdt|rU| t|jksQ| dk rUtd| ||d	d
S )a  
        Make a Categorical type from codes and categories or dtype.

        This constructor is useful if you already have codes and
        categories/dtype and so do not need the (computation intensive)
        factorization step, which is usually done on the constructor.

        If your data does not follow this convention, please use the normal
        constructor.

        Parameters
        ----------
        codes : array-like of int
            An integer array, where each integer points to a category in
            categories or dtype.categories, or else is -1 for NaN.
        categories : index-like, optional
            The categories for the categorical. Items need to be unique.
            If the categories are not given here, then they must be provided
            in `dtype`.
        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`.

        Returns
        -------
        Categorical

        Examples
        --------
        >>> dtype = pd.CategoricalDtype(['a', 'b'], ordered=True)
        >>> pd.Categorical.from_codes(codes=[0, 1, 0, 1], dtype=dtype)
        ['a', 'b', 'a', 'b']
        Categories (2, object): ['a' < 'b']
        )rc   r_   rl   NzKThe categories must be provided in 'categories' or 'dtype'. Both were None.zcodes cannot contain NA valuesr   z$codes need to be array-like integersrZ   z1codes need to be between -1 and len(categories)-1Tr   )r4   r   rc   r^   r,   r.   r9   rh   to_numpyrn   int64asarrayr]   maxmin)r   rf   rc   r_   rl   rs   r|   r|   r}   
from_codes  s"   *

&zCategorical.from_codesrN   c                 C     | j jS )a  
        The categories of this categorical.

        Setting assigns new values to each category (effectively a rename of
        each individual category).

        The assigned value has to be a list-like object. All items must be
        unique and the number of items in the new categories must be the same
        as the number of items in the old categories.

        Assigning to `categories` is a inplace operation!

        Raises
        ------
        ValueError
            If the new categories do not validate as categories or if the
            number of new categories is unequal the number of old 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.
        set_categories : Set the categories to the specified ones.
        )rl   rc   r   r|   r|   r}   rc     s   zCategorical.categoriesc                 C  s   t dtt d | | d S )NzlSetting categories in-place is deprecated and will raise in a future version. Use rename_categories instead.r   )r   r   r#   _set_categories)rp   rc   r|   r|   r}   rc     s   r   c                 C  r   )zF
        Whether the categories have an ordered relationship.
        )rl   r_   r   r|   r|   r}   r_     s   zCategorical.orderedc                 C  s   | j  }d|j_|S )a  
        The category codes of this categorical.

        Codes are an array of integers which are the positions of the actual
        values in the categories array.

        There is no setter, use the other categorical methods and the normal item
        setter to change values in the categorical.

        Returns
        -------
        ndarray[int]
            A non-writable view of the `codes` array.
        F)rg   viewflags	writeable)rp   vr|   r|   r}   rf     s   
zCategorical.codesc                   sd   |r
t || j}nt || jd}|s(| jjdur(t|jt| jjkr(tdt | j	| dS )a  
        Sets new categories inplace

        Parameters
        ----------
        fastpath : bool, default False
           Don't perform validation of the categories for uniqueness or nulls

        Examples
        --------
        >>> c = pd.Categorical(['a', 'b'])
        >>> c
        ['a', 'b']
        Categories (2, object): ['a', 'b']

        >>> c._set_categories(pd.Index(['a', 'c']))
        >>> c
        ['a', 'c']
        Categories (2, object): ['a', 'c']
        r   NzKnew categories need to have the same number of items as the old categories!)
r4   _from_fastpathr_   rl   rc   r]   r^   r   r   r   )rp   rc   r   	new_dtyper   r|   r}   r     s   
zCategorical._set_categoriesc                 C  s$   t | j| j|j}t| ||ddS )a+  
        Internal method for directly updating the CategoricalDtype

        Parameters
        ----------
        dtype : CategoricalDtype

        Notes
        -----
        We don't do any validation here. It's assumed that the dtype is
        a (valid) instance of `CategoricalDtype`.
        Tr   )re   rf   rc   rk   )rp   rl   rf   r|   r|   r}   r   5  s   zCategorical._set_dtypeinplacer   NoDefault | Literal[False]c                C  r   r   r|   rp   valuer   r|   r|   r}   set_orderedE     zCategorical.set_orderedLiteral[True]c                C  r   r   r|   r   r|   r|   r}   r  K  r   Categorical | Nonec                C  r   r   r|   r   r|   r|   r}   r  O  r   rp   r   )versionallowed_argsbool | NoDefaultc                 C  sb   |t urtdtt d nd}t|d}t| j|d}|r| n|  }t	||j
| |s/|S dS )a  
        Set the ordered attribute to the boolean value.

        Parameters
        ----------
        value : bool
           Set whether this categorical is ordered (True) or not (False).
        inplace : bool, default False
           Whether or not to set the ordered attribute in-place or return
           a copy of this categorical with ordered set to the value.

           .. deprecated:: 1.5.0

        zThe `inplace` parameter in pandas.Categorical.set_ordered is deprecated and will be removed in a future version. setting ordered-ness on categories will always return a new Categorical object.r   Fr   r   N)r   r   r   r#   r$   r4   rc   rY   r   r   r   )rp   r   r   r   r   r|   r|   r}   r  S  s   	
c                C  r   r   r|   rp   r   r|   r|   r}   
as_orderedy  r   zCategorical.as_orderedc                C  r   r   r|   r  r|   r|   r}   r	  }  r   c                 C      |t ur	t|d}| jd|dS )a  
        Set the Categorical to be ordered.

        Parameters
        ----------
        inplace : bool, default False
           Whether or not to set the ordered attribute in-place or return
           a copy of this categorical with ordered set to True.

           .. deprecated:: 1.5.0

        Returns
        -------
        Categorical or None
            Ordered Categorical or None if ``inplace=True``.
        r   Tr   r   r$   r  r  r|   r|   r}   r	    s   
c                C  r   r   r|   r  r|   r|   r}   as_unordered  r   zCategorical.as_unorderedc                C  r   r   r|   r  r|   r|   r}   r    r   c                 C  r
  )a  
        Set the Categorical to be unordered.

        Parameters
        ----------
        inplace : bool, default False
           Whether or not to set the ordered attribute in-place or return
           a copy of this categorical with ordered set to False.

           .. deprecated:: 1.5.0

        Returns
        -------
        Categorical or None
            Unordered Categorical or None if ``inplace=True``.
        r   Fr   r  r  r|   r|   r}   r    s   
c                 C  s   |t urtdtt d nd}t|d}|du r| jj}t||d}|r&| n|  }|rL|jj	durHt
|j	t
|jj	k rHd|j|jt
|j	k< |j}n	t|j|j	|j	}t||| |s`|S dS )a  
        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 simple 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 considers 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 a 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.
        inplace : bool, default False
           Whether or not to reorder the categories in-place or return a copy
           of this categorical with reordered categories.

           .. deprecated:: 1.3.0

        Returns
        -------
        Categorical with reordered categories or None if inplace.

        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.
        zThe `inplace` parameter in pandas.Categorical.set_categories is deprecated and will be removed in a future version. Removing unused categories will always return a new Categorical object.r   Fr   Nr   rZ   )r   r   r   r#   r$   rl   r_   r4   rY   rc   r]   rg   re   rf   r   r   )rp   new_categoriesr_   renamer   r   r   rf   r|   r|   r}   set_categories  s2   7	
zCategorical.set_categoriesLiteral[False] | NoDefaultc                C  r   r   r|   rp   r  r   r|   r|   r}   rename_categories  r  zCategorical.rename_categoriesc                C  r   r   r|   r  r|   r|   r}   r    r   r  c                   s   |t urtdtt d nd}t|d}|r| n|  }t r+ fdd|jD  nt r9 fdd|jD  |	  |sB|S dS )	a  
        Rename categories.

        Parameters
        ----------
        new_categories : list-like, dict-like or callable

            New categories which will replace old categories.

            * list-like: all items must be unique and the number of items in
              the new categories must match the existing number of categories.

            * dict-like: specifies a mapping from
              old categories to new. Categories not contained in the mapping
              are passed through and extra categories in the mapping are
              ignored.

            * callable : a callable that is called on all items in the old
              categories and whose return values comprise the new categories.

        inplace : bool, default False
            Whether or not to rename the categories inplace or return a copy of
            this categorical with renamed categories.

            .. deprecated:: 1.3.0

        Returns
        -------
        cat : Categorical or None
            Categorical with removed categories or None if ``inplace=True``.

        Raises
        ------
        ValueError
            If new categories are list-like and do not have the same number of
            items than the current categories or do not validate as categories

        See Also
        --------
        reorder_categories : Reorder categories.
        add_categories : Add new categories.
        remove_categories : Remove the specified categories.
        remove_unused_categories : Remove categories which are not used.
        set_categories : Set the categories to the specified ones.

        Examples
        --------
        >>> c = pd.Categorical(['a', 'a', 'b'])
        >>> c.rename_categories([0, 1])
        [0, 0, 1]
        Categories (2, int64): [0, 1]

        For dict-like ``new_categories``, extra keys are ignored and
        categories not in the dictionary are passed through

        >>> c.rename_categories({'a': 'A', 'c': 'C'})
        ['A', 'A', 'b']
        Categories (2, object): ['A', 'b']

        You may also provide a callable to create the new categories

        >>> c.rename_categories(lambda x: x.upper())
        ['A', 'A', 'B']
        Categories (2, object): ['A', 'B']
        zThe `inplace` parameter in pandas.Categorical.rename_categories is deprecated and will be removed in a future version. Removing unused categories will always return a new Categorical object.r   Fr   c                   s   g | ]}  ||qS r|   )getr   itemr  r|   r}   r   q      z1Categorical.rename_categories.<locals>.<listcomp>c                   s   g | ]} |qS r|   r|   r  r  r|   r}   r   s  r   N)
r   r   r   r#   r$   rY   r*   rc   callabler   )rp   r  r   r   r|   r  r}   r    s"   G	

c                 C  s   |t urtdtt d nd}t|d}t| jjt|kr"tdt	  t
d | j|||dW  d   S 1 s<w   Y  dS )	a  
        Reorder categories as specified in new_categories.

        `new_categories` need to include all old categories and no new category
        items.

        Parameters
        ----------
        new_categories : Index-like
           The categories in new order.
        ordered : bool, optional
           Whether or not the categorical is treated as a ordered categorical.
           If not given, do not change the ordered information.
        inplace : bool, default False
           Whether or not to reorder the categories inplace or return a copy of
           this categorical with reordered categories.

           .. deprecated:: 1.3.0

        Returns
        -------
        cat : Categorical or None
            Categorical with removed categories or None if ``inplace=True``.

        Raises
        ------
        ValueError
            If the new categories do not contain all old category items or any
            new ones

        See Also
        --------
        rename_categories : Rename categories.
        add_categories : Add new categories.
        remove_categories : Remove the specified categories.
        remove_unused_categories : Remove categories which are not used.
        set_categories : Set the categories to the specified ones.
        zThe `inplace` parameter in pandas.Categorical.reorder_categories is deprecated and will be removed in a future version. Reordering categories will always return a new Categorical object.r   Fr   z=items in new_categories are not the same as in old categoriesignore)r_   r   N)r   r   r   r#   r$   setrl   rc   r^   r   r   r  )rp   r  r_   r   r|   r|   r}   reorder_categoriesz  s    '	
$zCategorical.reorder_categoriesc                C  r   r   r|   r  r|   r|   r}   add_categories  r  zCategorical.add_categoriesc                C  r   r   r|   r  r|   r|   r}   r    r   c                 C  s   |t urtdtt d nd}t|d}t|s|g}t|t| jj@ }t	|dkr2t
d| t| jjt| }t|| j}|rF| n|  }t|j|j}t||| |s\|S dS )a  
        Add new categories.

        `new_categories` will be included at the last/highest place in the
        categories and will be unused directly after this call.

        Parameters
        ----------
        new_categories : category or list-like of category
           The new categories to be included.
        inplace : bool, default False
           Whether or not to add the categories inplace or return a copy of
           this categorical with added categories.

           .. deprecated:: 1.3.0

        Returns
        -------
        cat : Categorical or None
            Categorical with new categories added or None if ``inplace=True``.

        Raises
        ------
        ValueError
            If the new categories include old categories or do not validate as
            categories

        See Also
        --------
        rename_categories : Rename categories.
        reorder_categories : Reorder categories.
        remove_categories : Remove the specified categories.
        remove_unused_categories : Remove categories which are not used.
        set_categories : Set the categories to the specified ones.

        Examples
        --------
        >>> c = pd.Categorical(['c', 'b', 'c'])
        >>> c
        ['c', 'b', 'c']
        Categories (2, object): ['b', 'c']

        >>> c.add_categories(['d', 'a'])
        ['c', 'b', 'c']
        Categories (4, object): ['b', 'c', 'd', 'a']
        zThe `inplace` parameter in pandas.Categorical.add_categories is deprecated and will be removed in a future version. Removing unused categories will always return a new Categorical object.r   Fr   r   z0new categories must not include old categories: N)r   r   r   r#   r$   r/   r  rl   rc   r]   r^   r   r4   r_   rY   r%   r   r   r   )rp   r  r   already_includedr   r   rf   r|   r|   r}   r    s.   4	
c                   s   |t urtdtt d nd}t|d}t|s|g}t|  t| jj } fdd| jjD }t	t
|rFdd |D }d	d |D }t|d
krStd| t  td | j|| jd|dW  d   S 1 sow   Y  dS )a  
        Remove the specified categories.

        `removals` must be included in the old categories. Values which were in
        the removed categories will be set to NaN

        Parameters
        ----------
        removals : category or list of categories
           The categories which should be removed.
        inplace : bool, default False
           Whether or not to remove the categories inplace or return a copy of
           this categorical with removed categories.

           .. deprecated:: 1.3.0

        Returns
        -------
        cat : Categorical or None
            Categorical with removed categories or None if ``inplace=True``.

        Raises
        ------
        ValueError
            If the removals are not contained in the categories

        See Also
        --------
        rename_categories : Rename categories.
        reorder_categories : Reorder categories.
        add_categories : Add new categories.
        remove_unused_categories : Remove categories which are not used.
        set_categories : Set the categories to the specified ones.

        Examples
        --------
        >>> c = pd.Categorical(['a', 'c', 'b', 'c', 'd'])
        >>> c
        ['a', 'c', 'b', 'c', 'd']
        Categories (4, object): ['a', 'b', 'c', 'd']

        >>> c.remove_categories(['d', 'a'])
        [NaN, 'c', 'b', 'c', NaN]
        Categories (2, object): ['b', 'c']
        zThe `inplace` parameter in pandas.Categorical.remove_categories is deprecated and will be removed in a future version. Removing unused categories will always return a new Categorical object.r   Fr   c                   s   g | ]}| vr|qS r|   r|   )r   cremoval_setr|   r}   r   S  r  z1Categorical.remove_categories.<locals>.<listcomp>c                 S  s   h | ]}t |r|qS r|   r:   r   xr|   r|   r}   	<setcomp>W  r  z0Categorical.remove_categories.<locals>.<setcomp>c                 S  s   g | ]}t |r|qS r|   r!  r"  r|   r|   r}   r   X  r  r   z(removals must all be in old categories: r  )r_   r  r   N)r   r   r   r#   r$   r/   r  rl   rc   rh   r9   r]   r^   r   r   r  r_   )rp   removalsr   not_includedr  r|   r  r}   remove_categories  s0   .	

$zCategorical.remove_categoriesc                C  r   r   r|   r  r|   r|   r}   remove_unused_categoriesc  r  z$Categorical.remove_unused_categoriesc                C  r   r   r|   r  r|   r|   r}   r(  i  r   c                 C  s   |t urtdtt d nd}t|d}|r| n|  }tj|jdd\}}|j	dkr<|d dkr<|d	d
 |d	 }}|j
j|}tj|| jd}t||j}t||| |s\|S d
S )a  
        Remove categories which are not used.

        Parameters
        ----------
        inplace : bool, default False
           Whether or not to drop unused categories inplace or return a copy of
           this categorical with unused categories dropped.

           .. deprecated:: 1.2.0

        Returns
        -------
        cat : Categorical or None
            Categorical with unused categories dropped or None if ``inplace=True``.

        See Also
        --------
        rename_categories : Rename categories.
        reorder_categories : Reorder categories.
        add_categories : Add new categories.
        remove_categories : Remove the specified categories.
        set_categories : Set the categories to the specified ones.

        Examples
        --------
        >>> c = pd.Categorical(['a', 'c', 'b', 'c', 'd'])
        >>> c
        ['a', 'c', 'b', 'c', 'd']
        Categories (4, object): ['a', 'b', 'c', 'd']

        >>> c[2] = 'a'
        >>> c[4] = 'c'
        >>> c
        ['a', 'c', 'a', 'c', 'c']
        Categories (4, object): ['a', 'b', 'c', 'd']

        >>> c.remove_unused_categories()
        ['a', 'c', 'a', 'c', 'c']
        Categories (2, object): ['a', 'c']
        z}The `inplace` parameter in pandas.Categorical.remove_unused_categories is deprecated and will be removed in a future version.r   Fr   T)return_inverser   rZ   r   Nr   )r   r   r   r#   r$   rY   rn   uniquerg   sizerl   rc   taker4   r   r_   r%   r   r   )rp   r   r   r   invr  r   	new_codesr|   r|   r}   r(  m  s*   -
c                 C  sj   | j |}z| j| j || jdW S  ty4   t| jdkr+|	t
|tj}t|| j Y S w )a	  
        Map categories using an input mapping or function.

        Maps the categories to new categories. If the mapping correspondence is
        one-to-one the result is a :class:`~pandas.Categorical` which has the
        same order property as the original, otherwise a :class:`~pandas.Index`
        is returned. NaN values are unaffected.

        If a `dict` or :class:`~pandas.Series` is used any unmapped category is
        mapped to `NaN`. Note that if this happens an :class:`~pandas.Index`
        will be returned.

        Parameters
        ----------
        mapper : function, dict, or Series
            Mapping correspondence.

        Returns
        -------
        pandas.Categorical or pandas.Index
            Mapped categorical.

        See Also
        --------
        CategoricalIndex.map : Apply a mapping correspondence on a
            :class:`~pandas.CategoricalIndex`.
        Index.map : Apply a mapping correspondence on an
            :class:`~pandas.Index`.
        Series.map : Apply a mapping correspondence on a
            :class:`~pandas.Series`.
        Series.apply : Apply more complex functions on a
            :class:`~pandas.Series`.

        Examples
        --------
        >>> cat = pd.Categorical(['a', 'b', 'c'])
        >>> cat
        ['a', 'b', 'c']
        Categories (3, object): ['a', 'b', 'c']
        >>> cat.map(lambda x: x.upper())
        ['A', 'B', 'C']
        Categories (3, object): ['A', 'B', 'C']
        >>> cat.map({'a': 'first', 'b': 'second', 'c': 'third'})
        ['first', 'second', 'third']
        Categories (3, object): ['first', 'second', 'third']

        If the mapping is one-to-one the ordering of the categories is
        preserved:

        >>> cat = pd.Categorical(['a', 'b', 'c'], ordered=True)
        >>> cat
        ['a', 'b', 'c']
        Categories (3, object): ['a' < 'b' < 'c']
        >>> cat.map({'a': 3, 'b': 2, 'c': 1})
        [3, 2, 1]
        Categories (3, int64): [3 < 2 < 1]

        If the mapping is not one-to-one an :class:`~pandas.Index` is returned:

        >>> cat.map({'a': 'first', 'b': 'second', 'c': 'first'})
        Index(['first', 'second', 'first'], dtype='object')

        If a `dict` is used, all unmapped categories are mapped to `NaN` and
        the result is an :class:`~pandas.Index`:

        >>> cat.map({'a': 'first', 'b': 'second'})
        Index(['first', 'second', nan], dtype='object')
        )rc   r_   rZ   )rc   mapr   rg   rY   r_   r^   rn   rh   insertr]   nanr,  )rp   mapperr  r|   r|   r}   r/    s   EzCategorical.mapc                 C  s   t |s	| |S | |S r   )r-   _validate_listlike_validate_scalarrp   r   r|   r|   r}   _validate_setitem_value  s   

z#Categorical._validate_setitem_valuec                 C  s@   t || jjrd}|S || jv r| |}|S td| dd)aK  
        Convert a user-facing fill_value to a representation to use with our
        underlying ndarray, raising TypeError if this is not possible.

        Parameters
        ----------
        fill_value : object

        Returns
        -------
        fill_value : int

        Raises
        ------
        TypeError
        rZ   z5Cannot setitem on a Categorical with a new category (z), set the categories firstN)r8   rc   rl   ri   r`   )rp   ry   r|   r|   r}   r4    s   

zCategorical._validate_scalarNpDtype | Nonec                 C  s8   t | jj| j}|rt|| jjst||S t|S )z
        The numpy array interface.

        Returns
        -------
        numpy.array
            A numpy array of either the specified dtype or,
            if dtype==None (default), the same dtype as
            categorical.categories.dtype.
        )r@   rc   r   rg   r+   rl   rn   r   )rp   rl   ru   r|   r|   r}   	__array__;  s   
zCategorical.__array__ufuncnp.ufuncmethodstrc                 O  s   t j| ||g|R i |}|tur|S d|v r&tj| ||g|R i |S |dkr>tj| ||g|R i |}|tur>|S td| j d|j )NoutreducezObject with dtype z cannot perform the numpy op )	r<   !maybe_dispatch_ufunc_to_dunder_opNotImplementedr;   dispatch_ufunc_with_outdispatch_reduction_ufuncr`   rl   r   )rp   r9  r;  inputskwargsr   r|   r|   r}   __array_ufunc__O  s@   
zCategorical.__array_ufunc__c                   sb   t |tst |S d|vrt|d |d |d< d|v r)d|vr)|d|d< t | dS )z*Necessary for making this object picklabler   _categories_orderedrg   r   N)ra   dictr   __setstate__r4   pop)rp   stater   r|   r}   rI  l  s   
zCategorical.__setstate__c                 C  s   | j j| jjjj S r   )rg   nbytesrl   rc   r   r   r|   r|   r}   rL  z  s   zCategorical.nbytesdeepc                 C  s   | j j| jjj|d S )a  
        Memory usage of my values

        Parameters
        ----------
        deep : bool
            Introspect the data deeply, interrogate
            `object` dtypes for system-level memory consumption

        Returns
        -------
        bytes used

        Notes
        -----
        Memory usage does not include memory consumed by elements that
        are not components of the array if deep=False

        See Also
        --------
        numpy.ndarray.nbytes
        )rM  )rg   rL  rl   rc   memory_usage)rp   rM  r|   r|   r}   rN  ~  s   zCategorical.memory_usagec                 C  s
   | j dkS )aX  
        Detect missing values

        Missing values (-1 in .codes) are detected.

        Returns
        -------
        np.ndarray[bool] of whether my values are null

        See Also
        --------
        isna : Top-level isna.
        isnull : Alias of isna.
        Categorical.notna : Boolean inverse of Categorical.isna.

        rZ   )rg   r   r|   r|   r}   r9     s   
zCategorical.isnac                 C  s
   |    S )a  
        Inverse of isna

        Both missing values (-1 in .codes) and NA as a category are detected as
        null.

        Returns
        -------
        np.ndarray[bool] of whether my values are not null

        See Also
        --------
        notna : Top-level notna.
        notnull : Alias of notna.
        Categorical.isna : Boolean inverse of Categorical.notna.

        )r9   r   r|   r|   r}   r:     s   
zCategorical.notnadropnarO   c                 C  s   ddl m}m} | j| j}}t||dk}}t|| }}	|s&|	r8|	r*|n|| }
tj	|
|p4dd}nt	t
|||}t|d}t|| jj}| |}||||ddS )a{  
        Return a Series containing counts of each category.

        Every category will have an entry, even those with a count of 0.

        Parameters
        ----------
        dropna : bool, default True
            Don't include counts of NaN.

        Returns
        -------
        counts : Series

        See Also
        --------
        Series.value_counts
        r   )CategoricalIndexrO   )	minlengthrZ   r   )indexrl   )r   rP  rO   rg   rc   r]   rn   arangeallbincountr   appendr%   rl   _from_backing_data)rp   rO  rP  rO   coder   ncatrv   ixcleanobscountr|   r|   r}   value_counts  s   
zCategorical.value_countsr   type_t[Categorical]r   r   c                 C  s*   | j g |d}tj||jjd}||S )z
        Analogous to np.empty(shape, dtype=dtype)

        Parameters
        ----------
        shape : tuple[int]
        dtype : CategoricalDtype
        r   )r   rn   zerosr   rl   rW  )r   r   rl   r   backingr|   r|   r}   _empty  s   
zCategorical._emptyc                 C  sV   t | jjr| jj| jtdS t| jr&d| jv r&| jdj| jtj	dS t
| S )a  
        Return the values.

        For internal compatibility with pandas formatting.

        Returns
        -------
        np.ndarray or Index
            A numpy array of the same dtype as categorical.categories.dtype or
            Index if datetime / periods.
        r   rZ   r   )r2   rc   rl   r,  rg   r   r.   r   rn   r1  ro   r   r|   r|   r}   _internal_get_values  s
   
z Categorical._internal_get_valuesc                 C  s   | j std| ddS )zassert that we are orderedz)Categorical is not ordered for operation zG
you can use .as_ordered() to change the Categorical to an ordered one
N)r_   r`   )rp   rz   r|   r|   r}   check_for_ordered  s
   
zCategorical.check_for_ordered	quicksortc                   s   t  jd||d|S )a  
        Return the indices that would sort the Categorical.

        .. versionchanged:: 0.25.0

           Changed to sort missing values at the end.

        Parameters
        ----------
        ascending : bool, default True
            Whether the indices should result in an ascending
            or descending sort.
        kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional
            Sorting algorithm.
        **kwargs:
            passed through to :func:`numpy.argsort`.

        Returns
        -------
        np.ndarray[np.intp]

        See Also
        --------
        numpy.ndarray.argsort

        Notes
        -----
        While an ordering is applied to the category values, arg-sorting
        in this context refers more to organizing and grouping together
        based on matching category values. Thus, this function can be
        called on an unordered Categorical instance unlike the functions
        'Categorical.min' and 'Categorical.max'.

        Examples
        --------
        >>> pd.Categorical(['b', 'b', 'a', 'c']).argsort()
        array([2, 0, 1, 3])

        >>> cat = pd.Categorical(['b', 'b', 'a', 'c'],
        ...                      categories=['c', 'b', 'a'],
        ...                      ordered=True)
        >>> cat.argsort()
        array([3, 0, 1, 2])

        Missing values are placed at the end

        >>> cat = pd.Categorical([2, None, 1])
        >>> cat.argsort()
        array([2, 0, 1])
        )	ascendingkindNr|   )r   argsort)rp   rf  rg  rD  r   r|   r}   rh    s   4zCategorical.argsort)r   rf  na_positionLiteral[False]rf  ri  c                C  r   r   r|   rp   r   rf  ri  r|   r|   r}   r   T  s   zCategorical.sort_valuesrf  ri  c                C  r   r   r|   rk  r|   r|   r}   r   ^  r  lastc                 C  sb   t |d}|dvrtdt| t| ||d}|s%| j| }| |S | j| | jdd< dS )a7	  
        Sort the Categorical by category value returning a new
        Categorical by default.

        While an ordering is applied to the category values, sorting in this
        context refers more to organizing and grouping together based on
        matching category values. Thus, this function can be called on an
        unordered Categorical instance unlike the functions 'Categorical.min'
        and 'Categorical.max'.

        Parameters
        ----------
        inplace : bool, default False
            Do operation in place.
        ascending : bool, default True
            Order ascending. Passing False orders descending. The
            ordering parameter provides the method by which the
            category values are organized.
        na_position : {'first', 'last'} (optional, default='last')
            'first' puts NaNs at the beginning
            'last' puts NaNs at the end

        Returns
        -------
        Categorical or None

        See Also
        --------
        Categorical.sort
        Series.sort_values

        Examples
        --------
        >>> c = pd.Categorical([1, 2, 2, 1, 5])
        >>> c
        [1, 2, 2, 1, 5]
        Categories (3, int64): [1, 2, 5]
        >>> c.sort_values()
        [1, 1, 2, 2, 5]
        Categories (3, int64): [1, 2, 5]
        >>> c.sort_values(ascending=False)
        [5, 2, 2, 1, 1]
        Categories (3, int64): [1, 2, 5]

        Inplace sorting can be done as well:

        >>> c.sort_values(inplace=True)
        >>> c
        [1, 1, 2, 2, 5]
        Categories (3, int64): [1, 2, 5]
        >>>
        >>> c = pd.Categorical([1, 2, 2, 1, 5])

        'sort_values' behaviour with NaNs. Note that 'na_position'
        is independent of the 'ascending' parameter:

        >>> c = pd.Categorical([np.nan, 2, 2, np.nan, 5])
        >>> c
        [NaN, 2, 2, NaN, 5]
        Categories (2, int64): [2, 5]
        >>> c.sort_values()
        [2, 2, 5, NaN, NaN]
        Categories (2, int64): [2, 5]
        >>> c.sort_values(ascending=False)
        [5, 2, 2, NaN, NaN]
        Categories (2, int64): [2, 5]
        >>> c.sort_values(na_position='first')
        [NaN, NaN, 2, 2, 5]
        Categories (2, int64): [2, 5]
        >>> c.sort_values(ascending=False, na_position='first')
        [NaN, NaN, 5, 2, 2]
        Categories (2, int64): [2, 5]
        r   )rm  firstzinvalid na_position: rl  N)r$   r^   reprrJ   rg   rW  )rp   r   rf  ri  
sorted_idxrf   r|   r|   r}   r   d  s   
M

r   averagekeepaxisr;  	na_optionrf  pctrt  ru  rv  c                C  s*   |dkrt |  }tj||||||dS )z*
        See Series.rank.__doc__.
        r   rs  )r   _values_for_rank
algorithmsrank)rp   rt  r;  ru  rf  rv  vffr|   r|   r}   _rank  s   zCategorical._rankc                 C  sx   ddl m} | jr | j}|dk}| r|d}tj||< |S | j	 r,t
| }|S t
| || j j}|S )z
        For correctly ranking ordered categorical data. See GH#15420

        Ordered categorical data should be ranked on the basis of
        codes with -1 translated to NaN.

        Returns
        -------
        numpy.array

        r   rO   rZ   float64)r   rO   r_   rf   rh   r   rn   r1  rc   r   ro   r  ry  r   )rp   rO   r   rv   r|   r|   r}   rw    s   

	

zCategorical._values_for_rankc                 C  s   t dtt d t| S )z
        Return my 'dense' representation

        For internal compatibility with numpy arrays.

        Returns
        -------
        dense : array
        ziCategorical.to_dense is deprecated and will be removed in a future version.  Use np.asarray(cat) instead.r   )r   r   r#   rn   r   r   r|   r|   r}   to_dense  s   

zCategorical.to_densec                 C  r   r   )r   r   r|   r|   r}   rg     s   zCategorical._codesc                 C  s$   t dtt d t| || j d S )Nz|Setting the codes on a Categorical is deprecated and will raise in a future version. Create a new Categorical object insteadr   )r   r   r#   r   r   rl   r5  r|   r|   r}   rg     s   rw   c                 C  s   |dkrt jS | j| S r   )rn   NaNrc   )rp   rw   r|   r|   r}   	_box_func  s   
zCategorical._box_funcc                 C  s   | j |}| jj|}|S r   )rc   r   r   rl   rk   )rp   r   rX  r|   r|   r}   ri     s   zCategorical._unbox_scalar
allow_fillc                 C      t dtt d | j|||dS )Nz?Categorical.take_nd is deprecated, use Categorical.take insteadr   )r  ry   )r   r   r#   r,  )rp   indexerr  ry   r|   r|   r}   r@   $  s   zCategorical.take_ndc                   s4    j dkrt   S  fddtt D S )zJ
        Returns an Iterator over the values of this Categorical.
        r   c                 3  s    | ]} | V  qd S r   r|   )r   nr   r|   r}   r   6  r   z'Categorical.__iter__.<locals>.<genexpr>)r   iterrc  r   ranger]   r   r|   r   r}   __iter__/  s   
zCategorical.__iter__c                 C  s.   t || jjrt|   S t| || jdS )z?
        Returns True if `key` is in this Categorical.
        r   )r8   rc   rl   r   r9   rh   r   rg   )rp   r   r|   r|   r}   __contains__8  s   zCategorical.__contains__boxedc                 C  r   r   r|   )rp   r  r|   r|   r}   
_formatterE  r   zCategorical._formatter
   max_valsfooterc                 C  sv   |d }| d| j ddd}| ||  d j ddd}|dd  d|dd  }|r7| d|   }t|S )	zd
        a short repr displaying only max_vals and an optional (but default
        footer)
           NFlengthr  rZ   z, ..., r   
)	_get_repr_repr_footerr<  )rp   r  r  numheadtailr   r|   r|   r}   
_tidy_reprI  s   zCategorical._tidy_repr	list[str]c                 C  s   t ddkrdnt d}ddlm} t|jdtd}t| j|kr@|d }|| jd| }|| j| d }|dg | }n|| j}d	d
 |D }|S )z9
        return the base repr for the categories
        zdisplay.max_categoriesr   r  formatN)	formatterquotingr  z...c                 S  s   g | ]}|  qS r|   )stripr"  r|   r|   r}   r   o  r   z0Categorical._repr_categories.<locals>.<listcomp>)r   pandas.io.formatsr  r   format_arrayr   r]   rc   )rp   max_categoriesfmtr  r  r  r  category_strsr|   r|   r}   _repr_categoriesX  s    

zCategorical._repr_categoriesc                 C  s  |   }t| jj}dt| j d| d}t \}}tdp |}t r'd}d}d}t|}	| j	r4dnd	\}
}|
 d
 }|D ]5}|dkrc|	|
 t| |krc||dt|d   7 }t|d }	n|so||7 }|	t|7 }	||7 }d}q@|d |dd d S )z@
        Returns a string representation of the footer.
        zCategories (, z): zdisplay.widthr    T)   z < )r  r  r   r   F[z	 < ... < z ... ])r  r<  rc   rl   r]   r   r   rL   in_ipython_frontendr_   rstripreplace)rp   r  rl   	levheaderwidthheight	max_width	levstringstartcur_col_lensep_lenseplinesepvalr|   r|   r}   _repr_categories_infor  s,   
z!Categorical._repr_categories_infoc                 C  s   |   }dt|  d| S )NzLength: r  )r  r]   )rp   infor|   r|   r}   r    s   zCategorical._repr_footerr  r  c                 C  s.   ddl m} |j| |||d}| }t|S )Nr   r  )r  na_repr  )r  r  CategoricalFormatter	to_stringr<  )rp   r  r  r  r  r  r   r|   r|   r}   r    s   zCategorical._get_reprc                 C  sj   d}t | j|kr| |}|S t | jdkr#| jt | |kd}|S | jddddd}d	| }|S )
z(
        String representation.
        r  r   )r  FTr  r  r  z[], )r]   rg   r  r  r  )rp   _maxlenr   rs   r|   r|   r}   __repr__  s   

zCategorical.__repr__c                 C  s   t |dd}t|trt| j|jstd| |}|jS ddlm	} |j
|dd| j}t|r=t| s=td| j|}|j| jjdd	S )
NT)extract_numpyzCCannot set a Categorical with another, without identical categoriesr   rN   F)tupleize_colszMCannot setitem on a Categorical with a new category, set the categories firstrX   )rG   ra   rQ   r+   rl   r`   _encode_with_my_categoriesrg   r   rN   _with_infer
differencerc   r]   r9   rT  get_indexerr   r   )rp   r   rN   to_addrf   r|   r|   r}   r3    s$   

zCategorical._validate_listlike$dict[Hashable, npt.NDArray[np.intp]]c                   sX   | j }tt| j|j\ }t| } fddt||dd D }t	t||S )a  
        Compute the inverse of a categorical, returning
        a dict of categories -> indexers.

        *This is an internal function*

        Returns
        -------
        Dict[Hashable, np.ndarray[np.intp]]
            dict of categories -> indexers

        Examples
        --------
        >>> c = pd.Categorical(list('aabca'))
        >>> c
        ['a', 'a', 'b', 'c', 'a']
        Categories (3, object): ['a', 'b', 'c']
        >>> c.categories
        Index(['a', 'b', 'c'], dtype='object')
        >>> c.codes
        array([0, 0, 1, 2, 0], dtype=int8)
        >>> c._reverse_indexer()
        {'a': array([0, 1, 4]), 'b': array([2]), 'c': array([3])}

        c                 3  s     | ]\}} || V  qd S r   r|   )r   r  endrr|   r}   r     s    z/Categorical._reverse_indexer.<locals>.<genexpr>r   N)
rc   libalgosgroupsort_indexerr'   rf   r+  r&   cumsumziprH  )rp   rc   counts_resultr|   r  r}   _reverse_indexer  s    zCategorical._reverse_indexernumeric_onlyskipna)old_arg_namenew_arg_name)r  c                K     t |dd t d| | d t| js| jjS | jdk}|	 s7|r4|
 r4| j|  }ntjS | j }| d|S )ao  
        The minimum value of the object.

        Only ordered `Categoricals` have a minimum!

        .. versionchanged:: 1.0.0

           Returns an NA value on empty arrays

        Raises
        ------
        TypeError
            If the `Categorical` is not `ordered`.

        Returns
        -------
        min : the minimum of this `Categorical`
        rt  r   r|   r   rZ   N)nvvalidate_minmax_axisr  validate_minrd  r]   rg   rl   na_valuerT  rh   r   rn   r1  _wrap_reduction_resultrp   r  rD  goodpointerr|   r|   r}   r        



zCategorical.minc                K  r  )ao  
        The maximum value of the object.

        Only ordered `Categoricals` have a maximum!

        .. versionchanged:: 1.0.0

           Returns an NA value on empty arrays

        Raises
        ------
        TypeError
            If the `Categorical` is not `ordered`.

        Returns
        -------
        max : the maximum of this `Categorical`
        rt  r   r|   r   rZ   N)r  r  r  validate_maxrd  r]   rg   rl   r  rT  rh   r   rn   r1  r  r  r|   r|   r}   r   	  r  zCategorical.maxc                 C  s   t dtt d | j|dS )a8  
        Returns the mode(s) of the Categorical.

        Always returns `Categorical` even if only one value.

        Parameters
        ----------
        dropna : bool, default True
            Don't consider counts of NaN/NaT.

        Returns
        -------
        modes : `Categorical` (sorted)
        z`Categorical.mode is deprecated and will be removed in a future version. Use Series.mode instead.r   rO  )r   r   r#   _mode)rp   rO  r|   r|   r}   mode=	  s   zCategorical.modec                 C  sN   | j }d }|r|  }tj||d}ttj|}|j|jks J | |}|S )N)rv   )	rg   r9   rx  r  r   rn   r   rl   rW  )rp   rO  rf   rv   	res_codesresr|   r|   r}   r  T	  s   
zCategorical._modec                 C  s   t | j}| |S )a  
        Return the ``Categorical`` which ``categories`` and ``codes`` are
        unique.

        .. versionchanged:: 1.3.0

            Previously, unused categories were dropped from the new categories.

        Returns
        -------
        Categorical

        See Also
        --------
        pandas.unique
        CategoricalIndex.unique
        Series.unique : Return unique values of Series object.

        Examples
        --------
        >>> pd.Categorical(list("baabc")).unique()
        ['b', 'a', 'c']
        Categories (3, object): ['a', 'b', 'c']
        >>> pd.Categorical(list("baab"), categories=list("abc"), ordered=True).unique()
        ['b', 'a']
        Categories (3, object): ['a' < 'b' < 'c']
        )rA   rf   rW  )rp   unique_codesr|   r|   r}   r*  c	  s   

zCategorical.unique
res_valuesc                 C  s   |j | jj ks	J |S r   )rl   r   )rp   r  r|   r|   r}   _cast_quantile_result	  s   z!Categorical._cast_quantile_resultrq   r   c                 C  s6   t |tsdS | |r| |}t| j|jS dS )z
        Returns True if categorical arrays are equal.

        Parameters
        ----------
        other : `Categorical`

        Returns
        -------
        bool
        F)ra   rQ   rb   r  rn   array_equalrg   rp   rq   r|   r|   r}   rd   	  s   


zCategorical.equalstype[CategoricalT]	to_concatSequence[CategoricalT]rP   c                   s   ddl m} |d }||jkrtd| d|j |dkrTtdd |D s)tg }|D ] | fdd	t jd D  q-| j|dd
}|j	t
|ddd}|S ||}|S )Nr   )union_categoricalszaxis z) is out of bounds for array of dimension r   c                 s  s    | ]}|j d kV  qdS )r  N)r   r"  r|   r|   r}   r   	  s    z0Categorical._concat_same_type.<locals>.<genexpr>c                   s   g | ]
} d d |f qS r   r|   )r   rw   objr|   r}   r   	  s    z1Categorical._concat_same_type.<locals>.<listcomp>rt  rZ   F)order)pandas.core.dtypes.concatr  r   r^   rT  extendr  r   _concat_same_typereshaper]   )r   r  rt  r  rn  tc_flatres_flatr   r|   r  r}   r  	  s"   
$zCategorical._concat_same_typec                 C  s    t |j|j| jdd}| |S )z
        Re-encode another categorical using this Categorical's categories.

        Notes
        -----
        This assumes we have already checked
        self._categories_match_up_to_permutation(other).
        FrX   )re   rf   rc   rW  )rp   rq   rf   r|   r|   r}   r  	  s   
z&Categorical._encode_with_my_categoriesc                 C  s   t | jt |jkS )z
        Returns True if categoricals are the same dtype
          same categories, and same ordered

        Parameters
        ----------
        other : Categorical

        Returns
        -------
        bool
        )r   rl   r  r|   r|   r}   rb   	  s   z/Categorical._categories_match_up_to_permutationc              	   C  s6   t dtt d z| |W S  ttfy   Y dS w )NzPCategorical.is_dtype_equal is deprecated and will be removed in a future versionr   F)r   r   r#   rb   AttributeErrorr`   r  r|   r|   r}   r+   	  s   zCategorical.is_dtype_equalrM   c                 C  sZ   | j dd}||  }ddlm} ddlm} |||gdd}|dd	g|_d
|j_|S )z
        Describes this Categorical

        Returns
        -------
        description: `DataFrame`
            A dataframe with frequency and counts by category.
        Fr  r   r  )concatr   r  r  freqsrc   )	r^  sumr   rN   pandas.core.reshape.concatr  columnsrR  name)rp   r  r  rN   r  r   r|   r|   r}   describe	  s   	zCategorical.describenpt.NDArray[np.bool_]c                 C  sf   t |st|j}td| dt|dd}tt|}| j	|}|||dkB  }t
| j|S )a  
        Check whether `values` are contained in Categorical.

        Return a boolean NumPy Array showing whether each element in
        the Categorical matches an element in the passed sequence of
        `values` exactly.

        Parameters
        ----------
        values : set or list-like
            The sequence of values to test. Passing in a single string will
            raise a ``TypeError``. Instead, turn a single string into a
            list of one element.

        Returns
        -------
        np.ndarray[bool]

        Raises
        ------
        TypeError
          * If `values` is not a set or list-like

        See Also
        --------
        pandas.Series.isin : Equivalent method on Series.

        Examples
        --------
        >>> s = pd.Categorical(['lama', 'cow', 'lama', 'beetle', 'lama',
        ...                'hippo'])
        >>> s.isin(['cow', 'lama'])
        array([ True,  True,  True, False,  True, False])

        Passing a single string as ``s.isin('lama')`` will raise an error. Use
        a list of one element instead:

        >>> s.isin(['lama'])
        array([ True, False,  True, False,  True, False])
        zIonly list-like objects are allowed to be passed to isin(), you passed a [r  Nr   )r/   rk   r   r`   rH   rn   r   r9   rc   r  rx  r   rf   )rp   r   values_typer   code_valuesr|   r|   r}   r   	  s   )
zCategorical.isinc                C  r   r   r|   rp   
to_replacer   r   r|   r|   r}   r  0
  r  zCategorical.replacec                C  r   r   r|   r  r|   r|   r}   r  6
  r   c                 C  r  )aM  
        Replaces all instances of one value with another

        Parameters
        ----------
        to_replace: object
            The value to be replaced

        value: object
            The value to replace it with

        inplace: bool
            Whether the operation is done in-place

        Returns
        -------
        None if inplace is True, otherwise the new Categorical after replacement


        Examples
        --------
        >>> s = pd.Categorical([1, 2, 1, 3])
        >>> s.replace(1, 3)
        [3, 2, 3, 3]
        Categories (2, int64): [2, 3]
        zoCategorical.replace is deprecated and will be removed in a future version. Use Series.replace directly instead.r   )r  r   r   )r   r   r#   _replacer  r|   r|   r}   r  :
  s   c             	     sp  t |d}|r	| n|  }t|r fdd|D }n| i}| D ]\}}||kr,q#||jv rt|rTt  td |j|dd W d    n1 sNw   Y  q#|j	 }|
|}	||jv r|
|}
|
|j|j|	k< t  td |j|dd W d    n1 sw   Y  q#|||	< t  td |j|dd W d    n1 sw   Y  q#|s|S d S )Nr   c                   s   i | ]}| qS r|   r|   )r   replace_valuer   r|   r}   
<dictcomp>f
  s    z(Categorical._replace.<locals>.<dictcomp>r  Tr   )r$   rY   r/   itemsrc   r9   r   r   r'  r   rR  rg   r  )rp   r  r   r   r   replace_dictr  	new_valuerc   rR  value_indexr|   r	  r}   r  _
  sD   





zCategorical._replaceconvertc           	      C  s<   ddl m} | j}| j}|| |||}t|||dS )Nr   PandasArrayr   )pandas.core.arraysr  rc   rf   r   _str_mapr@   )	rp   fr  rl   r  r  rc   rf   r   r|   r|   r}   r  
  s
   zCategorical._str_map|c                 C  s    ddl m} || t|S )Nr   r  )r  r  r   r<  _str_get_dummies)rp   r  r  r|   r|   r}   r  
  s   zCategorical._str_get_dummies)NNNFT)rl   r   r   r   rY   r   r   r   )r   r4   )r   r   )r   r   )rl   r   ).)rl   r   rY   r   r   r   )rl   r5   rY   r   r   rD   )rl   r   rY   r   r   r   Tr   )NNN)rl   r   r   rQ   )r   rN   r   r   )r   r   )r   r   )F)rl   r4   r   rQ   )r   r   r   rQ   )r   r  r   r   )r   r   r   r  )r   r  r   r  )r   r  r   rQ   )rl   r7  r   r   )r9  r:  r;  r<  )rM  r   r   r   )rO  r   r   rO   )r   r_  r   r   rl   r4   r   rQ   )Tre  )r   rj  rf  r   ri  r<  r   rQ   )r   r  rf  r   ri  r<  r   r   )FTrm  )r   r   rf  r   ri  r<  r   r  )
rt  r   r;  r<  ru  r<  rf  r   rv  r   )r   r   )rw   r   )FN)r  r   r   rQ   r   r   )r  r   )r  T)r  r   r  r   r   r<  )r   r  )r   r<  )Tr  T)r  r   r  r   r   r<  )r   r  )rO  r   r   rQ   )r  r   r   r   )rq   r   r   r   )r   )r   r  r  r  rt  r   r   rP   )rq   rQ   r   rQ   )rq   rQ   r   r   )r   rM   )r   r  )r   rj  r   rQ   )r   r   )r  r   )r  )pr   
__module____qualname____doc____array_priority__rF   _hidden_attrs	frozenset_typ__annotations__r   propertyrl   r   r   classmethodr   r   r   r   r   r   rc   setterr_   rf   r   r   r  r"   r   r	  r  r  r  r  r  r'  r(  r/  r   r   eqr[   r   r\   ltrT   gtrU   lerV   gerW   r6  _validate_searchsorted_valuer4  rC   r8  rE  rI  rL  rN  r9   isnullr:   notnullr^  rb  rc  rd  rh  r   r{  rw  r~  rg   r  ri   r@   r  r  r  r  r  r  r  r  r  r3  r  r!   r   r   r  r  r*  r  rd   r  r  rb   r+   r  r   r  r  rn   r1  r  r  __classcell__r|   r|   r   r}   rQ      s  
 ik=DE
%%
Y]=OPJ
Q




+	5	[	
		!
%
$$5$,rc   r_   r"  )delegate	accessorstyp)r  r  r  r'  r(  r  r	  r  r;  c                   @  sL   e Zd ZdZdddZedd Zdd	 Zd
d Ze	dddZ
dd ZdS )CategoricalAccessora   
    Accessor object for categorical properties of the Series values.

    Be aware that assigning to `categories` is a inplace operation, while all
    methods return new categorical data per default (but can be called with
    `inplace=True`).

    Parameters
    ----------
    data : Series or CategoricalIndex

    Examples
    --------
    >>> s = pd.Series(list("abbccc")).astype("category")
    >>> s
    0    a
    1    b
    2    b
    3    c
    4    c
    5    c
    dtype: category
    Categories (3, object): ['a', 'b', 'c']

    >>> s.cat.categories
    Index(['a', 'b', 'c'], dtype='object')

    >>> s.cat.rename_categories(list("cba"))
    0    c
    1    b
    2    b
    3    a
    4    a
    5    a
    dtype: category
    Categories (3, object): ['c', 'b', 'a']

    >>> s.cat.reorder_categories(list("cba"))
    0    a
    1    b
    2    b
    3    c
    4    c
    5    c
    dtype: category
    Categories (3, object): ['c', 'b', 'a']

    >>> s.cat.add_categories(["d", "e"])
    0    a
    1    b
    2    b
    3    c
    4    c
    5    c
    dtype: category
    Categories (5, object): ['a', 'b', 'c', 'd', 'e']

    >>> s.cat.remove_categories(["a", "c"])
    0    NaN
    1      b
    2      b
    3    NaN
    4    NaN
    5    NaN
    dtype: category
    Categories (1, object): ['b']

    >>> s1 = s.cat.add_categories(["d", "e"])
    >>> s1.cat.remove_unused_categories()
    0    a
    1    b
    2    b
    3    c
    4    c
    5    c
    dtype: category
    Categories (3, object): ['a', 'b', 'c']

    >>> s.cat.set_categories(list("abcde"))
    0    a
    1    b
    2    b
    3    c
    4    c
    5    c
    dtype: category
    Categories (5, object): ['a', 'b', 'c', 'd', 'e']

    >>> s.cat.as_ordered()
    0    a
    1    b
    2    b
    3    c
    4    c
    5    c
    dtype: category
    Categories (3, object): ['a' < 'b' < 'c']

    >>> s.cat.as_unordered()
    0    a
    1    b
    2    b
    3    c
    4    c
    5    c
    dtype: category
    Categories (3, object): ['a', 'b', 'c']
    r   r   c                 C  s.   |  | |j| _|j| _|j| _|   d S r   )	_validater   _parentrR  _indexr   _name_freeze)rp   datar|   r|   r}   r      s
   
zCategoricalAccessor.__init__c                 C  s   t | js	tdd S )Nz2Can only use .cat accessor with a 'category' dtype)r(   rl   r  )r7  r|   r|   r}   r2  '  s   
zCategoricalAccessor._validatec                 C  s   t | j|S r   )rm   r3  )rp   r   r|   r|   r}   _delegate_property_get,  s   z*CategoricalAccessor._delegate_property_getc                 C  s   t | j||S r   )setattrr3  )rp   r   
new_valuesr|   r|   r}   _delegate_property_set/  s   z*CategoricalAccessor._delegate_property_setrO   c                 C  s   ddl m} || jj| jdS )z>
        Return Series of codes as well as the index.
        r   r|  )rR  )r   rO   r3  rf   r4  )rp   rO   r|   r|   r}   rf   2  s   zCategoricalAccessor.codesc                 O  sD   ddl m} t| j|}||i |}|d ur ||| j| jdS d S )Nr   r|  )rR  r   )r   rO   rm   r3  r4  r5  )rp   r   argsrD  rO   r;  r  r|   r|   r}   _delegate_method;  s   z$CategoricalAccessor._delegate_methodNr  )r   rO   )r   r  r  r  r   staticmethodr2  r8  r;  r"  rf   r=  r|   r|   r|   r}   r1  
  s    
m
r1  rN   r   c                 C  s<   | j dkr|  }t||}|| jS || }t||S )z
    utility routine to turn values into codes given the specified categories

    If `values` is known to be a Categorical, use recode_for_categories instead.
    r   )r   ravelr   r  r   get_indexer_forr%   )r   rc   flatrf   r|   r|   r}   r   G  s   



r   Trf   rY   c                 C  sX   t |dkr|r|  S | S ||r|r|  S | S t|||}t|| dd}|S )a#  
    Convert a set of codes for to a new set of categories

    Parameters
    ----------
    codes : np.ndarray
    old_categories, new_categories : Index
    copy: bool, default True
        Whether to copy if the codes are unchanged.

    Returns
    -------
    new_codes : np.ndarray[np.int64]

    Examples
    --------
    >>> old_cat = pd.Index(['b', 'a', 'c'])
    >>> new_cat = pd.Index(['a', 'b'])
    >>> codes = np.array([0, 1, 1, 2])
    >>> recode_for_categories(codes, old_cat, new_cat)
    array([ 1,  0,  0, -1], dtype=int8)
    r   rZ   r   )r]   rY   rd   r%   r  r@   )rf   old_categoriesr  rY   r  r.  r|   r|   r}   re   V  s   

re   tuple[np.ndarray, Index]c                 C  s   ddl m} t| stdt| r5t| } tjt| j	| j
jd}tj|| jd}||}| j
}||fS t| dd}|j	}|j
}||fS )az  
    Factorize an input `values` into `categories` and `codes`. Preserves
    categorical dtype in `categories`.

    Parameters
    ----------
    values : list-like

    Returns
    -------
    codes : ndarray
    categories : Index
        If `values` has a categorical dtype, then `categories` is
        a CategoricalIndex keeping the categories and order of `values`.
    r   )rP  zInput must be list-liker   Fr   )r   rP  r/   r`   r(   rG   rn   rS  r]   rc   rf   rl   rQ   r   )r   rP  	cat_codesr   rc   rf   r|   r|   r}   factorize_from_iterable  s   rE  $tuple[list[np.ndarray], list[Index]]c                 C  s:   t | dkr
g g fS tdd | D  \}}t|t|fS )a$  
    A higher-level wrapper over `factorize_from_iterable`.

    Parameters
    ----------
    iterables : list-like of list-likes

    Returns
    -------
    codes : list of ndarrays
    categories : list of Indexes

    Notes
    -----
    See `factorize_from_iterable` for more info.
    r   c                 s  s    | ]}t |V  qd S r   )rE  )r   itr|   r|   r}   r     r   z+factorize_from_iterables.<locals>.<genexpr>)r]   r  r   )	iterablesrf   rc   r|   r|   r}   factorize_from_iterables  s   rI  r  )rc   rN   r   r   r  )rf   r   rY   r   r   r   )r   rC  )r   rF  )
__future__r   csvr   	functoolsr   r   shutilr   typingr   r   r   r	   r
   r   r   r   warningsr   r   r   numpyrn   pandas._configr   pandas._libsr   r   r  r   pandas._libs.arraysr   pandas._libs.libr   r   pandas._typingr   r   r   r   r   r   r   r   pandas.compat.numpyr    r  pandas.util._decoratorsr!   r"   pandas.util._exceptionsr#   pandas.util._validatorsr$   pandas.core.dtypes.castr%   pandas.core.dtypes.commonr&   r'   r(   r)   r*   r+   r,   r-   r.   r/   r0   r1   r2   r3   pandas.core.dtypes.dtypesr4   r5   pandas.core.dtypes.genericr6   r7   pandas.core.dtypes.missingr8   r9   r:   pandas.corer;   r<   pandas.core.accessorr=   r>   pandas.core.algorithmscorerx  r?   r@   rA   pandas.core.arrays._mixinsrB   rC   pandas.core.baserD   rE   rF   pandas.core.commoncommonr   pandas.core.constructionrG   rH   pandas.core.ops.commonrI   pandas.core.sortingrJ    pandas.core.strings.object_arrayrK   r  rL   r   rM   rN   rO   rP   r   r   rQ   r1  r   re   rE  rI  r|   r|   r|   r}   <module>   s    (
(
@
I3                   5

 

+)