Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/pandas/core/series.py: 31%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2Data structure for 1-dimensional cross-sectional and time series data
3"""
5from __future__ import annotations
7from collections.abc import (
8 Callable,
9 Hashable,
10 Iterable,
11 Mapping,
12 Sequence,
13)
14import functools
15import operator
16import sys
17from textwrap import dedent
18from typing import (
19 IO,
20 TYPE_CHECKING,
21 Any,
22 Literal,
23 Self,
24 cast,
25 overload,
26)
27import warnings
29import numpy as np
31from pandas._libs import (
32 lib,
33 properties,
34 reshape,
35)
36from pandas._libs.lib import is_range_indexer
37from pandas.compat import CHAINED_WARNING_DISABLED
38from pandas.compat._constants import (
39 REF_COUNT,
40 REF_COUNT_METHOD,
41)
42from pandas.compat._optional import import_optional_dependency
43from pandas.compat.numpy import function as nv
44from pandas.errors import (
45 ChainedAssignmentError,
46 InvalidIndexError,
47 Pandas4Warning,
48)
49from pandas.errors.cow import (
50 _chained_assignment_method_update_msg,
51 _chained_assignment_msg,
52)
53from pandas.util._decorators import (
54 Appender,
55 deprecate_nonkeyword_arguments,
56 doc,
57 set_module,
58)
59from pandas.util._exceptions import (
60 find_stack_level,
61)
62from pandas.util._validators import (
63 validate_ascending,
64 validate_bool_kwarg,
65 validate_percentile,
66)
68from pandas.core.dtypes.astype import astype_is_view
69from pandas.core.dtypes.cast import (
70 LossySetitemError,
71 construct_1d_arraylike_from_scalar,
72 find_common_type,
73 infer_dtype_from,
74 maybe_box_native,
75 maybe_unbox_numpy_scalar,
76)
77from pandas.core.dtypes.common import (
78 is_dict_like,
79 is_float,
80 is_integer,
81 is_iterator,
82 is_list_like,
83 is_object_dtype,
84 is_scalar,
85 pandas_dtype,
86 validate_all_hashable,
87)
88from pandas.core.dtypes.dtypes import (
89 ExtensionDtype,
90)
91from pandas.core.dtypes.generic import (
92 ABCDataFrame,
93 ABCSeries,
94)
95from pandas.core.dtypes.inference import is_hashable
96from pandas.core.dtypes.missing import (
97 isna,
98 na_value_for_dtype,
99 notna,
100 remove_na_arraylike,
101)
103from pandas.core import (
104 algorithms,
105 base,
106 common as com,
107 nanops,
108 ops,
109 roperator,
110)
111from pandas.core.accessor import Accessor
112from pandas.core.apply import SeriesApply
113from pandas.core.arrays import ExtensionArray
114from pandas.core.arrays.arrow import (
115 ListAccessor,
116 StructAccessor,
117)
118from pandas.core.arrays.categorical import CategoricalAccessor
119from pandas.core.arrays.sparse import SparseAccessor
120from pandas.core.construction import (
121 array as pd_array,
122 extract_array,
123 sanitize_array,
124)
125from pandas.core.generic import NDFrame
126from pandas.core.indexers import (
127 disallow_ndim_indexing,
128 unpack_1tuple,
129)
130from pandas.core.indexes.accessors import CombinedDatetimelikeProperties
131from pandas.core.indexes.api import (
132 DatetimeIndex,
133 Index,
134 MultiIndex,
135 PeriodIndex,
136 default_index,
137 ensure_index,
138 maybe_sequence_to_range,
139)
140import pandas.core.indexes.base as ibase
141from pandas.core.indexes.multi import maybe_droplevels
142from pandas.core.indexing import (
143 check_bool_indexer,
144 check_dict_or_set_indexers,
145)
146from pandas.core.internals import SingleBlockManager
147from pandas.core.methods import selectn
148from pandas.core.shared_docs import _shared_docs
149from pandas.core.sorting import (
150 ensure_key_mapped,
151 nargsort,
152)
153from pandas.core.strings.accessor import StringMethods
154from pandas.core.tools.datetimes import to_datetime
156import pandas.io.formats.format as fmt
157from pandas.io.formats.info import (
158 SeriesInfo,
159)
160import pandas.plotting
162if TYPE_CHECKING:
163 from pandas._libs.internals import BlockValuesRefs
164 from pandas._typing import (
165 AggFuncType,
166 AnyAll,
167 AnyArrayLike,
168 ArrayLike,
169 ArrowArrayExportable,
170 ArrowStreamExportable,
171 Axis,
172 AxisInt,
173 CorrelationMethod,
174 DropKeep,
175 Dtype,
176 DtypeObj,
177 FilePath,
178 Frequency,
179 IgnoreRaise,
180 IndexKeyFunc,
181 IndexLabel,
182 Level,
183 ListLike,
184 MutableMappingT,
185 NaPosition,
186 NumpySorter,
187 NumpyValueArrayLike,
188 QuantileInterpolation,
189 ReindexMethod,
190 Renamer,
191 Scalar,
192 SortKind,
193 StorageOptions,
194 Suffixes,
195 ValueKeyFunc,
196 WriteBuffer,
197 npt,
198 )
200 from pandas.core.frame import DataFrame
201 from pandas.core.groupby.generic import SeriesGroupBy
203__all__ = ["Series"]
205_shared_doc_kwargs = {
206 "axes": "index",
207 "klass": "Series",
208 "axes_single_arg": "{0 or 'index'}",
209 "axis": """axis : {0 or 'index'}
210 Unused. Parameter needed for compatibility with DataFrame.""",
211 "inplace": """inplace : bool, default False
212 If True, performs operation inplace and returns None.""",
213 "unique": "np.ndarray",
214 "duplicated": "Series",
215 "optional_by": "",
216 "optional_reindex": """
217index : array-like, optional
218 New labels for the index. Preferably an Index object to avoid
219 duplicating data.
220axis : int or str, optional
221 Unused.""",
222}
224# ----------------------------------------------------------------------
225# Series class
228# error: Cannot override final attribute "ndim" (previously declared in base
229# class "NDFrame")
230# error: Cannot override final attribute "size" (previously declared in base
231# class "NDFrame")
232# definition in base class "NDFrame"
233@set_module("pandas")
234class Series(base.IndexOpsMixin, NDFrame): # type: ignore[misc]
235 """
236 One-dimensional ndarray with axis labels (including time series).
238 Labels need not be unique but must be a hashable type. The object
239 supports both integer- and label-based indexing and provides a host of
240 methods for performing operations involving the index. Statistical
241 methods from ndarray have been overridden to automatically exclude
242 missing data (currently represented as NaN).
244 Operations between Series (+, -, /, \\*, \\*\\*) align values based on their
245 associated index values-- they need not be the same length. The result
246 index will be the sorted union of the two indexes.
248 Parameters
249 ----------
250 data : array-like, Iterable, dict, or scalar value
251 Contains data stored in Series. If data is a dict, argument order is
252 maintained. Unordered sets are not supported.
253 index : array-like or Index (1d)
254 Values must be hashable and have the same length as `data`.
255 Non-unique index values are allowed. Will default to
256 RangeIndex (0, 1, 2, ..., n) if not provided. If data is dict-like
257 and index is None, then the keys in the data are used as the index. If the
258 index is not None, the resulting Series is reindexed with the index values.
259 dtype : str, numpy.dtype, or ExtensionDtype, optional
260 Data type for the output Series. If not specified, this will be
261 inferred from `data`.
262 See the :ref:`user guide <basics.dtypes>` for more usages.
263 name : Hashable, default None
264 The name to give to the Series.
265 copy : bool, default None
266 Whether to copy input data, only relevant for array, Series, and Index
267 inputs (for other input, e.g. a list, a new array is created anyway).
268 Defaults to True for array input and False for Index/Series.
269 Even when False for Index/Series, a shallow copy of the data is made.
270 Set to False to avoid copying array input at your own risk (if you
271 know the input data won't be modified elsewhere).
272 Set to True to force copying Series/Index input up front.
274 See Also
275 --------
276 DataFrame : Two-dimensional, size-mutable, potentially heterogeneous tabular data.
277 Index : Immutable sequence used for indexing and alignment.
279 Notes
280 -----
281 Please reference the :ref:`User Guide <basics.series>` for more information.
283 Examples
284 --------
285 Constructing Series from a dictionary with an Index specified
287 >>> d = {"a": 1, "b": 2, "c": 3}
288 >>> ser = pd.Series(data=d, index=["a", "b", "c"])
289 >>> ser
290 a 1
291 b 2
292 c 3
293 dtype: int64
295 The keys of the dictionary match with the Index values, hence the Index
296 values have no effect.
298 >>> d = {"a": 1, "b": 2, "c": 3}
299 >>> ser = pd.Series(data=d, index=["x", "y", "z"])
300 >>> ser
301 x NaN
302 y NaN
303 z NaN
304 dtype: float64
306 Note that the Index is first built with the keys from the dictionary.
307 After this the Series is reindexed with the given Index values, hence we
308 get all NaN as a result.
310 Constructing Series from a list with `copy=False`.
312 >>> r = [1, 2]
313 >>> ser = pd.Series(r, copy=False)
314 >>> ser.iloc[0] = 999
315 >>> r
316 [1, 2]
317 >>> ser
318 0 999
319 1 2
320 dtype: int64
322 Due to input data type the Series has a `copy` of
323 the original data even though `copy=False`, so
324 the data is unchanged.
326 Constructing Series from a 1d ndarray with `copy=False`.
328 >>> r = np.array([1, 2])
329 >>> ser = pd.Series(r, copy=False)
330 >>> ser.iloc[0] = 999
331 >>> r
332 array([999, 2])
333 >>> ser
334 0 999
335 1 2
336 dtype: int64
338 Due to input data type the Series has a `view` on
339 the original data, so
340 the data is changed as well.
341 """
343 _typ = "series"
344 _HANDLED_TYPES = (Index, ExtensionArray, np.ndarray)
346 _name: Hashable
347 _metadata: list[str] = ["_name"]
348 _internal_names_set = {"index", "name"} | NDFrame._internal_names_set
349 _accessors = {"dt", "cat", "str", "sparse"}
350 _hidden_attrs = (
351 base.IndexOpsMixin._hidden_attrs | NDFrame._hidden_attrs | frozenset([])
352 )
354 # similar to __array_priority__, positions Series after DataFrame
355 # but before Index and ExtensionArray. Should NOT be overridden by subclasses.
356 __pandas_priority__ = 3000
358 # Override cache_readonly bc Series is mutable
359 hasnans = property(
360 # error: "Callable[[IndexOpsMixin], bool]" has no attribute "fget"
361 base.IndexOpsMixin.hasnans.fget, # type: ignore[attr-defined]
362 doc=base.IndexOpsMixin.hasnans.__doc__,
363 )
364 _mgr: SingleBlockManager
366 # ----------------------------------------------------------------------
367 # Constructors
369 def __init__(
370 self,
371 data=None,
372 index=None,
373 dtype: Dtype | None = None,
374 name=None,
375 copy: bool | None = None,
376 ) -> None:
377 allow_mgr = False
378 if (
379 isinstance(data, SingleBlockManager)
380 and index is None
381 and dtype is None
382 and (copy is False or copy is None)
383 ):
384 if not allow_mgr:
385 # GH#52419
386 warnings.warn(
387 f"Passing a {type(data).__name__} to {type(self).__name__} "
388 "is deprecated and will raise in a future version. "
389 "Use public APIs instead.",
390 Pandas4Warning,
391 stacklevel=2,
392 )
393 data = data.copy(deep=False)
394 # GH#33357 called with just the SingleBlockManager
395 NDFrame.__init__(self, data)
396 self.name = name
397 return
399 if isinstance(data, (ExtensionArray, np.ndarray)):
400 if copy is not False:
401 if dtype is None or astype_is_view(data.dtype, pandas_dtype(dtype)):
402 data = data.copy()
403 copy = False
404 if copy is None:
405 copy = False
407 if isinstance(data, SingleBlockManager) and not copy:
408 data = data.copy(deep=False)
410 if not allow_mgr:
411 warnings.warn(
412 f"Passing a {type(data).__name__} to {type(self).__name__} "
413 "is deprecated and will raise in a future version. "
414 "Use public APIs instead.",
415 Pandas4Warning,
416 stacklevel=2,
417 )
418 allow_mgr = True
420 name = ibase.maybe_extract_name(name, data, type(self))
422 if index is not None:
423 index = ensure_index(index)
425 if dtype is not None:
426 dtype = self._validate_dtype(dtype)
428 if data is None:
429 index = index if index is not None else default_index(0)
430 if len(index) or dtype is not None:
431 data = na_value_for_dtype(pandas_dtype(dtype), compat=False)
432 else:
433 data = []
435 if isinstance(data, MultiIndex):
436 raise NotImplementedError(
437 "initializing a Series from a MultiIndex is not supported"
438 )
440 refs = None
441 if isinstance(data, Index):
442 if dtype is not None:
443 data = data.astype(dtype)
444 if not copy:
445 refs = data._references
447 elif isinstance(data, np.ndarray):
448 if len(data.dtype):
449 # GH#13296 we are dealing with a compound dtype, which
450 # should be treated as 2D
451 raise ValueError(
452 "Cannot construct a Series from an ndarray with "
453 "compound dtype. Use DataFrame instead."
454 )
455 elif isinstance(data, Series):
456 if index is None:
457 index = data.index
458 data = data._mgr.copy(deep=False)
459 else:
460 data = data.reindex(index)
461 data = data._mgr
462 if data._has_no_reference(0):
463 copy = False
464 elif isinstance(data, Mapping):
465 data, index = self._init_dict(data, index, dtype)
466 dtype = None
467 copy = False
468 elif isinstance(data, SingleBlockManager):
469 if index is None:
470 index = data.index
471 elif not data.index.equals(index) or copy:
472 # GH#19275 SingleBlockManager input should only be called
473 # internally
474 raise AssertionError(
475 "Cannot pass both SingleBlockManager "
476 "`data` argument and a different "
477 "`index` argument. `copy` must be False."
478 )
480 if not allow_mgr:
481 warnings.warn(
482 f"Passing a {type(data).__name__} to {type(self).__name__} "
483 "is deprecated and will raise in a future version. "
484 "Use public APIs instead.",
485 Pandas4Warning,
486 stacklevel=2,
487 )
488 allow_mgr = True
490 elif isinstance(data, ExtensionArray):
491 pass
492 else:
493 data = com.maybe_iterable_to_list(data)
494 if is_list_like(data) and not len(data) and dtype is None:
495 # GH 29405: Pre-2.0, this defaulted to float.
496 dtype = np.dtype(object)
498 if index is None:
499 if not is_list_like(data):
500 data = [data]
501 index = default_index(len(data))
502 elif is_list_like(data):
503 com.require_length_match(data, index)
505 # create/copy the manager
506 if isinstance(data, SingleBlockManager):
507 if dtype is not None:
508 if not astype_is_view(data.dtype, pandas_dtype(dtype)):
509 copy = False
510 data = data.astype(dtype=dtype)
511 if copy:
512 data = data.copy(deep=True)
513 else:
514 data = sanitize_array(data, index, dtype, copy)
515 data = SingleBlockManager.from_array(data, index, refs=refs)
517 NDFrame.__init__(self, data)
518 self.name = name
519 self._set_axis(0, index)
521 def _init_dict(
522 self, data: Mapping, index: Index | None = None, dtype: DtypeObj | None = None
523 ):
524 """
525 Derive the "_mgr" and "index" attributes of a new Series from a
526 dictionary input.
528 Parameters
529 ----------
530 data : dict or dict-like
531 Data used to populate the new Series.
532 index : Index or None, default None
533 Index for the new Series: if None, use dict keys.
534 dtype : np.dtype, ExtensionDtype, or None, default None
535 The dtype for the new Series: if None, infer from data.
537 Returns
538 -------
539 _data : BlockManager for the new Series
540 index : index for the new Series
541 """
542 # Looking for NaN in dict doesn't work ({np.nan : 1}[float('nan')]
543 # raises KeyError), so we iterate the entire dict, and align
544 if data:
545 # GH:34717, issue was using zip to extract key and values from data.
546 # using generators in effects the performance.
547 # Below is the new way of extracting the keys and values
549 keys = maybe_sequence_to_range(tuple(data.keys()))
550 values = list(data.values()) # Generating list of values- faster way
551 elif index is not None:
552 # fastpath for Series(data=None). Just use broadcasting a scalar
553 # instead of reindexing.
554 if len(index) or dtype is not None:
555 values = na_value_for_dtype(pandas_dtype(dtype), compat=False)
556 else:
557 values = []
558 keys = index
559 else:
560 keys, values = default_index(0), []
562 # Input is now list-like, so rely on "standard" construction:
563 s = Series(values, index=keys, dtype=dtype)
565 # Now we just make sure the order is respected, if any
566 if data and index is not None:
567 s = s.reindex(index)
568 return s._mgr, s.index
570 # ----------------------------------------------------------------------
572 def __arrow_c_stream__(self, requested_schema=None):
573 """
574 Export the pandas Series as an Arrow C stream PyCapsule.
576 This relies on pyarrow to convert the pandas Series to the Arrow
577 format (and follows the default behavior of ``pyarrow.Array.from_pandas``
578 in its handling of the index, i.e. to ignore it).
579 This conversion is not necessarily zero-copy.
581 Parameters
582 ----------
583 requested_schema : PyCapsule, default None
584 The schema to which the dataframe should be casted, passed as a
585 PyCapsule containing a C ArrowSchema representation of the
586 requested schema.
588 Returns
589 -------
590 PyCapsule
591 """
592 pa = import_optional_dependency("pyarrow", min_version="16.0.0")
593 type = (
594 pa.DataType._import_from_c_capsule(requested_schema)
595 if requested_schema is not None
596 else None
597 )
598 ca = pa.array(self, type=type)
599 if not isinstance(ca, pa.ChunkedArray):
600 ca = pa.chunked_array([ca])
601 return ca.__arrow_c_stream__()
603 # ----------------------------------------------------------------------
605 @property
606 def _constructor(self) -> type[Series]:
607 return Series
609 def _constructor_from_mgr(self, mgr, axes):
610 ser = Series._from_mgr(mgr, axes=axes)
611 ser._name = None # caller is responsible for setting real name
613 if type(self) is Series:
614 # This would also work `if self._constructor is Series`, but
615 # this check is slightly faster, benefiting the most-common case.
616 return ser
618 # We assume that the subclass __init__ knows how to handle a
619 # pd.Series object.
620 return self._constructor(ser)
622 @property
623 def _constructor_expanddim(self) -> Callable[..., DataFrame]:
624 """
625 Used when a manipulation result has one higher dimension as the
626 original, such as Series.to_frame()
627 """
628 from pandas.core.frame import DataFrame
630 return DataFrame
632 def _constructor_expanddim_from_mgr(self, mgr, axes):
633 from pandas.core.frame import DataFrame
635 df = DataFrame._from_mgr(mgr, axes=mgr.axes)
637 if type(self) is Series:
638 # This would also work `if self._constructor_expanddim is DataFrame`,
639 # but this check is slightly faster, benefiting the most-common case.
640 return df
642 # We assume that the subclass __init__ knows how to handle a
643 # pd.DataFrame object.
644 return self._constructor_expanddim(df)
646 # types
647 @property
648 def _can_hold_na(self) -> bool:
649 return self._mgr._can_hold_na
651 # ndarray compatibility
652 @property
653 def dtype(self) -> DtypeObj:
654 """
655 Return the dtype object of the underlying data.
657 See Also
658 --------
659 Series.dtypes : Return the dtype object of the underlying data.
660 Series.astype : Cast a pandas object to a specified dtype dtype.
661 Series.convert_dtypes : Convert columns to the best possible dtypes using dtypes
662 supporting pd.NA.
664 Examples
665 --------
666 >>> s = pd.Series([1, 2, 3])
667 >>> s.dtype
668 dtype('int64')
669 """
670 return self._mgr.dtype
672 @property
673 def dtypes(self) -> DtypeObj:
674 """
675 Return the dtype object of the underlying data.
677 See Also
678 --------
679 DataFrame.dtypes : Return the dtypes in the DataFrame.
681 Examples
682 --------
683 >>> s = pd.Series([1, 2, 3])
684 >>> s.dtypes
685 dtype('int64')
686 """
687 # DataFrame compatibility
688 return self.dtype
690 @property
691 def name(self) -> Hashable:
692 """
693 Return the name of the Series.
695 The name of a Series becomes its index or column name if it is used
696 to form a DataFrame. It is also used whenever displaying the Series
697 using the interpreter.
699 Returns
700 -------
701 label (hashable object)
702 The name of the Series, also the column name if part of a DataFrame.
704 See Also
705 --------
706 Series.rename : Sets the Series name when given a scalar input.
707 Index.name : Corresponding Index property.
709 Examples
710 --------
711 The Series name can be set initially when calling the constructor.
713 >>> s = pd.Series([1, 2, 3], dtype=np.int64, name="Numbers")
714 >>> s
715 0 1
716 1 2
717 2 3
718 Name: Numbers, dtype: int64
719 >>> s.name = "Integers"
720 >>> s
721 0 1
722 1 2
723 2 3
724 Name: Integers, dtype: int64
726 The name of a Series within a DataFrame is its column name.
728 >>> df = pd.DataFrame(
729 ... [[1, 2], [3, 4], [5, 6]], columns=["Odd Numbers", "Even Numbers"]
730 ... )
731 >>> df
732 Odd Numbers Even Numbers
733 0 1 2
734 1 3 4
735 2 5 6
736 >>> df["Even Numbers"].name
737 'Even Numbers'
738 """
739 return self._name
741 @name.setter
742 def name(self, value: Hashable) -> None:
743 validate_all_hashable(value, error_name=f"{type(self).__name__}.name")
744 object.__setattr__(self, "_name", value)
746 @property
747 def values(self):
748 """
749 Return Series as ndarray or ndarray-like depending on the dtype.
751 .. warning::
753 We recommend using :attr:`Series.array` or
754 :meth:`Series.to_numpy`, depending on whether you need
755 a reference to the underlying data or a NumPy array.
757 Returns
758 -------
759 numpy.ndarray or ndarray-like
761 See Also
762 --------
763 Series.array : Reference to the underlying data.
764 Series.to_numpy : A NumPy array representing the underlying data.
766 Examples
767 --------
768 >>> pd.Series([1, 2, 3]).values
769 array([1, 2, 3])
771 >>> pd.Series(list("aabc")).values
772 <ArrowStringArray>
773 ['a', 'a', 'b', 'c']
774 Length: 4, dtype: str
776 >>> pd.Series(list("aabc")).astype("category").values
777 ['a', 'a', 'b', 'c']
778 Categories (3, str): ['a', 'b', 'c']
780 Timezone aware datetime data is converted to UTC:
782 >>> pd.Series(pd.date_range("20130101", periods=3, tz="US/Eastern")).values
783 array(['2013-01-01T05:00:00.000000',
784 '2013-01-02T05:00:00.000000',
785 '2013-01-03T05:00:00.000000'], dtype='datetime64[us]')
786 """
787 return self._mgr.external_values()
789 @property
790 def _values(self):
791 """
792 Return the internal repr of this data (defined by Block.interval_values).
793 This are the values as stored in the Block (ndarray or ExtensionArray
794 depending on the Block class), with datetime64[ns] and timedelta64[ns]
795 wrapped in ExtensionArrays to match Index._values behavior.
797 Differs from the public ``.values`` for certain data types, because of
798 historical backwards compatibility of the public attribute (e.g. period
799 returns object ndarray and datetimetz a datetime64[ns] ndarray for
800 ``.values`` while it returns an ExtensionArray for ``._values`` in those
801 cases).
803 Differs from ``.array`` in that this still returns the numpy array if
804 the Block is backed by a numpy array (except for datetime64 and
805 timedelta64 dtypes), while ``.array`` ensures to always return an
806 ExtensionArray.
808 Overview:
810 dtype | values | _values | array |
811 ----------- | ------------- | ------------- | --------------------- |
812 Numeric | ndarray | ndarray | NumpyExtensionArray |
813 Category | Categorical | Categorical | Categorical |
814 dt64[ns] | ndarray[M8ns] | DatetimeArray | DatetimeArray |
815 dt64[ns tz] | ndarray[M8ns] | DatetimeArray | DatetimeArray |
816 td64[ns] | ndarray[m8ns] | TimedeltaArray| TimedeltaArray |
817 Period | ndarray[obj] | PeriodArray | PeriodArray |
818 Nullable | EA | EA | EA |
820 """
821 return self._mgr.internal_values()
823 @property
824 def _references(self) -> BlockValuesRefs:
825 return self._mgr._block.refs
827 @Appender(base.IndexOpsMixin.array.__doc__) # type: ignore[prop-decorator]
828 @property
829 def array(self) -> ExtensionArray:
830 arr = self._mgr.array_values()
831 # TODO decide on read-only https://github.com/pandas-dev/pandas/issues/63099
832 # arr = arr.view()
833 # arr._readonly = True
834 return arr
836 def __len__(self) -> int:
837 """
838 Return the length of the Series.
839 """
840 return len(self._mgr)
842 # ----------------------------------------------------------------------
843 # NDArray Compat
844 def __array__(
845 self, dtype: npt.DTypeLike | None = None, copy: bool | None = None
846 ) -> np.ndarray:
847 """
848 Return the values as a NumPy array.
850 Users should not call this directly. Rather, it is invoked by
851 :func:`numpy.array` and :func:`numpy.asarray`.
853 Parameters
854 ----------
855 dtype : str or numpy.dtype, optional
856 The dtype to use for the resulting NumPy array. By default,
857 the dtype is inferred from the data.
859 copy : bool or None, optional
860 See :func:`numpy.asarray`.
862 Returns
863 -------
864 numpy.ndarray
865 The values in the series converted to a :class:`numpy.ndarray`
866 with the specified `dtype`.
868 See Also
869 --------
870 array : Create a new array from data.
871 Series.array : Zero-copy view to the array backing the Series.
872 Series.to_numpy : Series method for similar behavior.
874 Examples
875 --------
876 >>> ser = pd.Series([1, 2, 3])
877 >>> np.asarray(ser)
878 array([1, 2, 3])
880 For timezone-aware data, the timezones may be retained with
881 ``dtype='object'``
883 >>> tzser = pd.Series(pd.date_range("2000", periods=2, tz="CET"))
884 >>> np.asarray(tzser, dtype="object")
885 array([Timestamp('2000-01-01 00:00:00+0100', tz='CET'),
886 Timestamp('2000-01-02 00:00:00+0100', tz='CET')],
887 dtype=object)
889 Or the values may be localized to UTC and the tzinfo discarded with
890 ``dtype='datetime64[ns]'``
892 >>> np.asarray(tzser, dtype="datetime64[ns]") # doctest: +ELLIPSIS
893 array(['1999-12-31T23:00:00.000000000', ...],
894 dtype='datetime64[ns]')
895 """
896 values = self._values
897 if copy is None:
898 # Note: branch avoids `copy=None` for NumPy 1.x support
899 arr = np.asarray(values, dtype=dtype)
900 else:
901 arr = np.array(values, dtype=dtype, copy=copy)
903 if copy is True:
904 return arr
905 if copy is False or astype_is_view(values.dtype, arr.dtype):
906 arr = arr.view()
907 arr.flags.writeable = False
908 return arr
910 # ----------------------------------------------------------------------
912 # indexers
913 @property
914 def axes(self) -> list[Index]:
915 """
916 Return a list of the row axis labels.
917 """
918 return [self.index]
920 # ----------------------------------------------------------------------
921 # Indexing Methods
923 def _ixs(self, i: int, axis: AxisInt = 0) -> Any:
924 """
925 Return the i-th value or values in the Series by location.
927 Parameters
928 ----------
929 i : int
931 Returns
932 -------
933 scalar
934 """
935 return self._values[i]
937 def _slice(self, slobj: slice, axis: AxisInt = 0) -> Series:
938 # axis kwarg is retained for compat with NDFrame method
939 # _slice is *always* positional
940 mgr = self._mgr.get_slice(slobj, axis=axis)
941 out = self._constructor_from_mgr(mgr, axes=mgr.axes)
942 out._name = self._name
943 return out.__finalize__(self)
945 def __getitem__(self, key):
946 check_dict_or_set_indexers(key)
947 key = com.apply_if_callable(key, self)
949 if key is Ellipsis:
950 return self.copy(deep=False)
952 key_is_scalar = is_scalar(key)
953 if isinstance(key, (list, tuple)):
954 key = unpack_1tuple(key)
956 elif key_is_scalar:
957 # Note: GH#50617 in 3.0 we changed int key to always be treated as
958 # a label, matching DataFrame behavior.
959 return self._get_value(key)
961 # Convert generator to list before going through hashable part
962 # (We will iterate through the generator there to check for slices)
963 if is_iterator(key):
964 key = list(key)
966 if is_hashable(key, allow_slice=False):
967 # Otherwise index.get_value will raise InvalidIndexError
968 try:
969 # For labels that don't resolve as scalars like tuples and frozensets
970 result = self._get_value(key)
972 return result
974 except (KeyError, TypeError, InvalidIndexError):
975 # InvalidIndexError for e.g. generator
976 # see test_series_getitem_corner_generator
977 if isinstance(key, tuple) and isinstance(self.index, MultiIndex):
978 # We still have the corner case where a tuple is a key
979 # in the first level of our MultiIndex
980 return self._get_values_tuple(key)
982 if isinstance(key, slice):
983 # Do slice check before somewhat-costly is_bool_indexer
984 return self._getitem_slice(key)
986 if com.is_bool_indexer(key):
987 key = check_bool_indexer(self.index, key)
988 key = np.asarray(key, dtype=bool)
989 return self._get_rows_with_mask(key)
991 return self._get_with(key)
993 def _get_with(self, key):
994 # other: fancy integer or otherwise
995 if isinstance(key, ABCDataFrame):
996 raise TypeError(
997 "Indexing a Series with DataFrame is not "
998 "supported, use the appropriate DataFrame column"
999 )
1000 elif isinstance(key, tuple):
1001 return self._get_values_tuple(key)
1003 return self.loc[key]
1005 def _get_values_tuple(self, key: tuple):
1006 # mpl hackaround
1007 if com.any_none(*key):
1008 # mpl compat if we look up e.g. ser[:, np.newaxis];
1009 # see tests.series.timeseries.test_mpl_compat_hack
1010 # the asarray is needed to avoid returning a 2D DatetimeArray
1011 result = np.asarray(self._values[key])
1012 disallow_ndim_indexing(result)
1013 return result
1015 if not isinstance(self.index, MultiIndex):
1016 raise KeyError("key of type tuple not found and not a MultiIndex")
1018 # If key is contained, would have returned by now
1019 indexer, new_index = self.index.get_loc_level(key)
1020 new_ser = self._constructor(self._values[indexer], index=new_index, copy=False)
1021 if isinstance(indexer, slice):
1022 new_ser._mgr.add_references(self._mgr)
1023 return new_ser.__finalize__(self)
1025 def _get_rows_with_mask(self, indexer: npt.NDArray[np.bool_]) -> Series:
1026 new_mgr = self._mgr.get_rows_with_mask(indexer)
1027 return self._constructor_from_mgr(new_mgr, axes=new_mgr.axes).__finalize__(self)
1029 def _get_value(self, label, takeable: bool = False):
1030 """
1031 Quickly retrieve single value at passed index label.
1033 Parameters
1034 ----------
1035 label : object
1036 takeable : interpret the index as indexers, default False
1038 Returns
1039 -------
1040 scalar value
1041 """
1042 if takeable:
1043 return self._values[label]
1045 # Similar to Index.get_value, but we do not fall back to positional
1046 loc = self.index.get_loc(label)
1048 if is_integer(loc):
1049 return self._values[loc]
1051 if isinstance(self.index, MultiIndex):
1052 mi = self.index
1053 new_values = self._values[loc]
1054 if len(new_values) == 1 and mi.nlevels == 1:
1055 # If more than one level left, we can not return a scalar
1056 return new_values[0]
1058 new_index = mi[loc]
1059 new_index = maybe_droplevels(new_index, label)
1060 new_ser = self._constructor(
1061 new_values, index=new_index, name=self.name, copy=False
1062 )
1063 if isinstance(loc, slice):
1064 new_ser._mgr.add_references(self._mgr)
1065 return new_ser.__finalize__(self)
1067 else:
1068 return self.iloc[loc]
1070 def __setitem__(self, key, value) -> None:
1071 if not CHAINED_WARNING_DISABLED:
1072 if sys.getrefcount(self) <= REF_COUNT and not com.is_local_in_caller_frame(
1073 self
1074 ):
1075 warnings.warn(
1076 _chained_assignment_msg, ChainedAssignmentError, stacklevel=2
1077 )
1079 check_dict_or_set_indexers(key)
1080 key = com.apply_if_callable(key, self)
1082 if key is Ellipsis:
1083 key = slice(None)
1085 if isinstance(key, slice):
1086 indexer = self.index._convert_slice_indexer(key, kind="getitem")
1087 return self._set_values(indexer, value)
1089 try:
1090 self._set_with_engine(key, value)
1091 except KeyError:
1092 # We have a scalar (or for MultiIndex or object-dtype, scalar-like)
1093 # key that is not present in self.index.
1094 # GH#12862 adding a new key to the Series
1095 self.loc[key] = value
1097 except (TypeError, ValueError, LossySetitemError):
1098 # The key was OK, but we cannot set the value losslessly
1099 indexer = self.index.get_loc(key)
1100 self._set_values(indexer, value)
1102 except InvalidIndexError as err:
1103 if isinstance(key, tuple) and not isinstance(self.index, MultiIndex):
1104 # cases with MultiIndex don't get here bc they raise KeyError
1105 # e.g. test_basic_getitem_setitem_corner
1106 raise KeyError(
1107 "key of type tuple not found and not a MultiIndex"
1108 ) from err
1110 if com.is_bool_indexer(key):
1111 key = check_bool_indexer(self.index, key)
1112 key = np.asarray(key, dtype=bool)
1114 if (
1115 is_list_like(value)
1116 and len(value) != len(self)
1117 and not isinstance(value, Series)
1118 and not is_object_dtype(self.dtype)
1119 ):
1120 # Series will be reindexed to have matching length inside
1121 # _where call below
1122 # GH#44265
1123 indexer = key.nonzero()[0]
1124 self._set_values(indexer, value)
1125 return
1127 # otherwise with listlike other we interpret series[mask] = other
1128 # as series[mask] = other[mask]
1129 try:
1130 self._where(~key, value, inplace=True)
1131 except InvalidIndexError:
1132 # test_where_dups
1133 self.iloc[key] = value
1134 return
1136 else:
1137 self._set_with(key, value)
1139 def _set_with_engine(self, key, value) -> None:
1140 loc = self.index.get_loc(key)
1142 # this is equivalent to self._values[key] = value
1143 self._mgr.setitem_inplace(loc, value)
1145 def _set_with(self, key, value) -> None:
1146 # We got here via exception-handling off of InvalidIndexError, so
1147 # key should always be listlike at this point.
1148 assert not isinstance(key, tuple)
1150 if is_iterator(key):
1151 # Without this, the call to infer_dtype will consume the generator
1152 key = list(key)
1154 self._set_labels(key, value)
1156 def _set_labels(self, key, value) -> None:
1157 key = com.asarray_tuplesafe(key)
1158 indexer: np.ndarray = self.index.get_indexer(key)
1159 mask = indexer == -1
1160 if mask.any():
1161 raise KeyError(f"{key[mask]} not in index")
1162 self._set_values(indexer, value)
1164 def _set_values(self, key, value) -> None:
1165 if isinstance(key, (Index, Series)):
1166 key = key._values
1168 self._mgr = self._mgr.setitem(indexer=key, value=value)
1170 def _set_value(self, label, value, takeable: bool = False) -> None:
1171 """
1172 Quickly set single value at passed label.
1174 If label is not contained, a new object is created with the label
1175 placed at the end of the result index.
1177 Parameters
1178 ----------
1179 label : object
1180 Partial indexing with MultiIndex not allowed.
1181 value : object
1182 Scalar value.
1183 takeable : interpret the index as indexers, default False
1184 """
1185 if not takeable:
1186 try:
1187 loc = self.index.get_loc(label)
1188 except KeyError:
1189 # set using a non-recursive method
1190 self.loc[label] = value
1191 return
1192 else:
1193 loc = label
1195 self._set_values(loc, value)
1197 # ----------------------------------------------------------------------
1198 # Unsorted
1200 def repeat(self, repeats: int | Sequence[int], axis: None = None) -> Series:
1201 """
1202 Repeat elements of a Series.
1204 Returns a new Series where each element of the current Series
1205 is repeated consecutively a given number of times.
1207 Parameters
1208 ----------
1209 repeats : int or array of ints
1210 The number of repetitions for each element. This should be a
1211 non-negative integer. Repeating 0 times will return an empty
1212 Series.
1213 axis : None
1214 Unused. Parameter needed for compatibility with DataFrame.
1216 Returns
1217 -------
1218 Series
1219 Newly created Series with repeated elements.
1221 See Also
1222 --------
1223 Index.repeat : Equivalent function for Index.
1224 numpy.repeat : Similar method for :class:`numpy.ndarray`.
1226 Examples
1227 --------
1228 >>> s = pd.Series(["a", "b", "c"])
1229 >>> s
1230 0 a
1231 1 b
1232 2 c
1233 dtype: str
1234 >>> s.repeat(2)
1235 0 a
1236 0 a
1237 1 b
1238 1 b
1239 2 c
1240 2 c
1241 dtype: str
1242 >>> s.repeat([1, 2, 3])
1243 0 a
1244 1 b
1245 1 b
1246 2 c
1247 2 c
1248 2 c
1249 dtype: str
1250 """
1251 nv.validate_repeat((), {"axis": axis})
1252 new_index = self.index.repeat(repeats)
1253 new_values = self._values.repeat(repeats)
1254 return self._constructor(new_values, index=new_index, copy=False).__finalize__(
1255 self, method="repeat"
1256 )
1258 @overload
1259 def reset_index(
1260 self,
1261 level: IndexLabel = ...,
1262 *,
1263 drop: Literal[False] = ...,
1264 name: Level = ...,
1265 inplace: Literal[False] = ...,
1266 allow_duplicates: bool = ...,
1267 ) -> DataFrame: ...
1269 @overload
1270 def reset_index(
1271 self,
1272 level: IndexLabel = ...,
1273 *,
1274 drop: Literal[True],
1275 name: Level = ...,
1276 inplace: Literal[False] = ...,
1277 allow_duplicates: bool = ...,
1278 ) -> Series: ...
1280 @overload
1281 def reset_index(
1282 self,
1283 level: IndexLabel = ...,
1284 *,
1285 drop: bool = ...,
1286 name: Level = ...,
1287 inplace: Literal[True],
1288 allow_duplicates: bool = ...,
1289 ) -> None: ...
1291 def reset_index(
1292 self,
1293 level: IndexLabel | None = None,
1294 *,
1295 drop: bool = False,
1296 name: Level = lib.no_default,
1297 inplace: bool = False,
1298 allow_duplicates: bool = False,
1299 ) -> DataFrame | Series | None:
1300 """
1301 Generate a new DataFrame or Series with the index reset.
1303 This is useful when the index needs to be treated as a column, or
1304 when the index is meaningless and needs to be reset to the default
1305 before another operation.
1307 Parameters
1308 ----------
1309 level : int, str, tuple, or list, default optional
1310 For a Series with a MultiIndex, only remove the specified levels
1311 from the index. Removes all levels by default.
1312 drop : bool, default False
1313 Just reset the index, without inserting it as a column in
1314 the new DataFrame.
1315 name : object, optional
1316 The name to use for the column containing the original Series
1317 values. Uses ``self.name`` by default. This argument is ignored
1318 when `drop` is True.
1319 inplace : bool, default False
1320 Modify the Series in place (do not create a new object).
1321 allow_duplicates : bool, default False
1322 Allow duplicate column labels to be created.
1324 Returns
1325 -------
1326 Series or DataFrame or None
1327 When `drop` is False (the default), a DataFrame is returned.
1328 The newly created columns will come first in the DataFrame,
1329 followed by the original Series values.
1330 When `drop` is True, a `Series` is returned.
1331 In either case, if ``inplace=True``, no value is returned.
1333 See Also
1334 --------
1335 DataFrame.reset_index: Analogous function for DataFrame.
1337 Examples
1338 --------
1339 >>> s = pd.Series(
1340 ... [1, 2, 3, 4],
1341 ... name="foo",
1342 ... index=pd.Index(["a", "b", "c", "d"], name="idx"),
1343 ... )
1345 Generate a DataFrame with default index.
1347 >>> s.reset_index()
1348 idx foo
1349 0 a 1
1350 1 b 2
1351 2 c 3
1352 3 d 4
1354 To specify the name of the new column use `name`.
1356 >>> s.reset_index(name="values")
1357 idx values
1358 0 a 1
1359 1 b 2
1360 2 c 3
1361 3 d 4
1363 To generate a new Series with the default set `drop` to True.
1365 >>> s.reset_index(drop=True)
1366 0 1
1367 1 2
1368 2 3
1369 3 4
1370 Name: foo, dtype: int64
1372 The `level` parameter is interesting for Series with a multi-level
1373 index.
1375 >>> arrays = [
1376 ... np.array(["bar", "bar", "baz", "baz"]),
1377 ... np.array(["one", "two", "one", "two"]),
1378 ... ]
1379 >>> s2 = pd.Series(
1380 ... range(4),
1381 ... name="foo",
1382 ... index=pd.MultiIndex.from_arrays(arrays, names=["a", "b"]),
1383 ... )
1385 To remove a specific level from the Index, use `level`.
1387 >>> s2.reset_index(level="a")
1388 a foo
1389 b
1390 one bar 0
1391 two bar 1
1392 one baz 2
1393 two baz 3
1395 If `level` is not set, all levels are removed from the Index.
1397 >>> s2.reset_index()
1398 a b foo
1399 0 bar one 0
1400 1 bar two 1
1401 2 baz one 2
1402 3 baz two 3
1403 """
1404 inplace = validate_bool_kwarg(inplace, "inplace")
1405 if drop:
1406 new_index = default_index(len(self))
1407 if level is not None:
1408 level_list: Sequence[Hashable]
1409 if not isinstance(level, (tuple, list)):
1410 level_list = [level]
1411 else:
1412 level_list = level
1413 level_list = [self.index._get_level_number(lev) for lev in level_list]
1414 if len(level_list) < self.index.nlevels:
1415 new_index = self.index.droplevel(level_list)
1417 if inplace:
1418 self.index = new_index
1419 else:
1420 new_ser = self.copy(deep=False)
1421 new_ser.index = new_index
1422 return new_ser.__finalize__(self, method="reset_index")
1423 elif inplace:
1424 raise TypeError(
1425 "Cannot reset_index inplace on a Series to create a DataFrame"
1426 )
1427 else:
1428 if name is lib.no_default:
1429 # For backwards compatibility, keep columns as [0] instead of
1430 # [None] when self.name is None
1431 if self.name is None:
1432 name = 0
1433 else:
1434 name = self.name
1436 df = self.to_frame(name)
1437 return df.reset_index(
1438 level=level, drop=drop, allow_duplicates=allow_duplicates
1439 )
1440 return None
1442 # ----------------------------------------------------------------------
1443 # Rendering Methods
1445 def __repr__(self) -> str:
1446 """
1447 Return a string representation for a particular Series.
1448 """
1449 repr_params = fmt.get_series_repr_params()
1450 return self.to_string(**repr_params)
1452 @overload
1453 def to_string(
1454 self,
1455 buf: None = ...,
1456 *,
1457 na_rep: str = ...,
1458 float_format: str | None = ...,
1459 header: bool = ...,
1460 index: bool = ...,
1461 length: bool = ...,
1462 dtype=...,
1463 name=...,
1464 max_rows: int | None = ...,
1465 min_rows: int | None = ...,
1466 ) -> str: ...
1468 @overload
1469 def to_string(
1470 self,
1471 buf: FilePath | WriteBuffer[str],
1472 *,
1473 na_rep: str = ...,
1474 float_format: str | None = ...,
1475 header: bool = ...,
1476 index: bool = ...,
1477 length: bool = ...,
1478 dtype=...,
1479 name=...,
1480 max_rows: int | None = ...,
1481 min_rows: int | None = ...,
1482 ) -> None: ...
1484 @deprecate_nonkeyword_arguments(
1485 Pandas4Warning, allowed_args=["self", "buf"], name="to_string"
1486 )
1487 def to_string(
1488 self,
1489 buf: FilePath | WriteBuffer[str] | None = None,
1490 na_rep: str = "NaN",
1491 float_format: str | None = None,
1492 header: bool = True,
1493 index: bool = True,
1494 length: bool = False,
1495 dtype: bool = False,
1496 name: bool = False,
1497 max_rows: int | None = None,
1498 min_rows: int | None = None,
1499 ) -> str | None:
1500 """
1501 Render a string representation of the Series.
1503 Parameters
1504 ----------
1505 buf : StringIO-like, optional
1506 Buffer to write to.
1507 na_rep : str, optional
1508 String representation of NaN to use, default 'NaN'.
1509 float_format : one-parameter function, optional
1510 Formatter function to apply to columns' elements if they are
1511 floats, default None.
1512 header : bool, default True
1513 Add the Series header (index name).
1514 index : bool, optional
1515 Add index (row) labels, default True.
1516 length : bool, default False
1517 Add the Series length.
1518 dtype : bool, default False
1519 Add the Series dtype.
1520 name : bool, default False
1521 Add the Series name if not None.
1522 max_rows : int, optional
1523 Maximum number of rows to show before truncating. If None, show
1524 all.
1525 min_rows : int, optional
1526 The number of rows to display in a truncated repr (when number
1527 of rows is above `max_rows`).
1529 Returns
1530 -------
1531 str or None
1532 String representation of Series if ``buf=None``, otherwise None.
1534 See Also
1535 --------
1536 Series.to_dict : Convert Series to dict object.
1537 Series.to_frame : Convert Series to DataFrame object.
1538 Series.to_markdown : Print Series in Markdown-friendly format.
1539 Series.to_timestamp : Cast to DatetimeIndex of Timestamps.
1541 Examples
1542 --------
1543 >>> ser = pd.Series([1, 2, 3]).to_string()
1544 >>> ser
1545 '0 1\\n1 2\\n2 3'
1546 """
1547 formatter = fmt.SeriesFormatter(
1548 self,
1549 name=name,
1550 length=length,
1551 header=header,
1552 index=index,
1553 dtype=dtype,
1554 na_rep=na_rep,
1555 float_format=float_format,
1556 min_rows=min_rows,
1557 max_rows=max_rows,
1558 )
1559 result = formatter.to_string()
1561 # catch contract violations
1562 if not isinstance(result, str):
1563 raise AssertionError(
1564 "result must be of type str, type "
1565 f"of result is {type(result).__name__!r}"
1566 )
1568 if buf is None:
1569 return result
1570 elif hasattr(buf, "write"):
1571 buf.write(result)
1572 else:
1573 with open(buf, "w", encoding="utf-8") as f:
1574 f.write(result)
1575 return None
1577 @overload
1578 def to_markdown(
1579 self,
1580 buf: None = ...,
1581 *,
1582 mode: str = ...,
1583 index: bool = ...,
1584 storage_options: StorageOptions | None = ...,
1585 **kwargs,
1586 ) -> str: ...
1588 @overload
1589 def to_markdown(
1590 self,
1591 buf: IO[str],
1592 *,
1593 mode: str = ...,
1594 index: bool = ...,
1595 storage_options: StorageOptions | None = ...,
1596 **kwargs,
1597 ) -> None: ...
1599 @overload
1600 def to_markdown(
1601 self,
1602 buf: IO[str] | None,
1603 *,
1604 mode: str = ...,
1605 index: bool = ...,
1606 storage_options: StorageOptions | None = ...,
1607 **kwargs,
1608 ) -> str | None: ...
1610 @deprecate_nonkeyword_arguments(
1611 Pandas4Warning, allowed_args=["self", "buf"], name="to_markdown"
1612 )
1613 def to_markdown(
1614 self,
1615 buf: IO[str] | None = None,
1616 mode: str = "wt",
1617 index: bool = True,
1618 storage_options: StorageOptions | None = None,
1619 **kwargs,
1620 ) -> str | None:
1621 """
1622 Print Series in Markdown-friendly format.
1624 Parameters
1625 ----------
1626 buf : str, Path or StringIO-like, optional, default None
1627 Buffer to write to. If None, the output is returned as a string.
1628 mode : str, optional
1629 Mode in which file is opened, "wt" by default.
1630 index : bool, optional, default True
1631 Add index (row) labels.
1633 storage_options : dict, optional
1634 Extra options that make sense for a particular storage connection, e.g.
1635 host, port, username, password, etc. For HTTP(S) URLs the key-value pairs
1636 are forwarded to ``urllib.request.Request`` as header options. For other
1637 URLs (e.g. starting with "s3://", and "gcs://") the key-value pairs are
1638 forwarded to ``fsspec.open``. Please see ``fsspec`` and ``urllib`` for more
1639 details, and for more examples on storage options refer `here
1640 <https://pandas.pydata.org/docs/user_guide/io.html?
1641 highlight=storage_options#reading-writing-remote-files>`_.
1643 **kwargs
1644 These parameters will be passed to `tabulate \
1645 <https://pypi.org/project/tabulate>`_.
1647 Returns
1648 -------
1649 str
1650 Series in Markdown-friendly format.
1652 See Also
1653 --------
1654 Series.to_frame : Rrite a text representation of object to the system clipboard.
1655 Series.to_latex : Render Series to LaTeX-formatted table.
1657 Notes
1658 -----
1659 Requires the `tabulate <https://pypi.org/project/tabulate>`_ package.
1661 Examples
1662 --------
1663 >>> s = pd.Series(["elk", "pig", "dog", "quetzal"], name="animal")
1664 >>> print(s.to_markdown())
1665 | | animal |
1666 |---:|:---------|
1667 | 0 | elk |
1668 | 1 | pig |
1669 | 2 | dog |
1670 | 3 | quetzal |
1672 Output markdown with a tabulate option.
1674 >>> print(s.to_markdown(tablefmt="grid"))
1675 +----+----------+
1676 | | animal |
1677 +====+==========+
1678 | 0 | elk |
1679 +----+----------+
1680 | 1 | pig |
1681 +----+----------+
1682 | 2 | dog |
1683 +----+----------+
1684 | 3 | quetzal |
1685 +----+----------+
1686 """
1687 return self.to_frame().to_markdown(
1688 buf, mode=mode, index=index, storage_options=storage_options, **kwargs
1689 )
1691 # ----------------------------------------------------------------------
1693 def items(self) -> Iterable[tuple[Hashable, Any]]:
1694 """
1695 Lazily iterate over (index, value) tuples.
1697 This method returns an iterable tuple (index, value). This is
1698 convenient if you want to create a lazy iterator.
1700 Returns
1701 -------
1702 iterable
1703 Iterable of tuples containing the (index, value) pairs from a
1704 Series.
1706 See Also
1707 --------
1708 DataFrame.items : Iterate over (column name, Series) pairs.
1709 DataFrame.iterrows : Iterate over DataFrame rows as (index, Series) pairs.
1711 Examples
1712 --------
1713 >>> s = pd.Series(["A", "B", "C"])
1714 >>> for index, value in s.items():
1715 ... print(f"Index : {index}, Value : {value}")
1716 Index : 0, Value : A
1717 Index : 1, Value : B
1718 Index : 2, Value : C
1719 """
1720 return zip(iter(self.index), iter(self), strict=True)
1722 # ----------------------------------------------------------------------
1723 # Misc public methods
1725 def keys(self) -> Index:
1726 """
1727 Return alias for index.
1729 Returns
1730 -------
1731 Index
1732 Index of the Series.
1734 See Also
1735 --------
1736 Series.index : The index (axis labels) of the Series.
1738 Examples
1739 --------
1740 >>> s = pd.Series([1, 2, 3], index=[0, 1, 2])
1741 >>> s.keys()
1742 Index([0, 1, 2], dtype='int64')
1743 """
1744 return self.index
1746 @overload
1747 def to_dict(
1748 self, *, into: type[MutableMappingT] | MutableMappingT
1749 ) -> MutableMappingT: ...
1751 @overload
1752 def to_dict(self, *, into: type[dict] = ...) -> dict: ...
1754 # error: Incompatible default for argument "into" (default has type "type[
1755 # dict[Any, Any]]", argument has type "type[MutableMappingT] | MutableMappingT")
1756 def to_dict(
1757 self,
1758 *,
1759 into: type[MutableMappingT] | MutableMappingT = dict, # type: ignore[assignment]
1760 ) -> MutableMappingT:
1761 """
1762 Convert Series to {label -> value} dict or dict-like object.
1764 Parameters
1765 ----------
1766 into : class, default dict
1767 The collections.abc.MutableMapping subclass to use as the return
1768 object. Can be the actual class or an empty instance of the mapping
1769 type you want. If you want a collections.defaultdict, you must
1770 pass it initialized.
1772 Returns
1773 -------
1774 collections.abc.MutableMapping
1775 Key-value representation of Series.
1777 See Also
1778 --------
1779 Series.to_list: Converts Series to a list of the values.
1780 Series.to_numpy: Converts Series to NumPy ndarray.
1781 Series.array: ExtensionArray of the data backing this Series.
1783 Examples
1784 --------
1785 >>> s = pd.Series([1, 2, 3, 4])
1786 >>> s.to_dict()
1787 {0: 1, 1: 2, 2: 3, 3: 4}
1788 >>> from collections import OrderedDict, defaultdict
1789 >>> s.to_dict(into=OrderedDict)
1790 OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
1791 >>> dd = defaultdict(list)
1792 >>> s.to_dict(into=dd)
1793 defaultdict(<class 'list'>, {0: 1, 1: 2, 2: 3, 3: 4})
1794 """
1795 # GH16122
1796 into_c = com.standardize_mapping(into)
1798 if is_object_dtype(self.dtype) or isinstance(self.dtype, ExtensionDtype):
1799 return into_c((k, maybe_box_native(v)) for k, v in self.items())
1800 else:
1801 # Not an object dtype => all types will be the same so let the default
1802 # indexer return native python type
1803 return into_c(self.items())
1805 def to_frame(self, name: Hashable = lib.no_default) -> DataFrame:
1806 """
1807 Convert Series to DataFrame.
1809 Parameters
1810 ----------
1811 name : object, optional
1812 The passed name should substitute for the series name (if it has
1813 one).
1815 Returns
1816 -------
1817 DataFrame
1818 DataFrame representation of Series.
1820 See Also
1821 --------
1822 Series.to_dict : Convert Series to dict object.
1824 Examples
1825 --------
1826 >>> s = pd.Series(["a", "b", "c"], name="vals")
1827 >>> s.to_frame()
1828 vals
1829 0 a
1830 1 b
1831 2 c
1832 """
1833 columns: Index
1834 if name is lib.no_default:
1835 name = self.name
1836 if name is None:
1837 # default to [0], same as we would get with DataFrame(self)
1838 columns = default_index(1)
1839 else:
1840 columns = Index([name])
1841 else:
1842 columns = Index([name])
1844 mgr = self._mgr.to_2d_mgr(columns)
1845 df = self._constructor_expanddim_from_mgr(mgr, axes=mgr.axes)
1846 return df.__finalize__(self, method="to_frame")
1848 @classmethod
1849 def from_arrow(cls, data: ArrowArrayExportable | ArrowStreamExportable) -> Series:
1850 """
1851 Construct a Series from an array-like Arrow object.
1853 This function accepts any Arrow-compatible array-like object implementing
1854 the `Arrow PyCapsule Protocol`_ (i.e. having an ``__arrow_c_array__``
1855 or ``__arrow_c_stream__`` method).
1857 This function currently relies on ``pyarrow`` to convert the object
1858 in Arrow format to pandas.
1860 .. _Arrow PyCapsule Protocol: https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html
1862 .. versionadded:: 3.0
1864 Parameters
1865 ----------
1866 data : pyarrow.Array or Arrow-compatible object
1867 Any array-like object implementing the Arrow PyCapsule Protocol
1868 (i.e. has an ``__arrow_c_array__`` or ``__arrow_c_stream__``
1869 method).
1871 Returns
1872 -------
1873 Series
1875 See Also
1876 --------
1877 DataFrame.from_arrow : Construct a DataFrame from an Arrow object.
1879 Examples
1880 --------
1881 >>> import pyarrow as pa
1882 >>> arrow_array = pa.array([1, 2, 3])
1883 >>> pd.Series.from_arrow(arrow_array)
1884 0 1
1885 1 2
1886 2 3
1887 dtype: int64
1888 """
1889 pa = import_optional_dependency("pyarrow", min_version="14.0.0")
1890 if not isinstance(data, (pa.Array, pa.ChunkedArray)):
1891 if not (
1892 hasattr(data, "__arrow_c_array__")
1893 or hasattr(data, "__arrow_c_stream__")
1894 ):
1895 # explicitly test this, because otherwise we would accept variour other
1896 # input types through the pa.chunked_array(..) call
1897 raise TypeError(
1898 "Expected an Arrow-compatible array-like object (i.e. having an "
1899 "'_arrow_c_array__' or '__arrow_c_stream__' method), got "
1900 f"'{type(data).__name__}' instead."
1901 )
1902 # using chunked_array() as it works for both arrays and streams
1903 pa_array = pa.chunked_array(data)
1904 else:
1905 pa_array = data
1907 ser = pa_array.to_pandas()
1908 return ser
1910 def _set_name(self, name, inplace: bool = False) -> Series:
1911 """
1912 Set the Series name.
1914 Parameters
1915 ----------
1916 name : str
1917 inplace : bool
1918 Whether to modify `self` directly or return a copy.
1919 """
1920 inplace = validate_bool_kwarg(inplace, "inplace")
1921 ser = self if inplace else self.copy(deep=False)
1922 ser.name = name
1923 return ser
1925 @Appender(
1926 dedent(
1927 """
1928 Examples
1929 --------
1930 >>> ser = pd.Series([390., 350., 30., 20.],
1931 ... index=['Falcon', 'Falcon', 'Parrot', 'Parrot'],
1932 ... name="Max Speed")
1933 >>> ser
1934 Falcon 390.0
1935 Falcon 350.0
1936 Parrot 30.0
1937 Parrot 20.0
1938 Name: Max Speed, dtype: float64
1940 We can pass a list of values to group the Series data by custom labels:
1942 >>> ser.groupby(["a", "b", "a", "b"]).mean()
1943 a 210.0
1944 b 185.0
1945 Name: Max Speed, dtype: float64
1947 Grouping by numeric labels yields similar results:
1949 >>> ser.groupby([0, 1, 0, 1]).mean()
1950 0 210.0
1951 1 185.0
1952 Name: Max Speed, dtype: float64
1954 We can group by a level of the index:
1956 >>> ser.groupby(level=0).mean()
1957 Falcon 370.0
1958 Parrot 25.0
1959 Name: Max Speed, dtype: float64
1961 We can group by a condition applied to the Series values:
1963 >>> ser.groupby(ser > 100).mean()
1964 Max Speed
1965 False 25.0
1966 True 370.0
1967 Name: Max Speed, dtype: float64
1969 **Grouping by Indexes**
1971 We can groupby different levels of a hierarchical index
1972 using the `level` parameter:
1974 >>> arrays = [['Falcon', 'Falcon', 'Parrot', 'Parrot'],
1975 ... ['Captive', 'Wild', 'Captive', 'Wild']]
1976 >>> index = pd.MultiIndex.from_arrays(arrays, names=('Animal', 'Type'))
1977 >>> ser = pd.Series([390., 350., 30., 20.], index=index, name="Max Speed")
1978 >>> ser
1979 Animal Type
1980 Falcon Captive 390.0
1981 Wild 350.0
1982 Parrot Captive 30.0
1983 Wild 20.0
1984 Name: Max Speed, dtype: float64
1986 >>> ser.groupby(level=0).mean()
1987 Animal
1988 Falcon 370.0
1989 Parrot 25.0
1990 Name: Max Speed, dtype: float64
1992 We can also group by the 'Type' level of the hierarchical index
1993 to get the mean speed for each type:
1995 >>> ser.groupby(level="Type").mean()
1996 Type
1997 Captive 210.0
1998 Wild 185.0
1999 Name: Max Speed, dtype: float64
2001 We can also choose to include `NA` in group keys or not by defining
2002 `dropna` parameter, the default setting is `True`.
2004 >>> ser = pd.Series([1, 2, 3, 3], index=["a", 'a', 'b', np.nan])
2005 >>> ser.groupby(level=0).sum()
2006 a 3
2007 b 3
2008 dtype: int64
2010 To include `NA` values in the group keys, set `dropna=False`:
2012 >>> ser.groupby(level=0, dropna=False).sum()
2013 a 3
2014 b 3
2015 NaN 3
2016 dtype: int64
2018 We can also group by a custom list with NaN values to handle
2019 missing group labels:
2021 >>> arrays = ['Falcon', 'Falcon', 'Parrot', 'Parrot']
2022 >>> ser = pd.Series([390., 350., 30., 20.], index=arrays, name="Max Speed")
2023 >>> ser.groupby(["a", "b", "a", np.nan]).mean()
2024 a 210.0
2025 b 350.0
2026 Name: Max Speed, dtype: float64
2028 >>> ser.groupby(["a", "b", "a", np.nan], dropna=False).mean()
2029 a 210.0
2030 b 350.0
2031 NaN 20.0
2032 Name: Max Speed, dtype: float64
2033 """
2034 )
2035 )
2036 @Appender(_shared_docs["groupby"] % _shared_doc_kwargs)
2037 @deprecate_nonkeyword_arguments(
2038 Pandas4Warning, allowed_args=["self", "by", "level"], name="groupby"
2039 )
2040 def groupby(
2041 self,
2042 by=None,
2043 level: IndexLabel | None = None,
2044 as_index: bool = True,
2045 sort: bool = True,
2046 group_keys: bool = True,
2047 observed: bool = True,
2048 dropna: bool = True,
2049 ) -> SeriesGroupBy:
2050 from pandas.core.groupby.generic import SeriesGroupBy
2052 if level is None and by is None:
2053 raise TypeError("You have to supply one of 'by' and 'level'")
2054 if not as_index:
2055 raise TypeError("as_index=False only valid with DataFrame")
2057 return SeriesGroupBy(
2058 obj=self,
2059 keys=by,
2060 level=level,
2061 as_index=as_index,
2062 sort=sort,
2063 group_keys=group_keys,
2064 observed=observed,
2065 dropna=dropna,
2066 )
2068 # ----------------------------------------------------------------------
2069 # Statistics, overridden ndarray methods
2071 # TODO: integrate bottleneck
2072 def count(self) -> int:
2073 """
2074 Return number of non-NA/null observations in the Series.
2076 Returns
2077 -------
2078 int
2079 Number of non-null values in the Series.
2081 See Also
2082 --------
2083 DataFrame.count : Count non-NA cells for each column or row.
2085 Examples
2086 --------
2087 >>> s = pd.Series([0.0, 1.0, np.nan])
2088 >>> s.count()
2089 2
2090 """
2091 return maybe_unbox_numpy_scalar(notna(self._values).sum().astype("int64"))
2093 def mode(self, dropna: bool = True) -> Series:
2094 """
2095 Return the mode(s) of the Series.
2097 The mode is the value that appears most often. There can be multiple modes.
2099 Always returns Series even if only one value is returned.
2101 Parameters
2102 ----------
2103 dropna : bool, default True
2104 Don't consider counts of NaN/NaT.
2106 Returns
2107 -------
2108 Series
2109 Modes of the Series in sorted order.
2111 See Also
2112 --------
2113 numpy.mode : Equivalent numpy function for computing median.
2114 Series.sum : Sum of the values.
2115 Series.median : Median of the values.
2116 Series.std : Standard deviation of the values.
2117 Series.var : Variance of the values.
2118 Series.min : Minimum value.
2119 Series.max : Maximum value.
2121 Examples
2122 --------
2123 >>> s = pd.Series([2, 4, 2, 2, 4, None])
2124 >>> s.mode()
2125 0 2.0
2126 dtype: float64
2128 More than one mode:
2130 >>> s = pd.Series([2, 4, 8, 2, 4, None])
2131 >>> s.mode()
2132 0 2.0
2133 1 4.0
2134 dtype: float64
2136 With and without considering null value:
2138 >>> s = pd.Series([2, 4, None, None, 4, None])
2139 >>> s.mode(dropna=False)
2140 0 NaN
2141 dtype: float64
2142 >>> s = pd.Series([2, 4, None, None, 4, None])
2143 >>> s.mode()
2144 0 4.0
2145 dtype: float64
2146 """
2147 # TODO: Add option for bins like value_counts()
2148 values = self._values
2149 if isinstance(values, np.ndarray):
2150 res_values, _ = algorithms.mode(values, dropna=dropna)
2151 else:
2152 res_values = values._mode(dropna=dropna)
2154 # Ensure index is type stable (should always use int index)
2155 return self._constructor(
2156 res_values,
2157 index=range(len(res_values)),
2158 name=self.name,
2159 copy=False,
2160 dtype=self.dtype,
2161 ).__finalize__(self, method="mode")
2163 def unique(self) -> ArrayLike:
2164 """
2165 Return unique values of Series object.
2167 Uniques are returned in order of appearance. Hash table-based unique,
2168 therefore does NOT sort.
2170 Returns
2171 -------
2172 ndarray or ExtensionArray
2173 The unique values returned as a NumPy array. See Notes.
2175 See Also
2176 --------
2177 Series.drop_duplicates : Return Series with duplicate values removed.
2178 unique : Top-level unique method for any 1-d array-like object.
2179 Index.unique : Return Index with unique values from an Index object.
2181 Notes
2182 -----
2183 Returns the unique values as a NumPy array. In case of an
2184 extension-array backed Series, a new
2185 :class:`~api.extensions.ExtensionArray` of that type with just
2186 the unique values is returned. This includes
2188 * Categorical
2189 * Period
2190 * Datetime with Timezone
2191 * Datetime without Timezone
2192 * Timedelta
2193 * Interval
2194 * Sparse
2195 * IntegerNA
2197 See Examples section.
2199 Examples
2200 --------
2201 >>> pd.Series([2, 1, 3, 3], name="A").unique()
2202 array([2, 1, 3])
2204 >>> pd.Series([pd.Timestamp("2016-01-01") for _ in range(3)]).unique()
2205 <DatetimeArray>
2206 ['2016-01-01 00:00:00']
2207 Length: 1, dtype: datetime64[us]
2209 >>> pd.Series(
2210 ... [pd.Timestamp("2016-01-01", tz="US/Eastern") for _ in range(3)]
2211 ... ).unique()
2212 <DatetimeArray>
2213 ['2016-01-01 00:00:00-05:00']
2214 Length: 1, dtype: datetime64[us, US/Eastern]
2216 A Categorical will return categories in the order of
2217 appearance and with the same dtype.
2219 >>> pd.Series(pd.Categorical(list("baabc"))).unique()
2220 ['b', 'a', 'c']
2221 Categories (3, str): ['a', 'b', 'c']
2222 >>> pd.Series(
2223 ... pd.Categorical(list("baabc"), categories=list("abc"), ordered=True)
2224 ... ).unique()
2225 ['b', 'a', 'c']
2226 Categories (3, str): ['a' < 'b' < 'c']
2227 """
2228 return super().unique()
2230 @overload
2231 def drop_duplicates(
2232 self,
2233 *,
2234 keep: DropKeep = ...,
2235 inplace: Literal[False] = ...,
2236 ignore_index: bool = ...,
2237 ) -> Series: ...
2239 @overload
2240 def drop_duplicates(
2241 self, *, keep: DropKeep = ..., inplace: Literal[True], ignore_index: bool = ...
2242 ) -> None: ...
2244 @overload
2245 def drop_duplicates(
2246 self, *, keep: DropKeep = ..., inplace: bool = ..., ignore_index: bool = ...
2247 ) -> Series | None: ...
2249 def drop_duplicates(
2250 self,
2251 *,
2252 keep: DropKeep = "first",
2253 inplace: bool = False,
2254 ignore_index: bool = False,
2255 ) -> Series | None:
2256 """
2257 Return Series with duplicate values removed.
2259 Parameters
2260 ----------
2261 keep : {'first', 'last', ``False``}, default 'first'
2262 Method to handle dropping duplicates:
2264 - 'first' : Drop duplicates except for the first occurrence.
2265 - 'last' : Drop duplicates except for the last occurrence.
2266 - ``False`` : Drop all duplicates.
2268 inplace : bool, default ``False``
2269 If ``True``, performs operation inplace and returns None.
2271 ignore_index : bool, default ``False``
2272 If ``True``, the resulting axis will be labeled 0, 1, …, n - 1.
2274 .. versionadded:: 2.0.0
2276 Returns
2277 -------
2278 Series or None
2279 Series with duplicates dropped or None if ``inplace=True``.
2281 See Also
2282 --------
2283 Index.drop_duplicates : Equivalent method on Index.
2284 DataFrame.drop_duplicates : Equivalent method on DataFrame.
2285 Series.duplicated : Related method on Series, indicating duplicate
2286 Series values.
2287 Series.unique : Return unique values as an array.
2289 Examples
2290 --------
2291 Generate a Series with duplicated entries.
2293 >>> s = pd.Series(
2294 ... ["llama", "cow", "llama", "beetle", "llama", "hippo"], name="animal"
2295 ... )
2296 >>> s
2297 0 llama
2298 1 cow
2299 2 llama
2300 3 beetle
2301 4 llama
2302 5 hippo
2303 Name: animal, dtype: str
2305 With the 'keep' parameter, the selection behavior of duplicated values
2306 can be changed. The value 'first' keeps the first occurrence for each
2307 set of duplicated entries. The default value of keep is 'first'.
2309 >>> s.drop_duplicates()
2310 0 llama
2311 1 cow
2312 3 beetle
2313 5 hippo
2314 Name: animal, dtype: str
2316 The value 'last' for parameter 'keep' keeps the last occurrence for
2317 each set of duplicated entries.
2319 >>> s.drop_duplicates(keep="last")
2320 1 cow
2321 3 beetle
2322 4 llama
2323 5 hippo
2324 Name: animal, dtype: str
2326 The value ``False`` for parameter 'keep' discards all sets of
2327 duplicated entries.
2329 >>> s.drop_duplicates(keep=False)
2330 1 cow
2331 3 beetle
2332 5 hippo
2333 Name: animal, dtype: str
2334 """
2335 inplace = validate_bool_kwarg(inplace, "inplace")
2336 result = super().drop_duplicates(keep=keep)
2338 if ignore_index:
2339 result.index = default_index(len(result))
2341 if inplace:
2342 self._update_inplace(result)
2343 return None
2344 else:
2345 return result
2347 def duplicated(self, keep: DropKeep = "first") -> Series:
2348 """
2349 Indicate duplicate Series values.
2351 Duplicated values are indicated as ``True`` values in the resulting
2352 Series. Either all duplicates, all except the first or all except the
2353 last occurrence of duplicates can be indicated.
2355 Parameters
2356 ----------
2357 keep : {'first', 'last', False}, default 'first'
2358 Method to handle dropping duplicates:
2360 - 'first' : Mark duplicates as ``True`` except for the first
2361 occurrence.
2362 - 'last' : Mark duplicates as ``True`` except for the last
2363 occurrence.
2364 - ``False`` : Mark all duplicates as ``True``.
2366 Returns
2367 -------
2368 Series[bool]
2369 Series indicating whether each value has occurred in the
2370 preceding values.
2372 See Also
2373 --------
2374 Index.duplicated : Equivalent method on pandas.Index.
2375 DataFrame.duplicated : Equivalent method on pandas.DataFrame.
2376 Series.drop_duplicates : Remove duplicate values from Series.
2378 Examples
2379 --------
2380 By default, for each set of duplicated values, the first occurrence is
2381 set on False and all others on True:
2383 >>> animals = pd.Series(["llama", "cow", "llama", "beetle", "llama"])
2384 >>> animals.duplicated()
2385 0 False
2386 1 False
2387 2 True
2388 3 False
2389 4 True
2390 dtype: bool
2392 which is equivalent to
2394 >>> animals.duplicated(keep="first")
2395 0 False
2396 1 False
2397 2 True
2398 3 False
2399 4 True
2400 dtype: bool
2402 By using 'last', the last occurrence of each set of duplicated values
2403 is set on False and all others on True:
2405 >>> animals.duplicated(keep="last")
2406 0 True
2407 1 False
2408 2 True
2409 3 False
2410 4 False
2411 dtype: bool
2413 By setting keep on ``False``, all duplicates are True:
2415 >>> animals.duplicated(keep=False)
2416 0 True
2417 1 False
2418 2 True
2419 3 False
2420 4 True
2421 dtype: bool
2422 """
2423 res = self._duplicated(keep=keep)
2424 result = self._constructor(res, index=self.index, copy=False)
2425 return result.__finalize__(self, method="duplicated")
2427 def idxmin(self, axis: Axis = 0, skipna: bool = True, *args, **kwargs) -> Hashable:
2428 """
2429 Return the row label of the minimum value.
2431 If multiple values equal the minimum, the first row label with that
2432 value is returned.
2434 Parameters
2435 ----------
2436 axis : {0 or 'index'}
2437 Unused. Parameter needed for compatibility with DataFrame.
2438 skipna : bool, default True
2439 Exclude NA/null values. If the entire Series is NA, or if ``skipna=False``
2440 and there is an NA value, this method will raise a ``ValueError``.
2441 *args, **kwargs
2442 Additional arguments and keywords have no effect but might be
2443 accepted for compatibility with NumPy.
2445 Returns
2446 -------
2447 Index
2448 Label of the minimum value.
2450 Raises
2451 ------
2452 ValueError
2453 If the Series is empty.
2455 See Also
2456 --------
2457 numpy.argmin : Return indices of the minimum values
2458 along the given axis.
2459 DataFrame.idxmin : Return index of first occurrence of minimum
2460 over requested axis.
2461 Series.idxmax : Return index *label* of the first occurrence
2462 of maximum of values.
2464 Notes
2465 -----
2466 This method is the Series version of ``ndarray.argmin``. This method
2467 returns the label of the minimum, while ``ndarray.argmin`` returns
2468 the position. To get the position, use ``series.values.argmin()``.
2470 Examples
2471 --------
2472 >>> s = pd.Series(data=[1, None, 4, 1], index=["A", "B", "C", "D"])
2473 >>> s
2474 A 1.0
2475 B NaN
2476 C 4.0
2477 D 1.0
2478 dtype: float64
2480 >>> s.idxmin()
2481 'A'
2482 """
2483 axis = self._get_axis_number(axis)
2484 iloc = self.argmin(axis, skipna, *args, **kwargs)
2485 return self.index[iloc]
2487 def idxmax(self, axis: Axis = 0, skipna: bool = True, *args, **kwargs) -> Hashable:
2488 """
2489 Return the row label of the maximum value.
2491 If multiple values equal the maximum, the first row label with that
2492 value is returned.
2494 Parameters
2495 ----------
2496 axis : {0 or 'index'}
2497 Unused. Parameter needed for compatibility with DataFrame.
2498 skipna : bool, default True
2499 Exclude NA/null values. If the entire Series is NA, or if ``skipna=False``
2500 and there is an NA value, this method will raise a ``ValueError``.
2501 *args, **kwargs
2502 Additional arguments and keywords have no effect but might be
2503 accepted for compatibility with NumPy.
2505 Returns
2506 -------
2507 Index
2508 Label of the maximum value.
2510 Raises
2511 ------
2512 ValueError
2513 If the Series is empty.
2515 See Also
2516 --------
2517 numpy.argmax : Return indices of the maximum values
2518 along the given axis.
2519 DataFrame.idxmax : Return index of first occurrence of maximum
2520 over requested axis.
2521 Series.idxmin : Return index *label* of the first occurrence
2522 of minimum of values.
2524 Notes
2525 -----
2526 This method is the Series version of ``ndarray.argmax``. This method
2527 returns the label of the maximum, while ``ndarray.argmax`` returns
2528 the position. To get the position, use ``series.values.argmax()``.
2530 Examples
2531 --------
2532 >>> s = pd.Series(data=[1, None, 4, 3, 4], index=["A", "B", "C", "D", "E"])
2533 >>> s
2534 A 1.0
2535 B NaN
2536 C 4.0
2537 D 3.0
2538 E 4.0
2539 dtype: float64
2541 >>> s.idxmax()
2542 'C'
2543 """
2544 axis = self._get_axis_number(axis)
2545 iloc = self.argmax(axis, skipna, *args, **kwargs)
2546 return self.index[iloc]
2548 def round(self, decimals: int = 0, *args, **kwargs) -> Series:
2549 """
2550 Round each value in a Series to the given number of decimals.
2552 Parameters
2553 ----------
2554 decimals : int, default 0
2555 Number of decimal places to round to. If decimals is negative,
2556 it specifies the number of positions to the left of the decimal point.
2557 *args, **kwargs
2558 Additional arguments and keywords have no effect but might be
2559 accepted for compatibility with NumPy.
2561 Returns
2562 -------
2563 Series
2564 Rounded values of the Series.
2566 See Also
2567 --------
2568 numpy.around : Round values of an np.array.
2569 DataFrame.round : Round values of a DataFrame.
2570 Series.dt.round : Round values of data to the specified freq.
2572 Notes
2573 -----
2574 For values exactly halfway between rounded decimal values, pandas rounds
2575 to the nearest even value (e.g. -0.5 and 0.5 round to 0.0, 1.5 and 2.5
2576 round to 2.0, etc.).
2578 Examples
2579 --------
2580 >>> s = pd.Series([-0.5, 0.1, 2.5, 1.3, 2.7])
2581 >>> s.round()
2582 0 -0.0
2583 1 0.0
2584 2 2.0
2585 3 1.0
2586 4 3.0
2587 dtype: float64
2588 """
2590 nv.validate_round(args, kwargs)
2592 if len(self) == 0:
2593 return self.copy()
2595 if is_object_dtype(self.dtype):
2596 values = self._values
2597 result = lib.map_infer(values, lambda x: round(x, decimals), convert=False)
2598 return self._constructor(result, index=self.index, copy=False).__finalize__(
2599 self, method="round"
2600 )
2601 new_mgr = self._mgr.round(decimals=decimals)
2602 return self._constructor_from_mgr(new_mgr, axes=new_mgr.axes).__finalize__(
2603 self, method="round"
2604 )
2606 @overload
2607 def quantile(
2608 self, q: float = ..., interpolation: QuantileInterpolation = ...
2609 ) -> float: ...
2611 @overload
2612 def quantile(
2613 self,
2614 q: Sequence[float] | AnyArrayLike,
2615 interpolation: QuantileInterpolation = ...,
2616 ) -> Series: ...
2618 @overload
2619 def quantile(
2620 self,
2621 q: float | Sequence[float] | AnyArrayLike = ...,
2622 interpolation: QuantileInterpolation = ...,
2623 ) -> float | Series: ...
2625 def quantile(
2626 self,
2627 q: float | Sequence[float] | AnyArrayLike = 0.5,
2628 interpolation: QuantileInterpolation = "linear",
2629 ) -> float | Series:
2630 """
2631 Return value at the given quantile.
2633 Parameters
2634 ----------
2635 q : float or array-like, default 0.5 (50% quantile)
2636 The quantile(s) to compute, which can lie in range: 0 <= q <= 1.
2637 interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'}
2638 This optional parameter specifies the interpolation method to use,
2639 when the desired quantile lies between two data points `i` and `j`:
2641 * linear: `i + (j - i) * (x-i)/(j-i)`, where `(x-i)/(j-i)` is
2642 the fractional part of the index surrounded by `i > j`.
2643 * lower: `i`.
2644 * higher: `j`.
2645 * nearest: `i` or `j` whichever is nearest.
2646 * midpoint: (`i` + `j`) / 2.
2648 Returns
2649 -------
2650 float or Series
2651 If ``q`` is an array, a Series will be returned where the
2652 index is ``q`` and the values are the quantiles, otherwise
2653 a float will be returned.
2655 See Also
2656 --------
2657 core.window.Rolling.quantile : Calculate the rolling quantile.
2658 numpy.percentile : Returns the q-th percentile(s) of the array elements.
2660 Examples
2661 --------
2662 >>> s = pd.Series([1, 2, 3, 4])
2663 >>> s.quantile(0.5)
2664 2.5
2665 >>> s.quantile([0.25, 0.5, 0.75])
2666 0.25 1.75
2667 0.50 2.50
2668 0.75 3.25
2669 dtype: float64
2670 """
2671 validate_percentile(q)
2673 # We dispatch to DataFrame so that core.internals only has to worry
2674 # about 2D cases.
2675 df = self.to_frame()
2677 result = df.quantile(q=q, interpolation=interpolation, numeric_only=False)
2678 if result.ndim == 2:
2679 result = result.iloc[:, 0]
2681 if is_list_like(q):
2682 result.name = self.name
2683 idx = Index(q, dtype=np.float64)
2684 return self._constructor(result, index=idx, name=self.name)
2685 else:
2686 # scalar
2687 return maybe_unbox_numpy_scalar(result.iloc[0])
2689 def corr(
2690 self,
2691 other: Series,
2692 method: CorrelationMethod = "pearson",
2693 min_periods: int | None = None,
2694 ) -> float:
2695 """
2696 Compute correlation with `other` Series, excluding missing values.
2698 The two `Series` objects are not required to be the same length and will be
2699 aligned internally before the correlation function is applied.
2701 Parameters
2702 ----------
2703 other : Series
2704 Series with which to compute the correlation.
2705 method : {'pearson', 'kendall', 'spearman'} or callable
2706 Method used to compute correlation:
2708 - pearson : Standard correlation coefficient
2709 - kendall : Kendall Tau correlation coefficient
2710 - spearman : Spearman rank correlation
2711 - callable: Callable with input two 1d ndarrays and returning a float.
2713 .. warning::
2714 Note that the returned matrix from corr will have 1 along the
2715 diagonals and will be symmetric regardless of the callable's
2716 behavior.
2717 min_periods : int, optional
2718 Minimum number of observations needed to have a valid result.
2720 Returns
2721 -------
2722 float
2723 Correlation with other.
2725 See Also
2726 --------
2727 DataFrame.corr : Compute pairwise correlation between columns.
2728 DataFrame.corrwith : Compute pairwise correlation with another
2729 DataFrame or Series.
2731 Notes
2732 -----
2733 Pearson, Kendall and Spearman correlation are currently computed using pairwise complete observations.
2735 * `Pearson correlation coefficient <https://en.wikipedia.org/wiki/Pearson_correlation_coefficient>`_
2736 * `Kendall rank correlation coefficient <https://en.wikipedia.org/wiki/Kendall_rank_correlation_coefficient>`_
2737 * `Spearman's rank correlation coefficient <https://en.wikipedia.org/wiki/Spearman%27s_rank_correlation_coefficient>`_
2739 Automatic data alignment: as with all pandas operations, automatic data alignment is performed for this method.
2740 ``corr()`` automatically considers values with matching indices.
2742 Examples
2743 --------
2744 >>> def histogram_intersection(a, b):
2745 ... v = np.minimum(a, b).sum().round(decimals=1)
2746 ... return v
2747 >>> s1 = pd.Series([0.2, 0.0, 0.6, 0.2])
2748 >>> s2 = pd.Series([0.3, 0.6, 0.0, 0.1])
2749 >>> s1.corr(s2, method=histogram_intersection)
2750 0.3
2752 Pandas auto-aligns the values with matching indices
2754 >>> s1 = pd.Series([1, 2, 3], index=[0, 1, 2])
2755 >>> s2 = pd.Series([1, 2, 3], index=[2, 1, 0])
2756 >>> s1.corr(s2)
2757 -1.0
2759 If the input is a constant array, the correlation is not defined in this case,
2760 and ``np.nan`` is returned.
2762 >>> s1 = pd.Series([0.45, 0.45])
2763 >>> s1.corr(s1)
2764 nan
2765 """ # noqa: E501
2766 this, other = self.align(other, join="inner")
2767 if len(this) == 0:
2768 return np.nan
2770 this_values = this.to_numpy(dtype=float, na_value=np.nan, copy=False)
2771 other_values = other.to_numpy(dtype=float, na_value=np.nan, copy=False)
2773 if method in ["pearson", "spearman", "kendall"] or callable(method):
2774 result = nanops.nancorr(
2775 this_values, other_values, method=method, min_periods=min_periods
2776 )
2777 result = maybe_unbox_numpy_scalar(result)
2778 return result
2780 raise ValueError(
2781 "method must be either 'pearson', "
2782 "'spearman', 'kendall', or a callable, "
2783 f"'{method}' was supplied"
2784 )
2786 def cov(
2787 self,
2788 other: Series,
2789 min_periods: int | None = None,
2790 ddof: int | None = 1,
2791 ) -> float:
2792 """
2793 Compute covariance with Series, excluding missing values.
2795 The two `Series` objects are not required to be the same length and
2796 will be aligned internally before the covariance is calculated.
2798 Parameters
2799 ----------
2800 other : Series
2801 Series with which to compute the covariance.
2802 min_periods : int, optional
2803 Minimum number of observations needed to have a valid result.
2804 ddof : int, default 1
2805 Delta degrees of freedom. The divisor used in calculations
2806 is ``N - ddof``, where ``N`` represents the number of elements.
2808 Returns
2809 -------
2810 float
2811 Covariance between Series and other normalized by N-1
2812 (unbiased estimator).
2814 See Also
2815 --------
2816 DataFrame.cov : Compute pairwise covariance of columns.
2818 Examples
2819 --------
2820 >>> s1 = pd.Series([0.90010907, 0.13484424, 0.62036035])
2821 >>> s2 = pd.Series([0.12528585, 0.26962463, 0.51111198])
2822 >>> s1.cov(s2)
2823 -0.01685762652715874
2824 """
2825 this, other = self.align(other, join="inner")
2826 if len(this) == 0:
2827 return np.nan
2828 this_values = this.to_numpy(dtype=float, na_value=np.nan, copy=False)
2829 other_values = other.to_numpy(dtype=float, na_value=np.nan, copy=False)
2830 result = nanops.nancov(
2831 this_values, other_values, min_periods=min_periods, ddof=ddof
2832 )
2833 result = maybe_unbox_numpy_scalar(result)
2834 return result
2836 def diff(self, periods: int = 1) -> Series:
2837 """
2838 First discrete difference of Series elements.
2840 Calculates the difference of a Series element compared with another
2841 element in the Series (default is element in previous row).
2843 Parameters
2844 ----------
2845 periods : int, default 1
2846 Periods to shift for calculating difference, accepts negative
2847 values.
2849 Returns
2850 -------
2851 Series
2852 First differences of the Series.
2854 See Also
2855 --------
2856 Series.pct_change: Percent change over given number of periods.
2857 Series.shift: Shift index by desired number of periods with an
2858 optional time freq.
2859 DataFrame.diff: First discrete difference of object.
2861 Notes
2862 -----
2863 For boolean dtypes, this uses :meth:`operator.xor` rather than
2864 :meth:`operator.sub`.
2865 The result is calculated according to current dtype in Series,
2866 however dtype of the result is always float64.
2868 Examples
2869 --------
2871 Difference with previous row
2873 >>> s = pd.Series([1, 1, 2, 3, 5, 8])
2874 >>> s.diff()
2875 0 NaN
2876 1 0.0
2877 2 1.0
2878 3 1.0
2879 4 2.0
2880 5 3.0
2881 dtype: float64
2883 Difference with 3rd previous row
2885 >>> s.diff(periods=3)
2886 0 NaN
2887 1 NaN
2888 2 NaN
2889 3 2.0
2890 4 4.0
2891 5 6.0
2892 dtype: float64
2894 Difference with following row
2896 >>> s.diff(periods=-1)
2897 0 0.0
2898 1 -1.0
2899 2 -1.0
2900 3 -2.0
2901 4 -3.0
2902 5 NaN
2903 dtype: float64
2905 Overflow in input dtype
2907 >>> s = pd.Series([1, 0], dtype=np.uint8)
2908 >>> s.diff()
2909 0 NaN
2910 1 255.0
2911 dtype: float64
2912 """
2913 if not lib.is_integer(periods):
2914 if not (is_float(periods) and periods.is_integer()):
2915 raise ValueError("periods must be an integer")
2916 result = algorithms.diff(self._values, periods)
2917 return self._constructor(
2918 result, index=self.index.view(), copy=False
2919 ).__finalize__(self, method="diff")
2921 def autocorr(self, lag: int = 1) -> float:
2922 """
2923 Compute the lag-N autocorrelation.
2925 This method computes the Pearson correlation between
2926 the Series and its shifted self.
2928 Parameters
2929 ----------
2930 lag : int, default 1
2931 Number of lags to apply before performing autocorrelation.
2933 Returns
2934 -------
2935 float
2936 The Pearson correlation between self and self.shift(lag).
2938 See Also
2939 --------
2940 Series.corr : Compute the correlation between two Series.
2941 Series.shift : Shift index by desired number of periods.
2942 DataFrame.corr : Compute pairwise correlation of columns.
2943 DataFrame.corrwith : Compute pairwise correlation between rows or
2944 columns of two DataFrame objects.
2946 Notes
2947 -----
2948 If the Pearson correlation is not well defined return 'NaN'.
2950 Examples
2951 --------
2952 >>> s = pd.Series([0.25, 0.5, 0.2, -0.05])
2953 >>> s.autocorr() # doctest: +ELLIPSIS
2954 0.10355...
2955 >>> s.autocorr(lag=2) # doctest: +ELLIPSIS
2956 -0.99999...
2958 If the Pearson correlation is not well defined, then 'NaN' is returned.
2960 >>> s = pd.Series([1, 0, 0, 0])
2961 >>> s.autocorr()
2962 nan
2963 """
2964 return self.corr(cast(Series, self.shift(lag)))
2966 def dot(self, other: AnyArrayLike | DataFrame) -> Series | np.ndarray:
2967 """
2968 Compute the dot product between the Series and the columns of other.
2970 This method computes the dot product between the Series and another
2971 one, or the Series and each columns of a DataFrame, or the Series and
2972 each columns of an array.
2974 It can also be called using `self @ other`.
2976 Parameters
2977 ----------
2978 other : Series, DataFrame or array-like
2979 The other object to compute the dot product with its columns.
2981 Returns
2982 -------
2983 scalar, Series or numpy.ndarray
2984 Return the dot product of the Series and other if other is a
2985 Series, the Series of the dot product of Series and each rows of
2986 other if other is a DataFrame or a numpy.ndarray between the Series
2987 and each columns of the numpy array.
2989 See Also
2990 --------
2991 DataFrame.dot: Compute the matrix product with the DataFrame.
2992 Series.mul: Multiplication of series and other, element-wise.
2994 Notes
2995 -----
2996 The Series and other has to share the same index if other is a Series
2997 or a DataFrame.
2999 Examples
3000 --------
3001 >>> s = pd.Series([0, 1, 2, 3])
3002 >>> other = pd.Series([-1, 2, -3, 4])
3003 >>> s.dot(other)
3004 8
3005 >>> s @ other
3006 8
3007 >>> df = pd.DataFrame([[0, 1], [-2, 3], [4, -5], [6, 7]])
3008 >>> s.dot(df)
3009 0 24
3010 1 14
3011 dtype: int64
3012 >>> arr = np.array([[0, 1], [-2, 3], [4, -5], [6, 7]])
3013 >>> s.dot(arr)
3014 array([24, 14])
3015 """
3016 if isinstance(other, (Series, ABCDataFrame)):
3017 common = self.index.union(other.index)
3018 if len(common) > len(self.index) or len(common) > len(other.index):
3019 raise ValueError("matrices are not aligned")
3021 left = self.reindex(index=common)
3022 right = other.reindex(index=common)
3023 lvals = left.values
3024 rvals = right.values
3025 else:
3026 lvals = self.values
3027 rvals = np.asarray(other)
3028 if lvals.shape[0] != rvals.shape[0]:
3029 raise Exception(
3030 f"Dot product shape mismatch, {lvals.shape} vs {rvals.shape}"
3031 )
3033 if isinstance(other, ABCDataFrame):
3034 common_type = find_common_type([self.dtypes, *list(other.dtypes)])
3035 return self._constructor(
3036 np.dot(lvals, rvals), index=other.columns, copy=False, dtype=common_type
3037 ).__finalize__(self, method="dot")
3038 elif isinstance(other, Series):
3039 result = np.dot(lvals, rvals)
3040 elif isinstance(rvals, np.ndarray):
3041 result = np.dot(lvals, rvals)
3042 else: # pragma: no cover
3043 raise TypeError(f"unsupported type: {type(other)}")
3044 return maybe_unbox_numpy_scalar(result)
3046 def __matmul__(self, other):
3047 """
3048 Matrix multiplication using binary `@` operator.
3049 """
3050 return self.dot(other)
3052 def __rmatmul__(self, other):
3053 """
3054 Matrix multiplication using binary `@` operator.
3055 """
3056 return self.dot(np.transpose(other))
3058 # Signature of "searchsorted" incompatible with supertype "IndexOpsMixin"
3059 def searchsorted( # type: ignore[override]
3060 self,
3061 value: NumpyValueArrayLike | ExtensionArray,
3062 side: Literal["left", "right"] = "left",
3063 sorter: NumpySorter | None = None,
3064 ) -> npt.NDArray[np.intp] | np.intp:
3065 """
3066 Find indices where elements should be inserted to maintain order.
3068 Find the indices into a sorted Series `self` such that, if the
3069 corresponding elements in `value` were inserted before the indices,
3070 the order of `self` would be preserved.
3072 .. note::
3073 The Series *must* be monotonically sorted, otherwise
3074 wrong locations will likely be returned. Pandas does *not*
3075 check this for you.
3077 Parameters
3078 ----------
3079 value : array-like or scalar
3080 Values to insert into `self`.
3081 side : {'left', 'right'}, optional
3082 If 'left', the index of the first suitable location found is given.
3083 If 'right', return the last such index. If there is no suitable
3084 index, return either 0 or N (where N is the length of `self`).
3085 sorter : 1-D array-like, optional
3086 Optional array of integer indices that sort `self` into ascending
3087 order. They are typically the result of ``np.argsort``.
3089 Returns
3090 -------
3091 int or array of int
3092 A scalar or array of insertion points with the
3093 same shape as `value`.
3095 See Also
3096 --------
3097 sort_values : Sort by the values along either axis.
3098 numpy.searchsorted : Similar method from NumPy.
3100 Notes
3101 -----
3102 Binary search is used to find the required insertion points.
3104 Examples
3105 --------
3106 >>> ser = pd.Series([1, 2, 3])
3107 >>> ser
3108 0 1
3109 1 2
3110 2 3
3111 dtype: int64
3112 >>> ser.searchsorted(4)
3113 np.int64(3)
3114 >>> ser.searchsorted([0, 4])
3115 array([0, 3])
3116 >>> ser.searchsorted([1, 3], side="left")
3117 array([0, 2])
3118 >>> ser.searchsorted([1, 3], side="right")
3119 array([1, 3])
3120 >>> ser = pd.Series(pd.to_datetime(["3/11/2000", "3/12/2000", "3/13/2000"]))
3121 >>> ser
3122 0 2000-03-11
3123 1 2000-03-12
3124 2 2000-03-13
3125 dtype: datetime64[us]
3126 >>> ser.searchsorted("3/14/2000")
3127 np.int64(3)
3128 >>> ser = pd.Categorical(
3129 ... ["apple", "bread", "bread", "cheese", "milk"], ordered=True
3130 ... )
3131 >>> ser
3132 ['apple', 'bread', 'bread', 'cheese', 'milk']
3133 Categories (4, str): ['apple' < 'bread' < 'cheese' < 'milk']
3134 >>> ser.searchsorted("bread")
3135 np.int64(1)
3136 >>> ser.searchsorted(["bread"], side="right")
3137 array([3])
3139 If the values are not monotonically sorted, wrong locations
3140 may be returned:
3142 >>> ser = pd.Series([2, 1, 3])
3143 >>> ser
3144 0 2
3145 1 1
3146 2 3
3147 dtype: int64
3148 >>> ser.searchsorted(1) # doctest: +SKIP
3149 0 # wrong result, correct would be 1
3150 """
3151 return base.IndexOpsMixin.searchsorted(self, value, side=side, sorter=sorter)
3153 # -------------------------------------------------------------------
3154 # Combination
3156 def _append_internal(self, to_append: Series, ignore_index: bool = False) -> Series:
3157 from pandas.core.reshape.concat import concat
3159 return concat([self, to_append], ignore_index=ignore_index)
3161 def compare(
3162 self,
3163 other: Series,
3164 align_axis: Axis = 1,
3165 keep_shape: bool = False,
3166 keep_equal: bool = False,
3167 result_names: Suffixes = ("self", "other"),
3168 ) -> DataFrame | Series:
3169 """
3170 Compare to another Series and show the differences.
3172 Parameters
3173 ----------
3174 other : Series
3175 Object to compare with.
3177 align_axis : {0 or 'index', 1 or 'columns'}, default 1
3178 Determine which axis to align the comparison on.
3180 * 0, or 'index' : Resulting differences are stacked vertically
3181 with rows drawn alternately from self and other.
3182 * 1, or 'columns' : Resulting differences are aligned horizontally
3183 with columns drawn alternately from self and other.
3185 keep_shape : bool, default False
3186 If true, all rows and columns are kept.
3187 Otherwise, only the ones with different values are kept.
3189 keep_equal : bool, default False
3190 If true, the result keeps values that are equal.
3191 Otherwise, equal values are shown as NaNs.
3193 result_names : tuple, default ('self', 'other')
3194 Set the dataframes names in the comparison.
3196 Returns
3197 -------
3198 Series or DataFrame
3199 If axis is 0 or 'index' the result will be a Series.
3200 The resulting index will be a MultiIndex with 'self' and 'other'
3201 stacked alternately at the inner level.
3203 If axis is 1 or 'columns' the result will be a DataFrame.
3204 It will have two columns namely 'self' and 'other'.
3206 See Also
3207 --------
3208 DataFrame.compare : Compare with another DataFrame and show differences.
3210 Notes
3211 -----
3212 Matching NaNs will not appear as a difference.
3214 Examples
3215 --------
3216 >>> s1 = pd.Series(["a", "b", "c", "d", "e"])
3217 >>> s2 = pd.Series(["a", "a", "c", "b", "e"])
3219 Align the differences on columns
3221 >>> s1.compare(s2)
3222 self other
3223 1 b a
3224 3 d b
3226 Stack the differences on indices
3228 >>> s1.compare(s2, align_axis=0)
3229 1 self b
3230 other a
3231 3 self d
3232 other b
3233 dtype: str
3235 Keep all original rows
3237 >>> s1.compare(s2, keep_shape=True)
3238 self other
3239 0 NaN NaN
3240 1 b a
3241 2 NaN NaN
3242 3 d b
3243 4 NaN NaN
3245 Keep all original rows and also all original values
3247 >>> s1.compare(s2, keep_shape=True, keep_equal=True)
3248 self other
3249 0 a a
3250 1 b a
3251 2 c c
3252 3 d b
3253 4 e e
3254 """
3256 return super().compare(
3257 other=other,
3258 align_axis=align_axis,
3259 keep_shape=keep_shape,
3260 keep_equal=keep_equal,
3261 result_names=result_names,
3262 )
3264 def combine(
3265 self,
3266 other: Series | Hashable,
3267 func: Callable[[Hashable, Hashable], Hashable],
3268 fill_value: Hashable | None = None,
3269 ) -> Series:
3270 """
3271 Combine the Series with a Series or scalar according to `func`.
3273 Combine the Series and `other` using `func` to perform elementwise
3274 selection for combined Series.
3275 `fill_value` is assumed when value is not present at some index
3276 from one of the two Series being combined.
3278 Parameters
3279 ----------
3280 other : Series or scalar
3281 The value(s) to be combined with the `Series`.
3282 func : function
3283 Function that takes two scalars as inputs and returns an element.
3284 fill_value : scalar, optional
3285 The value to assume when an index is missing from
3286 one Series or the other. The default specifies to use the
3287 appropriate NaN value for the underlying dtype of the Series.
3289 Returns
3290 -------
3291 Series
3292 The result of combining the Series with the other object.
3294 See Also
3295 --------
3296 Series.combine_first : Combine Series values, choosing the calling
3297 Series' values first.
3299 Examples
3300 --------
3301 Consider 2 Datasets ``s1`` and ``s2`` containing
3302 highest clocked speeds of different birds.
3304 >>> s1 = pd.Series({"falcon": 330.0, "eagle": 160.0})
3305 >>> s1
3306 falcon 330.0
3307 eagle 160.0
3308 dtype: float64
3309 >>> s2 = pd.Series({"falcon": 345.0, "eagle": 200.0, "duck": 30.0})
3310 >>> s2
3311 falcon 345.0
3312 eagle 200.0
3313 duck 30.0
3314 dtype: float64
3316 Now, to combine the two datasets and view the highest speeds
3317 of the birds across the two datasets
3319 >>> s1.combine(s2, max)
3320 duck NaN
3321 eagle 200.0
3322 falcon 345.0
3323 dtype: float64
3325 In the previous example, the resulting value for duck is missing,
3326 because the maximum of a NaN and a float is a NaN.
3327 So, in the example, we set ``fill_value=0``,
3328 so the maximum value returned will be the value from some dataset.
3330 >>> s1.combine(s2, max, fill_value=0)
3331 duck 30.0
3332 eagle 200.0
3333 falcon 345.0
3334 dtype: float64
3335 """
3336 if fill_value is None:
3337 fill_value = na_value_for_dtype(self.dtype, compat=False)
3339 if isinstance(other, Series):
3340 # If other is a Series, result is based on union of Series,
3341 # so do this element by element
3342 new_index = self.index.union(other.index)
3343 new_name = ops.get_op_result_name(self, other)
3344 new_values = np.empty(len(new_index), dtype=object)
3345 with np.errstate(all="ignore"):
3346 for i, idx in enumerate(new_index):
3347 lv = self.get(idx, fill_value)
3348 rv = other.get(idx, fill_value)
3349 new_values[i] = func(lv, rv)
3350 else:
3351 # Assume that other is a scalar, so apply the function for
3352 # each element in the Series
3353 new_index = self.index
3354 new_values = np.empty(len(new_index), dtype=object)
3355 with np.errstate(all="ignore"):
3356 new_values[:] = [func(lv, other) for lv in self._values]
3357 new_name = self.name
3359 res_values = self.array._cast_pointwise_result(new_values)
3360 return self._constructor(
3361 res_values,
3362 dtype=res_values.dtype,
3363 index=new_index,
3364 name=new_name,
3365 copy=False,
3366 )
3368 def combine_first(self, other) -> Series:
3369 """
3370 Update null elements with value in the same location in 'other'.
3372 Combine two Series objects by filling null values in one Series with
3373 non-null values from the other Series. Result index will be the union
3374 of the two indexes.
3376 Parameters
3377 ----------
3378 other : Series
3379 The value(s) to be used for filling null values.
3381 Returns
3382 -------
3383 Series
3384 The result of combining the provided Series with the other object.
3386 See Also
3387 --------
3388 Series.combine : Perform element-wise operation on two Series
3389 using a given function.
3391 Examples
3392 --------
3393 >>> s1 = pd.Series([1, np.nan])
3394 >>> s2 = pd.Series([3, 4, 5])
3395 >>> s1.combine_first(s2)
3396 0 1.0
3397 1 4.0
3398 2 5.0
3399 dtype: float64
3401 Null values still persist if the location of that null value
3402 does not exist in `other`
3404 >>> s1 = pd.Series({"falcon": np.nan, "eagle": 160.0})
3405 >>> s2 = pd.Series({"eagle": 200.0, "duck": 30.0})
3406 >>> s1.combine_first(s2)
3407 duck 30.0
3408 eagle 160.0
3409 falcon NaN
3410 dtype: float64
3411 """
3412 from pandas.core.reshape.concat import concat
3414 if self.dtype == other.dtype:
3415 if self.index.equals(other.index):
3416 return self.mask(self.isna(), other)
3418 new_index = self.index.union(other.index)
3420 this = self
3421 # identify the index subset to keep for each series
3422 keep_other = other.index.difference(this.index[notna(this)])
3423 keep_this = this.index.difference(keep_other)
3425 this = this.reindex(keep_this)
3426 other = other.reindex(keep_other)
3428 if this.dtype.kind == "M" and other.dtype.kind != "M":
3429 # TODO: try to match resos?
3430 other = to_datetime(other)
3431 warnings.warn(
3432 # GH#62931
3433 "Silently casting non-datetime 'other' to datetime in "
3434 "Series.combine_first is deprecated and will be removed "
3435 "in a future version. Explicitly cast before calling "
3436 "combine_first instead.",
3437 Pandas4Warning,
3438 stacklevel=find_stack_level(),
3439 )
3441 combined = concat([this, other])
3442 combined = combined.reindex(new_index)
3443 return combined.__finalize__(self, method="combine_first")
3445 def update(self, other: Series | Sequence | Mapping) -> None:
3446 """
3447 Modify Series in place using values from passed Series.
3449 Uses non-NA values from passed Series to make updates. Aligns
3450 on index.
3452 Parameters
3453 ----------
3454 other : Series, or object coercible into Series
3455 Other Series that provides values to update the current Series.
3457 See Also
3458 --------
3459 Series.combine : Perform element-wise operation on two Series
3460 using a given function.
3461 Series.transform: Modify a Series using a function.
3463 Examples
3464 --------
3465 >>> s = pd.Series([1, 2, 3])
3466 >>> s.update(pd.Series([4, 5, 6]))
3467 >>> s
3468 0 4
3469 1 5
3470 2 6
3471 dtype: int64
3473 >>> s = pd.Series(["a", "b", "c"])
3474 >>> s.update(pd.Series(["d", "e"], index=[0, 2]))
3475 >>> s
3476 0 d
3477 1 b
3478 2 e
3479 dtype: str
3481 >>> s = pd.Series([1, 2, 3])
3482 >>> s.update(pd.Series([4, 5, 6, 7, 8]))
3483 >>> s
3484 0 4
3485 1 5
3486 2 6
3487 dtype: int64
3489 If ``other`` contains NaNs the corresponding values are not updated
3490 in the original Series.
3492 >>> s = pd.Series([1, 2, 3])
3493 >>> s.update(pd.Series([4, np.nan, 6]))
3494 >>> s
3495 0 4
3496 1 2
3497 2 6
3498 dtype: int64
3500 ``other`` can also be a non-Series object type
3501 that is coercible into a Series
3503 >>> s = pd.Series([1, 2, 3])
3504 >>> s.update([4, np.nan, 6])
3505 >>> s
3506 0 4
3507 1 2
3508 2 6
3509 dtype: int64
3511 >>> s = pd.Series([1, 2, 3])
3512 >>> s.update({1: 9})
3513 >>> s
3514 0 1
3515 1 9
3516 2 3
3517 dtype: int64
3518 """
3519 if not CHAINED_WARNING_DISABLED:
3520 if sys.getrefcount(
3521 self
3522 ) <= REF_COUNT_METHOD and not com.is_local_in_caller_frame(self):
3523 warnings.warn(
3524 _chained_assignment_method_update_msg,
3525 ChainedAssignmentError,
3526 stacklevel=2,
3527 )
3529 if not isinstance(other, Series):
3530 other = Series(other)
3532 other = other.reindex_like(self)
3533 mask = notna(other)
3535 self._mgr = self._mgr.putmask(mask=mask, new=other)
3537 # ----------------------------------------------------------------------
3538 # Reindexing, sorting
3540 @overload
3541 def sort_values(
3542 self,
3543 *,
3544 axis: Axis = ...,
3545 ascending: bool | Sequence[bool] = ...,
3546 inplace: Literal[False] = ...,
3547 kind: SortKind = ...,
3548 na_position: NaPosition = ...,
3549 ignore_index: bool = ...,
3550 key: ValueKeyFunc = ...,
3551 ) -> Series: ...
3553 @overload
3554 def sort_values(
3555 self,
3556 *,
3557 axis: Axis = ...,
3558 ascending: bool | Sequence[bool] = ...,
3559 inplace: Literal[True],
3560 kind: SortKind = ...,
3561 na_position: NaPosition = ...,
3562 ignore_index: bool = ...,
3563 key: ValueKeyFunc = ...,
3564 ) -> None: ...
3566 @overload
3567 def sort_values(
3568 self,
3569 *,
3570 axis: Axis = ...,
3571 ascending: bool | Sequence[bool] = ...,
3572 inplace: bool = ...,
3573 kind: SortKind = ...,
3574 na_position: NaPosition = ...,
3575 ignore_index: bool = ...,
3576 key: ValueKeyFunc = ...,
3577 ) -> Series | None: ...
3579 def sort_values(
3580 self,
3581 *,
3582 axis: Axis = 0,
3583 ascending: bool | Sequence[bool] = True,
3584 inplace: bool = False,
3585 kind: SortKind = "quicksort",
3586 na_position: NaPosition = "last",
3587 ignore_index: bool = False,
3588 key: ValueKeyFunc | None = None,
3589 ) -> Series | None:
3590 """
3591 Sort by the values.
3593 Sort a Series in ascending or descending order by some
3594 criterion.
3596 Parameters
3597 ----------
3598 axis : {0 or 'index'}
3599 Unused. Parameter needed for compatibility with DataFrame.
3600 ascending : bool or list of bools, default True
3601 If True, sort values in ascending order, otherwise descending.
3602 inplace : bool, default False
3603 If True, perform operation in-place.
3604 kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, default 'quicksort'
3605 Choice of sorting algorithm. See also :func:`numpy.sort` for more
3606 information. 'mergesort' and 'stable' are the only stable algorithms.
3607 na_position : {'first' or 'last'}, default 'last'
3608 Argument 'first' puts NaNs at the beginning, 'last' puts NaNs at
3609 the end.
3610 ignore_index : bool, default False
3611 If True, the resulting axis will be labeled 0, 1, …, n - 1.
3612 key : callable, optional
3613 If not None, apply the key function to the series values
3614 before sorting. This is similar to the `key` argument in the
3615 builtin :meth:`sorted` function, with the notable difference that
3616 this `key` function should be *vectorized*. It should expect a
3617 ``Series`` and return an array-like.
3619 Returns
3620 -------
3621 Series or None
3622 Series ordered by values or None if ``inplace=True``.
3624 See Also
3625 --------
3626 Series.sort_index : Sort by the Series indices.
3627 DataFrame.sort_values : Sort DataFrame by the values along either axis.
3628 DataFrame.sort_index : Sort DataFrame by indices.
3630 Examples
3631 --------
3632 >>> s = pd.Series([np.nan, 1, 3, 10, 5])
3633 >>> s
3634 0 NaN
3635 1 1.0
3636 2 3.0
3637 3 10.0
3638 4 5.0
3639 dtype: float64
3641 Sort values ascending order (default behavior)
3643 >>> s.sort_values(ascending=True)
3644 1 1.0
3645 2 3.0
3646 4 5.0
3647 3 10.0
3648 0 NaN
3649 dtype: float64
3651 Sort values descending order
3653 >>> s.sort_values(ascending=False)
3654 3 10.0
3655 4 5.0
3656 2 3.0
3657 1 1.0
3658 0 NaN
3659 dtype: float64
3661 Sort values putting NAs first
3663 >>> s.sort_values(na_position="first")
3664 0 NaN
3665 1 1.0
3666 2 3.0
3667 4 5.0
3668 3 10.0
3669 dtype: float64
3671 Sort a series of strings
3673 >>> s = pd.Series(["z", "b", "d", "a", "c"])
3674 >>> s
3675 0 z
3676 1 b
3677 2 d
3678 3 a
3679 4 c
3680 dtype: str
3682 >>> s.sort_values()
3683 3 a
3684 1 b
3685 4 c
3686 2 d
3687 0 z
3688 dtype: str
3690 Sort using a key function. Your `key` function will be
3691 given the ``Series`` of values and should return an array-like.
3693 >>> s = pd.Series(["a", "B", "c", "D", "e"])
3694 >>> s.sort_values()
3695 1 B
3696 3 D
3697 0 a
3698 2 c
3699 4 e
3700 dtype: str
3701 >>> s.sort_values(key=lambda x: x.str.lower())
3702 0 a
3703 1 B
3704 2 c
3705 3 D
3706 4 e
3707 dtype: str
3709 NumPy ufuncs work well here. For example, we can
3710 sort by the ``sin`` of the value
3712 >>> s = pd.Series([-4, -2, 0, 2, 4])
3713 >>> s.sort_values(key=np.sin)
3714 1 -2
3715 4 4
3716 2 0
3717 0 -4
3718 3 2
3719 dtype: int64
3721 More complicated user-defined functions can be used,
3722 as long as they expect a Series and return an array-like
3724 >>> s.sort_values(key=lambda x: np.tan(x.cumsum()))
3725 0 -4
3726 3 2
3727 4 4
3728 1 -2
3729 2 0
3730 dtype: int64
3731 """
3732 inplace = validate_bool_kwarg(inplace, "inplace")
3733 # Validate the axis parameter
3734 self._get_axis_number(axis)
3736 if is_list_like(ascending):
3737 ascending = cast(Sequence[bool], ascending)
3738 if len(ascending) != 1:
3739 raise ValueError(
3740 f"Length of ascending ({len(ascending)}) must be 1 for Series"
3741 )
3742 ascending = ascending[0]
3744 ascending = validate_ascending(ascending)
3746 if na_position not in ["first", "last"]:
3747 raise ValueError(f"invalid na_position: {na_position}")
3749 # GH 35922. Make sorting stable by leveraging nargsort
3750 if key:
3751 values_to_sort = cast(Series, ensure_key_mapped(self, key))._values
3752 else:
3753 values_to_sort = self._values
3754 sorted_index = nargsort(values_to_sort, kind, bool(ascending), na_position)
3756 if is_range_indexer(sorted_index, len(sorted_index)):
3757 if inplace:
3758 return self._update_inplace(self)
3759 return self.copy(deep=False)
3761 result = self._constructor(
3762 self._values[sorted_index], index=self.index[sorted_index], copy=False
3763 )
3765 if ignore_index:
3766 result.index = default_index(len(sorted_index))
3768 if not inplace:
3769 return result.__finalize__(self, method="sort_values")
3770 self._update_inplace(result)
3771 return None
3773 @overload
3774 def sort_index(
3775 self,
3776 *,
3777 axis: Axis = ...,
3778 level: IndexLabel = ...,
3779 ascending: bool | Sequence[bool] = ...,
3780 inplace: Literal[True],
3781 kind: SortKind = ...,
3782 na_position: NaPosition = ...,
3783 sort_remaining: bool = ...,
3784 ignore_index: bool = ...,
3785 key: IndexKeyFunc = ...,
3786 ) -> None: ...
3788 @overload
3789 def sort_index(
3790 self,
3791 *,
3792 axis: Axis = ...,
3793 level: IndexLabel = ...,
3794 ascending: bool | Sequence[bool] = ...,
3795 inplace: Literal[False] = ...,
3796 kind: SortKind = ...,
3797 na_position: NaPosition = ...,
3798 sort_remaining: bool = ...,
3799 ignore_index: bool = ...,
3800 key: IndexKeyFunc = ...,
3801 ) -> Series: ...
3803 @overload
3804 def sort_index(
3805 self,
3806 *,
3807 axis: Axis = ...,
3808 level: IndexLabel = ...,
3809 ascending: bool | Sequence[bool] = ...,
3810 inplace: bool = ...,
3811 kind: SortKind = ...,
3812 na_position: NaPosition = ...,
3813 sort_remaining: bool = ...,
3814 ignore_index: bool = ...,
3815 key: IndexKeyFunc = ...,
3816 ) -> Series | None: ...
3818 def sort_index(
3819 self,
3820 *,
3821 axis: Axis = 0,
3822 level: IndexLabel | None = None,
3823 ascending: bool | Sequence[bool] = True,
3824 inplace: bool = False,
3825 kind: SortKind = "quicksort",
3826 na_position: NaPosition = "last",
3827 sort_remaining: bool = True,
3828 ignore_index: bool = False,
3829 key: IndexKeyFunc | None = None,
3830 ) -> Series | None:
3831 """
3832 Sort Series by index labels.
3834 Returns a new Series sorted by label if `inplace` argument is
3835 ``False``, otherwise updates the original series and returns None.
3837 Parameters
3838 ----------
3839 axis : {0 or 'index'}
3840 Unused. Parameter needed for compatibility with DataFrame.
3841 level : int, optional
3842 If not None, sort on values in specified index level(s).
3843 ascending : bool or list-like of bools, default True
3844 Sort ascending vs. descending. When the index is a MultiIndex the
3845 sort direction can be controlled for each level individually.
3846 inplace : bool, default False
3847 If True, perform operation in-place.
3848 kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, default 'quicksort'
3849 Choice of sorting algorithm. See also :func:`numpy.sort` for more
3850 information. 'mergesort' and 'stable' are the only stable algorithms. For
3851 DataFrames, this option is only applied when sorting on a single
3852 column or label.
3853 na_position : {'first', 'last'}, default 'last'
3854 If 'first' puts NaNs at the beginning, 'last' puts NaNs at the end.
3855 Not implemented for MultiIndex.
3856 sort_remaining : bool, default True
3857 If True and sorting by level and index is multilevel, sort by other
3858 levels too (in order) after sorting by specified level.
3859 ignore_index : bool, default False
3860 If True, the resulting axis will be labeled 0, 1, …, n - 1.
3861 key : callable, optional
3862 If not None, apply the key function to the index values
3863 before sorting. This is similar to the `key` argument in the
3864 builtin :meth:`sorted` function, with the notable difference that
3865 this `key` function should be *vectorized*. It should expect an
3866 ``Index`` and return an ``Index`` of the same shape.
3868 Returns
3869 -------
3870 Series or None
3871 The original Series sorted by the labels or None if ``inplace=True``.
3873 See Also
3874 --------
3875 DataFrame.sort_index: Sort DataFrame by the index.
3876 DataFrame.sort_values: Sort DataFrame by the value.
3877 Series.sort_values : Sort Series by the value.
3879 Examples
3880 --------
3881 >>> s = pd.Series(["a", "b", "c", "d"], index=[3, 2, 1, 4])
3882 >>> s.sort_index()
3883 1 c
3884 2 b
3885 3 a
3886 4 d
3887 dtype: str
3889 Sort Descending
3891 >>> s.sort_index(ascending=False)
3892 4 d
3893 3 a
3894 2 b
3895 1 c
3896 dtype: str
3898 By default NaNs are put at the end, but use `na_position` to place
3899 them at the beginning
3901 >>> s = pd.Series(["a", "b", "c", "d"], index=[3, 2, 1, np.nan])
3902 >>> s.sort_index(na_position="first")
3903 NaN d
3904 1.0 c
3905 2.0 b
3906 3.0 a
3907 dtype: str
3909 Specify index level to sort
3911 >>> arrays = [
3912 ... np.array(["qux", "qux", "foo", "foo", "baz", "baz", "bar", "bar"]),
3913 ... np.array(["two", "one", "two", "one", "two", "one", "two", "one"]),
3914 ... ]
3915 >>> s = pd.Series([1, 2, 3, 4, 5, 6, 7, 8], index=arrays)
3916 >>> s.sort_index(level=1)
3917 bar one 8
3918 baz one 6
3919 foo one 4
3920 qux one 2
3921 bar two 7
3922 baz two 5
3923 foo two 3
3924 qux two 1
3925 dtype: int64
3927 Does not sort by remaining levels when sorting by levels
3929 >>> s.sort_index(level=1, sort_remaining=False)
3930 qux one 2
3931 foo one 4
3932 baz one 6
3933 bar one 8
3934 qux two 1
3935 foo two 3
3936 baz two 5
3937 bar two 7
3938 dtype: int64
3940 Apply a key function before sorting
3942 >>> s = pd.Series([1, 2, 3, 4], index=["A", "b", "C", "d"])
3943 >>> s.sort_index(key=lambda x: x.str.lower())
3944 A 1
3945 b 2
3946 C 3
3947 d 4
3948 dtype: int64
3949 """
3951 return super().sort_index(
3952 axis=axis,
3953 level=level,
3954 ascending=ascending,
3955 inplace=inplace,
3956 kind=kind,
3957 na_position=na_position,
3958 sort_remaining=sort_remaining,
3959 ignore_index=ignore_index,
3960 key=key,
3961 )
3963 def argsort(
3964 self,
3965 axis: Axis = 0,
3966 kind: SortKind = "quicksort",
3967 order: None = None,
3968 stable: None = None,
3969 ) -> Series:
3970 """
3971 Return the integer indices that would sort the Series values.
3973 Override ndarray.argsort. Argsorts the value, omitting NA/null values,
3974 and places the result in the same locations as the non-NA values.
3976 Parameters
3977 ----------
3978 axis : {0 or 'index'}
3979 Unused. Parameter needed for compatibility with DataFrame.
3980 kind : {'mergesort', 'quicksort', 'heapsort', 'stable'}, default 'quicksort'
3981 Choice of sorting algorithm. See :func:`numpy.sort` for more
3982 information. 'mergesort' and 'stable' are the only stable algorithms.
3983 order : None
3984 Has no effect but is accepted for compatibility with numpy.
3985 stable : None
3986 Has no effect but is accepted for compatibility with numpy.
3988 Returns
3989 -------
3990 Series[np.intp]
3991 Positions of values within the sort order with -1 indicating
3992 nan values.
3994 See Also
3995 --------
3996 numpy.ndarray.argsort : Returns the indices that would sort this array.
3998 Examples
3999 --------
4000 >>> s = pd.Series([3, 2, 1])
4001 >>> s.argsort()
4002 0 2
4003 1 1
4004 2 0
4005 dtype: int64
4006 """
4007 if axis != -1:
4008 # GH#54257 We allow -1 here so that np.argsort(series) works
4009 self._get_axis_number(axis)
4011 result = self.array.argsort(kind=kind)
4013 res = self._constructor(
4014 result, index=self.index, name=self.name, dtype=np.intp, copy=False
4015 )
4016 return res.__finalize__(self, method="argsort")
4018 def nlargest(
4019 self, n: int = 5, keep: Literal["first", "last", "all"] = "first"
4020 ) -> Series:
4021 """
4022 Return the largest `n` elements.
4024 Parameters
4025 ----------
4026 n : int, default 5
4027 Return this many descending sorted values.
4028 keep : {'first', 'last', 'all'}, default 'first'
4029 When there are duplicate values that cannot all fit in a
4030 Series of `n` elements:
4032 - ``first`` : return the first `n` occurrences in order
4033 of appearance.
4034 - ``last`` : return the last `n` occurrences in reverse
4035 order of appearance.
4036 - ``all`` : keep all occurrences. This can result in a Series of
4037 size larger than `n`.
4039 Returns
4040 -------
4041 Series
4042 The `n` largest values in the Series, sorted in decreasing order.
4044 See Also
4045 --------
4046 Series.nsmallest: Get the `n` smallest elements.
4047 Series.sort_values: Sort Series by values.
4048 Series.head: Return the first `n` rows.
4050 Notes
4051 -----
4052 Faster than ``.sort_values(ascending=False).head(n)`` for small `n`
4053 relative to the size of the ``Series`` object.
4055 Examples
4056 --------
4057 >>> countries_population = {
4058 ... "Italy": 59000000,
4059 ... "France": 65000000,
4060 ... "Malta": 434000,
4061 ... "Maldives": 434000,
4062 ... "Brunei": 434000,
4063 ... "Iceland": 337000,
4064 ... "Nauru": 11300,
4065 ... "Tuvalu": 11300,
4066 ... "Anguilla": 11300,
4067 ... "Montserrat": 5200,
4068 ... }
4069 >>> s = pd.Series(countries_population)
4070 >>> s
4071 Italy 59000000
4072 France 65000000
4073 Malta 434000
4074 Maldives 434000
4075 Brunei 434000
4076 Iceland 337000
4077 Nauru 11300
4078 Tuvalu 11300
4079 Anguilla 11300
4080 Montserrat 5200
4081 dtype: int64
4083 The `n` largest elements where ``n=5`` by default.
4085 >>> s.nlargest()
4086 France 65000000
4087 Italy 59000000
4088 Malta 434000
4089 Maldives 434000
4090 Brunei 434000
4091 dtype: int64
4093 The `n` largest elements where ``n=3``. Default `keep` value is 'first'
4094 so Malta will be kept.
4096 >>> s.nlargest(3)
4097 France 65000000
4098 Italy 59000000
4099 Malta 434000
4100 dtype: int64
4102 The `n` largest elements where ``n=3`` and keeping the last duplicates.
4103 Brunei will be kept since it is the last with value 434000 based on
4104 the index order.
4106 >>> s.nlargest(3, keep="last")
4107 France 65000000
4108 Italy 59000000
4109 Brunei 434000
4110 dtype: int64
4112 The `n` largest elements where ``n=3`` with all duplicates kept. Note
4113 that the returned Series has five elements due to the three duplicates.
4115 >>> s.nlargest(3, keep="all")
4116 France 65000000
4117 Italy 59000000
4118 Malta 434000
4119 Maldives 434000
4120 Brunei 434000
4121 dtype: int64
4122 """
4123 return selectn.SelectNSeries(self, n=n, keep=keep).nlargest()
4125 def nsmallest(
4126 self, n: int = 5, keep: Literal["first", "last", "all"] = "first"
4127 ) -> Series:
4128 """
4129 Return the smallest `n` elements.
4131 Parameters
4132 ----------
4133 n : int, default 5
4134 Return this many ascending sorted values.
4135 keep : {'first', 'last', 'all'}, default 'first'
4136 When there are duplicate values that cannot all fit in a
4137 Series of `n` elements:
4139 - ``first`` : return the first `n` occurrences in order
4140 of appearance.
4141 - ``last`` : return the last `n` occurrences in reverse
4142 order of appearance.
4143 - ``all`` : keep all occurrences. This can result in a Series of
4144 size larger than `n`.
4146 Returns
4147 -------
4148 Series
4149 The `n` smallest values in the Series, sorted in increasing order.
4151 See Also
4152 --------
4153 Series.nlargest: Get the `n` largest elements.
4154 Series.sort_values: Sort Series by values.
4155 Series.head: Return the first `n` rows.
4157 Notes
4158 -----
4159 Faster than ``.sort_values().head(n)`` for small `n` relative to
4160 the size of the ``Series`` object.
4162 Examples
4163 --------
4164 >>> countries_population = {
4165 ... "Italy": 59000000,
4166 ... "France": 65000000,
4167 ... "Brunei": 434000,
4168 ... "Malta": 434000,
4169 ... "Maldives": 434000,
4170 ... "Iceland": 337000,
4171 ... "Nauru": 11300,
4172 ... "Tuvalu": 11300,
4173 ... "Anguilla": 11300,
4174 ... "Montserrat": 5200,
4175 ... }
4176 >>> s = pd.Series(countries_population)
4177 >>> s
4178 Italy 59000000
4179 France 65000000
4180 Brunei 434000
4181 Malta 434000
4182 Maldives 434000
4183 Iceland 337000
4184 Nauru 11300
4185 Tuvalu 11300
4186 Anguilla 11300
4187 Montserrat 5200
4188 dtype: int64
4190 The `n` smallest elements where ``n=5`` by default.
4192 >>> s.nsmallest()
4193 Montserrat 5200
4194 Nauru 11300
4195 Tuvalu 11300
4196 Anguilla 11300
4197 Iceland 337000
4198 dtype: int64
4200 The `n` smallest elements where ``n=3``. Default `keep` value is
4201 'first' so Nauru and Tuvalu will be kept.
4203 >>> s.nsmallest(3)
4204 Montserrat 5200
4205 Nauru 11300
4206 Tuvalu 11300
4207 dtype: int64
4209 The `n` smallest elements where ``n=3`` and keeping the last
4210 duplicates. Anguilla and Tuvalu will be kept since they are the last
4211 with value 11300 based on the index order.
4213 >>> s.nsmallest(3, keep="last")
4214 Montserrat 5200
4215 Anguilla 11300
4216 Tuvalu 11300
4217 dtype: int64
4219 The `n` smallest elements where ``n=3`` with all duplicates kept. Note
4220 that the returned Series has four elements due to the three duplicates.
4222 >>> s.nsmallest(3, keep="all")
4223 Montserrat 5200
4224 Nauru 11300
4225 Tuvalu 11300
4226 Anguilla 11300
4227 dtype: int64
4228 """
4229 return selectn.SelectNSeries(self, n=n, keep=keep).nsmallest()
4231 def swaplevel(
4232 self, i: Level = -2, j: Level = -1, copy: bool | lib.NoDefault = lib.no_default
4233 ) -> Series:
4234 """
4235 Swap levels i and j in a :class:`MultiIndex`.
4237 Default is to swap the two innermost levels of the index.
4239 Parameters
4240 ----------
4241 i, j : int or str
4242 Levels of the indices to be swapped. Can pass level name as string.
4243 copy : bool, default False
4244 This keyword is now ignored; changing its value will have no
4245 impact on the method.
4247 .. deprecated:: 3.0.0
4249 This keyword is ignored and will be removed in pandas 4.0. Since
4250 pandas 3.0, this method always returns a new object using a lazy
4251 copy mechanism that defers copies until necessary
4252 (Copy-on-Write). See the `user guide on Copy-on-Write
4253 <https://pandas.pydata.org/docs/dev/user_guide/copy_on_write.html>`__
4254 for more details.
4256 Returns
4257 -------
4258 Series
4259 Series with levels swapped in MultiIndex.
4261 See Also
4262 --------
4263 DataFrame.swaplevel : Swap levels i and j in a :class:`DataFrame`.
4264 Series.reorder_levels : Rearrange index levels using input order.
4265 MultiIndex.swaplevel : Swap levels i and j in a :class:`MultiIndex`.
4267 Examples
4268 --------
4269 >>> s = pd.Series(
4270 ... ["A", "B", "A", "C"],
4271 ... index=[
4272 ... ["Final exam", "Final exam", "Coursework", "Coursework"],
4273 ... ["History", "Geography", "History", "Geography"],
4274 ... ["January", "February", "March", "April"],
4275 ... ],
4276 ... )
4277 >>> s
4278 Final exam History January A
4279 Geography February B
4280 Coursework History March A
4281 Geography April C
4282 dtype: str
4284 In the following example, we will swap the levels of the indices.
4285 Here, we will swap the levels column-wise, but levels can be swapped row-wise
4286 in a similar manner. Note that column-wise is the default behavior.
4287 By not supplying any arguments for i and j, we swap the last and second to
4288 last indices.
4290 >>> s.swaplevel()
4291 Final exam January History A
4292 February Geography B
4293 Coursework March History A
4294 April Geography C
4295 dtype: str
4297 By supplying one argument, we can choose which index to swap the last
4298 index with. We can for example swap the first index with the last one as
4299 follows.
4301 >>> s.swaplevel(0)
4302 January History Final exam A
4303 February Geography Final exam B
4304 March History Coursework A
4305 April Geography Coursework C
4306 dtype: str
4308 We can also define explicitly which indices we want to swap by supplying values
4309 for both i and j. Here, we for example swap the first and second indices.
4311 >>> s.swaplevel(0, 1)
4312 History Final exam January A
4313 Geography Final exam February B
4314 History Coursework March A
4315 Geography Coursework April C
4316 dtype: str
4317 """
4318 self._check_copy_deprecation(copy)
4319 assert isinstance(self.index, MultiIndex)
4320 result = self.copy(deep=False)
4321 result.index = self.index.swaplevel(i, j)
4322 return result
4324 def reorder_levels(self, order: Sequence[Level]) -> Series:
4325 """
4326 Rearrange index levels using input order.
4328 May not drop or duplicate levels.
4330 Parameters
4331 ----------
4332 order : list of int representing new level order
4333 Reference level by number or key.
4335 Returns
4336 -------
4337 Series
4338 Type of caller with index as MultiIndex (new object).
4340 See Also
4341 --------
4342 DataFrame.reorder_levels : Rearrange index or column levels using
4343 input ``order``.
4345 Examples
4346 --------
4347 >>> arrays = [
4348 ... np.array(["dog", "dog", "cat", "cat", "bird", "bird"]),
4349 ... np.array(["white", "black", "white", "black", "white", "black"]),
4350 ... ]
4351 >>> s = pd.Series([1, 2, 3, 3, 5, 2], index=arrays)
4352 >>> s
4353 dog white 1
4354 black 2
4355 cat white 3
4356 black 3
4357 bird white 5
4358 black 2
4359 dtype: int64
4360 >>> s.reorder_levels([1, 0])
4361 white dog 1
4362 black dog 2
4363 white cat 3
4364 black cat 3
4365 white bird 5
4366 black bird 2
4367 dtype: int64
4368 """
4369 if not isinstance(self.index, MultiIndex): # pragma: no cover
4370 raise Exception("Can only reorder levels on a hierarchical axis.")
4372 result = self.copy(deep=False)
4373 assert isinstance(result.index, MultiIndex)
4374 result.index = result.index.reorder_levels(order)
4375 return result
4377 def explode(self, ignore_index: bool = False) -> Series:
4378 """
4379 Transform each element of a list-like to a row.
4381 Parameters
4382 ----------
4383 ignore_index : bool, default False
4384 If True, the resulting index will be labeled 0, 1, …, n - 1.
4386 Returns
4387 -------
4388 Series
4389 Exploded lists to rows; index will be duplicated for these rows.
4391 See Also
4392 --------
4393 Series.str.split : Split string values on specified separator.
4394 Series.unstack : Unstack, a.k.a. pivot, Series with MultiIndex
4395 to produce DataFrame.
4396 DataFrame.melt : Unpivot a DataFrame from wide format to long format.
4397 DataFrame.explode : Explode a DataFrame from list-like
4398 columns to long format.
4400 Notes
4401 -----
4402 This routine will explode list-likes including lists, tuples, sets,
4403 Series, and np.ndarray. The result dtype of the subset rows will
4404 be object. Scalars will be returned unchanged, and empty list-likes will
4405 result in an np.nan for that row. In addition, the ordering of elements in
4406 the output will be non-deterministic when exploding sets.
4408 Reference :ref:`the user guide <reshaping.explode>` for more examples.
4410 Examples
4411 --------
4412 >>> s = pd.Series([[1, 2, 3], "foo", [], [3, 4]])
4413 >>> s
4414 0 [1, 2, 3]
4415 1 foo
4416 2 []
4417 3 [3, 4]
4418 dtype: object
4420 >>> s.explode()
4421 0 1
4422 0 2
4423 0 3
4424 1 foo
4425 2 NaN
4426 3 3
4427 3 4
4428 dtype: object
4429 """
4430 if isinstance(self.dtype, ExtensionDtype):
4431 values, counts = self._values._explode()
4432 elif len(self) and is_object_dtype(self.dtype):
4433 values, counts = reshape.explode(np.asarray(self._values))
4434 else:
4435 result = self.copy()
4436 return result.reset_index(drop=True) if ignore_index else result
4438 if ignore_index:
4439 index: Index = default_index(len(values))
4440 else:
4441 index = self.index.repeat(counts)
4443 return self._constructor(values, index=index, name=self.name, copy=False)
4445 def unstack(
4446 self,
4447 level: IndexLabel = -1,
4448 fill_value: Hashable | None = None,
4449 sort: bool = True,
4450 ) -> DataFrame:
4451 """
4452 Unstack, also known as pivot, Series with MultiIndex to produce DataFrame.
4454 Parameters
4455 ----------
4456 level : int, str, or list of these, default last level
4457 Level(s) to unstack, can pass level name.
4458 fill_value : scalar value, default None
4459 Value to use when replacing NaN values.
4460 sort : bool, default True
4461 Sort the level(s) in the resulting MultiIndex columns.
4463 Returns
4464 -------
4465 DataFrame
4466 Unstacked Series.
4468 See Also
4469 --------
4470 DataFrame.unstack : Pivot the MultiIndex of a DataFrame.
4472 Notes
4473 -----
4474 Reference :ref:`the user guide <reshaping.stacking>` for more examples.
4476 Examples
4477 --------
4478 >>> s = pd.Series(
4479 ... [1, 2, 3, 4],
4480 ... index=pd.MultiIndex.from_product([["one", "two"], ["a", "b"]]),
4481 ... )
4482 >>> s
4483 one a 1
4484 b 2
4485 two a 3
4486 b 4
4487 dtype: int64
4489 >>> s.unstack(level=-1)
4490 a b
4491 one 1 2
4492 two 3 4
4494 >>> s.unstack(level=0)
4495 one two
4496 a 1 3
4497 b 2 4
4498 """
4499 from pandas.core.reshape.reshape import unstack
4501 return unstack(self, level, fill_value, sort)
4503 # ----------------------------------------------------------------------
4504 # function application
4506 def map(
4507 self,
4508 func: Callable | Mapping | Series | None = None,
4509 na_action: Literal["ignore"] | None = None,
4510 engine: Callable | None = None,
4511 **kwargs,
4512 ) -> Series:
4513 """
4514 Map values of Series according to an input mapping or function.
4516 Used for substituting each value in a Series with another value,
4517 that may be derived from a function, a ``dict`` or
4518 a :class:`Series`.
4520 Parameters
4521 ----------
4522 func : function, collections.abc.Mapping subclass or Series
4523 Function or mapping correspondence.
4524 na_action : {None, 'ignore'}, default None
4525 If 'ignore', propagate NaN values, without passing them to the
4526 mapping correspondence.
4527 engine : decorator, optional
4528 Choose the execution engine to use to run the function. Only used for
4529 functions. If ``map`` is called with a mapping or ``Series``, an
4530 exception will be raised. If ``engine`` is not provided the function will
4531 be executed by the regular Python interpreter.
4533 Options include JIT compilers such as Numba, Bodo or Blosc2, which in some
4534 cases can speed up the execution. To use an executor you can provide the
4535 decorators ``numba.jit``, ``numba.njit``, ``bodo.jit`` or ``blosc2.jit``.
4536 You can also provide the decorator with parameters, like
4537 ``numba.jit(nogit=True)``.
4539 Not all functions can be executed with all execution engines. In general,
4540 JIT compilers will require type stability in the function (no variable
4541 should change data type during the execution). And not all pandas and
4542 NumPy APIs are supported. Check the engine documentation for limitations.
4544 .. versionadded:: 3.0.0
4546 **kwargs
4547 Additional keyword arguments to pass as keywords arguments to
4548 `arg`.
4550 .. versionadded:: 3.0.0
4552 Returns
4553 -------
4554 Series
4555 Same index as caller.
4557 See Also
4558 --------
4559 Series.apply : For applying more complex functions on a Series.
4560 Series.replace: Replace values given in `to_replace` with `value`.
4561 DataFrame.apply : Apply a function row-/column-wise.
4562 DataFrame.map : Apply a function elementwise on a whole DataFrame.
4564 Notes
4565 -----
4566 When ``arg`` is a dictionary, values in Series that are not in the
4567 dictionary (as keys) are converted to ``NaN``. However, if the
4568 dictionary is a ``dict`` subclass that defines ``__missing__`` (i.e.
4569 provides a method for default values), then this default is used
4570 rather than ``NaN``.
4572 Examples
4573 --------
4574 >>> s = pd.Series(["cat", "dog", np.nan, "rabbit"])
4575 >>> s
4576 0 cat
4577 1 dog
4578 2 NaN
4579 3 rabbit
4580 dtype: str
4582 ``map`` accepts a ``dict`` or a ``Series``. Values that are not found
4583 in the ``dict`` are converted to ``NaN``, unless the dict has a default
4584 value (e.g. ``defaultdict``):
4586 >>> s.map({"cat": "kitten", "dog": "puppy"})
4587 0 kitten
4588 1 puppy
4589 2 NaN
4590 3 NaN
4591 dtype: str
4593 It also accepts a function:
4595 >>> s.map("I am a {}".format)
4596 0 I am a cat
4597 1 I am a dog
4598 2 I am a nan
4599 3 I am a rabbit
4600 dtype: str
4602 To avoid applying the function to missing values (and keep them as
4603 ``NaN``) ``na_action='ignore'`` can be used:
4605 >>> s.map("I am a {}".format, na_action="ignore")
4606 0 I am a cat
4607 1 I am a dog
4608 2 NaN
4609 3 I am a rabbit
4610 dtype: str
4612 For categorical data, the function is only applied to the categories:
4614 >>> s = pd.Series(list("cabaa"))
4615 >>> s.map(print)
4616 c
4617 a
4618 b
4619 a
4620 a
4621 0 None
4622 1 None
4623 2 None
4624 3 None
4625 4 None
4626 dtype: object
4628 >>> s_cat = s.astype("category")
4629 >>> s_cat.map(print) # function called once per unique category
4630 a
4631 b
4632 c
4633 0 None
4634 1 None
4635 2 None
4636 3 None
4637 4 None
4638 dtype: object
4639 """
4640 if func is None:
4641 if "arg" in kwargs:
4642 # `.map(arg=my_func)`
4643 func = kwargs.pop("arg")
4644 # https://github.com/pandas-dev/pandas/pull/61264
4645 warnings.warn(
4646 "The parameter `arg` has been renamed to `func`, and it "
4647 "will stop being supported in a future version of pandas.",
4648 Pandas4Warning,
4649 stacklevel=find_stack_level(),
4650 )
4651 else:
4652 raise ValueError("The `func` parameter is required")
4654 if engine is not None:
4655 if not callable(func):
4656 raise ValueError(
4657 "The engine argument can only be specified when func is a function"
4658 )
4659 if not hasattr(engine, "__pandas_udf__"):
4660 raise ValueError(f"Not a valid engine: {engine!r}")
4661 result = engine.__pandas_udf__.map( # type: ignore[attr-defined]
4662 data=self,
4663 func=func,
4664 args=(),
4665 kwargs=kwargs,
4666 decorator=engine,
4667 skip_na=na_action == "ignore",
4668 )
4669 if not isinstance(result, Series):
4670 result = Series(result, index=self.index, name=self.name)
4671 return result.__finalize__(self, method="map")
4673 if callable(func):
4674 func = functools.partial(func, **kwargs)
4675 new_values = self._map_values(func, na_action=na_action)
4676 return self._constructor(new_values, index=self.index, copy=False).__finalize__(
4677 self, method="map"
4678 )
4680 def _gotitem(self, key, ndim, subset=None) -> Self:
4681 """
4682 Sub-classes to define. Return a sliced object.
4684 Parameters
4685 ----------
4686 key : string / list of selections
4687 ndim : {1, 2}
4688 Requested ndim of result.
4689 subset : object, default None
4690 Subset to act on.
4691 """
4692 return self
4694 _agg_see_also_doc = dedent(
4695 """
4696 See Also
4697 --------
4698 Series.apply : Invoke function on a Series.
4699 Series.transform : Transform function producing a Series with like indexes.
4700 """
4701 )
4703 _agg_examples_doc = dedent(
4704 """
4705 Examples
4706 --------
4707 >>> s = pd.Series([1, 2, 3, 4])
4708 >>> s
4709 0 1
4710 1 2
4711 2 3
4712 3 4
4713 dtype: int64
4715 >>> s.agg('min')
4716 1
4718 >>> s.agg(['min', 'max'])
4719 min 1
4720 max 4
4721 dtype: int64
4722 """
4723 )
4725 def aggregate(self, func=None, axis: Axis = 0, *args, **kwargs):
4726 """
4727 Aggregate using one or more operations over the specified axis.
4729 Parameters
4730 ----------
4731 func : function, str, list or dict
4732 Function to use for aggregating the data. If a function, must either
4733 work when passed a Series or when passed to Series.apply.
4735 Accepted combinations are:
4737 - function
4738 - string function name
4739 - list of functions and/or function names, e.g. ``[np.sum, 'mean']``
4740 - dict of axis labels -> functions, function names or list of such.
4741 axis : {0 or 'index'}
4742 Unused. Parameter needed for compatibility with DataFrame.
4743 *args
4744 Positional arguments to pass to `func`.
4745 **kwargs
4746 Keyword arguments to pass to `func`.
4748 Returns
4749 -------
4750 scalar, Series or DataFrame
4751 The return can be:
4753 * scalar : when Series.agg is called with single function
4754 * Series : when DataFrame.agg is called with a single function
4755 * DataFrame : when DataFrame.agg is called with several functions
4757 See Also
4758 --------
4759 Series.apply : Invoke function on a Series.
4760 Series.transform : Transform function producing a Series with like indexes.
4762 Notes
4763 -----
4764 The aggregation operations are always performed over an axis, either the
4765 index (default) or the column axis. This behavior is different from
4766 `numpy` aggregation functions (`mean`, `median`, `prod`, `sum`, `std`,
4767 `var`), where the default is to compute the aggregation of the flattened
4768 array, e.g., ``numpy.mean(arr_2d)`` as opposed to
4769 ``numpy.mean(arr_2d, axis=0)``.
4771 `agg` is an alias for `aggregate`. Use the alias.
4773 Functions that mutate the passed object can produce unexpected
4774 behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
4775 for more details.
4777 A passed user-defined-function will be passed a Series for evaluation.
4779 If ``func`` defines an index relabeling, ``axis`` must be ``0`` or ``index``.
4781 Examples
4782 --------
4783 >>> s = pd.Series([1, 2, 3, 4])
4784 >>> s
4785 0 1
4786 1 2
4787 2 3
4788 3 4
4789 dtype: int64
4791 >>> s.agg("min")
4792 1
4794 >>> s.agg(["min", "max"])
4795 min 1
4796 max 4
4797 dtype: int64
4798 """
4800 # Validate the axis parameter
4801 self._get_axis_number(axis)
4803 # if func is None, will switch to user-provided "named aggregation" kwargs
4804 if func is None:
4805 func = dict(kwargs.items())
4807 op = SeriesApply(self, func, args=args, kwargs=kwargs)
4808 result = op.agg()
4809 return result
4811 agg = aggregate
4813 def transform(
4814 self, func: AggFuncType, axis: Axis = 0, *args, **kwargs
4815 ) -> DataFrame | Series:
4816 """
4817 Call ``func`` on self producing a Series with the same axis shape as self.
4819 Parameters
4820 ----------
4821 func : function, str, list-like or dict-like
4822 Function to use for transforming the data. If a function, must either
4823 work when passed a Series or when passed to Series.apply. If func
4824 is both list-like and dict-like, dict-like behavior takes precedence.
4826 Accepted combinations are:
4828 - function
4829 - string function name
4830 - list-like of functions and/or function names, e.g. ``[np.exp, 'sqrt']``
4831 - dict-like of axis labels -> functions, function names or list-like of such
4833 axis : {0 or 'index'}
4834 Unused. Parameter needed for compatibility with DataFrame.
4836 *args
4837 Positional arguments to pass to `func`.
4838 **kwargs
4839 Keyword arguments to pass to `func`.
4841 Returns
4842 -------
4843 Series
4844 A Series that must have the same length as self.
4846 Raises
4847 ------
4848 ValueError : If the returned Series has a different length than self.
4850 See Also
4851 --------
4852 Series.agg : Only perform aggregating type operations.
4853 Series.apply : Invoke function on a Series.
4855 Notes
4856 -----
4857 Functions that mutate the passed object can produce unexpected
4858 behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
4859 for more details.
4861 Examples
4862 --------
4863 >>> df = pd.DataFrame({"A": range(3), "B": range(1, 4)})
4864 >>> df
4865 A B
4866 0 0 1
4867 1 1 2
4868 2 2 3
4869 >>> df.transform(lambda x: x + 1)
4870 A B
4871 0 1 2
4872 1 2 3
4873 2 3 4
4875 Even though the resulting Series must have the same length as the
4876 input Series, it is possible to provide several input functions:
4878 >>> s = pd.Series(range(3))
4879 >>> s
4880 0 0
4881 1 1
4882 2 2
4883 dtype: int64
4884 >>> s.transform([np.sqrt, np.exp])
4885 sqrt exp
4886 0 0.000000 1.000000
4887 1 1.000000 2.718282
4888 2 1.414214 7.389056
4890 You can call transform on a GroupBy object:
4892 >>> df = pd.DataFrame(
4893 ... {
4894 ... "Date": [
4895 ... "2015-05-08",
4896 ... "2015-05-07",
4897 ... "2015-05-06",
4898 ... "2015-05-05",
4899 ... "2015-05-08",
4900 ... "2015-05-07",
4901 ... "2015-05-06",
4902 ... "2015-05-05",
4903 ... ],
4904 ... "Data": [5, 8, 6, 1, 50, 100, 60, 120],
4905 ... }
4906 ... )
4907 >>> df
4908 Date Data
4909 0 2015-05-08 5
4910 1 2015-05-07 8
4911 2 2015-05-06 6
4912 3 2015-05-05 1
4913 4 2015-05-08 50
4914 5 2015-05-07 100
4915 6 2015-05-06 60
4916 7 2015-05-05 120
4917 >>> df.groupby("Date")["Data"].transform("sum")
4918 0 55
4919 1 108
4920 2 66
4921 3 121
4922 4 55
4923 5 108
4924 6 66
4925 7 121
4926 Name: Data, dtype: int64
4928 >>> df = pd.DataFrame(
4929 ... {
4930 ... "c": [1, 1, 1, 2, 2, 2, 2],
4931 ... "type": ["m", "n", "o", "m", "m", "n", "n"],
4932 ... }
4933 ... )
4934 >>> df
4935 c type
4936 0 1 m
4937 1 1 n
4938 2 1 o
4939 3 2 m
4940 4 2 m
4941 5 2 n
4942 6 2 n
4943 >>> df["size"] = df.groupby("c")["type"].transform(len)
4944 >>> df
4945 c type size
4946 0 1 m 3
4947 1 1 n 3
4948 2 1 o 3
4949 3 2 m 4
4950 4 2 m 4
4951 5 2 n 4
4952 6 2 n 4
4953 """
4954 # Validate axis argument
4955 self._get_axis_number(axis)
4956 ser = self.copy(deep=False)
4957 result = SeriesApply(ser, func=func, args=args, kwargs=kwargs).transform()
4958 return result
4960 def apply(
4961 self,
4962 func: AggFuncType,
4963 args: tuple[Any, ...] = (),
4964 *,
4965 by_row: Literal[False, "compat"] = "compat",
4966 **kwargs,
4967 ) -> DataFrame | Series:
4968 """
4969 Invoke function on values of Series.
4971 Can be ufunc (a NumPy function that applies to the entire Series)
4972 or a Python function that only works on single values.
4974 Parameters
4975 ----------
4976 func : function
4977 Python function or NumPy ufunc to apply.
4978 args : tuple
4979 Positional arguments passed to func after the series value.
4980 by_row : False or "compat", default "compat"
4981 If ``"compat"`` and func is a callable, func will be passed each element of
4982 the Series, like ``Series.map``. If func is a list or dict of
4983 callables, will first try to translate each func into pandas methods. If
4984 that doesn't work, will try call to apply again with ``by_row="compat"``
4985 and if that fails, will call apply again with ``by_row=False``
4986 (backward compatible).
4987 If False, the func will be passed the whole Series at once.
4989 ``by_row`` has no effect when ``func`` is a string.
4991 .. versionadded:: 2.1.0
4992 **kwargs
4993 Additional keyword arguments passed to func.
4995 Returns
4996 -------
4997 Series or DataFrame
4998 If func returns a Series object the result will be a DataFrame.
5000 See Also
5001 --------
5002 Series.map: For element-wise operations.
5003 Series.agg: Only perform aggregating type operations.
5004 Series.transform: Only perform transforming type operations.
5006 Notes
5007 -----
5008 Functions that mutate the passed object can produce unexpected
5009 behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
5010 for more details.
5012 Examples
5013 --------
5014 Create a series with typical summer temperatures for each city.
5016 >>> s = pd.Series([20, 21, 12], index=["London", "New York", "Helsinki"])
5017 >>> s
5018 London 20
5019 New York 21
5020 Helsinki 12
5021 dtype: int64
5023 Square the values by defining a function and passing it as an
5024 argument to ``apply()``.
5026 >>> def square(x):
5027 ... return x**2
5028 >>> s.apply(square)
5029 London 400
5030 New York 441
5031 Helsinki 144
5032 dtype: int64
5034 Square the values by passing an anonymous function as an
5035 argument to ``apply()``.
5037 >>> s.apply(lambda x: x**2)
5038 London 400
5039 New York 441
5040 Helsinki 144
5041 dtype: int64
5043 Define a custom function that needs additional positional
5044 arguments and pass these additional arguments using the
5045 ``args`` keyword.
5047 >>> def subtract_custom_value(x, custom_value):
5048 ... return x - custom_value
5050 >>> s.apply(subtract_custom_value, args=(5,))
5051 London 15
5052 New York 16
5053 Helsinki 7
5054 dtype: int64
5056 Define a custom function that takes keyword arguments
5057 and pass these arguments to ``apply``.
5059 >>> def add_custom_values(x, **kwargs):
5060 ... for month in kwargs:
5061 ... x += kwargs[month]
5062 ... return x
5064 >>> s.apply(add_custom_values, june=30, july=20, august=25)
5065 London 95
5066 New York 96
5067 Helsinki 87
5068 dtype: int64
5070 Use a function from the Numpy library.
5072 >>> s.apply(np.log)
5073 London 2.995732
5074 New York 3.044522
5075 Helsinki 2.484907
5076 dtype: float64
5077 """
5078 return SeriesApply(
5079 self,
5080 func,
5081 by_row=by_row,
5082 args=args,
5083 kwargs=kwargs,
5084 ).apply()
5086 def _reindex_indexer(
5087 self,
5088 new_index: Index | None,
5089 indexer: npt.NDArray[np.intp] | None,
5090 ) -> Series:
5091 # Note: new_index is None iff indexer is None
5092 # if not None, indexer is np.intp
5093 if indexer is None and (
5094 new_index is None or new_index.names == self.index.names
5095 ):
5096 return self.copy(deep=False)
5098 new_values = algorithms.take_nd(
5099 self._values, indexer, allow_fill=True, fill_value=None
5100 )
5101 return self._constructor(new_values, index=new_index, copy=False)
5103 def _needs_reindex_multi(self, axes, method, level) -> bool:
5104 """
5105 Check if we do need a multi reindex; this is for compat with
5106 higher dims.
5107 """
5108 return False
5110 @overload
5111 def rename(
5112 self,
5113 index: Renamer | Hashable | None = ...,
5114 *,
5115 axis: Axis | None = ...,
5116 copy: bool | lib.NoDefault = ...,
5117 inplace: Literal[True],
5118 level: Level | None = ...,
5119 errors: IgnoreRaise = ...,
5120 ) -> Series | None: ...
5122 @overload
5123 def rename(
5124 self,
5125 index: Renamer | Hashable | None = ...,
5126 *,
5127 axis: Axis | None = ...,
5128 copy: bool | lib.NoDefault = ...,
5129 inplace: Literal[False] = ...,
5130 level: Level | None = ...,
5131 errors: IgnoreRaise = ...,
5132 ) -> Series: ...
5134 def rename(
5135 self,
5136 index: Renamer | Hashable | None = None,
5137 *,
5138 axis: Axis | None = None,
5139 copy: bool | lib.NoDefault = lib.no_default,
5140 inplace: bool = False,
5141 level: Level | None = None,
5142 errors: IgnoreRaise = "ignore",
5143 ) -> Series | None:
5144 """
5145 Alter Series index labels or name.
5147 Function / dict values must be unique (1-to-1). Labels not contained in
5148 a dict / Series will be left as-is. Extra labels listed don't throw an
5149 error.
5151 Alternatively, change ``Series.name`` with a scalar value.
5153 See the :ref:`user guide <basics.rename>` for more.
5155 Parameters
5156 ----------
5157 index : scalar, hashable sequence, dict-like or function optional
5158 Functions or dict-like are transformations to apply to
5159 the index.
5160 Scalar or hashable sequence-like will alter the ``Series.name``
5161 attribute.
5162 axis : {0 or 'index'}
5163 Unused. Parameter needed for compatibility with DataFrame.
5164 copy : bool, default False
5165 This keyword is now ignored; changing its value will have no
5166 impact on the method.
5168 .. deprecated:: 3.0.0
5170 This keyword is ignored and will be removed in pandas 4.0. Since
5171 pandas 3.0, this method always returns a new object using a lazy
5172 copy mechanism that defers copies until necessary
5173 (Copy-on-Write). See the `user guide on Copy-on-Write
5174 <https://pandas.pydata.org/docs/dev/user_guide/copy_on_write.html>`__
5175 for more details.
5177 inplace : bool, default False
5178 Whether to return a new Series. If True the value of copy is ignored.
5179 level : int or level name, default None
5180 In case of MultiIndex, only rename labels in the specified level.
5181 errors : {'ignore', 'raise'}, default 'ignore'
5182 If 'raise', raise `KeyError` when a `dict-like mapper` or
5183 `index` contains labels that are not present in the index being transformed.
5184 If 'ignore', existing keys will be renamed and extra keys will be ignored.
5186 Returns
5187 -------
5188 Series
5189 A shallow copy with index labels or name altered, or the same object
5190 if ``inplace=True`` and index is not a dict or callable else None.
5192 See Also
5193 --------
5194 DataFrame.rename : Corresponding DataFrame method.
5195 Series.rename_axis : Set the name of the axis.
5197 Examples
5198 --------
5199 >>> s = pd.Series([1, 2, 3])
5200 >>> s
5201 0 1
5202 1 2
5203 2 3
5204 dtype: int64
5205 >>> s.rename("my_name") # scalar, changes Series.name
5206 0 1
5207 1 2
5208 2 3
5209 Name: my_name, dtype: int64
5210 >>> s.rename(lambda x: x**2) # function, changes labels
5211 0 1
5212 1 2
5213 4 3
5214 dtype: int64
5215 >>> s.rename({1: 3, 2: 5}) # mapping, changes labels
5216 0 1
5217 3 2
5218 5 3
5219 dtype: int64
5220 """
5221 self._check_copy_deprecation(copy)
5222 if axis is not None:
5223 # Make sure we raise if an invalid 'axis' is passed.
5224 axis = self._get_axis_number(axis)
5226 if callable(index) or is_dict_like(index):
5227 # error: Argument 1 to "_rename" of "NDFrame" has incompatible
5228 # type "Union[Union[Mapping[Any, Hashable], Callable[[Any],
5229 # Hashable]], Hashable, None]"; expected "Union[Mapping[Any,
5230 # Hashable], Callable[[Any], Hashable], None]"
5231 return super()._rename(
5232 index, # type: ignore[arg-type]
5233 inplace=inplace,
5234 level=level,
5235 errors=errors,
5236 )
5237 else:
5238 return self._set_name(index, inplace=inplace)
5240 def set_axis(
5241 self,
5242 labels,
5243 *,
5244 axis: Axis = 0,
5245 copy: bool | lib.NoDefault = lib.no_default,
5246 ) -> Series:
5247 """
5248 Assign desired index to given axis.
5250 .. deprecated:: 3.0.0
5251 This keyword is ignored and will be removed in pandas 4.0. Since
5252 pandas 3.0, this method always returns a new object using a lazy
5253 copy mechanism that defers copies until necessary
5254 (Copy-on-Write). See the `user guide on Copy-on-Write
5255 <https://pandas.pydata.org/docs/dev/user_guide/copy_on_write.html>`__
5256 for more details.
5258 Indexes for row labels can be changed by assigning a list-like or Index.
5260 Parameters
5261 ----------
5262 labels : list-like or Index
5263 The values for the new index.
5264 axis : {0 or 'index'}, default 0
5265 The axis to update. The value 0 identifies the rows. For `Series`
5266 this parameter is unused and defaults to 0.
5267 copy : bool, default False
5268 This keyword is now ignored; changing its value will have no
5269 impact on the method.
5271 Returns
5272 -------
5273 Series
5274 A shallow copy of the object with axis altered to the given index.
5276 See Also
5277 --------
5278 Series.rename_axis : Alter the name of the index.
5280 Examples
5281 --------
5282 >>> s = pd.Series([1, 2, 3])
5283 >>> s
5284 0 1
5285 1 2
5286 2 3
5287 dtype: int64
5288 >>> s.set_axis(["a", "b", "c"], axis=0)
5289 a 1
5290 b 2
5291 c 3
5292 dtype: int64
5293 """
5295 return super().set_axis(labels, axis=axis, copy=copy)
5297 # error: Cannot determine type of 'reindex'
5299 def reindex( # type: ignore[override]
5300 self,
5301 index=None,
5302 *,
5303 axis: Axis | None = None,
5304 method: ReindexMethod | None = None,
5305 copy: bool | lib.NoDefault = lib.no_default,
5306 level: Level | None = None,
5307 fill_value: Scalar | None = None,
5308 limit: int | None = None,
5309 tolerance=None,
5310 ) -> Series:
5311 """
5312 Conform Series to new index with optional filling logic.
5314 Places NA/NaN in locations having no value in the previous index. A new object
5315 is produced unless the new index is equivalent to the current one and
5316 ``copy=False``.
5318 Parameters
5319 ----------
5320 index : scalar, list-like, dict-like or function, optional
5321 A scalar, list-like, dict-like or functions transformations to
5322 apply to that axis' values.
5323 axis : {0 or 'index'}, default 0
5324 The axis to rename. For `Series` this parameter is unused and defaults to 0.
5325 method : {None, 'backfill'/'bfill', 'pad'/'ffill', 'nearest'}
5326 Method to use for filling holes in reindexed DataFrame.
5327 Please note: this is only applicable to DataFrames/Series with a
5328 monotonically increasing/decreasing index.
5330 * None (default): don't fill gaps
5331 * pad / ffill: Propagate last valid observation forward to next
5332 valid.
5333 * backfill / bfill: Use next valid observation to fill gap.
5334 * nearest: Use nearest valid observations to fill gap.
5336 copy : bool, default False
5337 This keyword is now ignored; changing its value will have no
5338 impact on the method.
5340 .. deprecated:: 3.0.0
5342 This keyword is ignored and will be removed in pandas 4.0. Since
5343 pandas 3.0, this method always returns a new object using a lazy
5344 copy mechanism that defers copies until necessary
5345 (Copy-on-Write). See the `user guide on Copy-on-Write
5346 <https://pandas.pydata.org/docs/dev/user_guide/copy_on_write.html>`__
5347 for more details.
5349 level : int or name
5350 Broadcast across a level, matching Index values on the
5351 passed MultiIndex level.
5352 fill_value : scalar, default np.nan
5353 Value to use for missing values. Defaults to NaN, but can be any
5354 "compatible" value.
5355 limit : int, default None
5356 Maximum number of consecutive elements to forward or backward fill.
5357 tolerance : optional
5358 Maximum distance between original and new labels for inexact
5359 matches. The values of the index at the matching locations most
5360 satisfy the equation ``abs(index[indexer] - target) <= tolerance``.
5362 Tolerance may be a scalar value, which applies the same tolerance
5363 to all values, or list-like, which applies variable tolerance per
5364 element. List-like includes list, tuple, array, Series, and must be
5365 the same size as the index and its dtype must exactly match the
5366 index's type.
5368 Returns
5369 -------
5370 Series
5371 Series with changed index.
5373 See Also
5374 --------
5375 DataFrame.set_index : Set row labels.
5376 DataFrame.reset_index : Remove row labels or move them to new columns.
5377 DataFrame.reindex_like : Change to same indices as other DataFrame.
5379 Examples
5380 --------
5381 ``DataFrame.reindex`` supports two calling conventions
5383 * ``(index=index_labels, columns=column_labels, ...)``
5384 * ``(labels, axis={'index', 'columns'}, ...)``
5386 We *highly* recommend using keyword arguments to clarify your
5387 intent.
5389 Create a DataFrame with some fictional data.
5391 >>> index = ["Firefox", "Chrome", "Safari", "IE10", "Konqueror"]
5392 >>> columns = ["http_status", "response_time"]
5393 >>> df = pd.DataFrame(
5394 ... [[200, 0.04], [200, 0.02], [404, 0.07], [404, 0.08], [301, 1.0]],
5395 ... columns=columns,
5396 ... index=index,
5397 ... )
5398 >>> df
5399 http_status response_time
5400 Firefox 200 0.04
5401 Chrome 200 0.02
5402 Safari 404 0.07
5403 IE10 404 0.08
5404 Konqueror 301 1.00
5406 Create a new index and reindex the DataFrame. By default
5407 values in the new index that do not have corresponding
5408 records in the DataFrame are assigned ``NaN``.
5410 >>> new_index = ["Safari", "Iceweasel", "Comodo Dragon", "IE10", "Chrome"]
5411 >>> df.reindex(new_index)
5412 http_status response_time
5413 Safari 404.0 0.07
5414 Iceweasel NaN NaN
5415 Comodo Dragon NaN NaN
5416 IE10 404.0 0.08
5417 Chrome 200.0 0.02
5419 We can fill in the missing values by passing a value to
5420 the keyword ``fill_value``. Because the index is not monotonically
5421 increasing or decreasing, we cannot use arguments to the keyword
5422 ``method`` to fill the ``NaN`` values.
5424 >>> df.reindex(new_index, fill_value=0)
5425 http_status response_time
5426 Safari 404 0.07
5427 Iceweasel 0 0.00
5428 Comodo Dragon 0 0.00
5429 IE10 404 0.08
5430 Chrome 200 0.02
5432 >>> df.reindex(new_index, fill_value="missing")
5433 http_status response_time
5434 Safari 404 0.07
5435 Iceweasel missing missing
5436 Comodo Dragon missing missing
5437 IE10 404 0.08
5438 Chrome 200 0.02
5440 We can also reindex the columns.
5442 >>> df.reindex(columns=["http_status", "user_agent"])
5443 http_status user_agent
5444 Firefox 200 NaN
5445 Chrome 200 NaN
5446 Safari 404 NaN
5447 IE10 404 NaN
5448 Konqueror 301 NaN
5450 Or we can use "axis-style" keyword arguments
5452 >>> df.reindex(["http_status", "user_agent"], axis="columns")
5453 http_status user_agent
5454 Firefox 200 NaN
5455 Chrome 200 NaN
5456 Safari 404 NaN
5457 IE10 404 NaN
5458 Konqueror 301 NaN
5460 To further illustrate the filling functionality in
5461 ``reindex``, we will create a DataFrame with a
5462 monotonically increasing index (for example, a sequence
5463 of dates).
5465 >>> date_index = pd.date_range("1/1/2010", periods=6, freq="D")
5466 >>> df2 = pd.DataFrame(
5467 ... {"prices": [100, 101, np.nan, 100, 89, 88]}, index=date_index
5468 ... )
5469 >>> df2
5470 prices
5471 2010-01-01 100.0
5472 2010-01-02 101.0
5473 2010-01-03 NaN
5474 2010-01-04 100.0
5475 2010-01-05 89.0
5476 2010-01-06 88.0
5478 Suppose we decide to expand the DataFrame to cover a wider
5479 date range.
5481 >>> date_index2 = pd.date_range("12/29/2009", periods=10, freq="D")
5482 >>> df2.reindex(date_index2)
5483 prices
5484 2009-12-29 NaN
5485 2009-12-30 NaN
5486 2009-12-31 NaN
5487 2010-01-01 100.0
5488 2010-01-02 101.0
5489 2010-01-03 NaN
5490 2010-01-04 100.0
5491 2010-01-05 89.0
5492 2010-01-06 88.0
5493 2010-01-07 NaN
5495 The index entries that did not have a value in the original data frame
5496 (for example, '2009-12-29') are by default filled with ``NaN``.
5497 If desired, we can fill in the missing values using one of several
5498 options.
5500 For example, to back-propagate the last valid value to fill the ``NaN``
5501 values, pass ``bfill`` as an argument to the ``method`` keyword.
5503 >>> df2.reindex(date_index2, method="bfill")
5504 prices
5505 2009-12-29 100.0
5506 2009-12-30 100.0
5507 2009-12-31 100.0
5508 2010-01-01 100.0
5509 2010-01-02 101.0
5510 2010-01-03 NaN
5511 2010-01-04 100.0
5512 2010-01-05 89.0
5513 2010-01-06 88.0
5514 2010-01-07 NaN
5516 Please note that the ``NaN`` value present in the original DataFrame
5517 (at index value 2010-01-03) will not be filled by any of the
5518 value propagation schemes. This is because filling while reindexing
5519 does not look at DataFrame values, but only compares the original and
5520 desired indexes. If you do want to fill in the ``NaN`` values present
5521 in the original DataFrame, use the ``fillna()`` method.
5523 See the :ref:`user guide <basics.reindexing>` for more.
5524 """
5525 return super().reindex(
5526 index=index,
5527 method=method,
5528 level=level,
5529 fill_value=fill_value,
5530 limit=limit,
5531 tolerance=tolerance,
5532 copy=copy,
5533 )
5535 @overload # type: ignore[override]
5536 def rename_axis(
5537 self,
5538 mapper: IndexLabel | lib.NoDefault = ...,
5539 *,
5540 index=...,
5541 axis: Axis = ...,
5542 copy: bool | lib.NoDefault = ...,
5543 inplace: Literal[True],
5544 ) -> None: ...
5546 @overload
5547 def rename_axis(
5548 self,
5549 mapper: IndexLabel | lib.NoDefault = ...,
5550 *,
5551 index=...,
5552 axis: Axis = ...,
5553 copy: bool | lib.NoDefault = ...,
5554 inplace: Literal[False] = ...,
5555 ) -> Self: ...
5557 @overload
5558 def rename_axis(
5559 self,
5560 mapper: IndexLabel | lib.NoDefault = ...,
5561 *,
5562 index=...,
5563 axis: Axis = ...,
5564 copy: bool | lib.NoDefault = ...,
5565 inplace: bool = ...,
5566 ) -> Self | None: ...
5568 def rename_axis(
5569 self,
5570 mapper: IndexLabel | lib.NoDefault = lib.no_default,
5571 *,
5572 index=lib.no_default,
5573 axis: Axis = 0,
5574 copy: bool | lib.NoDefault = lib.no_default,
5575 inplace: bool = False,
5576 ) -> Self | None:
5577 """
5578 Set the name of the axis for the index.
5580 Parameters
5581 ----------
5582 mapper : scalar, list-like, optional
5583 Value to set the axis name attribute.
5585 Use either ``mapper`` and ``axis`` to
5586 specify the axis to target with ``mapper``, or ``index``.
5588 index : scalar, list-like, dict-like or function, optional
5589 A scalar, list-like, dict-like or functions transformations to
5590 apply to that axis' values.
5591 axis : {0 or 'index'}, default 0
5592 The axis to rename. For `Series` this parameter is unused and defaults to 0.
5593 copy : bool, default False
5594 This keyword is now ignored; changing its value will have no
5595 impact on the method.
5597 .. deprecated:: 3.0.0
5599 This keyword is ignored and will be removed in pandas 4.0. Since
5600 pandas 3.0, this method always returns a new object using a lazy
5601 copy mechanism that defers copies until necessary
5602 (Copy-on-Write). See the `user guide on Copy-on-Write
5603 <https://pandas.pydata.org/docs/dev/user_guide/copy_on_write.html>`__
5604 for more details.
5606 inplace : bool, default False
5607 Modifies the object directly, instead of creating a new Series
5608 or DataFrame.
5610 Returns
5611 -------
5612 Series, or None
5613 The same type as the caller or None if ``inplace=True``.
5615 See Also
5616 --------
5617 Series.rename : Alter Series index labels or name.
5618 DataFrame.rename : Alter DataFrame index labels or name.
5619 Index.rename : Set new names on index.
5621 Examples
5622 --------
5624 >>> s = pd.Series(["dog", "cat", "monkey"])
5625 >>> s
5626 0 dog
5627 1 cat
5628 2 monkey
5629 dtype: str
5630 >>> s.rename_axis("animal")
5631 animal
5632 0 dog
5633 1 cat
5634 2 monkey
5635 dtype: str
5636 """
5637 return super().rename_axis(
5638 mapper=mapper,
5639 index=index,
5640 axis=axis,
5641 inplace=inplace,
5642 copy=copy,
5643 )
5645 @overload
5646 def drop(
5647 self,
5648 labels: IndexLabel | ListLike = ...,
5649 *,
5650 axis: Axis = ...,
5651 index: IndexLabel | ListLike = ...,
5652 columns: IndexLabel | ListLike = ...,
5653 level: Level | None = ...,
5654 inplace: Literal[True],
5655 errors: IgnoreRaise = ...,
5656 ) -> None: ...
5658 @overload
5659 def drop(
5660 self,
5661 labels: IndexLabel | ListLike = ...,
5662 *,
5663 axis: Axis = ...,
5664 index: IndexLabel | ListLike = ...,
5665 columns: IndexLabel | ListLike = ...,
5666 level: Level | None = ...,
5667 inplace: Literal[False] = ...,
5668 errors: IgnoreRaise = ...,
5669 ) -> Series: ...
5671 @overload
5672 def drop(
5673 self,
5674 labels: IndexLabel | ListLike = ...,
5675 *,
5676 axis: Axis = ...,
5677 index: IndexLabel | ListLike = ...,
5678 columns: IndexLabel | ListLike = ...,
5679 level: Level | None = ...,
5680 inplace: bool = ...,
5681 errors: IgnoreRaise = ...,
5682 ) -> Series | None: ...
5684 def drop(
5685 self,
5686 labels: IndexLabel | ListLike = None,
5687 *,
5688 axis: Axis = 0,
5689 index: IndexLabel | ListLike = None,
5690 columns: IndexLabel | ListLike = None,
5691 level: Level | None = None,
5692 inplace: bool = False,
5693 errors: IgnoreRaise = "raise",
5694 ) -> Series | None:
5695 """
5696 Return Series with specified index labels removed.
5698 Remove elements of a Series based on specifying the index labels.
5699 When using a multi-index, labels on different levels can be removed
5700 by specifying the level.
5702 Parameters
5703 ----------
5704 labels : single label or list-like
5705 Index labels to drop.
5706 axis : {0 or 'index'}
5707 Unused. Parameter needed for compatibility with DataFrame.
5708 index : single label or list-like
5709 Redundant for application on Series, but 'index' can be used instead
5710 of 'labels'.
5711 columns : single label or list-like
5712 No change is made to the Series; use 'index' or 'labels' instead.
5713 level : int or level name, optional
5714 For MultiIndex, level for which the labels will be removed.
5715 inplace : bool, default False
5716 If True, do operation inplace and return None.
5717 errors : {'ignore', 'raise'}, default 'raise'
5718 If 'ignore', suppress error and only existing labels are dropped.
5720 Returns
5721 -------
5722 Series or None
5723 Series with specified index labels removed or None if ``inplace=True``.
5725 Raises
5726 ------
5727 KeyError
5728 If none of the labels are found in the index.
5730 See Also
5731 --------
5732 Series.reindex : Return only specified index labels of Series.
5733 Series.dropna : Return series without null values.
5734 Series.drop_duplicates : Return Series with duplicate values removed.
5735 DataFrame.drop : Drop specified labels from rows or columns.
5737 Examples
5738 --------
5739 >>> s = pd.Series(data=np.arange(3), index=["A", "B", "C"])
5740 >>> s
5741 A 0
5742 B 1
5743 C 2
5744 dtype: int64
5746 Drop labels B and C
5748 >>> s.drop(labels=["B", "C"])
5749 A 0
5750 dtype: int64
5752 Drop 2nd level label in MultiIndex Series
5754 >>> midx = pd.MultiIndex(
5755 ... levels=[["llama", "cow", "falcon"], ["speed", "weight", "length"]],
5756 ... codes=[[0, 0, 0, 1, 1, 1, 2, 2, 2], [0, 1, 2, 0, 1, 2, 0, 1, 2]],
5757 ... )
5758 >>> s = pd.Series([45, 200, 1.2, 30, 250, 1.5, 320, 1, 0.3], index=midx)
5759 >>> s
5760 llama speed 45.0
5761 weight 200.0
5762 length 1.2
5763 cow speed 30.0
5764 weight 250.0
5765 length 1.5
5766 falcon speed 320.0
5767 weight 1.0
5768 length 0.3
5769 dtype: float64
5771 >>> s.drop(labels="weight", level=1)
5772 llama speed 45.0
5773 length 1.2
5774 cow speed 30.0
5775 length 1.5
5776 falcon speed 320.0
5777 length 0.3
5778 dtype: float64
5779 """
5780 return super().drop(
5781 labels=labels,
5782 axis=axis,
5783 index=index,
5784 columns=columns,
5785 level=level,
5786 inplace=inplace,
5787 errors=errors,
5788 )
5790 def pop(self, item: Hashable) -> Any:
5791 """
5792 Return item and drops from series. Raise KeyError if not found.
5794 Parameters
5795 ----------
5796 item : label
5797 Index of the element that needs to be removed.
5799 Returns
5800 -------
5801 scalar
5802 Value that is popped from series.
5804 See Also
5805 --------
5806 Series.drop: Drop specified values from Series.
5807 Series.drop_duplicates: Return Series with duplicate values removed.
5809 Examples
5810 --------
5811 >>> ser = pd.Series([1, 2, 3])
5813 >>> ser.pop(0)
5814 1
5816 >>> ser
5817 1 2
5818 2 3
5819 dtype: int64
5820 """
5821 return maybe_unbox_numpy_scalar(super().pop(item=item))
5823 def info(
5824 self,
5825 verbose: bool | None = None,
5826 buf: IO[str] | None = None,
5827 max_cols: int | None = None,
5828 memory_usage: bool | str | None = None,
5829 show_counts: bool = True,
5830 ) -> None:
5831 """
5832 Print a concise summary of a Series.
5834 This method prints information about a Series including
5835 the index dtype, non-NA values and memory usage.
5837 Parameters
5838 ----------
5839 verbose : bool, optional
5840 Whether to print the full summary. By default, the setting in
5841 ``pandas.options.display.max_info_columns`` is followed.
5842 buf : writable buffer, defaults to sys.stdout
5843 Where to send the output. By default, the output is printed to
5844 sys.stdout. Pass a writable buffer if you need to further process
5845 the output.
5846 max_cols : int, optional
5847 Unused, exists only for compatibility with DataFrame.info.
5848 memory_usage : bool, str, optional
5849 Specifies whether total memory usage of the Series
5850 elements (including the index) should be displayed. By default,
5851 this follows the ``pandas.options.display.memory_usage`` setting.
5853 True always show memory usage. False never shows memory usage.
5854 A value of 'deep' is equivalent to "True with deep introspection".
5855 Memory usage is shown in human-readable units (base-2
5856 representation). Without deep introspection a memory estimation is
5857 made based in column dtype and number of rows assuming values
5858 consume the same memory amount for corresponding dtypes. With deep
5859 memory introspection, a real memory usage calculation is performed
5860 at the cost of computational resources. See the
5861 :ref:`Frequently Asked Questions <df-memory-usage>` for more
5862 details.
5863 show_counts : bool, optional
5864 Whether to show the non-null counts. By default, this is shown
5865 only if the DataFrame is smaller than
5866 ``pandas.options.display.max_info_rows`` and
5867 ``pandas.options.display.max_info_columns``. A value of True always
5868 shows the counts, and False never shows the counts.
5870 Returns
5871 -------
5872 None
5873 This method prints a summary of a Series and returns None.
5875 See Also
5876 --------
5877 Series.describe: Generate descriptive statistics of Series.
5878 Series.memory_usage: Memory usage of Series.
5880 Examples
5881 --------
5882 >>> int_values = [1, 2, 3, 4, 5]
5883 >>> text_values = ["alpha", "beta", "gamma", "delta", "epsilon"]
5884 >>> s = pd.Series(text_values, index=int_values)
5885 >>> s.info()
5886 <class 'pandas.Series'>
5887 Index: 5 entries, 1 to 5
5888 Series name: None
5889 Non-Null Count Dtype
5890 -------------- -----
5891 5 non-null str
5892 dtypes: str(1)
5893 memory usage: 106.0 bytes
5895 Prints a summary excluding information about its values:
5897 >>> s.info(verbose=False)
5898 <class 'pandas.Series'>
5899 Index: 5 entries, 1 to 5
5900 dtypes: str(1)
5901 memory usage: 106.0 bytes
5903 Pipe output of Series.info to buffer instead of sys.stdout, get
5904 buffer content and writes to a text file:
5906 >>> import io
5907 >>> buffer = io.StringIO()
5908 >>> s.info(buf=buffer)
5909 >>> s = buffer.getvalue()
5910 >>> with open("df_info.txt", "w", encoding="utf-8") as f: # doctest: +SKIP
5911 ... f.write(s)
5912 260
5914 The `memory_usage` parameter allows deep introspection mode, specially
5915 useful for big Series and fine-tune memory optimization:
5917 >>> random_strings_array = np.random.choice(["a", "b", "c"], 10**6)
5918 >>> s = pd.Series(np.random.choice(["a", "b", "c"], 10**6))
5919 >>> s.info()
5920 <class 'pandas.Series'>
5921 RangeIndex: 1000000 entries, 0 to 999999
5922 Series name: None
5923 Non-Null Count Dtype
5924 -------------- -----
5925 1000000 non-null str
5926 dtypes: str(1)
5927 memory usage: 8.6 MB
5929 >>> s.info(memory_usage="deep")
5930 <class 'pandas.Series'>
5931 RangeIndex: 1000000 entries, 0 to 999999
5932 Series name: None
5933 Non-Null Count Dtype
5934 -------------- -----
5935 1000000 non-null str
5936 dtypes: str(1)
5937 memory usage: 8.6 MB
5938 """
5939 return SeriesInfo(self, memory_usage).render(
5940 buf=buf,
5941 max_cols=max_cols,
5942 verbose=verbose,
5943 show_counts=show_counts,
5944 )
5946 def memory_usage(self, index: bool = True, deep: bool = False) -> int:
5947 """
5948 Return the memory usage of the Series.
5950 The memory usage can optionally include the contribution of
5951 the index and of elements of `object` dtype.
5953 Parameters
5954 ----------
5955 index : bool, default True
5956 Specifies whether to include the memory usage of the Series index.
5957 deep : bool, default False
5958 If True, introspect the data deeply by interrogating
5959 `object` dtypes for system-level memory consumption, and include
5960 it in the returned value.
5962 Returns
5963 -------
5964 int
5965 Bytes of memory consumed.
5967 See Also
5968 --------
5969 numpy.ndarray.nbytes : Total bytes consumed by the elements of the
5970 array.
5971 DataFrame.memory_usage : Bytes consumed by a DataFrame.
5973 Examples
5974 --------
5975 >>> s = pd.Series(range(3))
5976 >>> s.memory_usage()
5977 156
5979 Not including the index gives the size of the rest of the data, which
5980 is necessarily smaller:
5982 >>> s.memory_usage(index=False)
5983 24
5985 The memory footprint of `object` values is ignored by default:
5987 >>> s = pd.Series(["a", "b"])
5988 >>> s.values
5989 <ArrowStringArray>
5990 ['a', 'b']
5991 Length: 2, dtype: str
5992 >>> s.memory_usage()
5993 150
5994 >>> s.memory_usage(deep=True)
5995 150
5996 """
5997 v = self._memory_usage(deep=deep)
5998 if index:
5999 v += self.index.memory_usage(deep=deep)
6000 return v
6002 def isin(self, values) -> Series:
6003 """
6004 Whether elements in Series are contained in `values`.
6006 Return a boolean Series showing whether each element in the Series
6007 matches an element in the passed sequence of `values` exactly.
6009 Parameters
6010 ----------
6011 values : set or list-like
6012 The sequence of values to test. Passing in a single string will
6013 raise a ``TypeError``. Instead, turn a single string into a
6014 list of one element.
6016 Returns
6017 -------
6018 Series
6019 Series of booleans indicating if each element is in values.
6021 Raises
6022 ------
6023 TypeError
6024 * If `values` is a string
6026 See Also
6027 --------
6028 DataFrame.isin : Equivalent method on DataFrame.
6030 Examples
6031 --------
6032 >>> s = pd.Series(
6033 ... ["llama", "cow", "llama", "beetle", "llama", "hippo"], name="animal"
6034 ... )
6035 >>> s.isin(["cow", "llama"])
6036 0 True
6037 1 True
6038 2 True
6039 3 False
6040 4 True
6041 5 False
6042 Name: animal, dtype: bool
6044 To invert the boolean values, use the ``~`` operator:
6046 >>> ~s.isin(["cow", "llama"])
6047 0 False
6048 1 False
6049 2 False
6050 3 True
6051 4 False
6052 5 True
6053 Name: animal, dtype: bool
6055 Passing a single string as ``s.isin('llama')`` will raise an error. Use
6056 a list of one element instead:
6058 >>> s.isin(["llama"])
6059 0 True
6060 1 False
6061 2 True
6062 3 False
6063 4 True
6064 5 False
6065 Name: animal, dtype: bool
6067 Strings and integers are distinct and are therefore not comparable:
6069 >>> pd.Series([1]).isin(["1"])
6070 0 False
6071 dtype: bool
6072 >>> pd.Series([1.1]).isin(["1.1"])
6073 0 False
6074 dtype: bool
6075 """
6076 result = algorithms.isin(self._values, values)
6077 return self._constructor(result, index=self.index, copy=False).__finalize__(
6078 self, method="isin"
6079 )
6081 def between(
6082 self,
6083 left,
6084 right,
6085 inclusive: Literal["both", "neither", "left", "right"] = "both",
6086 ) -> Series:
6087 """
6088 Return boolean Series equivalent to left <= series <= right.
6090 This function returns a boolean vector containing `True` wherever the
6091 corresponding Series element is between the boundary values `left` and
6092 `right`. NA values are treated as `False`.
6094 Parameters
6095 ----------
6096 left : scalar or list-like
6097 Left boundary.
6098 right : scalar or list-like
6099 Right boundary.
6100 inclusive : {"both", "neither", "left", "right"}
6101 Include boundaries. Whether to set each bound as closed or open.
6103 Returns
6104 -------
6105 Series
6106 Series representing whether each element is between left and
6107 right (inclusive).
6109 See Also
6110 --------
6111 Series.gt : Greater than of series and other.
6112 Series.lt : Less than of series and other.
6114 Notes
6115 -----
6116 This function is equivalent to ``(left <= ser) & (ser <= right)``
6118 Examples
6119 --------
6120 >>> s = pd.Series([2, 0, 4, 8, np.nan])
6122 Boundary values are included by default:
6124 >>> s.between(1, 4)
6125 0 True
6126 1 False
6127 2 True
6128 3 False
6129 4 False
6130 dtype: bool
6132 With `inclusive` set to ``"neither"`` boundary values are excluded:
6134 >>> s.between(1, 4, inclusive="neither")
6135 0 True
6136 1 False
6137 2 False
6138 3 False
6139 4 False
6140 dtype: bool
6142 `left` and `right` can be any scalar value:
6144 >>> s = pd.Series(["Alice", "Bob", "Carol", "Eve"])
6145 >>> s.between("Anna", "Daniel")
6146 0 False
6147 1 True
6148 2 True
6149 3 False
6150 dtype: bool
6151 """
6152 if inclusive == "both":
6153 lmask = self >= left
6154 rmask = self <= right
6155 elif inclusive == "left":
6156 lmask = self >= left
6157 rmask = self < right
6158 elif inclusive == "right":
6159 lmask = self > left
6160 rmask = self <= right
6161 elif inclusive == "neither":
6162 lmask = self > left
6163 rmask = self < right
6164 else:
6165 raise ValueError(
6166 "Inclusive has to be either string of 'both',"
6167 "'left', 'right', or 'neither'."
6168 )
6170 return lmask & rmask
6172 def case_when(
6173 self,
6174 caselist: list[
6175 tuple[
6176 ArrayLike | Callable[[Series], Series | np.ndarray | Sequence[bool]],
6177 ArrayLike | Scalar | Callable[[Series], Series | np.ndarray],
6178 ],
6179 ],
6180 ) -> Series:
6181 """
6182 Replace values where the conditions are True.
6184 .. versionadded:: 2.2.0
6186 Parameters
6187 ----------
6188 caselist : A list of tuples of conditions and expected replacements
6189 Takes the form: ``(condition0, replacement0)``,
6190 ``(condition1, replacement1)``, ... .
6191 ``condition`` should be a 1-D boolean array-like object
6192 or a callable. If ``condition`` is a callable,
6193 it is computed on the Series
6194 and should return a boolean Series or array.
6195 The callable must not change the input Series
6196 (though pandas doesn`t check it). ``replacement`` should be a
6197 1-D array-like object, a scalar or a callable.
6198 If ``replacement`` is a callable, it is computed on the Series
6199 and should return a scalar or Series. The callable
6200 must not change the input Series
6201 (though pandas doesn`t check it).
6203 Returns
6204 -------
6205 Series
6206 A new Series with values replaced based on the provided conditions.
6208 See Also
6209 --------
6210 Series.mask : Replace values where the condition is True.
6212 Examples
6213 --------
6214 >>> c = pd.Series([6, 7, 8, 9], name="c")
6215 >>> a = pd.Series([0, 0, 1, 2])
6216 >>> b = pd.Series([0, 3, 4, 5])
6218 >>> c.case_when(
6219 ... caselist=[
6220 ... (a.gt(0), a), # condition, replacement
6221 ... (b.gt(0), b),
6222 ... ]
6223 ... )
6224 0 6
6225 1 3
6226 2 1
6227 3 2
6228 Name: c, dtype: int64
6229 """
6230 if not isinstance(caselist, list):
6231 raise TypeError(
6232 f"The caselist argument should be a list; instead got {type(caselist)}"
6233 )
6235 if not caselist:
6236 raise ValueError(
6237 "provide at least one boolean condition, "
6238 "with a corresponding replacement."
6239 )
6241 for num, entry in enumerate(caselist):
6242 if not isinstance(entry, tuple):
6243 raise TypeError(
6244 f"Argument {num} must be a tuple; instead got {type(entry)}."
6245 )
6246 if len(entry) != 2:
6247 raise ValueError(
6248 f"Argument {num} must have length 2; "
6249 "a condition and replacement; "
6250 f"instead got length {len(entry)}."
6251 )
6252 caselist = [
6253 (
6254 com.apply_if_callable(condition, self),
6255 com.apply_if_callable(replacement, self),
6256 )
6257 for condition, replacement in caselist
6258 ]
6259 default = self.copy(deep=False)
6260 conditions, replacements = zip(*caselist, strict=True)
6261 common_dtypes = [infer_dtype_from(arg)[0] for arg in [*replacements, default]]
6262 if len(set(common_dtypes)) > 1:
6263 common_dtype = find_common_type(common_dtypes)
6264 updated_replacements = []
6265 for condition, replacement in zip(conditions, replacements, strict=True):
6266 if is_scalar(replacement):
6267 replacement = construct_1d_arraylike_from_scalar(
6268 value=replacement, length=len(condition), dtype=common_dtype
6269 )
6270 elif isinstance(replacement, ABCSeries):
6271 replacement = replacement.astype(common_dtype)
6272 else:
6273 replacement = pd_array(replacement, dtype=common_dtype)
6274 updated_replacements.append(replacement)
6275 replacements = updated_replacements
6276 default = default.astype(common_dtype)
6278 counter = range(len(conditions) - 1, -1, -1)
6279 for position, condition, replacement in zip(
6280 counter, reversed(conditions), reversed(replacements), strict=True
6281 ):
6282 try:
6283 default = default.mask(
6284 condition, other=replacement, axis=0, inplace=False, level=None
6285 )
6286 except Exception as error:
6287 raise ValueError(
6288 f"Failed to apply condition{position} and replacement{position}."
6289 ) from error
6290 return default
6292 # error: Cannot determine type of 'isna'
6293 def isna(self) -> Series:
6294 """
6295 Detect missing values.
6297 Return a boolean same-sized Series indicating if the values are NA.
6298 NA values, such as None or :attr:`numpy.NaN`, get mapped to True
6299 values.
6300 Everything else gets mapped to False values. Characters such as empty
6301 strings ``''`` or :attr:`numpy.inf` are not considered NA values.
6303 Returns
6304 -------
6305 Series
6306 Mask of bool values for each element in Series that
6307 indicates whether an element is an NA value.
6309 See Also
6310 --------
6311 DataFrame.isna : Detect missing values.
6312 DataFrame.isnull : Alias of isna.
6313 Series.notna : Boolean inverse of isna.
6314 DataFrame.notna : Boolean inverse of isna.
6315 Series.notnull : Alias of notna.
6316 DataFrame.notnull : Alias of notna.
6317 Series.dropna : Omit axes labels with missing values.
6318 DataFrame.dropna : Omit axes labels with missing values.
6319 isna : Top-level isna.
6321 Examples
6322 --------
6323 Show which entries in a Series are NA.
6325 >>> ser = pd.Series([5, 6, np.nan])
6326 >>> ser
6327 0 5.0
6328 1 6.0
6329 2 NaN
6330 dtype: float64
6331 >>> ser.isna()
6332 0 False
6333 1 False
6334 2 True
6335 dtype: bool
6336 """
6337 return NDFrame.isna(self)
6339 # error: Cannot determine type of 'isna'
6340 @doc(NDFrame.isna, klass=_shared_doc_kwargs["klass"])
6341 def isnull(self) -> Series:
6342 """
6343 Series.isnull is an alias for Series.isna.
6344 """
6345 return super().isnull()
6347 # error: Cannot determine type of 'notna'
6348 def notna(self) -> Series:
6349 """
6350 Detect existing (non-missing) values.
6352 Return a boolean same-sized Series indicating if the values are not NA.
6353 Non-missing values get mapped to True. Characters such as empty
6354 strings ``''`` or :attr:`numpy.inf` are not considered NA values.
6355 NA values, such as None or :attr:`numpy.NaN`, get mapped to False
6356 values.
6358 Returns
6359 -------
6360 Series
6361 Mask of bool values for each element in Series that
6362 indicates whether an element is not an NA value.
6364 See Also
6365 --------
6366 Series.isna : Detect missing values.
6367 DataFrame.isna : Detect missing values.
6368 Series.isnull : Alias of isna.
6369 DataFrame.isnull : Alias of isna.
6370 DataFrame.notna : Boolean inverse of isna.
6371 DataFrame.notnull : Alias of notna.
6372 Series.dropna : Omit axes labels with missing values.
6373 DataFrame.dropna : Omit axes labels with missing values.
6374 notna : Top-level notna.
6376 Examples
6377 --------
6378 Show which entries in a Series are not NA.
6380 >>> ser = pd.Series([5, 6, np.nan])
6381 >>> ser
6382 0 5.0
6383 1 6.0
6384 2 NaN
6385 dtype: float64
6386 >>> ser.notna()
6387 0 True
6388 1 True
6389 2 False
6390 dtype: bool
6391 """
6392 return super().notna()
6394 # error: Cannot determine type of 'notna'
6395 @doc(NDFrame.notna, klass=_shared_doc_kwargs["klass"])
6396 def notnull(self) -> Series:
6397 """
6398 Series.notnull is an alias for Series.notna.
6399 """
6400 return super().notnull()
6402 @overload
6403 def dropna(
6404 self,
6405 *,
6406 axis: Axis = ...,
6407 inplace: Literal[False] = ...,
6408 how: AnyAll | None = ...,
6409 ignore_index: bool = ...,
6410 ) -> Series: ...
6412 @overload
6413 def dropna(
6414 self,
6415 *,
6416 axis: Axis = ...,
6417 inplace: Literal[True],
6418 how: AnyAll | None = ...,
6419 ignore_index: bool = ...,
6420 ) -> None: ...
6422 def dropna(
6423 self,
6424 *,
6425 axis: Axis = 0,
6426 inplace: bool = False,
6427 how: AnyAll | None = None,
6428 ignore_index: bool = False,
6429 ) -> Series | None:
6430 """
6431 Return a new Series with missing values removed.
6433 See the :ref:`User Guide <missing_data>` for more on which values are
6434 considered missing, and how to work with missing data.
6436 Parameters
6437 ----------
6438 axis : {0 or 'index'}
6439 Unused. Parameter needed for compatibility with DataFrame.
6440 inplace : bool, default False
6441 If True, do operation inplace and return None.
6442 how : str, optional
6443 Not in use. Kept for compatibility.
6444 ignore_index : bool, default ``False``
6445 If ``True``, the resulting axis will be labeled 0, 1, …, n - 1.
6447 .. versionadded:: 2.0.0
6449 Returns
6450 -------
6451 Series or None
6452 Series with NA entries dropped from it or None if ``inplace=True``.
6454 See Also
6455 --------
6456 Series.isna: Indicate missing values.
6457 Series.notna : Indicate existing (non-missing) values.
6458 Series.fillna : Replace missing values.
6459 DataFrame.dropna : Drop rows or columns which contain NA values.
6460 Index.dropna : Drop missing indices.
6462 Examples
6463 --------
6464 >>> ser = pd.Series([1.0, 2.0, np.nan])
6465 >>> ser
6466 0 1.0
6467 1 2.0
6468 2 NaN
6469 dtype: float64
6471 Drop NA values from a Series.
6473 >>> ser.dropna()
6474 0 1.0
6475 1 2.0
6476 dtype: float64
6478 Empty strings are not considered NA values. ``None`` is considered an
6479 NA value.
6481 >>> ser = pd.Series([np.nan, 2, pd.NaT, "", None, "I stay"])
6482 >>> ser
6483 0 NaN
6484 1 2
6485 2 NaT
6486 3
6487 4 None
6488 5 I stay
6489 dtype: object
6490 >>> ser.dropna()
6491 1 2
6492 3
6493 5 I stay
6494 dtype: object
6495 """
6496 inplace = validate_bool_kwarg(inplace, "inplace")
6497 ignore_index = validate_bool_kwarg(ignore_index, "ignore_index")
6498 # Validate the axis parameter
6499 self._get_axis_number(axis or 0)
6501 if self._can_hold_na:
6502 result = remove_na_arraylike(self)
6503 elif not inplace:
6504 result = self.copy(deep=False)
6505 else:
6506 result = self
6508 if ignore_index:
6509 result.index = default_index(len(result))
6511 if inplace:
6512 return self._update_inplace(result)
6513 else:
6514 return result
6516 # ----------------------------------------------------------------------
6517 # Time series-oriented methods
6519 def to_timestamp(
6520 self,
6521 freq: Frequency | None = None,
6522 how: Literal["s", "e", "start", "end"] = "start",
6523 copy: bool | lib.NoDefault = lib.no_default,
6524 ) -> Series:
6525 """
6526 Cast to DatetimeIndex of Timestamps, at *beginning* of period.
6528 This can be changed to the *end* of the period, by specifying `how="e"`.
6530 Parameters
6531 ----------
6532 freq : str, default frequency of PeriodIndex
6533 Desired frequency.
6534 how : {'s', 'e', 'start', 'end'}
6535 Convention for converting period to timestamp; start of period
6536 vs. end.
6537 copy : bool, default False
6538 This keyword is now ignored; changing its value will have no
6539 impact on the method.
6541 .. deprecated:: 3.0.0
6543 This keyword is ignored and will be removed in pandas 4.0. Since
6544 pandas 3.0, this method always returns a new object using a lazy
6545 copy mechanism that defers copies until necessary
6546 (Copy-on-Write). See the `user guide on Copy-on-Write
6547 <https://pandas.pydata.org/docs/dev/user_guide/copy_on_write.html>`__
6548 for more details.
6550 Returns
6551 -------
6552 Series with DatetimeIndex
6553 Series with the PeriodIndex cast to DatetimeIndex.
6555 See Also
6556 --------
6557 Series.to_period: Inverse method to cast DatetimeIndex to PeriodIndex.
6558 DataFrame.to_timestamp: Equivalent method for DataFrame.
6560 Examples
6561 --------
6562 >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y")
6563 >>> s1 = pd.Series([1, 2, 3], index=idx)
6564 >>> s1
6565 2023 1
6566 2024 2
6567 2025 3
6568 Freq: Y-DEC, dtype: int64
6570 The resulting frequency of the Timestamps is `YearBegin`
6572 >>> s1 = s1.to_timestamp()
6573 >>> s1
6574 2023-01-01 1
6575 2024-01-01 2
6576 2025-01-01 3
6577 Freq: YS-JAN, dtype: int64
6579 Using `freq` which is the offset that the Timestamps will have
6581 >>> s2 = pd.Series([1, 2, 3], index=idx)
6582 >>> s2 = s2.to_timestamp(freq="M")
6583 >>> s2
6584 2023-01-31 1
6585 2024-01-31 2
6586 2025-01-31 3
6587 Freq: YE-JAN, dtype: int64
6588 """
6589 self._check_copy_deprecation(copy)
6590 if not isinstance(self.index, PeriodIndex):
6591 raise TypeError(f"unsupported Type {type(self.index).__name__}")
6593 new_obj = self.copy(deep=False)
6594 new_index = self.index.to_timestamp(freq=freq, how=how)
6595 setattr(new_obj, "index", new_index)
6596 return new_obj
6598 def to_period(
6599 self,
6600 freq: str | None = None,
6601 copy: bool | lib.NoDefault = lib.no_default,
6602 ) -> Series:
6603 """
6604 Convert Series from DatetimeIndex to PeriodIndex.
6606 Parameters
6607 ----------
6608 freq : str, default None
6609 Frequency associated with the PeriodIndex.
6610 copy : bool, default False
6611 This keyword is now ignored; changing its value will have no
6612 impact on the method.
6614 .. deprecated:: 3.0.0
6616 This keyword is ignored and will be removed in pandas 4.0. Since
6617 pandas 3.0, this method always returns a new object using a lazy
6618 copy mechanism that defers copies until necessary
6619 (Copy-on-Write). See the `user guide on Copy-on-Write
6620 <https://pandas.pydata.org/docs/dev/user_guide/copy_on_write.html>`__
6621 for more details.
6623 Returns
6624 -------
6625 Series
6626 Series with index converted to PeriodIndex.
6628 See Also
6629 --------
6630 DataFrame.to_period: Equivalent method for DataFrame.
6631 Series.dt.to_period: Convert DateTime column values.
6633 Examples
6634 --------
6635 >>> idx = pd.DatetimeIndex(["2023", "2024", "2025"])
6636 >>> s = pd.Series([1, 2, 3], index=idx)
6637 >>> s = s.to_period()
6638 >>> s
6639 2023 1
6640 2024 2
6641 2025 3
6642 Freq: Y-DEC, dtype: int64
6644 Viewing the index
6646 >>> s.index
6647 PeriodIndex(['2023', '2024', '2025'], dtype='period[Y-DEC]')
6648 """
6649 self._check_copy_deprecation(copy)
6650 if not isinstance(self.index, DatetimeIndex):
6651 raise TypeError(f"unsupported Type {type(self.index).__name__}")
6653 new_obj = self.copy(deep=False)
6654 new_index = self.index.to_period(freq=freq)
6655 setattr(new_obj, "index", new_index)
6656 return new_obj
6658 # ----------------------------------------------------------------------
6659 # Add index
6660 _AXIS_ORDERS: list[Literal["index", "columns"]] = ["index"]
6661 _AXIS_LEN = len(_AXIS_ORDERS)
6662 _info_axis_number: Literal[0] = 0
6663 _info_axis_name: Literal["index"] = "index"
6665 index = properties.AxisProperty(
6666 axis=0,
6667 doc="""
6668 The index (axis labels) of the Series.
6670 The index of a Series is used to label and identify each element of the
6671 underlying data. The index can be thought of as an immutable ordered set
6672 (technically a multi-set, as it may contain duplicate labels), and is
6673 used to index and align data in pandas.
6675 Returns
6676 -------
6677 Index
6678 The index labels of the Series.
6680 See Also
6681 --------
6682 Series.reindex : Conform Series to new index.
6683 Index : The base pandas index type.
6685 Notes
6686 -----
6687 For more information on pandas indexing, see the `indexing user guide
6688 <https://pandas.pydata.org/docs/user_guide/indexing.html>`__.
6690 Examples
6691 --------
6692 To create a Series with a custom index and view the index labels:
6694 >>> cities = ['Kolkata', 'Chicago', 'Toronto', 'Lisbon']
6695 >>> populations = [14.85, 2.71, 2.93, 0.51]
6696 >>> city_series = pd.Series(populations, index=cities)
6697 >>> city_series.index
6698 Index(['Kolkata', 'Chicago', 'Toronto', 'Lisbon'], dtype='object')
6700 To change the index labels of an existing Series:
6702 >>> city_series.index = ['KOL', 'CHI', 'TOR', 'LIS']
6703 >>> city_series.index
6704 Index(['KOL', 'CHI', 'TOR', 'LIS'], dtype='object')
6705 """,
6706 )
6708 # ----------------------------------------------------------------------
6709 # Accessor Methods
6710 # ----------------------------------------------------------------------
6711 str = Accessor("str", StringMethods)
6712 dt = Accessor("dt", CombinedDatetimelikeProperties)
6713 cat = Accessor("cat", CategoricalAccessor)
6714 plot = Accessor("plot", pandas.plotting.PlotAccessor)
6715 sparse = Accessor("sparse", SparseAccessor)
6716 struct = Accessor("struct", StructAccessor)
6717 list = Accessor("list", ListAccessor)
6719 # ----------------------------------------------------------------------
6720 # Add plotting methods to Series
6721 hist = pandas.plotting.hist_series
6723 # ----------------------------------------------------------------------
6724 # Template-Based Arithmetic/Comparison Methods
6726 def _cmp_method(self, other, op):
6727 res_name = ops.get_op_result_name(self, other)
6729 if isinstance(other, Series) and not self._indexed_same(other):
6730 raise ValueError("Can only compare identically-labeled Series objects")
6732 lvalues = self._values
6733 rvalues = extract_array(other, extract_numpy=True, extract_range=True)
6735 res_values = ops.comparison_op(lvalues, rvalues, op)
6737 return self._construct_result(res_values, name=res_name, other=other)
6739 def _logical_method(self, other, op):
6740 res_name = ops.get_op_result_name(self, other)
6741 self, other = self._align_for_op(other, align_asobject=True)
6743 lvalues = self._values
6744 rvalues = extract_array(other, extract_numpy=True, extract_range=True)
6746 res_values = ops.logical_op(lvalues, rvalues, op)
6747 return self._construct_result(res_values, name=res_name, other=other)
6749 def _arith_method(self, other, op):
6750 self, other = self._align_for_op(other)
6751 return base.IndexOpsMixin._arith_method(self, other, op)
6753 def _align_for_op(self, right, align_asobject: bool = False):
6754 """align lhs and rhs Series"""
6755 # TODO: Different from DataFrame._align_for_op, list, tuple and ndarray
6756 # are not coerced here
6757 # because Series has inconsistencies described in GH#13637
6758 left = self
6760 if isinstance(right, Series):
6761 # avoid repeated alignment
6762 if not left.index.equals(right.index):
6763 if align_asobject:
6764 if left.dtype not in (object, np.bool_) or right.dtype not in (
6765 object,
6766 np.bool_,
6767 ):
6768 pass
6769 # GH#52538 no longer cast in these cases
6770 else:
6771 # to keep original value's dtype for bool ops
6772 left = left.astype(object)
6773 right = right.astype(object)
6775 left, right = left.align(right)
6777 return left, right
6779 def _binop(self, other: Series, func, level=None, fill_value=None) -> Series:
6780 """
6781 Perform generic binary operation with optional fill value.
6783 Parameters
6784 ----------
6785 other : Series
6786 func : binary operator
6787 fill_value : float or object
6788 Value to substitute for NA/null values. If both Series are NA in a
6789 location, the result will be NA regardless of the passed fill value.
6790 level : int or level name, default None
6791 Broadcast across a level, matching Index values on the
6792 passed MultiIndex level.
6794 Returns
6795 -------
6796 Series
6797 """
6798 this = self
6800 if not self.index.equals(other.index):
6801 this, other = self.align(other, level=level, join="outer")
6803 this_vals, other_vals = ops.fill_binop(this._values, other._values, fill_value)
6805 with np.errstate(all="ignore"):
6806 result = func(this_vals, other_vals)
6808 name = ops.get_op_result_name(self, other)
6810 out = this._construct_result(result, name, other)
6811 return cast(Series, out)
6813 def _construct_result(
6814 self,
6815 result: ArrayLike | tuple[ArrayLike, ArrayLike],
6816 name: Hashable,
6817 other: AnyArrayLike | DataFrame,
6818 ) -> Series | tuple[Series, Series]:
6819 """
6820 Construct an appropriately-labelled Series from the result of an op.
6822 Parameters
6823 ----------
6824 result : ndarray or ExtensionArray
6825 name : Label
6826 other : Series, DataFrame or array-like
6828 Returns
6829 -------
6830 Series
6831 In the case of __divmod__ or __rdivmod__, a 2-tuple of Series.
6832 """
6833 if isinstance(result, tuple):
6834 # produced by divmod or rdivmod
6836 res1 = self._construct_result(result[0], name=name, other=other)
6837 res2 = self._construct_result(result[1], name=name, other=other)
6839 # GH#33427 assertions to keep mypy happy
6840 assert isinstance(res1, Series)
6841 assert isinstance(res2, Series)
6842 return (res1, res2)
6844 # TODO: result should always be ArrayLike, but this fails for some
6845 # JSONArray tests
6846 dtype = getattr(result, "dtype", None)
6847 out = self._constructor(result, index=self.index, dtype=dtype, copy=False)
6848 out = out.__finalize__(self)
6849 out = out.__finalize__(other)
6851 # Set the result's name after __finalize__ is called because __finalize__
6852 # would set it back to self.name
6853 out.name = name
6854 return out
6856 def _flex_method(self, other, op, *, level=None, fill_value=None, axis: Axis = 0):
6857 if axis is not None:
6858 self._get_axis_number(axis)
6860 res_name = ops.get_op_result_name(self, other)
6862 if isinstance(other, Series):
6863 return self._binop(other, op, level=level, fill_value=fill_value)
6864 elif isinstance(other, (np.ndarray, list, tuple, ExtensionArray)):
6865 if len(other) != len(self):
6866 raise ValueError("Lengths must be equal")
6867 other = self._constructor(other, self.index, copy=False)
6868 result = self._binop(other, op, level=level, fill_value=fill_value)
6869 result._name = res_name
6870 return result
6871 elif isinstance(other, ABCDataFrame):
6872 # GH#46179
6873 raise TypeError(
6874 f"Series.{op.__name__.strip('_')} does not support a DataFrame "
6875 f"`other`. Use df.{op.__name__.strip('_')}(ser) instead."
6876 )
6877 else:
6878 if fill_value is not None:
6879 if isna(other):
6880 return op(self, fill_value)
6881 self = self.fillna(fill_value)
6883 return op(self, other)
6885 def eq(
6886 self,
6887 other,
6888 level: Level | None = None,
6889 fill_value: float | None = None,
6890 axis: Axis = 0,
6891 ) -> Series:
6892 """
6893 Return Equal to of series and other, element-wise (binary operator `eq`).
6895 Equivalent to ``series == other``, but with support to substitute a fill_value
6896 for missing data in either one of the inputs.
6898 Parameters
6899 ----------
6900 other : object
6901 When a Series is provided, will align on indexes. For all other types,
6902 will behave the same as ``==`` but with possibly different results due
6903 to the other arguments.
6904 level : int or name
6905 Broadcast across a level, matching Index values on the
6906 passed MultiIndex level.
6907 fill_value : None or float value, default None (NaN)
6908 Fill existing missing (NaN) values, and any new element needed for
6909 successful Series alignment, with this value before computation.
6910 If data in both corresponding Series locations is missing
6911 the result of filling (at that location) will be missing.
6912 axis : {0 or 'index'}
6913 Unused. Parameter needed for compatibility with DataFrame.
6915 Returns
6916 -------
6917 Series
6918 The result of the operation.
6920 See Also
6921 --------
6922 Series.ge : Return elementwise Greater than or equal to of series and other.
6923 Series.le : Return elementwise Less than or equal to of series and other.
6924 Series.gt : Return elementwise Greater than of series and other.
6925 Series.lt : Return elementwise Less than of series and other.
6927 Examples
6928 --------
6929 >>> a = pd.Series([1, 1, 1, np.nan], index=["a", "b", "c", "d"])
6930 >>> a
6931 a 1.0
6932 b 1.0
6933 c 1.0
6934 d NaN
6935 dtype: float64
6936 >>> b = pd.Series([1, np.nan, 1, np.nan], index=["a", "b", "d", "e"])
6937 >>> b
6938 a 1.0
6939 b NaN
6940 d 1.0
6941 e NaN
6942 dtype: float64
6943 >>> a.eq(b, fill_value=0)
6944 a True
6945 b False
6946 c False
6947 d False
6948 e False
6949 dtype: bool
6950 """
6951 return self._flex_method(
6952 other, operator.eq, level=level, fill_value=fill_value, axis=axis
6953 )
6955 @Appender(ops.make_flex_doc("ne", "series"))
6956 def ne(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
6957 return self._flex_method(
6958 other, operator.ne, level=level, fill_value=fill_value, axis=axis
6959 )
6961 def le(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
6962 """
6963 Return Less than or equal to of series and other, \
6964 element-wise (binary operator `le`).
6966 Equivalent to ``series <= other``, but with support to substitute a
6967 fill_value for missing data in either one of the inputs.
6969 Parameters
6970 ----------
6971 other : object
6972 When a Series is provided, will align on indexes. For all other types,
6973 will behave the same as ``==`` but with possibly different results due
6974 to the other arguments.
6975 level : int or name
6976 Broadcast across a level, matching Index values on the
6977 passed MultiIndex level.
6978 fill_value : None or float value, default None (NaN)
6979 Fill existing missing (NaN) values, and any new element needed for
6980 successful Series alignment, with this value before computation.
6981 If data in both corresponding Series locations is missing
6982 the result of filling (at that location) will be missing.
6983 axis : {0 or 'index'}
6984 Unused. Parameter needed for compatibility with DataFrame.
6986 Returns
6987 -------
6988 Series
6989 The result of the operation.
6991 See Also
6992 --------
6993 Series.ge : Return elementwise Greater than or equal to of series and other.
6994 Series.lt : Return elementwise Less than of series and other.
6995 Series.gt : Return elementwise Greater than of series and other.
6996 Series.eq : Return elementwise equal to of series and other.
6998 Examples
6999 --------
7000 >>> a = pd.Series([1, 1, 1, np.nan, 1], index=['a', 'b', 'c', 'd', 'e'])
7001 >>> a
7002 a 1.0
7003 b 1.0
7004 c 1.0
7005 d NaN
7006 e 1.0
7007 dtype: float64
7008 >>> b = pd.Series([0, 1, 2, np.nan, 1], index=['a', 'b', 'c', 'd', 'f'])
7009 >>> b
7010 a 0.0
7011 b 1.0
7012 c 2.0
7013 d NaN
7014 f 1.0
7015 dtype: float64
7016 >>> a.le(b, fill_value=0)
7017 a False
7018 b True
7019 c True
7020 d False
7021 e False
7022 f True
7023 dtype: bool
7024 """
7025 return self._flex_method(
7026 other, operator.le, level=level, fill_value=fill_value, axis=axis
7027 )
7029 @Appender(ops.make_flex_doc("lt", "series"))
7030 def lt(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7031 return self._flex_method(
7032 other, operator.lt, level=level, fill_value=fill_value, axis=axis
7033 )
7035 def ge(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7036 """
7037 Return Greater than or equal to of series and other, \
7038 element-wise (binary operator `ge`).
7040 Equivalent to ``series >= other``, but with support to substitute a
7041 fill_value for missing data in either one of the inputs.
7043 Parameters
7044 ----------
7045 other : object
7046 When a Series is provided, will align on indexes. For all other types,
7047 will behave the same as ``==`` but with possibly different results due
7048 to the other arguments.
7049 level : int or name
7050 Broadcast across a level, matching Index values on the
7051 passed MultiIndex level.
7052 fill_value : None or float value, default None (NaN)
7053 Fill existing missing (NaN) values, and any new element needed for
7054 successful Series alignment, with this value before computation.
7055 If data in both corresponding Series locations is missing
7056 the result of filling (at that location) will be missing.
7057 axis : {0 or 'index'}
7058 Unused. Parameter needed for compatibility with DataFrame.
7060 Returns
7061 -------
7062 Series
7063 The result of the operation.
7065 See Also
7066 --------
7067 Series.gt : Greater than comparison, element-wise.
7068 Series.le : Less than or equal to comparison, element-wise.
7069 Series.lt : Less than comparison, element-wise.
7070 Series.eq : Equal to comparison, element-wise.
7071 Series.ne : Not equal to comparison, element-wise.
7073 Examples
7074 --------
7075 >>> a = pd.Series([1, 1, 1, np.nan, 1], index=["a", "b", "c", "d", "e"])
7076 >>> a
7077 a 1.0
7078 b 1.0
7079 c 1.0
7080 d NaN
7081 e 1.0
7082 dtype: float64
7083 >>> b = pd.Series([0, 1, 2, np.nan, 1], index=["a", "b", "c", "d", "f"])
7084 >>> b
7085 a 0.0
7086 b 1.0
7087 c 2.0
7088 d NaN
7089 f 1.0
7090 dtype: float64
7091 >>> a.ge(b, fill_value=0)
7092 a True
7093 b True
7094 c False
7095 d False
7096 e True
7097 f False
7098 dtype: bool
7099 """
7100 return self._flex_method(
7101 other, operator.ge, level=level, fill_value=fill_value, axis=axis
7102 )
7104 @Appender(ops.make_flex_doc("gt", "series"))
7105 def gt(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7106 return self._flex_method(
7107 other, operator.gt, level=level, fill_value=fill_value, axis=axis
7108 )
7110 def add(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7111 """
7112 Return Addition of series and other, element-wise (binary operator `add`).
7114 Equivalent to ``series + other``, but with support to substitute a fill_value
7115 for missing data in either one of the inputs.
7117 Parameters
7118 ----------
7119 other : Series or scalar value
7120 With which to compute the addition.
7121 level : int or name
7122 Broadcast across a level, matching Index values on the
7123 passed MultiIndex level.
7124 fill_value : None or float value, default None (NaN)
7125 Fill existing missing (NaN) values, and any new element needed for
7126 successful Series alignment, with this value before computation.
7127 If data in both corresponding Series locations is missing
7128 the result of filling (at that location) will be missing.
7129 axis : {0 or 'index'}
7130 Unused. Parameter needed for compatibility with DataFrame.
7132 Returns
7133 -------
7134 Series
7135 The result of the operation.
7137 See Also
7138 --------
7139 Series.radd : Reverse of the Addition operator, see
7140 `Python documentation
7141 <https://docs.python.org/3/reference/datamodel.html#emulating-numeric-types>`_
7142 for more details.
7144 Examples
7145 --------
7146 >>> a = pd.Series([1, 1, 1, np.nan], index=["a", "b", "c", "d"])
7147 >>> a
7148 a 1.0
7149 b 1.0
7150 c 1.0
7151 d NaN
7152 dtype: float64
7153 >>> b = pd.Series([1, np.nan, 1, np.nan], index=["a", "b", "d", "e"])
7154 >>> b
7155 a 1.0
7156 b NaN
7157 d 1.0
7158 e NaN
7159 dtype: float64
7160 >>> a.add(b, fill_value=0)
7161 a 2.0
7162 b 1.0
7163 c 1.0
7164 d 1.0
7165 e NaN
7166 dtype: float64
7167 """
7168 return self._flex_method(
7169 other, operator.add, level=level, fill_value=fill_value, axis=axis
7170 )
7172 @Appender(ops.make_flex_doc("radd", "series"))
7173 def radd(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7174 return self._flex_method(
7175 other, roperator.radd, level=level, fill_value=fill_value, axis=axis
7176 )
7178 @Appender(ops.make_flex_doc("sub", "series"))
7179 def sub(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7180 return self._flex_method(
7181 other, operator.sub, level=level, fill_value=fill_value, axis=axis
7182 )
7184 subtract = sub
7186 @Appender(ops.make_flex_doc("rsub", "series"))
7187 def rsub(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7188 return self._flex_method(
7189 other, roperator.rsub, level=level, fill_value=fill_value, axis=axis
7190 )
7192 def mul(
7193 self,
7194 other,
7195 level: Level | None = None,
7196 fill_value: float | None = None,
7197 axis: Axis = 0,
7198 ) -> Series:
7199 """
7200 Return Multiplication of series and other, element-wise (binary operator `mul`).
7202 Equivalent to ``series * other``, but with support to substitute
7203 a fill_value for missing data in either one of the inputs.
7205 Parameters
7206 ----------
7207 other : Series or scalar value
7208 With which to compute the multiplication.
7209 level : int or name
7210 Broadcast across a level, matching Index values on the
7211 passed MultiIndex level.
7212 fill_value : None or float value, default None (NaN)
7213 Fill existing missing (NaN) values, and any new element needed for
7214 successful Series alignment, with this value before computation.
7215 If data in both corresponding Series locations is missing
7216 the result of filling (at that location) will be missing.
7217 axis : {0 or 'index'}
7218 Unused. Parameter needed for compatibility with DataFrame.
7220 Returns
7221 -------
7222 Series
7223 The result of the operation.
7225 See Also
7226 --------
7227 Series.rmul : Reverse of the Multiplication operator, see
7228 `Python documentation
7229 <https://docs.python.org/3/reference/datamodel.html#emulating-numeric-types>`_
7230 for more details.
7232 Examples
7233 --------
7234 >>> a = pd.Series([1, 1, 1, np.nan], index=["a", "b", "c", "d"])
7235 >>> a
7236 a 1.0
7237 b 1.0
7238 c 1.0
7239 d NaN
7240 dtype: float64
7241 >>> b = pd.Series([1, np.nan, 1, np.nan], index=["a", "b", "d", "e"])
7242 >>> b
7243 a 1.0
7244 b NaN
7245 d 1.0
7246 e NaN
7247 dtype: float64
7248 >>> a.multiply(b, fill_value=0)
7249 a 1.0
7250 b 0.0
7251 c 0.0
7252 d 0.0
7253 e NaN
7254 dtype: float64
7255 >>> a.mul(5, fill_value=0)
7256 a 5.0
7257 b 5.0
7258 c 5.0
7259 d 0.0
7260 dtype: float64
7261 """
7262 return self._flex_method(
7263 other, operator.mul, level=level, fill_value=fill_value, axis=axis
7264 )
7266 multiply = mul
7268 @Appender(ops.make_flex_doc("rmul", "series"))
7269 def rmul(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7270 return self._flex_method(
7271 other, roperator.rmul, level=level, fill_value=fill_value, axis=axis
7272 )
7274 def truediv(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7275 """
7276 Return Floating division of series and other, \
7277 element-wise (binary operator `truediv`).
7279 Equivalent to ``series / other``, but with support to substitute a
7280 fill_value for missing data in either one of the inputs.
7282 Parameters
7283 ----------
7284 other : Series or scalar value
7285 Series with which to compute division.
7286 level : int or name
7287 Broadcast across a level, matching Index values on the
7288 passed MultiIndex level.
7289 fill_value : None or float value, default None (NaN)
7290 Fill existing missing (NaN) values, and any new element needed for
7291 successful Series alignment, with this value before computation.
7292 If data in both corresponding Series locations is missing
7293 the result of filling (at that location) will be missing.
7294 axis : {0 or 'index'}
7295 Unused. Parameter needed for compatibility with DataFrame.
7297 Returns
7298 -------
7299 Series
7300 The result of the operation.
7302 See Also
7303 --------
7304 Series.rtruediv : Reverse of the Floating division operator, see
7305 `Python documentation
7306 <https://docs.python.org/3/reference/datamodel.html#emulating-numeric-types>`_
7307 for more details.
7309 Examples
7310 --------
7311 >>> a = pd.Series([1, 1, 1, np.nan], index=["a", "b", "c", "d"])
7312 >>> a
7313 a 1.0
7314 b 1.0
7315 c 1.0
7316 d NaN
7317 dtype: float64
7318 >>> b = pd.Series([1, np.nan, 1, np.nan], index=["a", "b", "d", "e"])
7319 >>> b
7320 a 1.0
7321 b NaN
7322 d 1.0
7323 e NaN
7324 dtype: float64
7325 >>> a.divide(b, fill_value=0)
7326 a 1.0
7327 b inf
7328 c inf
7329 d 0.0
7330 e NaN
7331 dtype: float64
7332 """
7333 return self._flex_method(
7334 other, operator.truediv, level=level, fill_value=fill_value, axis=axis
7335 )
7337 div = truediv
7338 divide = truediv
7340 @Appender(ops.make_flex_doc("rtruediv", "series"))
7341 def rtruediv(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7342 return self._flex_method(
7343 other, roperator.rtruediv, level=level, fill_value=fill_value, axis=axis
7344 )
7346 rdiv = rtruediv
7348 @Appender(ops.make_flex_doc("floordiv", "series"))
7349 def floordiv(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7350 return self._flex_method(
7351 other, operator.floordiv, level=level, fill_value=fill_value, axis=axis
7352 )
7354 @Appender(ops.make_flex_doc("rfloordiv", "series"))
7355 def rfloordiv(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7356 return self._flex_method(
7357 other, roperator.rfloordiv, level=level, fill_value=fill_value, axis=axis
7358 )
7360 def mod(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7361 """
7362 Return Modulo of series and other, element-wise (binary operator `mod`).
7364 Equivalent to ``series % other``, but with support to substitute a
7365 fill_value for missing data in either one of the inputs.
7367 Parameters
7368 ----------
7369 other : Series or scalar value
7370 Series with which to compute modulo.
7371 level : int or name
7372 Broadcast across a level, matching Index values on the
7373 passed MultiIndex level.
7374 fill_value : None or float value, default None (NaN)
7375 Fill existing missing (NaN) values, and any new element needed for
7376 successful Series alignment, with this value before computation.
7377 If data in both corresponding Series locations is missing
7378 the result of filling (at that location) will be missing.
7379 axis : {0 or 'index'}
7380 Unused. Parameter needed for compatibility with DataFrame.
7382 Returns
7383 -------
7384 Series
7385 The result of the operation.
7387 See Also
7388 --------
7389 Series.rmod : Reverse of the Modulo operator, see
7390 `Python documentation
7391 <https://docs.python.org/3/reference/datamodel.html#emulating-numeric-types>`_
7392 for more details.
7394 Examples
7395 --------
7396 >>> a = pd.Series([1, 1, 1, np.nan], index=["a", "b", "c", "d"])
7397 >>> a
7398 a 1.0
7399 b 1.0
7400 c 1.0
7401 d NaN
7402 dtype: float64
7403 >>> b = pd.Series([1, np.nan, 1, np.nan], index=["a", "b", "d", "e"])
7404 >>> b
7405 a 1.0
7406 b NaN
7407 d 1.0
7408 e NaN
7409 dtype: float64
7410 >>> a.mod(b, fill_value=0)
7411 a 0.0
7412 b NaN
7413 c NaN
7414 d 0.0
7415 e NaN
7416 dtype: float64
7417 """
7418 return self._flex_method(
7419 other, operator.mod, level=level, fill_value=fill_value, axis=axis
7420 )
7422 @Appender(ops.make_flex_doc("rmod", "series"))
7423 def rmod(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7424 return self._flex_method(
7425 other, roperator.rmod, level=level, fill_value=fill_value, axis=axis
7426 )
7428 @Appender(ops.make_flex_doc("pow", "series"))
7429 def pow(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7430 return self._flex_method(
7431 other, operator.pow, level=level, fill_value=fill_value, axis=axis
7432 )
7434 @Appender(ops.make_flex_doc("rpow", "series"))
7435 def rpow(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7436 return self._flex_method(
7437 other, roperator.rpow, level=level, fill_value=fill_value, axis=axis
7438 )
7440 @Appender(ops.make_flex_doc("divmod", "series"))
7441 def divmod(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7442 return self._flex_method(
7443 other, divmod, level=level, fill_value=fill_value, axis=axis
7444 )
7446 @Appender(ops.make_flex_doc("rdivmod", "series"))
7447 def rdivmod(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
7448 return self._flex_method(
7449 other, roperator.rdivmod, level=level, fill_value=fill_value, axis=axis
7450 )
7452 # ----------------------------------------------------------------------
7453 # Reductions
7455 def _reduce(
7456 self,
7457 op,
7458 # error: Variable "pandas.core.series.Series.str" is not valid as a type
7459 name: str, # type: ignore[valid-type]
7460 *,
7461 axis: Axis = 0,
7462 skipna: bool = True,
7463 numeric_only: bool = False,
7464 filter_type=None,
7465 **kwds,
7466 ):
7467 """
7468 Perform a reduction operation.
7470 If we have an ndarray as a value, then simply perform the operation,
7471 otherwise delegate to the object.
7472 """
7473 delegate = self._values
7475 if axis is not None:
7476 self._get_axis_number(axis)
7478 if isinstance(delegate, ExtensionArray):
7479 # dispatch to ExtensionArray interface
7480 result = delegate._reduce(name, skipna=skipna, **kwds)
7482 else:
7483 # dispatch to numpy arrays
7484 if numeric_only and self.dtype.kind not in "iufcb":
7485 # i.e. not is_numeric_dtype(self.dtype)
7486 kwd_name = "numeric_only"
7487 if name in ["any", "all"]:
7488 kwd_name = "bool_only"
7489 # GH#47500 - change to TypeError to match other methods
7490 raise TypeError(
7491 f"Series.{name} does not allow {kwd_name}={numeric_only} "
7492 "with non-numeric dtypes."
7493 )
7494 result = op(delegate, skipna=skipna, **kwds)
7496 result = maybe_unbox_numpy_scalar(result)
7497 return result
7499 # error: Signature of "any" incompatible with supertype "NDFrame"
7500 def any( # type: ignore[override]
7501 self,
7502 *,
7503 axis: Axis = 0,
7504 bool_only: bool = False,
7505 skipna: bool = True,
7506 **kwargs,
7507 ) -> bool:
7508 """
7509 Return whether any element is True, potentially over an axis.
7511 Returns False unless there is at least one element within a series or
7512 along a Dataframe axis that is True or equivalent (e.g. non-zero or
7513 non-empty).
7515 Parameters
7516 ----------
7517 axis : {0 or 'index', 1 or 'columns', None}, default 0
7518 Indicate which axis or axes should be reduced. For `Series` this parameter
7519 is unused and defaults to 0.
7521 * 0 / 'index' : reduce the index, return a Series whose index is the
7522 original column labels.
7523 * 1 / 'columns' : reduce the columns, return a Series whose index is the
7524 original index.
7525 * None : reduce all axes, return a scalar.
7527 bool_only : bool, default False
7528 Include only boolean columns. Not implemented for Series.
7529 skipna : bool, default True
7530 Exclude NA/null values. If the entire row/column is NA and skipna is
7531 True, then the result will be False, as for an empty row/column.
7532 If skipna is False, then NA are treated as True, because these are not
7533 equal to zero.
7534 **kwargs : any, default None
7535 Additional keywords have no effect but might be accepted for
7536 compatibility with NumPy.
7538 Returns
7539 -------
7540 Series or scalar
7541 If axis=None, then a scalar boolean is returned.
7542 Otherwise a Series is returned with index matching the index argument.
7544 See Also
7545 --------
7546 numpy.any : Numpy version of this method.
7547 Series.any : Return whether any element is True.
7548 Series.all : Return whether all elements are True.
7549 DataFrame.any : Return whether any element is True over requested axis.
7550 DataFrame.all : Return whether all elements are True over requested axis.
7552 Examples
7553 --------
7554 **Series**
7556 For Series input, the output is a scalar indicating whether any element
7557 is True.
7559 >>> pd.Series([False, False]).any()
7560 False
7561 >>> pd.Series([True, False]).any()
7562 True
7563 >>> pd.Series([], dtype="float64").any()
7564 False
7565 >>> pd.Series([np.nan]).any()
7566 False
7567 >>> pd.Series([np.nan]).any(skipna=False)
7568 True
7570 **DataFrame**
7572 Whether each column contains at least one True element (the default).
7574 >>> df = pd.DataFrame({"A": [1, 2], "B": [0, 2], "C": [0, 0]})
7575 >>> df
7576 A B C
7577 0 1 0 0
7578 1 2 2 0
7580 >>> df.any()
7581 A True
7582 B True
7583 C False
7584 dtype: bool
7586 Aggregating over the columns.
7588 >>> df = pd.DataFrame({"A": [True, False], "B": [1, 2]})
7589 >>> df
7590 A B
7591 0 True 1
7592 1 False 2
7594 >>> df.any(axis="columns")
7595 0 True
7596 1 True
7597 dtype: bool
7599 >>> df = pd.DataFrame({"A": [True, False], "B": [1, 0]})
7600 >>> df
7601 A B
7602 0 True 1
7603 1 False 0
7605 >>> df.any(axis="columns")
7606 0 True
7607 1 False
7608 dtype: bool
7610 Aggregating over the entire DataFrame with ``axis=None``.
7612 >>> df.any(axis=None)
7613 True
7615 `any` for an empty DataFrame is an empty Series.
7617 >>> pd.DataFrame([]).any()
7618 Series([], dtype: bool)
7619 """
7620 nv.validate_logical_func((), kwargs, fname="any")
7621 validate_bool_kwarg(skipna, "skipna", none_allowed=False)
7622 return self._reduce(
7623 nanops.nanany,
7624 name="any",
7625 axis=axis,
7626 numeric_only=bool_only,
7627 skipna=skipna,
7628 filter_type="bool",
7629 )
7631 @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="all")
7632 def all(
7633 self,
7634 axis: Axis = 0,
7635 bool_only: bool = False,
7636 skipna: bool = True,
7637 **kwargs,
7638 ) -> bool:
7639 """
7640 Return whether all elements are True, potentially over an axis.
7642 Returns True unless there at least one element within a series or
7643 along a Dataframe axis that is False or equivalent (e.g. zero or
7644 empty).
7646 Parameters
7647 ----------
7648 axis : {0 or 'index', 1 or 'columns', None}, default 0
7649 Indicate which axis or axes should be reduced. For `Series` this parameter
7650 is unused and defaults to 0.
7652 * 0 / 'index' : reduce the index, return a Series whose index is the
7653 original column labels.
7654 * 1 / 'columns' : reduce the columns, return a Series whose index is the
7655 original index.
7656 * None : reduce all axes, return a scalar.
7658 bool_only : bool, default False
7659 Include only boolean columns. Not implemented for Series.
7660 skipna : bool, default True
7661 Exclude NA/null values. If the entire row/column is NA and skipna is
7662 True, then the result will be True, as for an empty row/column.
7663 If skipna is False, then NA are treated as True, because these are not
7664 equal to zero.
7665 **kwargs : any, default None
7666 Additional keywords have no effect but might be accepted for
7667 compatibility with NumPy.
7669 Returns
7670 -------
7671 Series or scalar
7672 If axis=None, then a scalar boolean is returned.
7673 Otherwise a Series is returned with index matching the index argument.
7675 See Also
7676 --------
7677 Series.all : Return True if all elements are True.
7678 DataFrame.any : Return True if one (or more) elements are True.
7680 Examples
7681 --------
7682 **Series**
7684 >>> pd.Series([True, True]).all()
7685 True
7686 >>> pd.Series([True, False]).all()
7687 False
7688 >>> pd.Series([], dtype="float64").all()
7689 True
7690 >>> pd.Series([np.nan]).all()
7691 True
7692 >>> pd.Series([np.nan]).all(skipna=False)
7693 True
7695 **DataFrames**
7697 Create a DataFrame from a dictionary.
7699 >>> df = pd.DataFrame({"col1": [True, True], "col2": [True, False]})
7700 >>> df
7701 col1 col2
7702 0 True True
7703 1 True False
7705 Default behaviour checks if values in each column all return True.
7707 >>> df.all()
7708 col1 True
7709 col2 False
7710 dtype: bool
7712 Specify ``axis='columns'`` to check if values in each row all return True.
7714 >>> df.all(axis="columns")
7715 0 True
7716 1 False
7717 dtype: bool
7719 Or ``axis=None`` for whether every value is True.
7721 >>> df.all(axis=None)
7722 False
7723 """
7724 nv.validate_logical_func((), kwargs, fname="all")
7725 validate_bool_kwarg(skipna, "skipna", none_allowed=False)
7726 return self._reduce(
7727 nanops.nanall,
7728 name="all",
7729 axis=axis,
7730 numeric_only=bool_only,
7731 skipna=skipna,
7732 filter_type="bool",
7733 )
7735 @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="min")
7736 def min(
7737 self,
7738 axis: Axis | None = 0,
7739 skipna: bool = True,
7740 numeric_only: bool = False,
7741 **kwargs,
7742 ):
7743 """
7744 Return the minimum of the values over the requested axis.
7746 If you want the *index* of the minimum, use ``idxmin``.
7747 This is the equivalent of the ``numpy.ndarray`` method ``argmin``.
7749 Parameters
7750 ----------
7751 axis : {index (0)}
7752 Axis for the function to be applied on.
7753 For `Series` this parameter is unused and defaults to 0.
7755 For DataFrames, specifying ``axis=None`` will apply the aggregation
7756 across both axes.
7758 .. versionadded:: 2.0.0
7760 skipna : bool, default True
7761 Exclude NA/null values when computing the result.
7762 numeric_only : bool, default False
7763 Include only float, int, boolean columns.
7764 **kwargs
7765 Additional keyword arguments to be passed to the function.
7767 Returns
7768 -------
7769 scalar or Series (if level specified)
7770 The minimum of the values in the Series.
7772 See Also
7773 --------
7774 numpy.min : Equivalent numpy function for arrays.
7775 Series.min : Return the minimum.
7776 Series.max : Return the maximum.
7777 Series.idxmin : Return the index of the minimum.
7778 Series.idxmax : Return the index of the maximum.
7779 DataFrame.min : Return the minimum over the requested axis.
7780 DataFrame.max : Return the maximum over the requested axis.
7781 DataFrame.idxmin : Return the index of the minimum over the requested axis.
7782 DataFrame.idxmax : Return the index of the maximum over the requested axis.
7784 Examples
7785 --------
7786 >>> idx = pd.MultiIndex.from_arrays(
7787 ... [["warm", "warm", "cold", "cold"], ["dog", "falcon", "fish", "spider"]],
7788 ... names=["blooded", "animal"],
7789 ... )
7790 >>> s = pd.Series([4, 2, 0, 8], name="legs", index=idx)
7791 >>> s
7792 blooded animal
7793 warm dog 4
7794 falcon 2
7795 cold fish 0
7796 spider 8
7797 Name: legs, dtype: int64
7799 >>> s.min()
7800 0
7801 """
7802 return NDFrame.min(
7803 self, axis=axis, skipna=skipna, numeric_only=numeric_only, **kwargs
7804 )
7806 @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="max")
7807 def max(
7808 self,
7809 axis: Axis | None = 0,
7810 skipna: bool = True,
7811 numeric_only: bool = False,
7812 **kwargs,
7813 ):
7814 """
7815 Return the maximum of the values over the requested axis.
7817 If you want the *index* of the maximum, use ``idxmax``.
7818 This is the equivalent of the ``numpy.ndarray`` method ``argmax``.
7820 Parameters
7821 ----------
7822 axis : {index (0)}
7823 Axis for the function to be applied on.
7824 For `Series` this parameter is unused and defaults to 0.
7826 For DataFrames, specifying ``axis=None`` will apply the aggregation
7827 across both axes.
7829 .. versionadded:: 2.0.0
7831 skipna : bool, default True
7832 Exclude NA/null values when computing the result.
7833 numeric_only : bool, default False
7834 Include only float, int, boolean columns.
7835 **kwargs
7836 Additional keyword arguments to be passed to the function.
7838 Returns
7839 -------
7840 scalar or Series (if level specified)
7841 The maximum of the values in the Series.
7843 See Also
7844 --------
7845 numpy.max : Equivalent numpy function for arrays.
7846 Series.min : Return the minimum.
7847 Series.max : Return the maximum.
7848 Series.idxmin : Return the index of the minimum.
7849 Series.idxmax : Return the index of the maximum.
7850 DataFrame.min : Return the minimum over the requested axis.
7851 DataFrame.max : Return the maximum over the requested axis.
7852 DataFrame.idxmin : Return the index of the minimum over the requested axis.
7853 DataFrame.idxmax : Return the index of the maximum over the requested axis.
7855 Examples
7856 --------
7857 >>> idx = pd.MultiIndex.from_arrays(
7858 ... [["warm", "warm", "cold", "cold"], ["dog", "falcon", "fish", "spider"]],
7859 ... names=["blooded", "animal"],
7860 ... )
7861 >>> s = pd.Series([4, 2, 0, 8], name="legs", index=idx)
7862 >>> s
7863 blooded animal
7864 warm dog 4
7865 falcon 2
7866 cold fish 0
7867 spider 8
7868 Name: legs, dtype: int64
7870 >>> s.max()
7871 8
7872 """
7873 return NDFrame.max(
7874 self, axis=axis, skipna=skipna, numeric_only=numeric_only, **kwargs
7875 )
7877 @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="sum")
7878 def sum(
7879 self,
7880 axis: Axis | None = None,
7881 skipna: bool = True,
7882 numeric_only: bool = False,
7883 min_count: int = 0,
7884 **kwargs,
7885 ):
7886 """
7887 Return the sum of the values over the requested axis.
7889 This is equivalent to the method ``numpy.sum``.
7891 Parameters
7892 ----------
7893 axis : {index (0)}
7894 Axis for the function to be applied on.
7895 For `Series` this parameter is unused and defaults to 0.
7897 .. warning::
7899 The behavior of DataFrame.sum with ``axis=None`` is deprecated,
7900 in a future version this will reduce over both axes and return a scalar
7901 To retain the old behavior, pass axis=0 (or do not pass axis).
7903 .. versionadded:: 2.0.0
7905 skipna : bool, default True
7906 Exclude NA/null values when computing the result.
7907 numeric_only : bool, default False
7908 Include only float, int, boolean columns. Not implemented for Series.
7910 min_count : int, default 0
7911 The required number of valid values to perform the operation. If fewer than
7912 ``min_count`` non-NA values are present the result will be NA.
7913 **kwargs
7914 Additional keyword arguments to be passed to the function.
7916 Returns
7917 -------
7918 scalar or Series (if level specified)
7919 Sum of the values for the requested axis.
7921 See Also
7922 --------
7923 numpy.sum : Equivalent numpy function for computing sum.
7924 Series.mean : Mean of the values.
7925 Series.median : Median of the values.
7926 Series.std : Standard deviation of the values.
7927 Series.var : Variance of the values.
7928 Series.min : Minimum value.
7929 Series.max : Maximum value.
7931 Examples
7932 --------
7933 >>> idx = pd.MultiIndex.from_arrays(
7934 ... [["warm", "warm", "cold", "cold"], ["dog", "falcon", "fish", "spider"]],
7935 ... names=["blooded", "animal"],
7936 ... )
7937 >>> s = pd.Series([4, 2, 0, 8], name="legs", index=idx)
7938 >>> s
7939 blooded animal
7940 warm dog 4
7941 falcon 2
7942 cold fish 0
7943 spider 8
7944 Name: legs, dtype: int64
7946 >>> s.sum()
7947 14
7949 By default, the sum of an empty or all-NA Series is ``0``.
7951 >>> pd.Series([], dtype="float64").sum() # min_count=0 is the default
7952 0.0
7954 This can be controlled with the ``min_count`` parameter. For example, if
7955 you'd like the sum of an empty series to be NaN, pass ``min_count=1``.
7957 >>> pd.Series([], dtype="float64").sum(min_count=1)
7958 nan
7960 Thanks to the ``skipna`` parameter, ``min_count`` handles all-NA and
7961 empty series identically.
7963 >>> pd.Series([np.nan]).sum()
7964 0.0
7966 >>> pd.Series([np.nan]).sum(min_count=1)
7967 nan
7968 """
7969 return NDFrame.sum(
7970 self,
7971 axis=axis,
7972 skipna=skipna,
7973 numeric_only=numeric_only,
7974 min_count=min_count,
7975 **kwargs,
7976 )
7978 @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="prod")
7979 def prod(
7980 self,
7981 axis: Axis | None = None,
7982 skipna: bool = True,
7983 numeric_only: bool = False,
7984 min_count: int = 0,
7985 **kwargs,
7986 ):
7987 """
7988 Return the product of the values over the requested axis.
7990 By default, missing values are skipped. To include them in the calculation,
7991 set ``skipna`` parameter to False.
7993 Parameters
7994 ----------
7995 axis : {index (0)}
7996 Axis for the function to be applied on.
7997 For `Series` this parameter is unused and defaults to 0.
7999 .. warning::
8000 The behavior of DataFrame.prod with ``axis=None`` is deprecated,
8001 in a future version this will reduce over both axes and return a scalar
8002 To retain the old behavior, pass axis=0 (or do not pass axis).
8004 .. versionadded:: 2.0.0
8005 skipna : bool, default True
8006 Exclude NA/null values when computing the result.
8007 numeric_only : bool, default False
8008 Include only float, int, boolean columns. Not implemented for Series.
8009 min_count : int, default 0
8010 The required number of valid values to perform the operation. If fewer than
8011 ``min_count`` non-NA values are present the result will be NA.
8012 **kwargs
8013 Additional keyword arguments to be passed to the function.
8015 Returns
8016 -------
8017 scalar
8018 Value containing the calculation referenced in the description.
8020 See Also
8021 --------
8022 Series.sum : Return the sum.
8023 Series.min : Return the minimum.
8024 Series.max : Return the maximum.
8025 Series.idxmin : Return the index of the minimum.
8026 Series.idxmax : Return the index of the maximum.
8028 DataFrame.sum : Return the sum over the requested axis.
8029 DataFrame.min : Return the minimum over the requested axis.
8030 DataFrame.max : Return the maximum over the requested axis.
8031 DataFrame.idxmin : Return the index of the minimum over the requested axis.
8032 DataFrame.idxmax : Return the index of the maximum over the requested axis.
8034 Examples
8035 --------
8036 By default, the product of an empty or all-NA Series is ``1``
8038 >>> pd.Series([], dtype="float64").prod()
8039 1.0
8041 This can be controlled with the ``min_count`` parameter
8043 >>> pd.Series([], dtype="float64").prod(min_count=1)
8044 nan
8046 Thanks to the ``skipna`` parameter, ``min_count`` handles all-NA and
8047 empty series identically.
8049 >>> pd.Series([np.nan]).prod()
8050 1.0
8051 >>> pd.Series([np.nan]).prod(min_count=1)
8052 nan
8053 """
8054 return NDFrame.prod(
8055 self,
8056 axis=axis,
8057 skipna=skipna,
8058 numeric_only=numeric_only,
8059 min_count=min_count,
8060 **kwargs,
8061 )
8063 @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="mean")
8064 def mean(
8065 self,
8066 axis: Axis | None = 0,
8067 skipna: bool = True,
8068 numeric_only: bool = False,
8069 **kwargs,
8070 ) -> Any:
8071 """
8072 Return the mean of the values over the requested axis.
8074 Parameters
8075 ----------
8076 axis : {index (0)}
8077 Axis for the function to be applied on.
8078 For `Series` this parameter is unused and defaults to 0.
8080 For DataFrames, specifying ``axis=None`` will apply the aggregation
8081 across both axes.
8083 .. versionadded:: 2.0.0
8085 skipna : bool, default True
8086 Exclude NA/null values when computing the result.
8087 numeric_only : bool, default False
8088 Include only float, int, boolean columns.
8089 **kwargs
8090 Additional keyword arguments to be passed to the function.
8092 Returns
8093 -------
8094 scalar or Series (if level specified)
8095 Mean of the values for the requested axis.
8097 See Also
8098 --------
8099 numpy.median : Equivalent numpy function for computing median.
8100 Series.sum : Sum of the values.
8101 Series.median : Median of the values.
8102 Series.std : Standard deviation of the values.
8103 Series.var : Variance of the values.
8104 Series.min : Minimum value.
8105 Series.max : Maximum value.
8107 Examples
8108 --------
8109 >>> s = pd.Series([1, 2, 3])
8110 >>> s.mean()
8111 2.0
8112 """
8113 return NDFrame.mean(
8114 self, axis=axis, skipna=skipna, numeric_only=numeric_only, **kwargs
8115 )
8117 @deprecate_nonkeyword_arguments(
8118 Pandas4Warning, allowed_args=["self"], name="median"
8119 )
8120 def median(
8121 self,
8122 axis: Axis | None = 0,
8123 skipna: bool = True,
8124 numeric_only: bool = False,
8125 **kwargs,
8126 ) -> Any:
8127 """
8128 Return the median of the values over the requested axis.
8130 Parameters
8131 ----------
8132 axis : {index (0)}
8133 Axis for the function to be applied on.
8134 For `Series` this parameter is unused and defaults to 0.
8136 For DataFrames, specifying ``axis=None`` will apply the aggregation
8137 across both axes.
8139 .. versionadded:: 2.0.0
8141 skipna : bool, default True
8142 Exclude NA/null values when computing the result.
8143 numeric_only : bool, default False
8144 Include only float, int, boolean columns.
8145 **kwargs
8146 Additional keyword arguments to be passed to the function.
8148 Returns
8149 -------
8150 scalar or Series (if level specified)
8151 Median of the values for the requested axis.
8153 See Also
8154 --------
8155 numpy.median : Equivalent numpy function for computing median.
8156 Series.sum : Sum of the values.
8157 Series.median : Median of the values.
8158 Series.std : Standard deviation of the values.
8159 Series.var : Variance of the values.
8160 Series.min : Minimum value.
8161 Series.max : Maximum value.
8163 Examples
8164 --------
8165 >>> s = pd.Series([1, 2, 3])
8166 >>> s.median()
8167 2.0
8169 With a DataFrame
8171 >>> df = pd.DataFrame({"a": [1, 2], "b": [2, 3]}, index=["tiger", "zebra"])
8172 >>> df
8173 a b
8174 tiger 1 2
8175 zebra 2 3
8176 >>> df.median()
8177 a 1.5
8178 b 2.5
8179 dtype: float64
8181 Using axis=1
8183 >>> df.median(axis=1)
8184 tiger 1.5
8185 zebra 2.5
8186 dtype: float64
8188 In this case, `numeric_only` should be set to `True`
8189 to avoid getting an error.
8191 >>> df = pd.DataFrame({"a": [1, 2], "b": ["T", "Z"]}, index=["tiger", "zebra"])
8192 >>> df.median(numeric_only=True)
8193 a 1.5
8194 dtype: float64
8195 """
8196 return NDFrame.median(
8197 self, axis=axis, skipna=skipna, numeric_only=numeric_only, **kwargs
8198 )
8200 @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="sem")
8201 def sem(
8202 self,
8203 axis: Axis | None = None,
8204 skipna: bool = True,
8205 ddof: int = 1,
8206 numeric_only: bool = False,
8207 **kwargs,
8208 ):
8209 """
8210 Return unbiased standard error of the mean over requested axis.
8212 Normalized by N-1 by default. This can be changed using the ddof argument
8214 Parameters
8215 ----------
8216 axis : {index (0)}
8217 This parameter is unused and defaults to 0.
8218 skipna : bool, default True
8219 Exclude NA/null values. If an entire row/column is NA, the result
8220 will be NA.
8221 ddof : int, default 1
8222 Delta Degrees of Freedom. The divisor used in calculations is N - ddof,
8223 where N represents the number of elements.
8224 numeric_only : bool, default False
8225 Include only float, int, boolean columns. Not implemented for Series.
8226 **kwargs :
8227 Additional keywords have no effect but might be accepted
8228 for compatibility with NumPy.
8230 Returns
8231 -------
8232 scalar or Series (if level specified)
8233 Unbiased standard error of the mean over requested axis.
8235 See Also
8236 --------
8237 scipy.stats.sem : Compute standard error of the mean.
8238 Series.std : Return sample standard deviation over requested axis.
8239 Series.var : Return unbiased variance over requested axis.
8240 Series.mean : Return the mean of the values over the requested axis.
8241 Series.median : Return the median of the values over the requested axis.
8242 Series.mode : Return the mode(s) of the Series.
8244 Examples
8245 --------
8246 >>> s = pd.Series([1, 2, 3])
8247 >>> round(s.sem(), 6)
8248 0.57735
8249 """
8250 return NDFrame.sem(
8251 self,
8252 axis=axis,
8253 skipna=skipna,
8254 ddof=ddof,
8255 numeric_only=numeric_only,
8256 **kwargs,
8257 )
8259 @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="var")
8260 def var(
8261 self,
8262 axis: Axis | None = None,
8263 skipna: bool = True,
8264 ddof: int = 1,
8265 numeric_only: bool = False,
8266 **kwargs,
8267 ):
8268 """
8269 Return unbiased variance over requested axis.
8271 Normalized by N-1 by default. This can be changed using the ddof argument.
8273 Parameters
8274 ----------
8275 axis : {index (0)}
8276 For `Series` this parameter is unused and defaults to 0.
8278 .. warning::
8280 The behavior of DataFrame.var with ``axis=None`` is deprecated,
8281 in a future version this will reduce over both axes and return a scalar
8282 To retain the old behavior, pass axis=0 (or do not pass axis).
8284 skipna : bool, default True
8285 Exclude NA/null values. If an entire row/column is NA, the result
8286 will be NA.
8287 ddof : int, default 1
8288 Delta Degrees of Freedom. The divisor used in calculations is N - ddof,
8289 where N represents the number of elements.
8290 numeric_only : bool, default False
8291 Include only float, int, boolean columns. Not implemented for Series.
8292 **kwargs :
8293 Additional keywords passed.
8295 Returns
8296 -------
8297 scalar or Series (if level specified)
8298 Unbiased variance over requested axis.
8300 See Also
8301 --------
8302 numpy.var : Equivalent function in NumPy.
8303 Series.std : Returns the standard deviation of the Series.
8304 DataFrame.var : Returns the variance of the DataFrame.
8305 DataFrame.std : Return standard deviation of the values over
8306 the requested axis.
8308 Examples
8309 --------
8310 >>> df = pd.DataFrame(
8311 ... {
8312 ... "person_id": [0, 1, 2, 3],
8313 ... "age": [21, 25, 62, 43],
8314 ... "height": [1.61, 1.87, 1.49, 2.01],
8315 ... }
8316 ... ).set_index("person_id")
8317 >>> df
8318 age height
8319 person_id
8320 0 21 1.61
8321 1 25 1.87
8322 2 62 1.49
8323 3 43 2.01
8325 >>> df.var()
8326 age 352.916667
8327 height 0.056367
8328 dtype: float64
8330 Alternatively, ``ddof=0`` can be set to normalize by N instead of N-1:
8332 >>> df.var(ddof=0)
8333 age 264.687500
8334 height 0.042275
8335 dtype: float64
8336 """
8337 return NDFrame.var(
8338 self,
8339 axis=axis,
8340 skipna=skipna,
8341 ddof=ddof,
8342 numeric_only=numeric_only,
8343 **kwargs,
8344 )
8346 @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="std")
8347 def std(
8348 self,
8349 axis: Axis | None = None,
8350 skipna: bool = True,
8351 ddof: int = 1,
8352 numeric_only: bool = False,
8353 **kwargs,
8354 ):
8355 """
8356 Return sample standard deviation.
8358 Normalized by N-1 by default. This can be changed using the ddof argument.
8360 Parameters
8361 ----------
8362 axis : {index (0)}
8363 This parameter is unused and defaults to 0.
8364 skipna : bool, default True
8365 Exclude NA/null values. If Series is NA, the result
8366 will be NA.
8367 ddof : int, default 1
8368 Delta Degrees of Freedom. The divisor used in calculations is N - ddof,
8369 where N represents the number of elements.
8370 numeric_only : bool, default False
8371 Not implemented for Series.
8372 **kwargs :
8373 Additional keywords have no effect but might be accepted
8374 for compatibility with NumPy.
8376 Returns
8377 -------
8378 scalar
8379 Standard deviation over all values in the Series.
8381 See Also
8382 --------
8383 numpy.std : Compute the standard deviation along the specified axis.
8384 Series.var : Return unbiased variance over requested axis.
8385 Series.sem : Return unbiased standard error of the mean over requested axis.
8386 Series.mean : Return the mean of the values over the requested axis.
8387 Series.median : Return the median of the values over the requested axis.
8388 Series.mode : Return the mode(s) of the Series.
8390 Examples
8391 --------
8392 >>> s = pd.Series([1, 2, 3])
8393 >>> s.std()
8394 1.0
8396 Alternatively, ``ddof=0`` can be set to normalize by $N$ instead of $N-1$:
8398 >>> s.std(ddof=0)
8399 0.816496580927726
8400 """
8401 return NDFrame.std(
8402 self,
8403 axis=axis,
8404 skipna=skipna,
8405 ddof=ddof,
8406 numeric_only=numeric_only,
8407 **kwargs,
8408 )
8410 @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="skew")
8411 def skew(
8412 self,
8413 axis: Axis | None = 0,
8414 skipna: bool = True,
8415 numeric_only: bool = False,
8416 **kwargs,
8417 ):
8418 """
8419 Return unbiased skew over requested axis.
8421 Normalized by N-1.
8423 Parameters
8424 ----------
8425 axis : {index (0)}
8426 This parameter is unused and defaults to 0.
8427 skipna : bool, default True
8428 Exclude NA/null values when computing the result.
8429 numeric_only : bool, default False
8430 Unused.
8431 **kwargs
8432 Additional keyword arguments to be passed to the function.
8434 Returns
8435 -------
8436 scalar
8437 Unbiased skew of the Series.
8439 See Also
8440 --------
8442 Series.var : Return unbiased variance over requested axis.
8443 Series.std : Return unbiased standard deviation over requested axis.
8445 Examples
8446 --------
8447 >>> s = pd.Series([1, 2, 3])
8448 >>> s.skew()
8449 0.0
8450 """
8451 return NDFrame.skew(
8452 self, axis=axis, skipna=skipna, numeric_only=numeric_only, **kwargs
8453 )
8455 @deprecate_nonkeyword_arguments(Pandas4Warning, allowed_args=["self"], name="kurt")
8456 def kurt(
8457 self,
8458 axis: Axis | None = 0,
8459 skipna: bool = True,
8460 numeric_only: bool = False,
8461 **kwargs,
8462 ):
8463 """
8464 Return unbiased kurtosis over requested axis.
8466 Kurtosis obtained using Fisher's definition of
8467 kurtosis (kurtosis of normal == 0.0). Normalized by N-1.
8469 Parameters
8470 ----------
8471 axis : {index (0)}
8472 Axis for the function to be applied on.
8473 For `Series` this parameter is unused and defaults to 0.
8475 For DataFrames, specifying ``axis=None`` will apply the aggregation
8476 across both axes.
8478 .. versionadded:: 2.0.0
8480 skipna : bool, default True
8481 Exclude NA/null values when computing the result.
8482 numeric_only : bool, default False
8483 Include only float, int, boolean columns.
8485 **kwargs
8486 Additional keyword arguments to be passed to the function.
8488 Returns
8489 -------
8490 scalar
8491 Unbiased kurtosis.
8493 See Also
8494 --------
8495 Series.skew : Return unbiased skew over requested axis.
8496 Series.var : Return unbiased variance over requested axis.
8497 Series.std : Return unbiased standard deviation over requested axis.
8499 Examples
8500 --------
8501 >>> s = pd.Series([1, 2, 2, 3], index=["cat", "dog", "dog", "mouse"])
8502 >>> s
8503 cat 1
8504 dog 2
8505 dog 2
8506 mouse 3
8507 dtype: int64
8508 >>> s.kurt()
8509 1.5
8510 """
8511 return NDFrame.kurt(
8512 self, axis=axis, skipna=skipna, numeric_only=numeric_only, **kwargs
8513 )
8515 kurtosis = kurt
8516 product = prod
8518 def cummin(self, axis: Axis = 0, skipna: bool = True, *args, **kwargs) -> Self:
8519 """
8520 Return cumulative minimum over a Series.
8522 Returns a Series of the same size containing the cumulative
8523 minimum.
8525 Parameters
8526 ----------
8527 axis : {0 or 'index'}, default 0
8528 This parameter is unused and defaults to 0.
8529 skipna : bool, default True
8530 If the entire series is NA, the result will be NA.
8531 *args, **kwargs
8532 Additional keywords have no effect but might be accepted for
8533 compatibility with NumPy.
8535 Returns
8536 -------
8537 Series
8538 Return cumulative minimum of the Series.
8540 See Also
8541 --------
8542 core.window.expanding.Expanding.min : Similar functionality
8543 but ignores ``NaN`` values.
8544 Series.min : Return the minimum value of the Series.
8545 Series.cummax : Return cumulative maximum.
8546 Series.cumsum : Return cumulative sum.
8547 Series.cumprod : Return cumulative product.
8549 Examples
8550 --------
8551 >>> s = pd.Series([2, np.nan, 5, -1, 0])
8552 >>> s
8553 0 2.0
8554 1 NaN
8555 2 5.0
8556 3 -1.0
8557 4 0.0
8558 dtype: float64
8560 By default, NA values are ignored.
8562 >>> s.cummin()
8563 0 2.0
8564 1 NaN
8565 2 2.0
8566 3 -1.0
8567 4 -1.0
8568 dtype: float64
8570 To include NA values in the operation, use ``skipna=False``
8572 >>> s.cummin(skipna=False)
8573 0 2.0
8574 1 NaN
8575 2 NaN
8576 3 NaN
8577 4 NaN
8578 dtype: float64
8579 """
8580 return NDFrame.cummin(self, axis, skipna, *args, **kwargs)
8582 def cummax(self, axis: Axis = 0, skipna: bool = True, *args, **kwargs) -> Self:
8583 """
8584 Return cumulative maximum over a Series.
8586 Returns a Series of the same size containing the cumulative
8587 maximum.
8589 Parameters
8590 ----------
8591 axis : {0 or 'index'}, default 0
8592 This parameter is unused and defaults to 0.
8593 skipna : bool, default True
8594 Exclude NA/null values. If the series is NA, the result is NA.
8595 *args, **kwargs
8596 Additional keywords have no effect but might be accepted for
8597 compatibility with NumPy.
8599 Returns
8600 -------
8601 Series
8602 Return cumulative maximum of Series.
8604 See Also
8605 --------
8606 core.window.expanding.Expanding.max : Similar functionality
8607 but ignores ``NaN`` values.
8608 Series.max : Return the maximum over a Series.
8609 Series.cummin : Return cumulative minimum.
8610 Series.cumsum : Return cumulative sum.
8611 Series.cumprod : Return cumulative product.
8613 Examples
8614 --------
8615 >>> s = pd.Series([2, np.nan, 5, -1, 0])
8616 >>> s
8617 0 2.0
8618 1 NaN
8619 2 5.0
8620 3 -1.0
8621 4 0.0
8622 dtype: float64
8624 By default, NA values are ignored.
8626 >>> s.cummax()
8627 0 2.0
8628 1 NaN
8629 2 5.0
8630 3 5.0
8631 4 5.0
8632 dtype: float64
8634 To include NA values in the operation, use ``skipna=False``
8636 >>> s.cummax(skipna=False)
8637 0 2.0
8638 1 NaN
8639 2 NaN
8640 3 NaN
8641 4 NaN
8642 dtype: float64
8643 """
8644 return NDFrame.cummax(self, axis, skipna, *args, **kwargs)
8646 def cumsum(self, axis: Axis = 0, skipna: bool = True, *args, **kwargs) -> Self:
8647 """
8648 Return cumulative sum over a Series.
8650 Returns a Series of the same size containing the cumulative sum.
8652 Parameters
8653 ----------
8654 axis : {0 or 'index'}, default 0
8655 This parameter is unused and defaults to 0.
8656 skipna : bool, default True
8657 Exclude NA/null values. If entire series is NA, the result will be NA.
8658 *args, **kwargs
8659 Additional keywords have no effect but might be accepted for
8660 compatibility with NumPy.
8662 Returns
8663 -------
8664 Series
8665 Return cumulative sum of Series.
8667 See Also
8668 --------
8669 core.window.expanding.Expanding.sum : Similar functionality
8670 but ignores ``NaN`` values.
8671 Series.sum : Return the sum over Series.
8672 Series.cummax : Return cumulative maximum.
8673 Series.cummin : Return cumulative minimum.
8674 Series.cumprod : Return cumulative product.
8676 Examples
8677 --------
8678 >>> s = pd.Series([2, np.nan, 5, -1, 0])
8679 >>> s
8680 0 2.0
8681 1 NaN
8682 2 5.0
8683 3 -1.0
8684 4 0.0
8685 dtype: float64
8687 By default, NA values are ignored.
8689 >>> s.cumsum()
8690 0 2.0
8691 1 NaN
8692 2 7.0
8693 3 6.0
8694 4 6.0
8695 dtype: float64
8697 To include NA values in the operation, use ``skipna=False``
8699 >>> s.cumsum(skipna=False)
8700 0 2.0
8701 1 NaN
8702 2 NaN
8703 3 NaN
8704 4 NaN
8705 dtype: float64
8706 """
8707 return NDFrame.cumsum(self, axis, skipna, *args, **kwargs)
8709 def cumprod(self, axis: Axis = 0, skipna: bool = True, *args, **kwargs) -> Self:
8710 """
8711 Return cumulative product over a Series.
8713 Returns a Series of the same size containing the cumulative
8714 product.
8716 Parameters
8717 ----------
8718 axis : {0 or 'index'}, default 0
8719 This parameter is unused and defaults to 0.
8720 skipna : bool, default True
8721 Exclude NA/null values. If entire Series is NA, the result will be NA.
8722 *args, **kwargs
8723 Additional keywords have no effect but might be accepted for
8724 compatibility with NumPy.
8726 Returns
8727 -------
8728 Series
8729 Return cumulative product of Series.
8731 See Also
8732 --------
8733 core.window.expanding.Expanding.prod : Similar functionality
8734 but ignores ``NaN`` values.
8735 Series.prod : Return the product over Series.
8736 Series.cummax : Return cumulative maximum.
8737 Series.cummin : Return cumulative minimum.
8738 Series.cumsum : Return cumulative sum.
8740 Examples
8741 --------
8742 >>> s = pd.Series([2, np.nan, 5, -1, 0])
8743 >>> s
8744 0 2.0
8745 1 NaN
8746 2 5.0
8747 3 -1.0
8748 4 0.0
8749 dtype: float64
8751 By default, NA values are ignored.
8753 >>> s.cumprod()
8754 0 2.0
8755 1 NaN
8756 2 10.0
8757 3 -10.0
8758 4 -0.0
8759 dtype: float64
8761 To include NA values in the operation, use ``skipna=False``
8763 >>> s.cumprod(skipna=False)
8764 0 2.0
8765 1 NaN
8766 2 NaN
8767 3 NaN
8768 4 NaN
8769 dtype: float64
8770 """
8771 return NDFrame.cumprod(self, axis, skipna, *args, **kwargs)