Skip to content

narwhals.Series

Narwhals Series, backed by a native series.

Warning

This class is not meant to be instantiated directly - instead:

  • If the native object is a series from one of the supported backend (e.g. pandas.Series, polars.Series, pyarrow.ChunkedArray), you can use narwhals.from_native: 

    narwhals.from_native(native_series, allow_series=True)
narwhals.from_native(native_series, series_only=True)

  • If the object is a generic sequence (e.g. a list or a tuple of values), you can create a series via narwhals.new_series: 

    narwhals.new_series(
    name=name,
    values=values,
    native_namespace=narwhals.get_native_namespace(another_object),
)

dtype: DType property

Get the data type of the Series.

Returns:

Type Description
DType

The data type of the Series.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([1, 2, 3])
>>> nw.from_native(s_native, series_only=True).dtype
Int64

implementation: Implementation property

Return implementation of native Series.

This can be useful when you need to use special-casing for features outside of Narwhals' scope - for example, when dealing with pandas' Period Dtype.

Returns:

Type Description
Implementation

Implementation.

Examples:

>>> import narwhals as nw
>>> import pandas as pd

>>> s_native = pd.Series([1, 2, 3])
>>> s = nw.from_native(s_native, series_only=True)

>>> s.implementation
<Implementation.PANDAS: 1>

>>> s.implementation.is_pandas()
True

>>> s.implementation.is_pandas_like()
True

>>> s.implementation.is_polars()
False

name: str property

Get the name of the Series.

Returns:

Type Description
str

The name of the Series.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series("foo", [1, 2, 3])
>>> nw.from_native(s_native, series_only=True).name
'foo'

shape: tuple[int] property

Get the shape of the Series.

Returns:

Type Description
tuple[int]

A tuple containing the length of the Series.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([1, 2, 3])
>>> nw.from_native(s_native, series_only=True).shape
(3,)

__arrow_c_stream__(requested_schema: object | None = None) -> object

Export a Series via the Arrow PyCapsule Interface.

Narwhals doesn't implement anything itself here:

  • if the underlying series implements the interface, it'll return that
  • else, it'll call to_arrow and then defer to PyArrow's implementation

See PyCapsule Interface for more.

__getitem__(idx: int | slice | Sequence[int] | Self) -> Any | Self

Retrieve elements from the object using integer indexing or slicing.

Parameters:

Name Type Description Default
idx int | slice | Sequence[int] | Self

The index, slice, or sequence of indices to retrieve.

  • If idx is an integer, a single element is returned.
  • If idx is a slice, a sequence of integers, or another Series (with integer values) a subset of the Series is returned.
 required

Returns:

Type Description
Any | Self

A single element if idx is an integer, else a subset of the Series.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 2, 3]])
>>> nw.from_native(s_native, series_only=True)[0]
1

>>> nw.from_native(s_native, series_only=True)[
...     :2
... ].to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    1,
    2
  ]
]

__iter__() -> Iterator[Any]

abs() -> Self

Calculate the absolute value of each element.

Returns:

Type Description
Self

A new Series with the absolute values of the original elements.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[2, -4, 3]])
>>> nw.from_native(
...     s_native, series_only=True
... ).abs().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    2,
    4,
    3
  ]
]

alias(name: str) -> Self

Rename the Series.

Notes

This method is very cheap, but does not guarantee that data will be copied. For example:

s1: nw.Series
s2 = s1.alias("foo")
arr = s2.to_numpy()
arr[0] = 999

may (depending on the backend, and on the version) result in s1's data being modified. We recommend:

- if you need to alias an object and don't need the original
  one around any more, just use `alias` without worrying about it.
- if you were expecting `alias` to copy data, then explicitly call
  `.clone` before calling `alias`.

Parameters:

Name Type Description Default
name str

The new name.

 required

Returns:

Type Description
Self

A new Series with the updated name.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([1, 2, 3], name="foo")
>>> nw.from_native(s_native, series_only=True).alias("bar").to_native()
0    1
1    2
2    3
Name: bar, dtype: int64

all() -> bool

Return whether all values in the Series are True.

Returns:

Type Description
bool

A boolean indicating if all values in the Series are True.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[False, True, False]])
>>> nw.from_native(s_native, series_only=True).all()
False

any() -> bool

Return whether any of the values in the Series are True.

Notes

Only works on Series of data type Boolean.

Returns:

Type Description
bool

A boolean indicating if any values in the Series are True.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([False, True, False])
>>> nw.from_native(s_native, series_only=True).any()
np.True_

arg_max() -> int

Returns the index of the maximum value.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1, 2, 3])
>>> nw.from_native(s_native, series_only=True).arg_max()
2

arg_min() -> int

Returns the index of the minimum value.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 2, 3]])
>>> nw.from_native(s_native, series_only=True).arg_min()
0

arg_true() -> Self

Find elements where boolean Series is True.

Returns:

Type Description
Self

A new Series with the indices of elements that are True.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1, None, None, 2])
>>> nw.from_native(
...     s_native, series_only=True
... ).is_null().arg_true().to_native()
shape: (2,)
Series: '' [u32]
[
   1
   2
]

cast(dtype: DType | type[DType]) -> Self

