a
    DBìjŒ×  ã                   @  s  d Z ddlmZ ddlZddlZddlmZ ddlmZm	Z	m
Z
 ddlZddlZddlmZmZmZmZ ddlmZmZmZmZmZmZ ddl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*m+Z+m,Z,m-Z-m.Z.m/Z/m0Z0m1Z1 ddl2m3Z3 ddl4m5Z5m6Z6m7Z7m8Z8 ddl9m:Z:m;Z;m<Z<m=Z=m>Z>m?Z? ddl@mAZAmBZB ddlCmDZD ddlEmFZGmHZHmIZI ddlJmKZK e�r²ddlmLZLmMZMmNZN ddlOmPZPmQZQmRZR ddlSmTZTmUZU dddœdd„ZVdddddœdd„ZWd dd!œd"d#„ZXejYejZej[ej\ej]ej^ej_ej`ejaejbejcejdejeejfd$œZgdd%œd&d'„Zhdd dœd(d)„Zid*d+„ Zjdd,dœd-d.„Zkd†d/d0œd1d2„ZlejZmd3Znd4d4d5d6œd7d8„Zod‡dd:d;d<d/d=d>œd?d@„ZpeedAƒedBƒedCƒdD�dˆd:d:d;dFdGœdHdI„ƒZqd‰d:d:d:d:dJdKœdLdM„ZrdŠd:d:d:d:dJdKœdNdO„Zsd‹dd:d/dPdQœdRdS„ZtdŒddUd/d5dVœdWdX„Zud�dd:d/ddQœdYdZ„ZvdŽdd]d d d:d:d^d_œd`da„Zwd�dbd]d:dcœddde„Zxd�ddgdhdidjdkœdldm„Zyh dn£Zzd‘d,d]doœdpdq„Z{d’drdsd:d:d:dtduœdvdw„Z|ddxœdydz„Z}dddœd{d|„Z~d}d}d}d~œdd€„Zd“dd�d:d‚dƒœd„d…„Z€dS )”zl
Generic data algorithms. This module is experimental at the moment and not
intended for public consumption
é    )ÚannotationsN)Údedent)ÚTYPE_CHECKINGÚLiteralÚcast)ÚalgosÚ	hashtableÚiNaTÚlib)ÚAnyArrayLikeÚ	ArrayLikeÚAxisIntÚDtypeObjÚTakeIndexerÚnpt)Údoc)Úfind_stack_level)Ú'construct_1d_object_array_from_listlikeÚnp_find_common_type)Úensure_float64Úensure_objectÚensure_platform_intÚis_array_likeÚis_bool_dtypeÚis_complex_dtypeÚis_dict_likeÚis_extension_array_dtypeÚis_float_dtypeÚ
is_integerÚis_integer_dtypeÚis_list_likeÚis_object_dtypeÚis_signed_integer_dtypeÚneeds_i8_conversion)Úconcat_compat)ÚBaseMaskedDtypeÚCategoricalDtypeÚExtensionDtypeÚNumpyEADtype)ÚABCDatetimeArrayÚABCExtensionArrayÚABCIndexÚABCMultiIndexÚ	ABCSeriesÚABCTimedeltaArray)ÚisnaÚna_value_for_dtype)Útake_nd)ÚarrayÚensure_wrapped_if_datetimelikeÚextract_array)Úvalidate_indices)ÚListLikeÚNumpySorterÚNumpyValueArrayLike)ÚCategoricalÚIndexÚSeries)ÚBaseMaskedArrayÚExtensionArrayr   z
np.ndarray)ÚvaluesÚreturnc                 C  sH  t | tƒst| dd�} t| jƒr.tt | ¡ƒS t | jtƒr^t	d| ƒ} | j
sTt| jƒS t | ¡S t | jtƒrzt	d| ƒ} | jS t| jƒr¶t | tjƒr t | ¡ d¡S t | ¡jddd�S n|t| jƒrÊt | ¡S t| jƒ� rô| jjdv rêt| ƒS t | ¡S t| jƒ�rt	tj| ƒS t| jƒ�r2|  d	¡}t	tj|ƒ}|S tj| td
�} t| ƒS )a„  
    routine to ensure that our data is of the correct
    input dtype for lower-level routines

    This will coerce:
    - ints -> int64
    - uint -> uint64
    - bool -> uint8
    - datetimelike -> i8
    - datetime64tz -> i8 (in local tz)
    - categorical -> codes

    Parameters
    ----------
    values : np.ndarray or ExtensionArray

    Returns
    -------
    np.ndarray
    T©Úextract_numpyr<   r9   Úuint8F©Úcopy)é   é   é   Úi8©Údtype)Ú
isinstancer,   r4   r!   rJ   r   ÚnpÚasarrayr%   r   Z_hasnaÚ_ensure_dataÚ_datar&   Úcodesr   ÚndarrayÚviewÚastyper   r   Úitemsizer   r   r#   Úobject)r>   Znpvalues© rV   úU/mnt/bigstor/www/usecases/.venv/lib/python3.9/site-packages/pandas/core/algorithms.pyrN   j   s<    










rN   r   r   )r>   rJ   Úoriginalr?   c                 C  sN   t | tƒr| j|kr| S t |tjƒs<| ¡ }|j| |d�} n| j|dd�} | S )zç
    reverse of _ensure_data

    Parameters
    ----------
    values : np.ndarray or ExtensionArray
    dtype : np.dtype or ExtensionDtype
    original : AnyArrayLike

    Returns
    -------
    ExtensionArray or np.ndarray
    rI   FrC   )rK   r*   rJ   rL   Zconstruct_array_typeZ_from_sequencerS   )r>   rJ   rX   ÚclsrV   rV   rW   Ú_reconstruct_data¸   s    rZ   Ústr)Ú	func_namer?   c                 C  st   t | ttttjfƒsp|dkr4tj|› d�tt	ƒ d� t
