polars.Series#

class polars.Series(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]#

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"}.