Cast between data types.

Parameters:

Name Type Description Default
dtype DType | type[DType]

Data type that the object will be cast into.

 required

Returns:

Type Description
Self

A new Series with the specified data type.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[True, False, True]])
>>> nw.from_native(s_native, series_only=True).cast(nw.Int64).to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    1,
    0,
    1
  ]
]

clip(lower_bound: Self | Any | None = None, upper_bound: Self | Any | None = None) -> Self

Clip values in the Series.

Parameters:

Name Type Description Default
lower_bound Self | Any | None

Lower bound value.

 None
upper_bound Self | Any | None

Upper bound value.

 None

Returns:

Type Description
Self

A new Series with values clipped to the specified bounds.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([-1, 1, -3, 3, -5, 5])
>>> nw.from_native(s_native, series_only=True).clip(-1, 3).to_native()
0   -1
1    1
2   -1
3    3
4   -1
5    3
dtype: int64

count() -> int

Returns the number of non-null elements in the Series.

Returns:

Type Description
int

The number of non-null elements in the Series.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 2, None]])
>>> nw.from_native(s_native, series_only=True).count()
2

cum_count(*, reverse: bool = False) -> Self

Return the cumulative count of the non-null values in the series.

Parameters:

Name Type Description Default
reverse bool

reverse the operation

 False

Returns:

Type Description
Self

A new Series with the cumulative count of non-null values.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series(["x", "k", None, "d"])
>>> nw.from_native(s_native, series_only=True).cum_count(
...     reverse=True
... ).to_native()
shape: (4,)
Series: '' [u32]
[
    3
    2
    1
    1
]

cum_max(*, reverse: bool = False) -> Self

Return the cumulative max of the non-null values in the series.

Parameters:

Name Type Description Default
reverse bool

reverse the operation

 False

Returns:

Type Description
Self

A new Series with the cumulative max of non-null values.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 3, None, 2]])
>>> nw.from_native(
...     s_native, series_only=True
... ).cum_max().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    1,
    3,
    null,
    3
  ]
]

cum_min(*, reverse: bool = False) -> Self

Return the cumulative min of the non-null values in the series.

Parameters:

Name Type Description Default
reverse bool

reverse the operation

 False

Returns:

Type Description
Self

A new Series with the cumulative min of non-null values.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([3, 1, None, 2])
>>> nw.from_native(s_native, series_only=True).cum_min().to_native()
0    3.0
1    1.0
2    NaN
3    1.0
dtype: float64

cum_prod(*, reverse: bool = False) -> Self

Return the cumulative product of the non-null values in the series.

Parameters:

Name Type Description Default
reverse bool

reverse the operation

 False

Returns:

Type Description
Self

A new Series with the cumulative product of non-null values.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1, 3, None, 2])
>>> nw.from_native(
...     s_native, series_only=True
... ).cum_prod().to_native()
shape: (4,)
Series: '' [i64]
[
   1
   3
   null
   6
]

cum_sum(*, reverse: bool = False) -> Self

Calculate the cumulative sum.

Parameters:

Name Type Description Default
reverse bool

reverse the operation

 False

Returns:

Type Description
Self

A new Series with the cumulative sum of non-null values.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([2, 4, 3])
>>> nw.from_native(s_native, series_only=True).cum_sum().to_native()
0    2
1    6
2    9
dtype: int64

diff() -> Self

Calculate the difference with the previous element, for each element.

Notes

pandas may change the dtype here, for example when introducing missing values in an integer column. To ensure, that the dtype doesn't change, you may want to use fill_null and cast. For example, to calculate the diff and fill missing values with 0 in a Int64 column, you could do:

s.diff().fill_null(0).cast(nw.Int64)

Returns:

Type Description
Self

A new Series with the difference between each element and its predecessor.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[2, 4, 3]])
>>> nw.from_native(
...     s_native, series_only=True
... ).diff().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    null,
    2,
    -1
  ]
]

drop_nulls() -> Self

Drop null values.

Notes

pandas handles null values differently from Polars and PyArrow. See null_handling for reference.

Returns:

Type Description
Self

A new Series with null values removed.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([2, 4, None, 3, 5])
>>> nw.from_native(s_native, series_only=True).drop_nulls().to_native()
0    2.0
1    4.0
3    3.0
4    5.0
dtype: float64

ewm_mean(*, com: float | None = None, span: float | None = None, half_life: float | None = None, alpha: float | None = None, adjust: bool = True, min_samples: int = 1, ignore_nulls: bool = False) -> Self

Compute exponentially-weighted moving average.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Parameters:

Name Type Description Default
com float | None

Specify decay in terms of center of mass, \(\gamma\), with
\(\alpha = \frac{1}{1+\gamma}\forall\gamma\geq0\)

 None
span float | None

Specify decay in terms of span, \(\theta\), with
\(\alpha = \frac{2}{\theta + 1} \forall \theta \geq 1\)

 None
half_life float | None

Specify decay in terms of half-life, \(\tau\), with
\(\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \tau } \right\} \forall \tau > 0\)

 None
alpha float | None

Specify smoothing factor alpha directly, \(0 < \alpha \leq 1\).

 None
adjust bool