j| dd�}|dv rft | tƒr\t| ƒ} t| ƒ} n
t | ¡} | S )z5
    ensure that we are arraylike if not already
    úisin-targetsz with argument that is not not a Series, Index, ExtensionArray, or np.ndarray is deprecated and will raise in a future version.©Ú
stacklevelF©Zskipna)ÚmixedÚstringúmixed-integer)rK   r+   r-   r*   rL   rQ   ÚwarningsÚwarnÚFutureWarningr   r
   Úinfer_dtypeÚtupleÚlistr   rM   )r>   r\   ÚinferredrV   rV   rW   Ú_ensure_arraylikeÙ   s    û


rk   )Z
complex128Z	complex64Úfloat64Úfloat32Zuint64Zuint32Zuint16rB   Úint64Úint32Úint16Úint8rb   rU   ©r>   c                 C  s    t | ƒ} t| ƒ}t| }|| fS )z‰
    Parameters
    ----------
    values : np.ndarray

    Returns
    -------
    htable : HashTable subclass
    values : ndarray
    )rN   Ú_check_object_for_stringsÚ_hashtables)r>   Úndtyper   rV   rV   rW   Ú_get_hashtable_algo  s    rv   c                 C  s&   | j j}|dkr"tj| dd�r"d}|S )z 
    Check if we can use string hashtable instead of object hashtable.

    Parameters
    ----------
    values : ndarray

    Returns
    -------
    str
    rU   Fr`   rb   )rJ   Únamer
   Zis_string_array)r>   ru   rV   rV   rW   rs     s
    rs   c                 C  s   t | ƒS )a3
  
    Return unique values based on a hash table.

    Uniques are returned in order of appearance. This does NOT sort.

    Significantly faster than numpy.unique for long enough sequences.
    Includes NA values.

    Parameters
    ----------
    values : 1d array-like

    Returns
    -------
    numpy.ndarray or ExtensionArray

        The return can be:

        * Index : when the input is an Index
        * Categorical : when the input is a Categorical dtype
        * ndarray : when the input is a Series/ndarray

        Return numpy.ndarray or ExtensionArray.

    See Also
    --------
    Index.unique : Return unique values from an Index.
    Series.unique : Return unique values of Series object.

    Examples
    --------
    >>> pd.unique(pd.Series([2, 1, 3, 3]))
    array([2, 1, 3])

    >>> pd.unique(pd.Series([2] + [1] * 5))
    array([2, 1])

    >>> pd.unique(pd.Series([pd.Timestamp("20160101"), pd.Timestamp("20160101")]))
    array(['2016-01-01T00:00:00.000000000'], dtype='datetime64[ns]')

    >>> pd.unique(
    ...     pd.Series(
    ...         [
    ...             pd.Timestamp("20160101", tz="US/Eastern"),
    ...             pd.Timestamp("20160101", tz="US/Eastern"),
    ...         ]
    ...     )
    ... )
    <DatetimeArray>
    ['2016-01-01 00:00:00-05:00']
    Length: 1, dtype: datetime64[ns, US/Eastern]

    >>> pd.unique(
    ...     pd.Index(
    ...         [
    ...             pd.Timestamp("20160101", tz="US/Eastern"),
    ...             pd.Timestamp("20160101", tz="US/Eastern"),
    ...         ]
    ...     )
    ... )
    DatetimeIndex(['2016-01-01 00:00:00-05:00'],
            dtype='datetime64[ns, US/Eastern]',
            freq=None)

    >>> pd.unique(np.array(list("baabc"), dtype="O"))
    array(['b', 'a', 'c'], dtype=object)

    An unordered Categorical will return categories in the
    order of appearance.

    >>> pd.unique(pd.Series(pd.Categorical(list("baabc"))))
    ['b', 'a', 'c']
    Categories (3, object): ['a', 'b', 'c']

    >>> pd.unique(pd.Series(pd.Categorical(list("baabc"), categories=list("abc"))))
    ['b', 'a', 'c']
    Categories (3, object): ['a', 'b', 'c']

    An ordered Categorical preserves the category ordering.

    >>> pd.unique(
    ...     pd.Series(
    ...         pd.Categorical(list("baabc"), categories=list("abc"), ordered=True)
    ...     )
    ... )
    ['b', 'a', 'c']
    Categories (3, object): ['a' < 'b' < 'c']

    An array of tuples

    >>> pd.unique(pd.Series([("a", "b"), ("b", "a"), ("a", "c"), ("b", "a")]).values)
    array([('a', 'b'), ('b', 'a'), ('a', 'c')], dtype=object)
    )Úunique_with_maskrr   rV   rV   rW   Úunique3  s    ^ry   Úintc                 C  s8   t | ƒdkrdS t| ƒ} t |  ¡  d¡¡dk ¡ }|S )aH  
    Return the number of unique values for integer array-likes.

    Significantly faster than pandas.unique for long enough sequences.
    No checks are done to ensure input is integral.

    Parameters
    ----------
    values : 1d array-like

    Returns
    -------
    int : The number of unique values in ``values``
    r   Zintp)ÚlenrN   rL   ZbincountÚravelrS   Úsum)r>   ÚresultrV   rV   rW   Únunique_ints”  s
    r   znpt.NDArray[np.bool_] | None©Úmaskc                 C  sž   t | dd�} t| jtƒr |  ¡ S | }t| ƒ\}} |t| ƒƒ}|du r`| | ¡}t||j|ƒ}|S |j| |d�\}}t||j|ƒ}|dusŒJ ‚|| d¡fS dS )z?See algorithms.unique for docs. Takes a mask for masked arrays.ry   ©r\   Nr€   Úbool)	rk   rK   rJ   r'   ry   rv   r{   rZ   rS   )r>   r�   rX   r   ÚtableÚuniquesrV   rV   rW   rx   «  s    
