polars.Series#

A Series represents a single column in a polars DataFrame.

Parameters:

namestr, default None: Name of the series. Will be used as a column name when used in a DataFrame. When not specified, name is set to an empty string.
valuesArrayLike, default None: One-dimensional data in various forms. Supported are: Sequence, Series, pyarrow Array, and numpy ndarray.
dtypeDataType, default None: Polars dtype of the Series data. If not specified, the dtype is inferred.
strict: Throw error on numeric overflow.
nan_to_null: In case a numpy array is used to create this Series, indicate how to deal with np.nan values.
dtype_if_empty=dtype_if_emptyDataType, default None: If no dtype is specified and values contains None or an empty list, set the Polars dtype of the Series data. If not specified, Float32 is used.

Examples

Constructing a Series by specifying name and values positionally:

>>> s = pl.Series("a", [1, 2, 3])
>>> s
shape: (3,)
Series: 'a' [i64]
[
        1
        2
        3
]

Notice that the dtype is automatically inferred as a polars Int64:

>>> s.dtype
<class 'polars.datatypes.Int64'>

Constructing a Series with a specific dtype:

>>> s2 = pl.Series("a", [1, 2, 3], dtype=pl.Float32)
>>> s2
shape: (3,)
Series: 'a' [f32]
[
    1.0
    2.0
    3.0
]

It is possible to construct a Series with values as the first positional argument. This syntax considered an anti-pattern, but it can be useful in certain scenarios. You must specify any other arguments through keywords.

>>> s3 = pl.Series([1, 2, 3])
>>> s3
shape: (3,)
Series: '' [i64]
[
        1
        2
        3
]

Attributes:

arr: Create an object namespace of all list related methods.
cat: Create an object namespace of all categorical related methods.
dt: Create an object namespace of all datetime related methods.
dtype: Get the data type of this Series.
flags: Get flags that are set on the Series.
inner_dtype: Get the inner dtype in of a List typed Series.
name: Get the name of this Series.
shape: Shape of this Series.
str: Create an object namespace of all string related methods.
struct: Create an object namespace of all struct related methods.
time_unit: Get the time unit of underlying Datetime Series as {“ns”, “us”, “ms”}.

Methods