Divide by decaying adjustment factor in beginning periods to account for imbalance in relative weightings

  • When adjust=True (the default) the EW function is calculated using weights \(w_i = (1 - \alpha)^i\)
  • When adjust=False the EW function is calculated recursively by $$ y_0=x_0 $$ $$ y_t = (1 - \alpha)y_{t - 1} + \alpha x_t $$
 True
min_samples int

Minimum number of observations in window required to have a value (otherwise result is null).

 1
ignore_nulls bool

Ignore missing values when calculating weights.

  • When ignore_nulls=False (default), weights are based on absolute positions. For example, the weights of \(x_0\) and \(x_2\) used in calculating the final weighted average of \([x_0, None, x_2]\) are \((1-\alpha)^2\) and \(1\) if adjust=True, and \((1-\alpha)^2\) and \(\alpha\) if adjust=False.
  • When ignore_nulls=True, weights are based on relative positions. For example, the weights of \(x_0\) and \(x_2\) used in calculating the final weighted average of \([x_0, None, x_2]\) are \(1-\alpha\) and \(1\) if adjust=True, and \(1-\alpha\) and \(\alpha\) if adjust=False.
 False

Returns:

Type Description
Self

Series

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series(name="a", data=[1, 2, 3])
>>> nw.from_native(s_native, series_only=True).ewm_mean(
...     com=1, ignore_nulls=False
... ).to_native()
0    1.000000
1    1.666667
2    2.428571
Name: a, dtype: float64

fill_null(value: Any | None = None, strategy: Literal['forward', 'backward'] | None = None, limit: int | None = None) -> Self

Fill null values using the specified value.

Parameters:

Name Type Description Default
value Any | None

Value used to fill null values.

 None
strategy Literal['forward', 'backward'] | None

Strategy used to fill null values.

 None
limit int | None

Number of consecutive null values to fill when using the 'forward' or 'backward' strategy.

 None
Notes

pandas handles null values differently from Polars and PyArrow. See null_handling for reference.

Returns:

Type Description
Self

A new Series with null values filled according to the specified value or strategy.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([1, 2, None])
>>>
>>> nw.from_native(s_native, series_only=True).fill_null(5).to_native()
0    1.0
1    2.0
2    5.0
dtype: float64

Or using a strategy:

>>> nw.from_native(s_native, series_only=True).fill_null(
...     strategy="forward", limit=1
... ).to_native()
0    1.0
1    2.0
2    2.0
dtype: float64

filter(other: Any) -> Self

Filter elements in the Series based on a condition.

Returns:

Type Description
Self

A new Series with elements that satisfy the condition.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([4, 10, 15, 34, 50])
>>> s_nw = nw.from_native(s_native, series_only=True)
>>> s_nw.filter(s_nw > 10).to_native()
2    15
3    34
4    50
dtype: int64

gather_every(n: int, offset: int = 0) -> Self

Take every nth value in the Series and return as new Series.

Parameters:

Name Type Description Default
n int

Gather every n-th row.

 required
offset int

Starting index.

 0

Returns:

Type Description
Self

A new Series with every nth value starting from the offset.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 2, 3, 4]])
>>> nw.from_native(s_native, series_only=True).gather_every(
...     n=2, offset=1
... ).to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    2,
    4
  ]
]

head(n: int = 10) -> Self

Get the first n rows.

Parameters:

Name Type Description Default
n int

Number of rows to return.

 10

Returns:

Type Description
Self

A new Series containing the first n rows.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series(list(range(10)))
>>> nw.from_native(s_native, series_only=True).head(3).to_native()
0    0
1    1
2    2
dtype: int64

hist(bins: list[float | int] | None = None, *, bin_count: int | None = None, include_breakpoint: bool = True) -> DataFrame[Any]

Bin values into buckets and count their occurrences.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Parameters:

Name Type Description Default
bins list[float | int] | None

A monotonically increasing sequence of values.

 None
bin_count int | None

If no bins provided, this will be used to determine the distance of the bins.

 None
include_breakpoint bool

Include a column that shows the intervals as categories.

 True

Returns:

Type Description
DataFrame[Any]

A new DataFrame containing the counts of values that occur within each passed bin.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series([1, 3, 8, 8, 2, 1, 3], name="a")
>>> nw.from_native(s_native, series_only=True).hist(bin_count=4)
┌────────────────────┐
| Narwhals DataFrame |
|--------------------|
|   breakpoint  count|
|0        2.75      3|
|1        4.50      2|
|2        6.25      0|
|3        8.00      2|
└────────────────────┘

is_between(lower_bound: Any | Self, upper_bound: Any | Self, closed: Literal['left', 'right', 'none', 'both'] = 'both') -> Self

Get a boolean mask of the values that are between the given lower/upper bounds.

Parameters:

Name Type Description Default
lower_bound Any | Self

Lower bound value.

 required
upper_bound Any | Self

Upper bound value.

 required
closed Literal['left', 'right', 'none', 'both']

Define which sides of the interval are closed (inclusive).

 'both'
Notes

If the value of the lower_bound is greater than that of the upper_bound, then the values will be False, as no value can satisfy the condition.

Returns:

Type Description
Self