rx   i@B r6   znpt.NDArray[np.bool_])Úcompsr>   r?   c                 C  sä  t | ƒstdt| ƒj› d�ƒ‚t |ƒs<tdt|ƒj› d�ƒ‚t|ttttj	fƒsŽt
|ƒ}t|dd�}t|ƒdkr²|jjdv r²t| ƒs²t|ƒ}n$t|tƒr¤t |¡}nt|ddd�}t| d	d�}t|dd
�}t|tj	ƒsà| |¡S t|jƒrøt|ƒ |¡S t|jƒ�r t|jƒ�s tj|jtd�S t|jƒ�r<t|| t¡ƒS t|jtƒ�r`tt |¡t |¡ƒS t|ƒtk�rªt|ƒdk�rª|jtk�rªt |ƒ !¡ �r dd„ }ndd„ }n0t"|j|jƒ}|j|dd�}|j|dd�}t#j$}|||ƒS )zÀ
    Compute the isin boolean array.

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

    Returns
    -------
    ndarray[bool]
        Same length as `comps`.
    zIonly list-like objects are allowed to be passed to isin(), you passed a `ú`r]   r‚   r   ZiufcbT)rA   Zextract_rangeÚisinr@   rI   é   c                 S  s   t  t  | |¡ ¡ t  | ¡¡S ©N)rL   Ú
logical_orrˆ   r|   Úisnan)ÚcÚvrV   rV   rW   Úf  s    zisin.<locals>.fc                 S  s   t  | |¡ ¡ S rŠ   )rL   rˆ   r|   )ÚaÚbrV   rV   rW   Ú<lambda>  ó    zisin.<locals>.<lambda>FrC   )%r    Ú	TypeErrorÚtypeÚ__name__rK   r+   r-   r*   rL   rQ   ri   rk   r{   rJ   Úkindr"   r   r,   r2   r4   rˆ   r#   Úpd_arrayr!   ZzerosÚshaperƒ   rS   rU   r'   rM   Ú_MINIMUM_COMP_ARR_LENr/   Úanyr   ÚhtableZismember)r†   r>   Zorig_valuesZcomps_arrayr�   ÚcommonrV   rV   rW   rˆ   É  sf    ÿÿÿÿ
ÿ
þý




ÿ
þý

rˆ   Trƒ   z
int | NonerU   z'tuple[npt.NDArray[np.intp], np.ndarray])r>   Úuse_na_sentinelÚ	size_hintÚna_valuer�   r?   c           
      C  sf   | }| j jdv rt}t| ƒ\}} ||p,t| ƒƒ}|j| d|||d�\}}	t||j |ƒ}t|	ƒ}	|	|fS )a(  
    Factorize a numpy array to codes and uniques.

    This doesn't do any coercion of types or unboxing before factorization.

    Parameters
    ----------
    values : ndarray
    use_na_sentinel : bool, default True
        If True, the sentinel -1 will be used for NaN values. If False,
        NaN values will be encoded as non-negative integers and will not drop the
        NaN from the uniques of the values.
    size_hint : int, optional
        Passed through to the hashtable's 'get_labels' method
    na_value : object, optional
        A value in `values` to consider missing. Note: only use this
        parameter when you know that you don't have any values pandas would
        consider missing in the array (NaN for float data, iNaT for
        datetimes, etc.).
    mask : ndarray[bool], optional
        If not None, the mask is used as indicator for missing values
        (True = missing, False = valid) instead of `na_value` or
        condition "val != val".

    Returns
    -------
    codes : ndarray[np.intp]
    uniques : ndarray
    ÚmMéÿÿÿÿ)Zna_sentinelr    r�   Z	ignore_na)rJ   r—   r	   rv   r{   Ú	factorizerZ   r   )
r>   rž   rŸ   r    r�   rX   Ú
hash_klassr„   r…   rP   rV   rV   rW   Úfactorize_array$  s    $û
	r¥   z�    values : sequence
        A 1-D sequence. Sequences that aren't pandas objects are
        coerced to ndarrays before factorization.
    zt    sort : bool, default False
        Sort `uniques` and shuffle `codes` to maintain the
        relationship.
    zG    size_hint : int, optional
        Hint to the hashtable sizer.
    )r>   ÚsortrŸ   Fz%tuple[np.ndarray, np.ndarray | Index])r¦   rž   rŸ   r?   c           	      C  s  t | ttfƒr| j||d�S t| dd�} | }t | ttfƒr\| jdur\| j|d�\}}||fS t | tj	ƒsz| j|d�\}}nVt 
| ¡} |s¾| jtkr¾t| ƒ}| ¡ r¾t| jdd�}t ||| ¡} t| ||d	�\}}|röt|ƒd
kröt|||ddd�\}}t||j|ƒ}||fS )aN  
    Encode the object as an enumerated type or categorical variable.

    This method is useful for obtaining a numeric representation of an
    array when all that matters is identifying distinct values. `factorize`
    is available as both a top-level function :func:`pandas.factorize`,
    and as a method :meth:`Series.factorize` and :meth:`Index.factorize`.

    Parameters
    ----------
    {values}{sort}
    use_na_sentinel : bool, default True
        If True, the sentinel -1 will be used for NaN values. If False,
        NaN values will be encoded as non-negative integers and will not drop the
        NaN from the uniques of the values.

        .. versionadded:: 1.5.0
    {size_hint}
    Returns
    -------
    codes : ndarray
        An integer ndarray that's an indexer into `uniques`.
        ``uniques.take(codes)`` will have the same values as `values`.
    uniques : ndarray, Index, or Categorical
        The unique valid values. When `values` is Categorical, `uniques`
        is a Categorical. When `values` is some other pandas object, an
        `Index` is returned. Otherwise, a 1-D ndarray is returned.

        .. note::

           Even if there's a missing value in `values`, `uniques` will
           *not* contain an entry for it.

    See Also
    --------
    cut : Discretize continuous-valued array.
    unique : Find the unique value in an array.

    Notes
    -----
    Reference :ref:`the user guide <reshaping.factorize>` for more examples.

    Examples
    --------
    These examples all show factorize as a top-level method like
    ``pd.factorize(values)``. The results are identical for methods like
    :meth:`Series.factorize`.

    >>> codes, uniques = pd.factorize(np.array(['b', 'b', 'a', 'c', 'b'], dtype="O"))
    >>> codes
    array([0, 0, 1, 2, 0])
    >>> uniques
    array(['b', 'a', 'c'], dtype=object)

    With ``sort=True``, the `uniques` will be sorted, and `codes` will be
    shuffled so that the relationship is the maintained.

    >>> codes, uniques = pd.factorize(np.array(['b', 'b', 'a', 'c', 'b'], dtype="O"),
    ...                               sort=True)
    >>> codes
    array([1, 1, 0, 2, 1])
    >>> uniques
    array(['a', 'b', 'c'], dtype=object)

    When ``use_na_sentinel=True`` (the default), missing values are indicated in
    the `codes` with the sentinel value ``-1`` and missing values are not
    included in `uniques`.

    >>> codes, uniques = pd.factorize(np.array(['b', None, 'a', 'c', 'b'], dtype="O"))
    >>> codes
    array([ 0, -1,  1,  2,  0])
    >>> uniques
    array(['b', 'a', 'c'], dtype=object)

    Thus far, we've only factorized lists (which are internally coerced to
    NumPy arrays). When factorizing pandas objects, the type of `uniques`
    will differ. For Categoricals, a `Categorical` is returned.

    >>> cat = pd.Categorical(['a', 'a', 'c'], categories=['a', 'b', 'c'])
    >>> codes, uniques = pd.factorize(cat)
    >>> codes
    array([0, 0, 1])
    >>> uniques
    ['a', 'c']
    Categories (3, object): ['a', 'b', 'c']

    Notice that ``'b'`` is in ``uniques.categories``, despite not being
    present in ``cat.values``.

    For all other pandas objects, an Index of the appropriate type is
    returned.

    >>> cat = pd.Series(['a', 'a', 'c'])
    >>> codes, uniques = pd.factorize(cat)
    >>> codes
    array([0, 0, 1])
    >>> uniques
    Index(['a', 'c'], dtype='object')

    If NaN is in the values, and we want to include NaN in the uniques of the
    values, it can be achieved by setting ``use_na_sentinel=False``.

    >>> values = np.array([1, 2, 1, np.nan])
    >>> codes, uniques = pd.factorize(values)  # default: use_na_sentinel=True
    >>> codes
    array([ 0,  1,  0, -1])
    >>> uniques
    array([1., 2.])

    >>> codes, uniques = pd.factorize(values, use_na_sentinel=False)
    >>> codes
    array([0, 1, 0, 2])
    >>> uniques
    array([ 1.,  2., nan])
    )r¦   rž   r£   r‚   N)r¦   )rž   F)Úcompat)rž   rŸ   r   T)rž   Úassume_uniqueÚverify)rK   r+   r-   r£   rk   r)   r.   ÚfreqrL   rQ   rM   rJ   rU   r/   r›   r0   Úwherer¥   r{   Ú	safe_sortrZ   )	r>   r¦   rž   rŸ   rX   rP   r…   Z	null_maskr    rV   rV   rW   r£   b  sD     ÿþ
ý
û
r£   r;   )r¦   Ú	ascendingÚ	normalizeÚdropnar?   c                 C  s&   t jdttƒ d� t| |||||d�S )aK  
    Compute a histogram of the counts of non-null values.

    Parameters
    ----------
    values : ndarray (1-d)
    sort : bool, default True
        Sort by values
    ascending : bool, default False
        Sort in ascending order
    normalize: bool, default False
        If True then compute a relative histogram
    bins : integer, optional
        Rather than count values, group them into half-open bins,
        convenience for pd.cut, only works with numeric data
    dropna : bool, default True
        Don't include counts of NaN

    Returns
    -------
    Series
    zupandas.value_counts is deprecated and will be removed in a future version. Use pd.Series(obj).value_counts() instead.r^   )r¦   r­   r®   Úbinsr¯   )rd   re   rf   r   Úvalue_counts_internal)r>   r¦   r­   r®   r°   r¯   rV   rV   rW   Úvalue_counts/  s    ûúr²   c              
   C  s\  ddl m}m} t| dd ƒ}|r$dnd}	|d urøddlm}
 t| |ƒrL| j} z|
| |dd�}W n. tyŒ } ztd	ƒ|‚W Y d }~n
d }~0 0 |j	|d
�}|	|_
||j ¡  }|j d¡|_| ¡ }|rä|jdk ¡ rä|jdd… }t t|ƒg¡}�n<t| ƒ�rF|| dd�jj	|d
�}|	|_
||j_
|j}t|tjƒ�s4t |¡}nît| tƒ�rŒtt| jƒƒ}|| |	d�j||d� ¡ }| j|j_|j}n¨t| dd�} t| |ƒ\}}}|j tj!k�rÂ| tj"¡}||ƒ}|j t#dfv �rò|j t$k�rò| t$¡}n,|j |j k�r|j dk�rt%j&dt't(ƒ d� ||_
||||	dd�}|�rF|j)|d�}|�rX|| *¡  }|S )Nr   )r:   r;   rw   Z
proportionÚcount)ÚcutT)Zinclude_lowestz+bins argument only works with numeric data.©r¯   ÚintervalFrC   )Úindexrw   )Úlevelr¯   r²   r‚   rb   zàThe behavior of value_counts with object-dtype is deprecated. In a future version, this will *not* perform dtype inference on the resulting index. To retain the old behavior, use `result.index = result.index.infer_objects()`r^   )r·   rw   rD   )r­   )+Úpandasr:   r;   ÚgetattrZpandas.core.reshape.tiler´   rK   Ú_valuesr”   r²   rw   r·   ÚnotnarS   Z
sort_indexÚallZilocrL   r2   r{   r   rQ   rM   r,   ri   ÚrangeZnlevelsÚgroupbyÚsizeÚnamesrk   Úvalue_counts_arraylikerJ   Zfloat16rm   rƒ   rU   rd   re   rf   r   Zsort_valuesr}   )r>   r¦   r­   r®   r°   r¯   r:   r;   Z
index_namerw   r´   ÚiiÚerrr~   ÚcountsZlevelsÚkeysÚ_ÚidxrV   rV   rW   r±   ^  sr    
 
ÿÿ

ÿþù	r±   z,tuple[ArrayLike, npt.NDArray[np.int64], int])r>   r¯   r�   r?   c                 C  sb   | }t | ƒ} tj| ||d�\}}}t|jƒrJ|rJ|tk}|| ||  }}t||j|ƒ}|||fS )zÓ
    Parameters
    ----------
    values : np.ndarray
    dropna : bool
    mask : np.ndarray[bool] or None, default None

    Returns
    -------
    uniques : np.ndarray
    counts : np.ndarray[np.int64]
    r€   )rN   rœ   Zvalue_countr#   rJ   r	   rZ   )r>   r¯   r�   rX   rÆ   rÅ   Z
na_counterZres_keysrV   rV   rW   rÂ   Ã  s    
rÂ   ÚfirstzLiteral['first', 'last', False])r>   Úkeepr�   r?   c                 C  s   t | ƒ} tj| ||d�S )ax  
    Return boolean ndarray denoting duplicate values.

    Parameters
    ----------
    values : np.ndarray or ExtensionArray
        Array over which to check for duplicate values.
    keep : {'first', 'last', False}, default 'first'
        - ``first`` : Mark duplicates as ``True`` except for the first
          occurrence.
        - ``last`` : Mark duplicates as ``True`` except for the last
          occurrence.
        - False : Mark all duplicates as ``True``.
    mask : ndarray[bool], optional
        array indicating which elements to exclude from checking

    Returns
    -------
    duplicated : ndarray[bool]
    )rÊ   r�   )rN   rœ   Ú
duplicated)r>   rÊ   r�   rV   rV   rW   rË   â  s    rË   c              
   C  s¾   t | dd�} | }t| jƒr8t| ƒ} td| ƒ} | j|d�S t| ƒ} tj| ||d�\}}|durd||fS zt	|ƒ}W n: t
yª } z"tjd|› �tƒ d� W Y d}~n
d}~0 0 t||j|ƒ}|S )	a  
    Returns the mode(s) of an array.

    Parameters
    ----------
    values : array-like
        Array over which to check for duplicate values.
    dropna : bool, default True
        Don't consider counts of NaN/NaT.

    Returns
    -------
    np.ndarray or ExtensionArray
    Úmoder‚   r=   rµ   )r¯   r�   NzUnable to sort modes: r^   )rk   r#   rJ   r3   r   Ú_moderN   rœ   rÌ   r¬   r”   rd   re   r   rZ   )r>   r¯   r�   rX   ZnpresultZres_maskrÄ   r~   rV   rV   rW   rÌ   ÿ  s&    

þrÌ   ÚaveragerÊ   r   znpt.NDArray[np.float64])r>   ÚaxisÚmethodÚ	na_optionr­   Úpctr?   c              	   C  sd   t | jƒ}t| ƒ} | jdkr4tj| |||||d�}n,| jdkrXtj| ||||||d�}ntdƒ‚|S )a÷  
    Rank the values along a given axis.

    Parameters
    ----------
    values : np.ndarray or ExtensionArray
        Array whose values will be ranked. The number of dimensions in this
        array must not exceed 2.
    axis : int, default 0
        Axis over which to perform rankings.
    method : {'average', 'min', 'max', 'first', 'dense'}, default 'average'
        The method by which tiebreaks are broken during the ranking.
    na_option : {'keep', 'top'}, default 'keep'
        The method by which NaNs are placed in the ranking.
        - ``keep``: rank each NaN value with a NaN ranking
        - ``top``: replace each NaN with either +/- inf so that they
                   there are ranked at the top
    ascending : bool, default True
        Whether or not the elements should be ranked in ascending order.
    pct : bool, default False
        Whether or not to the display the returned rankings in integer form
        (e.g. 1, 2, 3) or in percentile form (e.g. 0.333..., 0.666..., 1).
    é   )Úis_datetimelikeÚties_methodr­   rÑ   rÒ   rE   )rÏ   rÔ   rÕ   r­   rÑ   rÒ   z&Array with ndim > 2 are not supported.)r#   rJ   rN   Úndimr   Zrank_1dZrank_2dr”   )r>   rÏ   rÐ   rÑ   r­   rÒ   rÔ   ZranksrV   rV   rW   Úrank+  s.    

ú
ù
r×   r   )ÚindicesrÏ   Ú
allow_fillc                 C  sz   t | tjtttfƒs&tjdtt	ƒ d� t
| ƒs8t | ¡} t|ƒ}|rht|| j| ƒ t| ||d|d�}n| j||d�}|S )ak	  
    Take elements from an array.

    Parameters
    ----------
    arr : array-like or scalar value
        Non array-likes (sequences/scalars without a dtype) are coerced
        to an ndarray.

        .. deprecated:: 2.1.0
            Passing an argument other than a numpy.ndarray, ExtensionArray,
            Index, or Series is deprecated.

    indices : sequence of int or one-dimensional np.ndarray of int
        Indices to be taken.
    axis : int, default 0
        The axis over which to select values.
    allow_fill : bool, default False
        How to handle negative values in `indices`.

        * False: negative values in `indices` indicate positional indices
          from the right (the default). This is similar to :func:`numpy.take`.

        * True: negative values in `indices` indicate
          missing values. These values are set to `fill_value`. Any other
          negative values raise a ``ValueError``.

    fill_value : any, optional
        Fill value to use for NA-indices when `allow_fill` is True.
        This may be ``None``, in which case the default NA value for
        the type (``self.dtype.na_value``) is used.

        For multi-dimensional `arr`, each *element* is filled with
        `fill_value`.

    Returns
    -------
    ndarray or ExtensionArray
        Same type as the input.

    Raises
    ------
    IndexError
        When `indices` is out of bounds for the array.
    ValueError
        When the indexer contains negative values other than ``-1``
        and `allow_fill` is True.

    Notes
    -----
    When `allow_fill` is False, `indices` may be whatever dimensionality
    is accepted by NumPy for `arr`.

    When `allow_fill` is True, `indices` should be 1-D.

    See Also
    --------
    numpy.take : Take elements from an array along an axis.

    Examples
    --------
    >>> import pandas as pd

    With the default ``allow_fill=False``, negative numbers indicate
    positional indices from the right.

    >>> pd.api.extensions.take(np.array([10, 20, 30]), [0, 0, -1])
    array([10, 10, 30])

    Setting ``allow_fill=True`` will place `fill_value` in those positions.

    >>> pd.api.extensions.take(np.array([10, 20, 30]), [0, 0, -1], allow_fill=True)
    array([10., 10., nan])

    >>> pd.api.extensions.take(np.array([10, 20, 30]), [0, 0, -1], allow_fill=True,
    ...      fill_value=-10)
    array([ 10,  10, -10])
    z­pd.api.extensions.take accepting non-standard inputs is deprecated and will raise in a future version. Pass either a numpy.ndarray, ExtensionArray, Index, or Series instead.r^   T)rÏ   rÙ   Ú
fill_value)rÏ   )rK   rL   rQ   r*   r+   r-   rd   re   rf   r   r   rM   r   r5   r™   r1   Útake)ÚarrrØ   rÏ   rÙ   rÚ   r~   rV   rV   rW   rÛ   k  s     Uû

ÿrÛ   Úleftz$NumpyValueArrayLike | ExtensionArrayzLiteral['left', 'right']zNumpySorter | Noneznpt.NDArray[np.intp] | np.intp)rÜ   ÚvalueÚsideÚsorterr?   c                 C  sÔ   |durt |ƒ}t| tjƒr¼| jjdv r¼t|ƒs8t|ƒr¼t | jj	¡}t|ƒrZt 
|g¡nt 
|¡}||jk ¡ rˆ||jk ¡ rˆ| j}n|j}t|ƒr¨tt| 	|¡ƒ}qÄttt|ƒ|d�}nt| ƒ} | j|||d�S )aû  
    Find indices where elements should be inserted to maintain order.

    Find the indices into a sorted array `arr` (a) such that, if the
    corresponding elements in `value` were inserted before the indices,
    the order of `arr` would be preserved.

    Assuming that `arr` is sorted:

    ======  ================================
    `side`  returned index `i` satisfies
    ======  ================================
    left    ``arr[i-1] < value <= self[i]``
    right   ``arr[i-1] <= value < self[i]``
    ======  ================================

    Parameters
    ----------
    arr: np.ndarray, ExtensionArray, Series
        Input array. If `sorter` is None, then it must be sorted in
        ascending order, otherwise `sorter` must be an array of indices
        that sort it.
    value : array-like or scalar
        Values to insert into `arr`.
    side : {'left', 'right'}, optional
        If 'left', the index of the first suitable location found is given.
        If 'right', return the last such index.  If there is no suitable
        index, return either 0 or N (where N is the length of `self`).
    sorter : 1-D array-like, optional
        Optional array of integer indices that sort array a into ascending
        order. They are typically the result of argsort.

    Returns
    -------
    array of ints or int
        If value is array-like, array of insertion points.
        If value is scalar, a single integer.

    See Also
    --------
    numpy.searchsorted : Similar method from NumPy.
    NÚiurI   )rß   rà   )r   rK   rL   rQ   rJ   r—   r   r   Úiinfor•   r2   Úminr½   Úmaxr   rz   r˜   r   r3   Úsearchsorted)rÜ   rÞ   rß   rà   râ   Z	value_arrrJ   rV   rV   rW   rå   à  s(    0
ÿ
þýý	rå   >   rp   rq   rl   rm   rn   ro   )ÚnrÏ   c                 C  sX  t |ƒ}tj}| j}t|ƒ}|r(tj}ntj}t|t	ƒrF|  
¡ } | j}t| tjƒs¬t| d|j› d�ƒr˜|dkrˆtdt| ƒj› d|› �ƒ‚|| |  |¡ƒS tt| ƒj› d�ƒ‚d}| jjdv rÖtj}|  d¡} t}d	}n4|râtj}n(|jd
v �r
| jjdv �rtj}ntj}| j}|dk�r&|  dd¡} t |¡}tj| j|d�}	tdƒgd }
|dk�rbtd|ƒnt|dƒ|
|< ||	t|
ƒ< | jjt v �r t!j"| |	|||d� nŠtdƒgd }|dk�rÂt|dƒntd|ƒ||< t|ƒ}tdƒgd }|dk�rütd| ƒn
t| dƒ||< t|ƒ}|| | | | ƒ|	|< |�r:|	 d¡}	|dk�rT|	dd…df }	|	S )aQ  
    difference of n between self,
    analogous to s-s.shift(n)

    Parameters
    ----------
    arr : ndarray or ExtensionArray
    n : int
        number of periods
    axis : {0, 1}
        axis to shift on
    stacklevel : int, default 3
        The stacklevel for the lost dtype warning.

    Returns
    -------
    shifted
    Ú__r   zcannot diff z	 on axis=zK has no 'diff' method. Convert to a suitable dtype prior to calling 'diff'.Fr¡   rH   Trá   )rq   rp   rÓ   r¢   rI   NrE   )Zdatetimelikeztimedelta64[ns])#rz   rL   ÚnanrJ   r   ÚoperatorÚxorÚsubrK   r(   Zto_numpyrQ   Úhasattrr–   Ú
ValueErrorr•   Úshiftr”   r—   rn   rR   r	   Zobject_rw   rm   rl   rÖ   ZreshapeÚemptyr™   Úslicerh   Ú_diff_specialr   Zdiff_2d)rÜ   ræ   rÏ   ÚnarJ   Zis_boolÚopZis_timedeltaZ	orig_ndimZout_arrZ
na_indexerZ_res_indexerZres_indexerZ_lag_indexerZlag_indexerrV   rV   rW   Údiff;  sh    
ÿ


""&

rô   zIndex | ArrayLikeznpt.NDArray[np.intp] | Nonez.AnyArrayLike | tuple[AnyArrayLike, np.ndarray])r>   rP   rž   r¨   r©   r?   c              	   C  sþ  t | tjttfƒstdƒ‚d}t | jtƒsFtj	| dd�dkrFt
| ƒ}nVz|  ¡ }|  |¡}W n> ttjfyš   | jrŽt | d tƒrŽt| ƒ}nt
| ƒ}Y n0 |du r¨|S t|ƒs¸tdƒ‚tt |¡ƒ}|sætt| ƒƒt| ƒksætdƒ‚|du �r t| ƒ\}} |t| ƒƒ}| | ¡ t| |¡ƒ}|�rl| ¡ }	|�rX|t| ƒ k |t| ƒkB }
d||
< nd}
t|	|d	d
�}nhtjt|ƒtd�}| |t t|ƒ¡¡ |j|dd�}|�rÔ|d	k}
|�rÔ|
|t| ƒ k B |t| ƒkB }
|�rò|
du�ròt  ||
d	¡ |t|ƒfS )a  
    Sort ``values`` and reorder corresponding ``codes``.

    ``values`` should be unique if ``codes`` is not None.
    Safe for use with mixed types (int, str), orders ints before strs.

    Parameters
    ----------
    values : list-like
        Sequence; must be unique if ``codes`` is not None.
    codes : np.ndarray[intp] or None, default None
        Indices to ``values``. All out of bound indices are treated as
        "not found" and will be masked with ``-1``.
    use_na_sentinel : bool, default True
        If True, the sentinel -1 will be used for NaN values. If False,
        NaN values will be encoded as non-negative integers and will not drop the
        NaN from the uniques of the values.
    assume_unique : bool, default False
        When True, ``values`` are assumed to be unique, which can speed up
        the calculation. Ignored when ``codes`` is None.
    verify : bool, default True
        Check if codes are out of bound for the values and put out of bound
        codes equal to ``-1``. If ``verify=False``, it is assumed there
        are no out of bound codes. Ignored when ``codes`` is None.

    Returns
    -------
    ordered : AnyArrayLike
        Sorted ``values``
    new_codes : ndarray
        Reordered ``codes``; returned when ``codes`` is not None.

    Raises
    ------
    TypeError
        * If ``values`` is not list-like or if ``codes`` is neither None
        nor list-like
        * If ``values`` cannot be sorted
    ValueError
        * If ``codes`` is not None and ``values`` contain duplicates.
    zbOnly np.ndarray, ExtensionArray, and Index objects are allowed to be passed to safe_sort as valuesNFr`   rc   r   zMOnly list-like objects or None are allowed to be passed to safe_sort as codesz,values should be unique if codes is not Noner¢   ©rÚ   rI   Úwrap)rÌ   )!rK   rL   rQ   r*   r+   r”   rJ   r'   r
   rg   Ú_sort_mixedÚargsortrÛ   ÚdecimalÚInvalidOperationrÀ   rh   Ú_sort_tuplesr    r   rM   r{   ry   rí   rv   Zmap_locationsÚlookupr1   rï   rz   ÚputZarangeZputmask)r>   rP   rž   r¨   r©   rà   Úorderedr¤   ÚtZorder2r�   Z	new_codesZreverse_indexerrV   rV   rW   r¬   ¬  s`    0ÿ
ÿþ

ÿ


r¬   )r?   c           
      C  s¢   t jdd„ | D ƒtd�}t jdd„ | D ƒtd�}| | @ }t  | | ¡}t  | | ¡}| ¡ d  |¡}| ¡ d  |¡}| ¡ d }t  |||g¡}	|  |	¡S )z3order ints before strings before nulls in 1d arraysc                 S  s   g | ]}t |tƒ‘qS rV   )rK   r[   ©Ú.0ÚxrV   rV   rW   Ú
<listcomp>0  r“   z_sort_mixed.<locals>.<listcomp>rI   c                 S  s   g | ]}t |ƒ‘qS rV   )r/   r   rV   rV   rW   r  1  r“   r   )rL   r2   rƒ   rø   ZnonzerorÛ   Zconcatenate)
r>   Zstr_posZnull_posÚnum_posZstr_argsortZnum_argsortZstr_locsZnum_locsZ	null_locsZlocsrV   rV   rW   r÷   .  s    r÷   c                 C  s:   ddl m} ddlm} || dƒ\}}||dd�}| | S )a  
    Convert array of tuples (1d) to array of arrays (2d).
    We need to keep the columns separately as they contain different types and
    nans (can't use `np.sort` as it may fail when str and nan are mixed in a
    column as types cannot be compared).
    r   )Ú	to_arrays)Úlexsort_indexerNT)Zorders)Z"pandas.core.internals.constructionr  Zpandas.core.sortingr  )r>   r  r  ZarraysrÇ   ÚindexerrV   rV   rW   rû   =  s
    rû   zArrayLike | Index)ÚlvalsÚrvalsr?   c           	      C  s  ddl m} t ¡ �8 tjddtd� t| dd�}t|dd�}W d  ƒ n1 sR0    Y  |j|dd	�\}}t 	|j
|j
¡}|||jd
dd�}t| tƒr´t|tƒr´|  |¡ ¡ }n<t| tƒrÄ| j} t|tƒrÔ|j}t| |gƒ}t|ƒ}t|ƒ}| |¡j
}t ||¡S )aù  
    Extracts the union from lvals and rvals with respect to duplicates and nans in
    both arrays.

    Parameters
    ----------
    lvals: np.ndarray or ExtensionArray
        left values which is ordered in front.
    rvals: np.ndarray or ExtensionArray
        right values ordered after lvals.

    Returns
    -------
    np.ndarray or ExtensionArray
        Containing the unsorted union of both arrays.

    Notes
    -----
    Caller is responsible for ensuring lvals.dtype == rvals.dtype.
    r   ©r;   Úignorez<The behavior of value_counts with object-dtype is deprecated)ÚcategoryFrµ   Nrõ   rz   )r·   rJ   rD   )r¹   r;   rd   Úcatch_warningsÚfilterwarningsrf   r±   ÚalignrL   Úmaximumr>   r·   rK   r,   Úappendry   r+   r»   r$   r3   ZreindexÚrepeat)	r  r	  r;   Zl_countZr_countZfinal_countZunique_valsÚcombinedZrepeatsrV   rV   rW   Úunion_with_duplicatesL  s.    
ý*

r  zLiteral['ignore'] | Nonez#np.ndarray | ExtensionArray | Index)rÜ   Ú	na_actionÚconvertr?   c           	        s  |dvrd|› d�}t |ƒ‚t|ƒrzt|tƒrJt|dƒrJ|‰ ‡ fdd„}n0ddlm} t|ƒdkrr||tj	d	�}n||ƒ}t|t
ƒr¶|d
krš||j ¡  }|j | ¡}t|j|ƒ}|S t| ƒsÆ|  ¡ S | jtdd�}|du rìtj|||d�S tj||t|ƒ tj¡|d�S dS )a®  
    Map values using an input mapping or function.

    Parameters
    ----------
    mapper : function, dict, or Series
        Mapping correspondence.
    na_action : {None, 'ignore'}, default None
        If 'ignore', propagate NA values, without passing them to the
        mapping correspondence.
    convert : bool, default True
        Try to find better dtype for elementwise function results. If
        False, leave as dtype=object.

    Returns
    -------
    Union[ndarray, Index, ExtensionArray]
        The output of the mapping function applied to the array.
        If the function returns a tuple with more than one element
        a MultiIndex will be returned.
    )Nr  z+na_action must either be 'ignore' or None, z was passedÚ__missing__c                   s"   ˆ t | tƒrt | ¡rtjn|  S rŠ   )rK   ÚfloatrL   rŒ   rè   )r  ©Zdict_with_defaultrV   rW   r’   ª  s   ÿzmap_array.<locals>.<lambda>r   r
  rI   r  FrC   N)r  )r�   r  )rí   r   rK   Údictrì   r¹   r;   r{   rL   rl   r-   r·   r¼   Zget_indexerr1   r»   rD   rS   rU   r
   Z	map_inferZmap_infer_maskr/   rR   rB   )	rÜ   Zmapperr  r  Úmsgr;   r  Ú
new_valuesr>   rV   r  rW   Ú	map_arrayƒ  s2    
ÿr  )N)TNNN)FTN)TFFNT)TFFNT)N)rÉ   N)TN)r   rÎ   rÊ   TF)r   FN)rÝ   N)r   )NTFT)NT)�Ú__doc__Ú
__future__r   rù   ré   Útextwrapr   Útypingr   r   r   rd   ÚnumpyrL   Zpandas._libsr   r   rœ   r	   r
   Zpandas._typingr   r   r   r   r   r   Zpandas.util._decoratorsr   Zpandas.util._exceptionsr   Zpandas.core.dtypes.castr   r   Zpandas.core.dtypes.commonr   r   r   r   r   r   r   r   r   r   r   r    r!   r"   r#   Zpandas.core.dtypes.concatr$   Zpandas.core.dtypes.dtypesr%   r&   r'   r(   Zpandas.core.dtypes.genericr)   r*   r+   r,   r-   r.   Zpandas.core.dtypes.missingr/   r0   Zpandas.core.array_algos.taker1   Zpandas.core.constructionr2   r˜   r3   r4   Zpandas.core.indexersr5   r6   r7   r8   r¹   r9   r:   r;   Zpandas.core.arraysr<   r=   rN   rZ   rk   ZComplex128HashTableZComplex64HashTableZFloat64HashTableZFloat32HashTableZUInt64HashTableZUInt32HashTableZUInt16HashTableZUInt8HashTableZInt64HashTableZInt32HashTableZInt16HashTableZInt8HashTableZStringHashTableZPyObjectHashTablert   rv   rs   ry   r   rx   Zunique1drš   rˆ   r¥   r£   r²   r±   rÂ   rË   rÌ   r×   rÛ   rå   rñ   rô   r¬   r÷   rû   r  r  rV   rV   rV   rW   Ú<module>   sê    D 	N!òa]    û>ÿÿÿñ   ü :     ú1     úf ÿ!  ý ÿ.     úC   ûx  üXs    û :  ü