`abs`()	Compute absolute values.
`alias`(name)	Return a copy of the Series with a new alias/name.
`all`()	Check if all boolean values in the column are True.
`any`()	Check if any boolean value in the column is True.
`append`(other[, append_chunks])	Append a Series to this one.
`apply`(func[, return_dtype, skip_nulls])	Apply a custom/user-defined function (UDF) over elements in this Series and return a new Series.
`arccos`()	Compute the element-wise value for the inverse cosine.
`arccosh`()	Compute the element-wise value for the inverse hyperbolic cosine.
`arcsin`()	Compute the element-wise value for the inverse sine.
`arcsinh`()	Compute the element-wise value for the inverse hyperbolic sine.
`arctan`()	Compute the element-wise value for the inverse tangent.
`arctanh`()	Compute the element-wise value for the inverse hyperbolic tangent.
`arg_max`()	Get the index of the maximal value.
`arg_min`()	Get the index of the minimal value.
`arg_sort`([reverse, nulls_last])	Get the index values that would sort this Series.
`arg_true`()	Get index values where Boolean Series evaluate True.
`arg_unique`()	Get unique index as Series.
`argsort`([reverse, nulls_last])	Get the index values that would sort this Series.
`cast`(dtype[, strict])	Cast between data types.
`ceil`()	Rounds up to the nearest integer value.
`chunk_lengths`()	Get the length of each individual chunk.
`cleared`()	Create an empty copy of the current Series.
`clip`(min_val, max_val)	Clip (limit) the values in an array to a min and max boundary.
`clip_max`(max_val)	Clip (limit) the values in an array to a max boundary.
`clip_min`(min_val)	Clip (limit) the values in an array to a min boundary.
`clone`()	Very cheap deepcopy/clone.
`cos`()	Compute the element-wise value for the cosine.
`cosh`()	Compute the element-wise value for the hyperbolic cosine.
`cummax`([reverse])	Get an array with the cumulative max computed at every element.
`cummin`([reverse])	Get an array with the cumulative min computed at every element.
`cumprod`([reverse])	Get an array with the cumulative product computed at every element.
`cumsum`([reverse])	Get an array with the cumulative sum computed at every element.
`cumulative_eval`(expr[, min_periods, parallel])	Run an expression over a sliding window that increases 1 slot every iteration.
`describe`()	Quick summary statistics of a series.
`diff`([n, null_behavior])	Calculate the n-th discrete difference.
`dot`(other)	Compute the dot/inner product between two Series.
`drop_nans`()	Drop NaN values.
`drop_nulls`()	Create a new Series that copies data from this Series without null values.
`entropy`([base, normalize])	Computes the entropy.
`estimated_size`([unit])	Return an estimation of the total (heap) allocated size of the Series.
`ewm_mean`([com, span, half_life, alpha, ...])	Exponentially-weighted moving average.
`ewm_std`([com, span, half_life, alpha, ...])	Exponentially-weighted moving standard deviation.
`ewm_var`([com, span, half_life, alpha, ...])	Exponentially-weighted moving variance.
`exp`()	Compute the exponential, element-wise.
`explode`()	Explode a list or utf8 Series.
`extend_constant`(value, n)	Extend the Series with given number of values.
`fill_nan`(fill_value)	Fill floating point NaN value with a fill value.
`fill_null`([value, strategy, limit])	Fill null values using the specified value or strategy.
`filter`(predicate)	Filter elements by a boolean mask.
`floor`()	Rounds down to the nearest integer value.
`has_validity`()	Return True if the Series has a validity bitmask.
`hash`([seed, seed_1, seed_2, seed_3])	Hash the Series.
`head`([n])	Get the first n rows.
`interpolate`()	Interpolate intermediate values.
`is_boolean`()	Check if this Series is a Boolean.
`is_datelike`()	Check if this Series datatype is datelike.
`is_duplicated`()	Get mask of all duplicated values.
`is_empty`()	Check if the Series is empty.
`is_finite`()	Returns a boolean Series indicating which values are finite.
`is_first`()	Get a mask of the first unique value.
`is_float`()	Check if this Series has floating point numbers.
`is_in`(other)	Check if elements of this Series are in the other Series.
`is_infinite`()	Returns a boolean Series indicating which values are infinite.
`is_nan`()	Returns a boolean Series indicating which values are not NaN.
`is_not_nan`()	Returns a boolean Series indicating which values are not NaN.
`is_not_null`()	Returns a boolean Series indicating which values are not null.
`is_null`()	Returns a boolean Series indicating which values are null.
`is_numeric`()	Check if this Series datatype is numeric.
`is_unique`()	Get mask of all unique values.
`is_utf8`()	Check if this Series datatype is a Utf8.
`kurtosis`([fisher, bias])	Compute the kurtosis (Fisher or Pearson) of a dataset.
`len`()	Length of this Series.
`limit`([n])	Get the first n rows.
`log`([base])	Compute the logarithm to a given base.
`log10`()	Compute the base 10 logarithm of the input array, element-wise.
`max`()	Get the maximum value in this Series.
`mean`()	Reduce this Series to the mean value.
`median`()	Get the median of this Series.
`min`()	Get the minimal value in this Series.
`mode`()	Compute the most occurring value(s).
`n_chunks`()	Get the number of chunks that this Series contains.
`n_unique`()	Count the number of unique values in this Series.
`nan_max`()	Get maximum value, but propagate/poison encountered NaN values.
`nan_min`()	Get minimum value, but propagate/poison encountered NaN values.
`null_count`()	Count the null values in this Series.
`pct_change`([n])	Computes percentage change between values.
`peak_max`()	Get a boolean mask of the local maximum peaks.
`peak_min`()	Get a boolean mask of the local minimum peaks.
`product`()	Reduce this Series to the product value.
`quantile`(quantile[, interpolation])	Get the quantile value of this Series.
`rank`([method, reverse])	Assign ranks to data, dealing with ties appropriately.
`rechunk`([in_place])	Create a single chunk of memory for this Series.
`reinterpret`([signed])	Reinterpret the underlying bits as a signed/unsigned integer.
`rename`(name[, in_place])	Rename this Series.
`reshape`(dims)	Reshape this Series to a flat Series or a Series of Lists.
`reverse`()	Return Series in reverse order.
`rolling_apply`(function, window_size[, ...])	Apply a custom rolling window function.
`rolling_max`(window_size[, weights, ...])	Apply a rolling max (moving max) over the values in this array.
`rolling_mean`(window_size[, weights, ...])	Apply a rolling mean (moving mean) over the values in this array.
`rolling_median`(window_size[, weights, ...])	Compute a rolling median.
`rolling_min`(window_size[, weights, ...])	Apply a rolling min (moving min) over the values in this array.
`rolling_quantile`(quantile[, interpolation, ...])	Compute a rolling quantile.
`rolling_skew`(window_size[, bias])	Compute a rolling skew.
`rolling_std`(window_size[, weights, ...])	Compute a rolling std dev.
`rolling_sum`(window_size[, weights, ...])	Apply a rolling sum (moving sum) over the values in this array.
`rolling_var`(window_size[, weights, ...])	Compute a rolling variance.
`round`(decimals)	Round underlying floating point data by decimals digits.
`sample`([n, frac, with_replacement, shuffle, ...])	Sample from this Series.
`search_sorted`(element)	Find indices where elements should be inserted to maintain order.
`series_equal`(other[, null_equal, strict])	Check if series is equal with another Series.
`set`(filter, value)	Set masked values.
`set_at_idx`(idx, value)	Set values at the index locations.
`set_sorted`([reverse])	Flags the Series as 'sorted'.
`shift`([periods])	Shift the values by a given period.
`shift_and_fill`(periods, fill_value)	Shift the values by a given period and fill the resulting null values.
`shrink_to_fit`([in_place])	Shrink Series memory usage.
`shuffle`([seed])	Shuffle the contents of this Series.
`sign`()	Compute the element-wise indication of the sign.
`sin`()	Compute the element-wise value for the sine.
`sinh`()	Compute the element-wise value for the hyperbolic sine.
`skew`([bias])	Compute the sample skewness of a data set.
`slice`(offset[, length])	Get a slice of this Series.
`sort`([reverse, in_place])	Sort this Series.
`sqrt`()	Compute the square root of the elements.
`std`([ddof])	Get the standard deviation of this Series.
`sum`()	Reduce this Series to the sum value.
`tail`([n])	Get the last n rows.
`take`(indices)	Take values by index.
`take_every`(n)	Take every nth value in the Series and return as new Series.
`tan`()	Compute the element-wise value for the tangent.
`tanh`()	Compute the element-wise value for the hyperbolic tangent.
`to_arrow`()	Get the underlying Arrow Array.
`to_dummies`()	Get dummy variables.
`to_frame`([name])	Cast this Series to a DataFrame.
`to_list`([use_pyarrow])	Convert this Series to a Python List.
`to_numpy`(*args[, zero_copy_only, writable])	Convert this Series to numpy.
`to_pandas`()	Convert this Series to a pandas Series.
`to_physical`()	Cast to physical representation of the logical dtype.
`top_k`([k, reverse])	Return the k largest elements.
`unique`([maintain_order])	Get unique elements in series.
`unique_counts`()	Return a count of the unique values in the order of appearance.
`value_counts`([sort])	Count the unique values in a Series.
`var`([ddof])	Get variance of this Series.
`view`([ignore_nulls])	Get a view into this Series data with a numpy array.
`zip_with`(mask, other)	Take values from self or other based on the given mask.