A boolean Series indicating which values are between the given bounds.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 2, 3, 4, 5]])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.is_between(2, 4, "right").to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    false,
    false,
    true,
    true,
    false
  ]
]

is_duplicated() -> Self

Get a mask of all duplicated rows in the Series.

Returns:

Type Description
Self

A new Series with boolean values indicating duplicated rows.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 2, 3, 1]])
>>> nw.from_native(
...     s_native, series_only=True
... ).is_duplicated().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    true,
    false,
    false,
    true
  ]
]

is_empty() -> bool

Check if the series is empty.

Returns:

Type Description
bool

A boolean indicating if the series is empty.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1, 2, 3])
>>> s_nw = nw.from_native(s_native, series_only=True)

>>> s_nw.is_empty()
False
>>> s_nw.filter(s_nw > 10).is_empty()
True

is_finite() -> Self

Returns a boolean Series indicating which values are finite.

Warning

Different backend handle null values differently. is_finite will return False for NaN and Null's in the Dask and pandas non-nullable backend, while for Polars, PyArrow and pandas nullable backends null values are kept as such.

Returns:

Type Description
Self

Expression of Boolean data type.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[float("nan"), float("inf"), 2.0, None]])
>>> nw.from_native(
...     s_native, series_only=True
... ).is_finite().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    false,
    false,
    true,
    null
  ]
]

is_first_distinct() -> Self

Return a boolean mask indicating the first occurrence of each distinct value.

Returns:

Type Description
Self

A new Series with boolean values indicating the first occurrence of each distinct value.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1, 1, 2, 3, 2])
>>> nw.from_native(
...     s_native, series_only=True
... ).is_first_distinct().to_native()
shape: (5,)
Series: '' [bool]
[
    true
    false
    true
    true
    false
]

is_in(other: Any) -> Self

Check if the elements of this Series are in the other sequence.

Parameters:

Name Type Description Default
other Any

Sequence of primitive type.

 required

Returns:

Type Description
Self

A new Series with boolean values indicating if the elements are in the other sequence.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 2, 3]])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.is_in([3, 2, 8]).to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    false,
    true,
    true
  ]
]

is_last_distinct() -> Self

Return a boolean mask indicating the last occurrence of each distinct value.

Returns:

Type Description
Self

A new Series with boolean values indicating the last occurrence of each distinct value.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([1, 1, 2, 3, 2])
>>> nw.from_native(s_native, series_only=True).is_last_distinct().to_native()
0    False
1     True
2    False
3     True
4     True
dtype: bool

is_nan() -> Self

Returns a boolean Series indicating which values are NaN.

Returns:

Type Description
Self

A boolean Series indicating which values are NaN.
Notes

pandas handles null values differently from Polars and PyArrow. See null_handling for reference.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([0.0, None, 2.0], dtype="Float64")
>>> nw.from_native(s_native, series_only=True).is_nan().to_native()
0    False
1     <NA>
2    False
dtype: boolean

is_null() -> Self

Returns a boolean Series indicating which values are null.

Notes

pandas handles null values differently from Polars and PyArrow. See null_handling for reference.

Returns:

Type Description
Self

A boolean Series indicating which values are null.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 2, None]])
>>> nw.from_native(
...     s_native, series_only=True
... ).is_null().to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    false,
    false,
    true
  ]
]

is_sorted(*, descending: bool = False) -> bool

Check if the Series is sorted.

Parameters:

Name Type Description Default
descending bool

Check if the Series is sorted in descending order.

 False

Returns:

Type Description
bool

A boolean indicating if the Series is sorted.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[3, 2, 1]])
>>> s_nw = nw.from_native(s_native, series_only=True)

>>> s_nw.is_sorted(descending=False)
False

>>> s_nw.is_sorted(descending=True)
True

is_unique() -> Self

Get a mask of all unique rows in the Series.

Returns:

Type Description
Self

A new Series with boolean values indicating unique rows.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([1, 2, 3, 1])
>>> nw.from_native(s_native, series_only=True).is_unique().to_native()
0    False
1     True
2     True
3    False
dtype: bool

item(index: int | None = None) -> Any

Return the Series as a scalar, or return the element at the given index.

If no index is provided, this is equivalent to s[0], with a check that the shape is (1,). With an index, this is equivalent to s[index].

Returns:

Type Description
Any

The scalar value of the Series or the element at the given index.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> nw.from_native(pl.Series("a", [1]), series_only=True).item()
1

>>> nw.from_native(pl.Series("a", [9, 8, 7]), series_only=True).item(-1)
7

len() -> int

Return the number of elements in the Series.

Null values count towards the total.

Returns:

Type Description
int

The number of elements in the Series.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 2, None]])
>>> nw.from_native(s_native, series_only=True).len()
3

max() -> Any

Get the maximum value in this Series.

Returns:

Type Description
Any

The maximum value in the Series.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([1, 2, 3])
>>> nw.from_native(s_native, series_only=True).max()
np.int64(3)

mean() -> float

Reduce this Series to the mean value.

Returns:

Type Description
float

The average of all elements in the Series.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([1.2, 4.2])
>>> nw.from_native(s_native, series_only=True).mean()
np.float64(2.7)

median() -> float

Reduce this Series to the median value.

Notes

