o թZh@sUdZddlmZddlZddlmZmZmZmZm Z m Z m Z ddl Z ddl ZddlmZddlmZddlmZmZmZmZmZmZmZddlmZdd lmZdd l m!Z!dd l"m#Z#m$Z$dd l%m&Z&dd l'm(Z(ddl)m*Z*m+Z+ddl,m-Z-ddl.m/Z/m0Z0m1Z1ddl2m3Z3m4Z4ddl5m6Z6m7Z7m8Z8ddl9m:Z:ddl;mZ>ddl?m@Z@mAZAerddlBmCZCmDZDddlmEZEmFZFmGZGmHZHddlImJZJmKZKmLZLiZMdeNd<dddddZOGdd d e:ZPGd!d"d"ZQGd#d$d$eeZRGd%dde<ZSdS)&z. Base and utility classes for pandas objects. ) annotationsN) TYPE_CHECKINGAnyGenericLiteralcastfinaloverload)using_copy_on_write)lib)AxisIntDtypeObj IndexLabelNDFrameTSelfShapenpt)PYPY)functionAbstractMethodError)cache_readonlydoc)find_stack_level)can_hold_element)is_object_dtype is_scalar)ExtensionDtype) ABCDataFrameABCIndex ABCSeries)isnaremove_na_arraylike) algorithmsnanopsops) DirNamesMixin)OpsMixin)ExtensionArray)ensure_wrapped_if_datetimelike extract_array)HashableIterator)DropKeep NumpySorterNumpyValueArrayLike ScalarLike_co) DataFrameIndexSerieszdict[str, str] _shared_docs IndexOpsMixin)klassZinplaceunique duplicatedcsNeZdZUdZded<eddZddd ZddddZdfdd Z Z S) PandasObjectz/ Baseclass for various pandas objects. zdict[str, Any]_cachecCst|S)zK Class constructor (for this class it's just `__class__`). )typeselfr?G/var/www/html/lang_env/lib/python3.10/site-packages/pandas/core/base.py _constructorlzPandasObject._constructorreturnstrcCs t|S)zI Return a string representation for a particular object. )object__repr__r=r?r?r@rFss zPandasObject.__repr__Nkey str | NoneNonecCs6t|dsdS|dur|jdS|j|ddS)zV Reset cached properties. If ``key`` is passed, only clears that key. r;N)hasattrr;clearpop)r>rGr?r?r@ _reset_cachezs zPandasObject._reset_cacheintcs>t|dd}|r|dd}tt|r|S|StS)zx Generates the total memory usage for an object that returns either a value or Series of values memory_usageNTdeep)getattrrNrsumsuper __sizeof__)r>rOZmem __class__r?r@rUs   zPandasObject.__sizeof__)rCrDN)rGrHrCrIrCrN) __name__ __module__ __qualname____doc____annotations__propertyrArFrMrU __classcell__r?r?rVr@r:ds     r:c@s$eZdZdZd ddZd dd Zd S) NoNewAttributesMixina Mixin which prevents adding new attributes. Prevents additional attributes via xxx.attribute = "something" after a call to `self.__freeze()`. Mainly used to prevent the user from using wrong attributes on an accessor (`Series.cat/.str/.dt`). If you really want to add a new attribute at a later time, you need to use `object.__setattr__(self, key, value)`. rCrIcCst|dddS)z9 Prevents setting additional attributes. __frozenTN)rE __setattr__r=r?r?r@_freezeszNoNewAttributesMixin._freezerGrDcCsTt|ddr!|dks!|t|jvs!t||ddus!td|dt|||dS)NrbFr;z"You cannot add any new attribute '')rRr<__dict__AttributeErrorrErc)r>rGvaluer?r?r@rcs z NoNewAttributesMixin.__setattr__N)rCrI)rGrDrCrI)rZr[r\r]rdrcr?r?r?r@ras rac@seZdZUdZded<dZded<ded<d d gZeeZe e d d Z e d dZ e e d ddZe e ddZddZd!d"ddZe d#ddZddZeZdS)$SelectionMixinz mixin implementing the selection & aggregation interface on a group-like object sub-classes need to define: obj, exclusions robjNzIndexLabel | None _selectionzfrozenset[Hashable] exclusionsr; __setstate__cCs&t|jtttttjfs|jgS|jSrX) isinstancerklisttupler rnpndarrayr=r?r?r@_selection_lists zSelectionMixin._selection_listcCs(|jdus t|jtr|jS|j|jSrX)rkrnrjr r=r?r?r@ _selected_objs zSelectionMixin._selected_objrCrNcC|jjSrX)rtndimr=r?r?r@rvzSelectionMixin.ndimcCsRt|jtr |jS|jdur|j|jSt|jdkr&|jj|jdddS|jS)NrT)axisZ only_slice) rnrjr rkZ_getitem_nocopyrslenrlZ _drop_axisr=r?r?r@_obj_with_exclusionss  z#SelectionMixin._obj_with_exclusionscCs|jdurtd|jdt|tttttjfrIt |j j |t t |kr@tt ||j j }tdt|dd|jt|ddS||j vrUtd||j |j}|j||dS) Nz Column(s) z already selectedzColumns not found: rx)rvzColumn not found: )rk IndexErrorrnrorpr rrqrrrzrjcolumns intersectionset differenceKeyErrorrD_gotitemrv)r>rGbad_keysrvr?r?r@ __getitem__s   zSelectionMixin.__getitem__rvcCt|)a sub-classes to define return a sliced object Parameters ---------- key : str / list of selections ndim : {1, 2} requested ndim of result subset : object, default None subset to act on r)r>rGrvsubsetr?r?r@rs zSelectionMixin._gotitemrSeries | DataFramecCsXd}|jdkrt|r||vst|r|}|S|jdkr*t|r*||jkr*|}|S)zO Infer the `selection` to pass to our constructor in _gotitem. Nr}rx)rvr rZ is_list_likename)r>rGrZ selectionr?r?r@_infer_selections zSelectionMixin._infer_selectioncOrrXr)r>funcargskwargsr?r?r@ aggregateszSelectionMixin.aggregaterYrX)rvrN)rr)rZr[r\r]r^rkZ_internal_namesrZ_internal_names_setrr_rsrrtrvr{rrrrZaggr?r?r?r@ris0       ric@sheZdZUdZdZedgZded<eddd Z edd d Z e dddZ ee ddZ edddZdddZedddZe ddZedddZeddd Zedd"d#Ze d$d%ejfdd-d.Ze edd/d0Zed1d2d3d4 5ddd9d:Zeed2d1d;d4 5dddd?ZeZddAdBZeddCdDZ e dddFdGZ!e % 5 % $ 5dddMdNZ"dOdPZ#e dddQdRZ$eddSdTZ%eddUdVZ&eddWdXZ'e dddZd[Z(ee)j*d\d\d\e+,d]d^ % 5dddadbZ*dce-dd<e. e edddmdnZ/e. e edddqdnZ/ee-dddrds t $dddxdnZ/dydzdd}d~Z0e ddddZ1ddZ2ddZ3d$S)r5zS Common ops mixin to support a unified interface / docs for Series / Index itolistzfrozenset[str] _hidden_attrsrCr cCrrXrr=r?r?r@dtype'rwzIndexOpsMixin.dtypeExtensionArray | np.ndarraycCrrXrr=r?r?r@_values,rwzIndexOpsMixin._valuesrcOst|||S)zw Return the transpose, which is by definition self. Returns ------- %(klass)s )nvZvalidate_transpose)r>rrr?r?r@ transpose1s zIndexOpsMixin.transposea Return the transpose, which is by definition self. Examples -------- For Series: >>> s = pd.Series(['Ant', 'Bear', 'Cow']) >>> s 0 Ant 1 Bear 2 Cow dtype: object >>> s.T 0 Ant 1 Bear 2 Cow dtype: object For Index: >>> idx = pd.Index([1, 2, 3]) >>> idx.T Index([1, 2, 3], dtype='int64') )rrcCru)z Return a tuple of the shape of the underlying data. Examples -------- >>> s = pd.Series([1, 2, 3]) >>> s.shape (3,) )rshaper=r?r?r@rZs zIndexOpsMixin.shaperNcCrrXrr=r?r?r@__len__gszIndexOpsMixin.__len__ Literal[1]cCsdS)a Number of dimensions of the underlying data, by definition 1. Examples -------- >>> s = pd.Series(['Ant', 'Bear', 'Cow']) >>> s 0 Ant 1 Bear 2 Cow dtype: object >>> s.ndim 1 For Index: >>> idx = pd.Index([1, 2, 3]) >>> idx Index([1, 2, 3], dtype='int64') >>> idx.ndim 1 rxr?r=r?r?r@rvkszIndexOpsMixin.ndimcCs t|dkr tt|Std)a Return the first element of the underlying data as a Python scalar. Returns ------- scalar The first element of Series or Index. Raises ------ ValueError If the data is not length = 1. Examples -------- >>> s = pd.Series([1]) >>> s.item() 1 For an index: >>> s = pd.Series([1], index=['a']) >>> s.index.item() 'a' rxz6can only convert an array of size 1 to a Python scalar)rznextiter ValueErrorr=r?r?r@items  zIndexOpsMixin.itemcCru)a Return the number of bytes in the underlying data. Examples -------- For Series: >>> s = pd.Series(['Ant', 'Bear', 'Cow']) >>> s 0 Ant 1 Bear 2 Cow dtype: object >>> s.nbytes 24 For Index: >>> idx = pd.Index([1, 2, 3]) >>> idx Index([1, 2, 3], dtype='int64') >>> idx.nbytes 24 )rnbytesr=r?r?r@rszIndexOpsMixin.nbytescCs t|jS)a Return the number of elements in the underlying data. Examples -------- For Series: >>> s = pd.Series(['Ant', 'Bear', 'Cow']) >>> s 0 Ant 1 Bear 2 Cow dtype: object >>> s.size 3 For Index: >>> idx = pd.Index([1, 2, 3]) >>> idx Index([1, 2, 3], dtype='int64') >>> idx.size 3 )rzrr=r?r?r@sizes zIndexOpsMixin.sizer(cCr)ac The ExtensionArray of the data backing this Series or Index. Returns ------- ExtensionArray An ExtensionArray of the values stored within. For extension types, this is the actual array. For NumPy native types, this is a thin (no copy) wrapper around :class:`numpy.ndarray`. ``.array`` differs from ``.values``, which may require converting the data to a different form. See Also -------- Index.to_numpy : Similar method that always returns a NumPy array. Series.to_numpy : Similar method that always returns a NumPy array. Notes ----- This table lays out the different array types for each extension dtype within pandas. ================== ============================= dtype array type ================== ============================= category Categorical period PeriodArray interval IntervalArray IntegerNA IntegerArray string StringArray boolean BooleanArray datetime64[ns, tz] DatetimeArray ================== ============================= For any 3rd-party extension types, the array type will be an ExtensionArray. For all remaining dtypes ``.array`` will be a :class:`arrays.NumpyExtensionArray` wrapping the actual ndarray stored within. If you absolutely need a NumPy array (possibly with copying / coercing data), then use :meth:`Series.to_numpy` instead. Examples -------- For regular NumPy types like int, and float, a NumpyExtensionArray is returned. >>> pd.Series([1, 2, 3]).array [1, 2, 3] Length: 3, dtype: int64 For extension types, like Categorical, the actual ExtensionArray is returned >>> ser = pd.Series(pd.Categorical(['a', 'b', 'a'])) >>> ser.array ['a', 'b', 'a'] Categories (2, object): ['a', 'b'] rr=r?r?r@arrays?zIndexOpsMixin.arrayNFrnpt.DTypeLike | Nonecopyboolna_valuerE np.ndarrayc Kst|jtr|jj|f||d|S|r%tt|}td|d|t j uo7|t j uo6t |jt j }|j}|rWt||sJt j||d}n|}||t t|<t j||d}|rb|rg|strt |jdd|ddrtr|s|}d|j_|S|}|S)a A NumPy ndarray representing the values in this Series or Index. Parameters ---------- dtype : str or numpy.dtype, optional The dtype to pass to :meth:`numpy.asarray`. copy : bool, default False Whether to ensure that the returned value is not a view on another array. Note that ``copy=False`` does not *ensure* that ``to_numpy()`` is no-copy. Rather, ``copy=True`` ensure that a copy is made, even if not strictly necessary. na_value : Any, optional The value to use for missing values. The default value depends on `dtype` and the type of the array. **kwargs Additional keywords passed through to the ``to_numpy`` method of the underlying array (for extension arrays). Returns ------- numpy.ndarray See Also -------- Series.array : Get the actual data stored within. Index.array : Get the actual data stored within. DataFrame.to_numpy : Similar method for DataFrame. Notes ----- The returned array will be the same up to equality (values equal in `self` will be equal in the returned array; likewise for values that are not equal). When `self` contains an ExtensionArray, the dtype may be different. For example, for a category-dtype Series, ``to_numpy()`` will return a NumPy array and the categorical dtype will be lost. For NumPy dtypes, this will be a reference to the actual data stored in this Series or Index (assuming ``copy=False``). Modifying the result in place will modify the data stored in the Series or Index (not that we recommend doing that). For extension types, ``to_numpy()`` *may* require copying data and coercing the result to a NumPy type (possibly object), which may be expensive. When you need a no-copy reference to the underlying data, :attr:`Series.array` should be used instead. This table lays out the different dtypes and default return types of ``to_numpy()`` for various dtypes within pandas. ================== ================================ dtype array type ================== ================================ category[T] ndarray[T] (same dtype as input) period ndarray[object] (Periods) interval ndarray[object] (Intervals) IntegerNA ndarray[object] datetime64[ns] datetime64[ns] datetime64[ns, tz] ndarray[object] (Timestamps) ================== ================================ Examples -------- >>> ser = pd.Series(pd.Categorical(['a', 'b', 'a'])) >>> ser.to_numpy() array(['a', 'b', 'a'], dtype=object) Specify the `dtype` to control how datetime-aware data is represented. Use ``dtype=object`` to return an ndarray of pandas :class:`Timestamp` objects, each with the correct ``tz``. >>> ser = pd.Series(pd.date_range('2000', periods=2, tz="CET")) >>> ser.to_numpy(dtype=object) array([Timestamp('2000-01-01 00:00:00+0100', tz='CET'), Timestamp('2000-01-02 00:00:00+0100', tz='CET')], dtype=object) Or ``dtype='datetime64[ns]'`` to return an ndarray of native datetime64 values. The values are converted to UTC and the timezone info is dropped. >>> ser.to_numpy(dtype="datetime64[ns]") ... # doctest: +ELLIPSIS array(['1999-12-31T23:00:00.000000000', '2000-01-01T23:00:00...'], dtype='datetime64[ns]') )rrz/to_numpy() got an unexpected keyword argument 're)rNr}F)rnrrrto_numpyrrkeys TypeErrorr no_defaultrqnanZ issubdtypeZfloatingrrZasarrayrZ asanyarrayr!r Z shares_memoryviewflagsZ writeable) r>rrrrrZfillnavaluesresultr?r?r@rs2 _    zIndexOpsMixin.to_numpycCs|j SrX)rr=r?r?r@emptyrwzIndexOpsMixin.emptymaxminZlargest)opZopposerhTryAxisInt | NoneskipnacO|j}t|t|||}t|tr2|s.|r.tj dt |j dt t ddS|Stj||d}|dkrMtj dt |j dt t d|S)ab Return int position of the {value} value in the Series. If the {op}imum is achieved in multiple locations, the first row position is returned. Parameters ---------- axis : {{None}} Unused. Parameter needed for compatibility with DataFrame. skipna : bool, default True Exclude NA/null values when showing the result. *args, **kwargs Additional arguments and keywords for compatibility with NumPy. Returns ------- int Row position of the {op}imum value. See Also -------- Series.arg{op} : Return position of the {op}imum value. Series.arg{oppose} : Return position of the {oppose}imum value. numpy.ndarray.arg{op} : Equivalent method for numpy arrays. Series.idxmax : Return index label of the maximum values. Series.idxmin : Return index label of the minimum values. Examples -------- Consider dataset containing cereal calories >>> s = pd.Series({{'Corn Flakes': 100.0, 'Almond Delight': 110.0, ... 'Cinnamon Toast Crunch': 120.0, 'Cocoa Puff': 110.0}}) >>> s Corn Flakes 100.0 Almond Delight 110.0 Cinnamon Toast Crunch 120.0 Cocoa Puff 110.0 dtype: float64 >>> s.argmax() 2 >>> s.argmin() 0 The maximum cereal calories is the third element and the minimum cereal calories is the first element, since series is zero-indexed. The behavior of x.argmax/argmin with skipna=False and NAs, or with all-NAs is deprecated. In a future version this will raise ValueError. stacklevelr|r)rrvalidate_minmax_axisZvalidate_argmax_with_skipnarnr(r!anywarningswarnr<rZ FutureWarningrargmaxr$Z nanargmaxr>ryrrrZdelegaterr?r?r@rs(6   zIndexOpsMixin.argmaxZsmallestcOr)Nrrrr|r)rrrZvalidate_argmin_with_skipnarnr(r!rrrr<rZrrargminr$Z nanargminrr?r?r@rs(   zIndexOpsMixin.argmincCs |jS)a Return a list of the values. These are each a scalar type, which is a Python scalar (for str, int, float) or a pandas scalar (for Timestamp/Timedelta/Interval/Period) Returns ------- list See Also -------- numpy.ndarray.tolist : Return the array as an a.ndim-levels deep nested list of Python scalars. Examples -------- For Series >>> s = pd.Series([1, 2, 3]) >>> s.to_list() [1, 2, 3] For Index: >>> idx = pd.Index([1, 2, 3]) >>> idx Index([1, 2, 3], dtype='int64') >>> idx.to_list() [1, 2, 3] )rrr=r?r?r@rs "zIndexOpsMixin.tolistr,cCs.t|jtjs t|jSt|jjt|jjS)a Return an iterator of the values. These are each a scalar type, which is a Python scalar (for str, int, float) or a pandas scalar (for Timestamp/Timedelta/Interval/Period) Returns ------- iterator Examples -------- >>> s = pd.Series([1, 2, 3]) >>> for x in s: ... print(x) 1 2 3 ) rnrrqrrrmaprrangerr=r?r?r@__iter__Ds zIndexOpsMixin.__iter__cCstt|S)ak Return True if there are any NaNs. Enables various performance speedups. Returns ------- bool Examples -------- >>> s = pd.Series([1, 2, 3, None]) >>> s 0 1.0 1 2.0 2 3.0 3 NaN dtype: float64 >>> s.hasnans True )rr!rr=r?r?r@hasnans`szIndexOpsMixin.hasnansconvertcCs0|j}t|tr|j||dStj||||dS)a An internal function that maps values using the input correspondence (which can be a dict, Series, or function). Parameters ---------- mapper : function, dict, or Series The input correspondence object na_action : {None, 'ignore'} If 'ignore', propagate NA values, without passing them to the mapping function convert : bool, default True Try to find better dtype for elementwise function results. If False, leave as dtype=object. Note that the dtype is always preserved for some extension array dtypes, such as Categorical. Returns ------- Union[Index, MultiIndex], inferred The output of the mapping function applied to the index. If the function returns a tuple with more than one element a MultiIndex will be returned. ) na_action)rr)rrnr(rr#Z map_array)r>Zmapperrrarrr?r?r@ _map_values{s zIndexOpsMixin._map_values normalizesort ascendingdropnar3cCstj||||||dS)a= Return a Series containing counts of unique values. The resulting object will be in descending order so that the first element is the most frequently-occurring element. Excludes NA values by default. Parameters ---------- normalize : bool, default False If True then the object returned will contain the relative frequencies of the unique values. sort : bool, default True Sort by frequencies when True. Preserve the order of the data when False. ascending : bool, default False Sort in ascending order. bins : int, optional Rather than count values, group them into half-open bins, a convenience for ``pd.cut``, only works with numeric data. dropna : bool, default True Don't include counts of NaN. Returns ------- Series See Also -------- Series.count: Number of non-NA elements in a Series. DataFrame.count: Number of non-NA elements in a DataFrame. DataFrame.value_counts: Equivalent method on DataFrames. Examples -------- >>> index = pd.Index([3, 1, 2, 3, 4, np.nan]) >>> index.value_counts() 3.0 2 1.0 1 2.0 1 4.0 1 Name: count, dtype: int64 With `normalize` set to `True`, returns the relative frequency by dividing all values by the sum of values. >>> s = pd.Series([3, 1, 2, 3, 4, np.nan]) >>> s.value_counts(normalize=True) 3.0 0.4 1.0 0.2 2.0 0.2 4.0 0.2 Name: proportion, dtype: float64 **bins** Bins can be useful for going from a continuous variable to a categorical variable; instead of counting unique apparitions of values, divide the index in the specified number of half-open bins. >>> s.value_counts(bins=3) (0.996, 2.0] 2 (2.0, 3.0] 2 (3.0, 4.0] 1 Name: count, dtype: int64 **dropna** With `dropna` set to `False` we can also see NaN index values. >>> s.value_counts(dropna=False) 3.0 2 1.0 1 2.0 1 4.0 1 NaN 1 Name: count, dtype: int64 )rrrbinsr)r#Zvalue_counts_internal)r>rrrrrr?r?r@ value_countssWzIndexOpsMixin.value_countscCs,|j}t|tjs|}|St|}|SrX)rrnrqrrr8r#Zunique1d)r>rrr?r?r@r8s   zIndexOpsMixin.uniquecCs|}|r t|}t|S)a Return number of unique elements in the object. Excludes NA values by default. Parameters ---------- dropna : bool, default True Don't include NaN in the count. Returns ------- int See Also -------- DataFrame.nunique: Method nunique for DataFrame. Series.count: Count non-NA/null observations in the Series. Examples -------- >>> s = pd.Series([1, 3, 5, 7, 7]) >>> s 0 1 1 3 2 5 3 7 4 7 dtype: int64 >>> s.nunique() 4 )r8r"rz)r>rZuniqsr?r?r@nuniques#zIndexOpsMixin.nuniquecCs|jddt|kS)a. Return boolean if values in the object are unique. Returns ------- bool Examples -------- >>> s = pd.Series([1, 2, 3]) >>> s.is_unique True >>> s = pd.Series([1, 2, 3, 1]) >>> s.is_unique False F)r)rrzr=r?r?r@ is_unique,szIndexOpsMixin.is_uniquecCddlm}||jS)aY Return boolean if values in the object are monotonically increasing. Returns ------- bool Examples -------- >>> s = pd.Series([1, 2, 2]) >>> s.is_monotonic_increasing True >>> s = pd.Series([3, 2, 1]) >>> s.is_monotonic_increasing False rr2)pandasr2is_monotonic_increasingr>r2r?r?r@rA  z%IndexOpsMixin.is_monotonic_increasingcCr)a\ Return boolean if values in the object are monotonically decreasing. Returns ------- bool Examples -------- >>> s = pd.Series([3, 2, 2, 1]) >>> s.is_monotonic_decreasing True >>> s = pd.Series([1, 2, 3]) >>> s.is_monotonic_decreasing False rr)rr2is_monotonic_decreasingrr?r?r@rXrz%IndexOpsMixin.is_monotonic_decreasingrQcCsTt|jdr |jj|dS|jj}|r(t|jr(ts(ttj |j }|t |7}|S)a Memory usage of the values. Parameters ---------- deep : bool, default False Introspect the data deeply, interrogate `object` dtypes for system-level memory consumption. Returns ------- bytes used See Also -------- numpy.ndarray.nbytes : Total bytes consumed by the elements of the array. Notes ----- Memory usage does not include memory consumed by elements that are not components of the array if deep=False or if used on PyPy Examples -------- >>> idx = pd.Index([1, 2, 3]) >>> idx.memory_usage() 24 rOrP) rJrrOrrrrrrqrrrr Zmemory_usage_of_objects)r>rQvrr?r?r@ _memory_usageos zIndexOpsMixin._memory_usager6z sort : bool, default False Sort `uniques` and shuffle `codes` to maintain the relationship. )rorderZ size_hintruse_na_sentinel"tuple[npt.NDArray[np.intp], Index]cCsftj|j||d\}}|jtjkr|tj}t|t r%| |}||fSddl m }||}||fS)N)rrrr) r# factorizerrrqZfloat16ZastypeZfloat32rnrrArr2)r>rrcodesZuniquesr2r?r?r@rs     zIndexOpsMixin.factorizea Find indices where elements should be inserted to maintain order. Find the indices into a sorted {klass} `self` such that, if the corresponding elements in `value` were inserted before the indices, the order of `self` would be preserved. .. note:: The {klass} *must* be monotonically sorted, otherwise wrong locations will likely be returned. Pandas does *not* check this for you. Parameters ---------- value : array-like or scalar Values to insert into `self`. 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 `self` into ascending order. They are typically the result of ``np.argsort``. Returns ------- int or array of int A scalar or array of insertion points with the same shape as `value`. See Also -------- sort_values : Sort by the values along either axis. numpy.searchsorted : Similar method from NumPy. Notes ----- Binary search is used to find the required insertion points. Examples -------- >>> ser = pd.Series([1, 2, 3]) >>> ser 0 1 1 2 2 3 dtype: int64 >>> ser.searchsorted(4) 3 >>> ser.searchsorted([0, 4]) array([0, 3]) >>> ser.searchsorted([1, 3], side='left') array([0, 2]) >>> ser.searchsorted([1, 3], side='right') array([1, 3]) >>> ser = pd.Series(pd.to_datetime(['3/11/2000', '3/12/2000', '3/13/2000'])) >>> ser 0 2000-03-11 1 2000-03-12 2 2000-03-13 dtype: datetime64[ns] >>> ser.searchsorted('3/14/2000') 3 >>> ser = pd.Categorical( ... ['apple', 'bread', 'bread', 'cheese', 'milk'], ordered=True ... ) >>> ser ['apple', 'bread', 'bread', 'cheese', 'milk'] Categories (4, object): ['apple' < 'bread' < 'cheese' < 'milk'] >>> ser.searchsorted('bread') 1 >>> ser.searchsorted(['bread'], side='right') array([3]) If the values are not monotonically sorted, wrong locations may be returned: >>> ser = pd.Series([2, 1, 3]) >>> ser 0 2 1 1 2 3 dtype: int64 >>> ser.searchsorted(1) # doctest: +SKIP 0 # wrong result, correct would be 1 searchsorted.rhr0sideLiteral['left', 'right']sorterr.np.intpcCdSrXr?r>rhrrr?r?r@r#zIndexOpsMixin.searchsortednpt.ArrayLike | ExtensionArraynpt.NDArray[np.intp]cCrrXr?rr?r?r@r,rr2)r7left$NumpyValueArrayLike | ExtensionArrayNumpySorter | Nonenpt.NDArray[np.intp] | np.intpcCsXt|trdt|jd}t||j}t|tjs#|j|||dSt j||||dS)Nz(Value must be 1-D array-like or scalar, z is not supported)rr) rnrr<rZrrrqrrrr#)r>rhrrmsgrr?r?r@r5s  firstkeeprr-cCs|j|d}||SNr) _duplicated)r>rr9r?r?r@drop_duplicatesOs  zIndexOpsMixin.drop_duplicatesnpt.NDArray[np.bool_]cCs*|j}t|tr|j|dStj||dSr)rrnr(r9r#)r>rrr?r?r@rTs  zIndexOpsMixin._duplicatedcCst||}|j}t|ddd}t||j}t|}t|tr*t |j |j |j }t jddt|||}Wdn1sBwY|j||dS)NT)Z extract_numpyZ extract_rangeignore)all)r)r%Zget_op_result_namerr*Zmaybe_prepare_scalar_for_oprr)rnrrqZarangestartstopstepZerrstateZ arithmetic_op_construct_result)r>otherrZres_nameZlvaluesZrvaluesrr?r?r@ _arith_method[s  zIndexOpsMixin._arith_methodcCr)z~ Construct an appropriately-wrapped result from the ArrayLike result of an arithmetic-like operation. r)r>rrr?r?r@rjrBzIndexOpsMixin._construct_result)rCr )rCr)rCr)rCrrY)rCr)rCr()rrrrrrErCr)rCr)NT)ryrrrrCrN)rCr,)rr)FTFNT) rrrrrrrrrCr3)T)rrrCrN)F)rQrrCrN)FT)rrrrrCr)..)rhr0rrrr.rCr)rhrrrrr.rCr)rN)rhrrrrrrCr)rr-)r)rr-rCr)4rZr[r\r]Z__array_priority__ frozensetrr^r_rrrrTrrrvrrrrr rrrrrrrZto_listrrrrrr8rrrrrr#rtextwrapdedentr4r rrrrrr?r?r?r@r5s             @ S!$  _ '   )i )Tr] __future__rrtypingrrrrrrr rnumpyrqZpandas._configr Z pandas._libsr Zpandas._typingr r rrrrrZ pandas.compatrZpandas.compat.numpyrrZ pandas.errorsrZpandas.util._decoratorsrrZpandas.util._exceptionsrZpandas.core.dtypes.castrZpandas.core.dtypes.commonrrZpandas.core.dtypes.dtypesrZpandas.core.dtypes.genericrrr Zpandas.core.dtypes.missingr!r"Z pandas.corer#r$r%Zpandas.core.accessorr&Zpandas.core.arrayliker'Zpandas.core.arraysr(Zpandas.core.constructionr)r*collections.abcr+r,r-r.r/r0rr1r2r3r4r^Z_indexops_doc_kwargsr:rarir5r?r?r?r@sL $   $         /"g