__init__(name: str | ArrayLike | None = None, values: ArrayLike | Sequence[Any] | None = None, dtype: type[DataType] | DataType | None = None, strict: bool = True, nan_to_null: bool = False, dtype_if_empty: type[DataType] | DataType | None = None)[source]#

Methods

`__init__`([name, values, dtype, strict, ...])
`abs`()	Compute absolute values.
`alias`(name)	Return a copy of the Series with a new alias/name.
`all`()	Check if all boolean values in the column are True.
`any`()	Check if any boolean value in the column is True.
`append`(other[, append_chunks])	Append a Series to this one.
`apply`(func[, return_dtype, skip_nulls])	Apply a custom/user-defined function (UDF) over elements in this Series and return a new Series.
`arccos`()	Compute the element-wise value for the inverse cosine.
`arccosh`()	Compute the element-wise value for the inverse hyperbolic cosine.
`arcsin`()	Compute the element-wise value for the inverse sine.
`arcsinh`()	Compute the element-wise value for the inverse hyperbolic sine.
`arctan`()	Compute the element-wise value for the inverse tangent.
`arctanh`()	Compute the element-wise value for the inverse hyperbolic tangent.
`arg_max`()	Get the index of the maximal value.
`arg_min`()	Get the index of the minimal value.
`arg_sort`([reverse, nulls_last])	Get the index values that would sort this Series.
`arg_true`()	Get index values where Boolean Series evaluate True.
`arg_unique`()	Get unique index as Series.
`argsort`([reverse, nulls_last])	Get the index values that would sort this Series.
`cast`(dtype[, strict])	Cast between data types.
`ceil`()	Rounds up to the nearest integer value.
`chunk_lengths`()	Get the length of each individual chunk.
`cleared`()	Create an empty copy of the current Series.
`clip`(min_val, max_val)	Clip (limit) the values in an array to a min and max boundary.
`clip_max`(max_val)	Clip (limit) the values in an array to a max boundary.
`clip_min`(min_val)	Clip (limit) the values in an array to a min boundary.
`clone`()	Very cheap deepcopy/clone.
`cos`()	Compute the element-wise value for the cosine.
`cosh`()	Compute the element-wise value for the hyperbolic cosine.
`cummax`([reverse])	Get an array with the cumulative max computed at every element.
`cummin`([reverse])	Get an array with the cumulative min computed at every element.
`cumprod`([reverse])	Get an array with the cumulative product computed at every element.
`cumsum`([reverse])	Get an array with the cumulative sum computed at every element.
`cumulative_eval`(expr[, min_periods, parallel])	Run an expression over a sliding window that increases 1 slot every iteration.
`describe`()	Quick summary statistics of a series.
`diff`([n, null_behavior])	Calculate the n-th discrete difference.
`dot`(other)	Compute the dot/inner product between two Series.
`drop_nans`()	Drop NaN values.
`drop_nulls`()	Create a new Series that copies data from this Series without null values.
`entropy`([base, normalize])	Computes the entropy.
`estimated_size`([unit])	Return an estimation of the total (heap) allocated size of the Series.
`ewm_mean`([com, span, half_life, alpha, ...])	Exponentially-weighted moving average.
`ewm_std`([com, span, half_life, alpha, ...])	Exponentially-weighted moving standard deviation.
`ewm_var`([com, span, half_life, alpha, ...])	Exponentially-weighted moving variance.
`exp`()	Compute the exponential, element-wise.
`explode`()	Explode a list or utf8 Series.
`extend_constant`(value, n)	Extend the Series with given number of values.
`fill_nan`(fill_value)	Fill floating point NaN value with a fill value.
`fill_null`([value, strategy, limit])	Fill null values using the specified value or strategy.
`filter`(predicate)	Filter elements by a boolean mask.
`floor`()	Rounds down to the nearest integer value.
`has_validity`()	Return True if the Series has a validity bitmask.
`hash`([seed, seed_1, seed_2, seed_3])	Hash the Series.
`head`([n])	Get the first n rows.
`interpolate`()	Interpolate intermediate values.
`is_boolean`()	Check if this Series is a Boolean.
`is_datelike`()	Check if this Series datatype is datelike.
`is_duplicated`()	Get mask of all duplicated values.
`is_empty`()	Check if the Series is empty.
`is_finite`()	Returns a boolean Series indicating which values are finite.
`is_first`()	Get a mask of the first unique value.
`is_float`()	Check if this Series has floating point numbers.
`is_in`(other)	Check if elements of this Series are in the other Series.
`is_infinite`()	Returns a boolean Series indicating which values are infinite.
`is_nan`()	Returns a boolean Series indicating which values are not NaN.
`is_not_nan`()	Returns a boolean Series indicating which values are not NaN.
`is_not_null`()	Returns a boolean Series indicating which values are not null.
`is_null`()	Returns a boolean Series indicating which values are null.
`is_numeric`()	Check if this Series datatype is numeric.
`is_unique`()	Get mask of all unique values.
`is_utf8`()	Check if this Series datatype is a Utf8.
`kurtosis`([fisher, bias])	Compute the kurtosis (Fisher or Pearson) of a dataset.
`len`()	Length of this Series.
`limit`([n])	Get the first n rows.
`log`([base])	Compute the logarithm to a given base.
`log10`()	Compute the base 10 logarithm of the input array, element-wise.
`max`()	Get the maximum value in this Series.
`mean`()	Reduce this Series to the mean value.
`median`()	Get the median of this Series.
`min`()	Get the minimal value in this Series.
`mode`()	Compute the most occurring value(s).
`n_chunks`()	Get the number of chunks that this Series contains.
`n_unique`()	Count the number of unique values in this Series.
`nan_max`()	Get maximum value, but propagate/poison encountered NaN values.
`nan_min`()	Get minimum value, but propagate/poison encountered NaN values.
`null_count`()	Count the null values in this Series.
`pct_change`([n])	Computes percentage change between values.
`peak_max`()	Get a boolean mask of the local maximum peaks.
`peak_min`()	Get a boolean mask of the local minimum peaks.
`product`()	Reduce this Series to the product value.
`quantile`(quantile[, interpolation])	Get the quantile value of this Series.
`rank`([method, reverse])	Assign ranks to data, dealing with ties appropriately.
`rechunk`([in_place])	Create a single chunk of memory for this Series.
`reinterpret`([signed])	Reinterpret the underlying bits as a signed/unsigned integer.
`rename`(name[, in_place])	Rename this Series.
`reshape`(dims)	Reshape this Series to a flat Series or a Series of Lists.
`reverse`()	Return Series in reverse order.
`rolling_apply`(function, window_size[, ...])	Apply a custom rolling window function.
`rolling_max`(window_size[, weights, ...])	Apply a rolling max (moving max) over the values in this array.
`rolling_mean`(window_size[, weights, ...])	Apply a rolling mean (moving mean) over the values in this array.
`rolling_median`(window_size[, weights, ...])	Compute a rolling median.
`rolling_min`(window_size[, weights, ...])	Apply a rolling min (moving min) over the values in this array.
`rolling_quantile`(quantile[, interpolation, ...])	Compute a rolling quantile.
`rolling_skew`(window_size[, bias])	Compute a rolling skew.
`rolling_std`(window_size[, weights, ...])	Compute a rolling std dev.
`rolling_sum`(window_size[, weights, ...])	Apply a rolling sum (moving sum) over the values in this array.
`rolling_var`(window_size[, weights, ...])	Compute a rolling variance.
`round`(decimals)	Round underlying floating point data by decimals digits.
`sample`([n, frac, with_replacement, shuffle, ...])	Sample from this Series.
`search_sorted`(element)	Find indices where elements should be inserted to maintain order.
`series_equal`(other[, null_equal, strict])	Check if series is equal with another Series.
`set`(filter, value)	Set masked values.
`set_at_idx`(idx, value)	Set values at the index locations.
`set_sorted`([reverse])	Flags the Series as 'sorted'.
`shift`([periods])	Shift the values by a given period.
`shift_and_fill`(periods, fill_value)	Shift the values by a given period and fill the resulting null values.
`shrink_to_fit`([in_place])	Shrink Series memory usage.
`shuffle`([seed])	Shuffle the contents of this Series.
`sign`()	Compute the element-wise indication of the sign.
`sin`()	Compute the element-wise value for the sine.
`sinh`()	Compute the element-wise value for the hyperbolic sine.
`skew`([bias])	Compute the sample skewness of a data set.
`slice`(offset[, length])	Get a slice of this Series.
`sort`([reverse, in_place])	Sort this Series.
`sqrt`()	Compute the square root of the elements.
`std`([ddof])	Get the standard deviation of this Series.
`sum`()	Reduce this Series to the sum value.
`tail`([n])	Get the last n rows.
`take`(indices)	Take values by index.
`take_every`(n)	Take every nth value in the Series and return as new Series.
`tan`()	Compute the element-wise value for the tangent.
`tanh`()	Compute the element-wise value for the hyperbolic tangent.
`to_arrow`()	Get the underlying Arrow Array.
`to_dummies`()	Get dummy variables.
`to_frame`([name])	Cast this Series to a DataFrame.
`to_list`([use_pyarrow])	Convert this Series to a Python List.
`to_numpy`(*args[, zero_copy_only, writable])	Convert this Series to numpy.
`to_pandas`()	Convert this Series to a pandas Series.
`to_physical`()	Cast to physical representation of the logical dtype.
`top_k`([k, reverse])	Return the k largest elements.
`unique`([maintain_order])	Get unique elements in series.
`unique_counts`()	Return a count of the unique values in the order of appearance.
`value_counts`([sort])	Count the unique values in a Series.
`var`([ddof])	Get variance of this Series.
`view`([ignore_nulls])	Get a view into this Series data with a numpy array.
`zip_with`(mask, other)	Take values from self or other based on the given mask.

Attributes

`arr`	Create an object namespace of all list related methods.
`cat`	Create an object namespace of all categorical related methods.
`dt`	Create an object namespace of all datetime related methods.
`dtype`	Get the data type of this Series.
`flags`	Get flags that are set on the Series.
`inner_dtype`	Get the inner dtype in of a List typed Series.
`name`	Get the name of this Series.
`shape`	Shape of this Series.
`str`	Create an object namespace of all string related methods.
`struct`	Create an object namespace of all struct related methods.
`time_unit`	Get the time unit of underlying Datetime Series as {"ns", "us", "ms"}.