Results might slightly differ across backends due to differences in the underlying algorithms used to compute the median.

Returns:

Type Description
float

The median value of all elements in the Series.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[5, 3, 8]])
>>> nw.from_native(s_native, series_only=True).median()
5.0

min() -> Any

Get the minimal value in this Series.

Returns:

Type Description
Any

The minimum value in the Series.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1, 2, 3])
>>> nw.from_native(s_native, series_only=True).min()
1

mode() -> Self

Compute the most occurring value(s).

Can return multiple values.

Returns:

Type Description
Self

A new Series containing the mode(s) (values that appear most frequently).

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series([1, 1, 2, 2, 3])
>>> nw.from_native(s_native, series_only=True).mode().sort().to_native()
0    1
1    2
dtype: int64

n_unique() -> int

Count the number of unique values.

Returns:

Type Description
int

Number of unique values in the Series.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1, 2, 2, 3])
>>> nw.from_native(s_native, series_only=True).n_unique()
3

null_count() -> int

Count the number of null values.

Notes

pandas handles null values differently from Polars and PyArrow. See null_handling for reference.

Returns:

Type Description
int

The number of null values in the Series.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, None, None]])
>>> nw.from_native(s_native, series_only=True).null_count()
2

pipe(function: Callable[[Any], Self], *args: Any, **kwargs: Any) -> Self

Pipe function call.

Returns:

Type Description
Self

A new Series with the results of the piped function applied.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series([1, 2, 3])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.pipe(lambda x: x + 2).to_native()
shape: (3,)
Series: '' [i64]
[
    3
    4
    5
]

quantile(quantile: float, interpolation: Literal['nearest', 'higher', 'lower', 'midpoint', 'linear']) -> float

Get quantile value of the series.

Note

pandas and Polars may have implementation differences for a given interpolation method.

Parameters:

Name Type Description Default
quantile float

Quantile between 0.0 and 1.0.

 required
interpolation Literal['nearest', 'higher', 'lower', 'midpoint', 'linear']

Interpolation method.

 required

Returns:

Type Description
float

The quantile value.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series(list(range(50)))
>>> s_nw = nw.from_native(s_native, series_only=True)
>>> [
...     s_nw.quantile(quantile=q, interpolation="nearest")
...     for q in (0.1, 0.25, 0.5, 0.75, 0.9)
... ]
[5.0, 12.0, 25.0, 37.0, 44.0]

rank(method: Literal['average', 'min', 'max', 'dense', 'ordinal'] = 'average', *, descending: bool = False) -> Self

Assign ranks to data, dealing with ties appropriately.

Notes

The resulting dtype may differ between backends.

Parameters:

Name Type Description Default
method Literal['average', 'min', 'max', 'dense', 'ordinal']

The method used to assign ranks to tied elements. The following methods are available (default is 'average'):

  • 'average' : The average of the ranks that would have been assigned to all the tied values is assigned to each value.
  • 'min' : The minimum of the ranks that would have been assigned to all the tied values is assigned to each value. (This is also referred to as "competition" ranking.)
  • 'max' : The maximum of the ranks that would have been assigned to all the tied values is assigned to each value.
  • 'dense' : Like 'min', but the rank of the next highest element is assigned the rank immediately after those assigned to the tied elements.
  • 'ordinal' : All values are given a distinct rank, corresponding to the order that the values occur in the Series.
 'average'
descending bool

Rank in descending order.

 False

Returns:

Type Description
Self

A new series with rank data as values.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[3, 6, 1, 1, 6]])
>>> nw.from_native(s_native, series_only=True).rank(
...     method="dense"
... ).to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    2,
    3,
    1,
    1,
    3
  ]
]

rename(name: str) -> Self

Rename the Series.

Alias for Series.alias().

Notes

This method is very cheap, but does not guarantee that data will be copied. For example:

s1: nw.Series
s2 = s1.rename("foo")
arr = s2.to_numpy()
arr[0] = 999

may (depending on the backend, and on the version) result in s1's data being modified. We recommend:

- if you need to rename an object and don't need the original
  one around any more, just use `rename` without worrying about it.
- if you were expecting `rename` to copy data, then explicitly call
  `.clone` before calling `rename`.

Parameters:

Name Type Description Default
name str

The new name.

 required

Returns:

Type Description
Self

A new Series with the updated name.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series("foo", [1, 2, 3])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.rename("bar").to_native()
shape: (3,)
Series: 'bar' [i64]
[
   1
   2
   3
]

replace_strict(old: Sequence[Any] | Mapping[Any, Any], new: Sequence[Any] | None = None, *, return_dtype: DType | type[DType] | None = None) -> Self

Replace all values by different values.

This function must replace all non-null input values (else it raises an error).

Parameters:

Name Type Description Default
old Sequence[Any] | Mapping[Any, Any]

Sequence of values to replace. It also accepts a mapping of values to their replacement as syntactic sugar for replace_all(old=list(mapping.keys()), new=list(mapping.values())).

 required
new Sequence[Any] | None

Sequence of values to replace by. Length must match the length of old.

 None
return_dtype DType | type[DType] | None

The data type of the resulting expression. If set to None (default), the data type is determined automatically based on the other inputs.

 None

Returns:

Type Description
Self

A new Series with values replaced according to the mapping.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([3, 0, 1, 2], name="a")
>>> nw.from_native(s_native, series_only=True).replace_strict(
...     [0, 1, 2, 3],
...     ["zero", "one", "two", "three"],
...     return_dtype=nw.String,
... ).to_native()
0    three
1     zero
2      one
3      two
Name: a, dtype: object

rolling_mean(window_size: int, *, min_samples: int | None = None, center: bool = False) -> Self

Apply a rolling mean (moving mean) over the values.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

A window of length window_size will traverse the values. The resulting values will be aggregated to their mean.

The window at a given row will include the row itself and the window_size - 1 elements before it.

Parameters:

Name Type Description Default
window_size int

The length of the window in number of elements. It must be a strictly positive integer.

 required
min_samples int | None

The number of values in the window that should be non-null before computing a result. If set to None (default), it will be set equal to window_size. If provided, it must be a strictly positive integer, and less than or equal to window_size

 None
center bool

Set the labels at the center of the window.

 False

Returns:

Type Description
Self

A new series.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1.0, 2.0, 3.0, 4.0]])
>>> nw.from_native(s_native, series_only=True).rolling_mean(
...     window_size=2
... ).to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    null,
    1.5,
    2.5,
    3.5
  ]
]

rolling_std(window_size: int, *, min_samples: int | None = None, center: bool = False, ddof: int = 1) -> Self

Apply a rolling standard deviation (moving standard deviation) over the values.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

A window of length window_size will traverse the values. The resulting values will be aggregated to their standard deviation.

The window at a given row will include the row itself and the window_size - 1 elements before it.

Parameters:

Name Type Description Default
window_size int

The length of the window in number of elements. It must be a strictly positive integer.

 required
min_samples int | None

The number of values in the window that should be non-null before computing a result. If set to None (default), it will be set equal to window_size. If provided, it must be a strictly positive integer, and less than or equal to window_size.

 None
center bool

Set the labels at the center of the window.

 False
ddof int

Delta Degrees of Freedom; the divisor for a length N window is N - ddof.

 1

Returns:

Type Description
Self

A new series.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([1.0, 3.0, 1.0, 4.0])
>>> nw.from_native(s_native, series_only=True).rolling_std(
...     window_size=2, min_samples=1
... ).to_native()
0         NaN
1    1.414214
2    1.414214
3    2.121320
dtype: float64

rolling_sum(window_size: int, *, min_samples: int | None = None, center: bool = False) -> Self

Apply a rolling sum (moving sum) over the values.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

A window of length window_size will traverse the values. The resulting values will be aggregated to their sum.

The window at a given row will include the row itself and the window_size - 1 elements before it.

Parameters:

Name Type Description Default
window_size int

The length of the window in number of elements. It must be a strictly positive integer.

 required
min_samples int | None

The number of values in the window that should be non-null before computing a result. If set to None (default), it will be set equal to window_size. If provided, it must be a strictly positive integer, and less than or equal to window_size

 None
center bool

Set the labels at the center of the window.

 False

Returns:

Type Description
Self

A new series.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([1.0, 2.0, 3.0, 4.0])
>>> nw.from_native(s_native, series_only=True).rolling_sum(
...     window_size=2
... ).to_native()
0    NaN
1    3.0
2    5.0
3    7.0
dtype: float64

rolling_var(window_size: int, *, min_samples: int | None = None, center: bool = False, ddof: int = 1) -> Self

Apply a rolling variance (moving variance) over the values.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

A window of length window_size will traverse the values. The resulting values will be aggregated to their variance.

The window at a given row will include the row itself and the window_size - 1 elements before it.

Parameters:

Name Type Description Default
window_size int

The length of the window in number of elements. It must be a strictly positive integer.

 required
min_samples int | None

The number of values in the window that should be non-null before computing a result. If set to None (default), it will be set equal to window_size. If provided, it must be a strictly positive integer, and less than or equal to window_size.

 None
center bool

Set the labels at the center of the window.

 False
ddof int

Delta Degrees of Freedom; the divisor for a length N window is N - ddof.

 1

Returns:

Type Description
Self

A new series.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1.0, 3.0, 1.0, 4.0])
>>> nw.from_native(s_native, series_only=True).rolling_var(
...     window_size=2, min_samples=1
... ).to_native()
shape: (4,)
Series: '' [f64]
[
   null
   2.0
   2.0
   4.5
]

round(decimals: int = 0) -> Self

Round underlying floating point data by decimals digits.

Parameters:

Name Type Description Default
decimals int

Number of decimals to round by.

 0

Returns:

Type Description
Self

A new Series with rounded values.
Notes

For values exactly halfway between rounded decimal values pandas behaves differently than Polars and Arrow.

pandas rounds to the nearest even value (e.g. -0.5 and 0.5 round to 0.0, 1.5 and 2.5 round to 2.0, 3.5 and 4.5 to 4.0, etc..).

Polars and Arrow round away from 0 (e.g. -0.5 to -1.0, 0.5 to 1.0, 1.5 to 2.0, 2.5 to 3.0, etc..).

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1.12345, 2.56789, 3.901234])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.round(1).to_native()
shape: (3,)
Series: '' [f64]
[
   1.1
   2.6
   3.9
]

sample(n: int | None = None, *, fraction: float | None = None, with_replacement: bool = False, seed: int | None = None) -> Self

Sample randomly from this Series.

Parameters:

Name Type Description Default
n int | None

Number of items to return. Cannot be used with fraction.

 None
fraction float | None

Fraction of items to return. Cannot be used with n.

 None
with_replacement bool

Allow values to be sampled more than once.

 False
seed int | None

Seed for the random number generator. If set to None (default), a random seed is generated for each sample operation.

 None

Returns:

Type Description
Self

A new Series containing randomly sampled values from the original Series.
Notes

The sample method returns a Series with a specified number of randomly selected items chosen from this Series. The results are not consistent across libraries.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1, 2, 3, 4])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.sample(
...     fraction=1.0, with_replacement=True
... ).to_native()
shape: (4,)
Series: '' [i64]
[
   1
   4
   3
   4
]

scatter(indices: int | Sequence[int], values: Any) -> Self

Set value(s) at given position(s).

Parameters:

Name Type Description Default
indices int | Sequence[int]

Position(s) to set items at.

 required
values Any

Values to set.

 required

Returns:

Type Description
Self

A new Series with values set at given positions.
Note

This method always returns a new Series, without modifying the original one. Using this function in a for-loop is an anti-pattern, we recommend building up your positions and values beforehand and doing an update in one go.

For example, instead of

for i in [1, 3, 2]:
    value = some_function(i)
    s = s.scatter(i, value)

prefer

positions = [1, 3, 2]
values = [some_function(x) for x in positions]
s = s.scatter(positions, values)

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> df_native = pa.table({"a": [1, 2, 3], "b": [4, 5, 6]})
>>> df_nw = nw.from_native(df_native)
>>> df_nw.with_columns(df_nw["a"].scatter([0, 1], [999, 888])).to_native()
pyarrow.Table
a: int64
b: int64
----
a: [[999,888,3]]
b: [[4,5,6]]

shift(n: int) -> Self

Shift values by n positions.

Parameters:

Name Type Description Default
n int

Number of indices to shift forward. If a negative value is passed, values are shifted in the opposite direction instead.

 required

Returns:

Type Description
Self

A new Series with values shifted by n positions.
Notes

pandas may change the dtype here, for example when introducing missing values in an integer column. To ensure, that the dtype doesn't change, you may want to use fill_null and cast. For example, to shift and fill missing values with 0 in a Int64 column, you could do:

s.shift(1).fill_null(0).cast(nw.Int64)

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([2, 4, 3])
>>> nw.from_native(s_native, series_only=True).shift(1).to_native()
0    NaN
1    2.0
2    4.0
dtype: float64

sort(*, descending: bool = False, nulls_last: bool = False) -> Self

Sort this Series. Place null values first.

Parameters:

Name Type Description Default
descending bool

Sort in descending order.

 False
nulls_last bool

Place null values last instead of first.

 False

Returns:

Type Description
Self

A new sorted Series.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([5, None, 1, 2])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.sort(descending=True).to_native()
shape: (4,)
Series: '' [i64]
[
   null
   5
   2
   1
]

skew() -> float | None

Calculate the sample skewness of the Series.

Returns:

Type Description
float | None

The sample skewness of the Series.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1, 1, 2, 10, 100])
>>> nw.from_native(s_native, series_only=True).skew()
1.4724267269058975
Notes

The skewness is a measure of the asymmetry of the probability distribution. A perfectly symmetric distribution has a skewness of 0.

std(*, ddof: int = 1) -> float

Get the standard deviation of this Series.

Parameters:

Name Type Description Default
ddof int

"Delta Degrees of Freedom": the divisor used in the calculation is N - ddof, where N represents the number of elements.

 1

Returns:

Type Description
float

The standard deviation of all elements in the Series.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1, 2, 3])
>>> nw.from_native(s_native, series_only=True).std()
1.0

sum() -> float

Reduce this Series to the sum value.

Returns:

Type Description
float

The sum of all elements in the Series.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 2, 3]])
>>> nw.from_native(s_native, series_only=True).sum()
6

tail(n: int = 10) -> Self

Get the last n rows.

Parameters:

Name Type Description Default
n int

Number of rows to return.

 10

Returns:

Type Description
Self

A new Series with the last n rows.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([list(range(10))])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.tail(3).to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    7,
    8,
    9
  ]
]

to_arrow() -> ArrowArray

Convert to arrow.

Returns:

Type Description
ArrowArray

A PyArrow Array containing the data from the Series.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1, 2, 3, 4])
>>> nw.from_native(
...     s_native, series_only=True
... ).to_arrow()
<pyarrow.lib.Int64Array object at ...>
[
    1,
    2,
    3,
    4
]

to_dummies(*, separator: str = '_', drop_first: bool = False) -> DataFrame[Any]

Get dummy/indicator variables.

Parameters:

Name Type Description Default
separator str

Separator/delimiter used when generating column names.

 '_'
drop_first bool

Remove the first category from the variable being encoded.

 False

Returns:

Type Description
DataFrame[Any]

A new DataFrame containing the dummy/indicator variables.
Notes

pandas and Polars handle null values differently. Polars distinguishes between NaN and Null, whereas pandas doesn't.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([1, 2, 3], name="a")
>>> s_nw = nw.from_native(s_native, series_only=True)

>>> s_nw.to_dummies(drop_first=False).to_native()
   a_1  a_2  a_3
0    1    0    0
1    0    1    0
2    0    0    1

>>> s_nw.to_dummies(drop_first=True).to_native()
   a_2  a_3
0    0    0
1    1    0
2    0    1

to_frame() -> DataFrame[Any]

Convert to dataframe.

Returns:

Type Description
DataFrame[Any]

A DataFrame containing this Series as a single column.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series("a", [1, 2])
>>> nw.from_native(s_native, series_only=True).to_frame().to_native()
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
└─────┘

to_list() -> list[Any]

Convert to list.

Notes

This function converts to Python scalars. It's typically more efficient to keep your data in the format native to your original dataframe, so we recommend only calling this when you absolutely need to.

Returns:

Type Description
list[Any]

A list of Python objects.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 2, 3]])
>>> nw.from_native(s_native, series_only=True).to_list()
[1, 2, 3]

to_numpy() -> _1DArray

Convert to numpy.

Returns:

Type Description
_1DArray

NumPy ndarray representation of the Series.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([1, 2, 3], name="a")
>>> nw.from_native(s_native, series_only=True).to_numpy()
array([1, 2, 3]...)

to_pandas() -> pd.Series

Convert to pandas Series.

Returns:

Type Description
Series

A pandas Series containing the data from this Series.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series("a", [1, 2, 3])
>>> nw.from_native(s_native, series_only=True).to_pandas()
0    1
1    2
2    3
Name: a, dtype: int64

to_polars() -> pl.Series

Convert to polars Series.

Returns:

Type Description
Series

A polars Series containing the data from this Series.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 2, 3]])
>>> nw.from_native(
...     s_native, series_only=True
... ).to_polars()
shape: (3,)
Series: '' [i64]
[
    1
    2
    3
]

to_native() -> IntoSeriesT

Convert Narwhals series to native series.

Returns:

Type Description
IntoSeriesT

Series of class that user started with.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([1, 2])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.to_native()
shape: (2,)
Series: '' [i64]
[
  1
  2
]

unique(*, maintain_order: bool = False) -> Self

Returns unique values of the series.

Parameters:

Name Type Description Default
maintain_order bool

Keep the same order as the original series. This may be more expensive to compute. Settings this to True blocks the possibility to run on the streaming engine for Polars.

 False

Returns:

Type Description
Self

A new Series with duplicate values removed.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>>
>>> s_native = pl.Series([2, 4, 4, 6])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.unique(
...     maintain_order=True
... ).to_native()
shape: (3,)
Series: '' [i64]
[
   2
   4
   6
]

value_counts(*, sort: bool = False, parallel: bool = False, name: str | None = None, normalize: bool = False) -> DataFrame[Any]

Count the occurrences of unique values.

Parameters:

Name Type Description Default
sort bool

Sort the output by count in descending order. If set to False (default), the order of the output is random.

 False
parallel bool

Execute the computation in parallel. Used for Polars only.

 False
name str | None

Give the resulting count column a specific name; if normalize is True defaults to "proportion", otherwise defaults to "count".

 None
normalize bool

If true gives relative frequencies of the unique values

 False

Returns:

Type Description
DataFrame[Any]

A DataFrame with two columns:
DataFrame[Any]
  • The original values as first column
DataFrame[Any]
  • Either count or proportion as second column, depending on normalize parameter.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> s_native = pd.Series([1, 1, 2, 3, 2], name="s")
>>> nw.from_native(s_native, series_only=True).value_counts(
...     sort=True
... ).to_native()
   s  count
0  1      2
1  2      2
2  3      1

var(*, ddof: int = 1) -> float

Get the variance of this Series.

Parameters:

Name Type Description Default
ddof int

"Delta Degrees of Freedom": the divisor used in the calculation is N - ddof, where N represents the number of elements.

 1

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> s_native = pa.chunked_array([[1, 2, 3]])
>>> nw.from_native(s_native, series_only=True).var()
1.0

zip_with(mask: Self, other: Self) -> Self

Take values from self or other based on the given mask.

Where mask evaluates true, take values from self. Where mask evaluates false, take values from other.

Parameters:

Name Type Description Default
mask Self

Boolean Series

 required
other Self

Series of same type.

 required

Returns:

Type Description
Self

A new Series with values selected from self or other based on the mask.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>> data_native = pa.chunked_array([[1, 2, 3, 4, 5]])
>>> other_native = pa.chunked_array([[5, 4, 3, 2, 1]])
>>> mask_native = pa.chunked_array([[True, False, True, False, True]])
>>>
>>> data_nw = nw.from_native(data_native, series_only=True)
>>> other_nw = nw.from_native(other_native, series_only=True)
>>> mask_nw = nw.from_native(mask_native, series_only=True)
>>>
>>> data_nw.zip_with(mask_nw, other_nw).to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    1,
    4,
    3,
    2,
    5
  ]
]