`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, e.g.:
```
narwhals.new_series(name="price", values=[10.5, 9.4, 1.2], backend="pandas")
```

dtype `property`

dtype: DType

Get 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 `property`

implementation: Implementation

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.

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: 'pandas'>

>>> s.implementation.is_pandas()
True

>>> s.implementation.is_pandas_like()
True

>>> s.implementation.is_polars()
False

name `property`

name: str

Get 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 `property`

shape: tuple[int]

Get the shape 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__

__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

__getitem__(idx: SingleIndexSelector) -> Any

__getitem__(idx: MultiIndexSelector) -> Self

__getitem__(
    idx: SingleIndexSelector | MultiIndexSelector,
) -> Any | Self

Retrieve elements from the object using integer indexing or slicing.

Parameters:

Name	Type	Description	Default
`idx`	`SingleIndexSelector \| MultiIndexSelector`	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

__iter__() -> Iterator[Any]

abs

abs() -> Self

Calculate the absolute value of each element.

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

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

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

all() -> bool

Return whether all values in the Series are True.

If there are no non-null elements, the result is 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

any() -> bool

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

If there are no non-null elements, the result is False.

Notes

Only works on Series of data type Boolean.

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

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

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

arg_true() -> Self

Find elements where boolean Series is 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

cast(dtype: IntoDType) -> Self

Cast between data types.

Parameters:

Name	Type	Description	Default
`dtype`	`IntoDType`	Data type that the object will be cast into.	required

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

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

Clip values in the Series.

Parameters:

Name	Type	Description	Default
`lower_bound`	`Self \| NumericLiteral \| TemporalLiteral \| None`	Lower bound value.	`None`
`upper_bound`	`Self \| NumericLiteral \| TemporalLiteral \| None`	Upper bound value.	`None`

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

count() -> int

Returns 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

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`

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

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`

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

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`

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

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`

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

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

Calculate the cumulative sum.

Parameters:

Name	Type	Description	Default
`reverse`	`bool`	reverse the operation	`False`

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

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)

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

drop_nulls() -> Self

Drop null values.

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([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

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.

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`

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

exp

exp() -> Self

Compute the exponent.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series([-1, 0, 1], name="a")
>>> s = nw.from_native(s_native, series_only=True)
>>> s.exp()
┌───────────────────────┐
|    Narwhals Series    |
|-----------------------|
|0    0.367879          |
|1    1.000000          |
|2    2.718282          |
|Name: a, dtype: float64|
└───────────────────────┘

fill_nan

fill_nan(value: float | None) -> Self

Fill floating point NaN values with given value.

Parameters:

Name	Type	Description	Default
`value`	`float \| None`	Value used to fill NaN values.	required

Notes

This function only fills 'NaN' values, not null ones, except for pandas which doesn't distinguish between them. See null_handling for reference.

Examples:

>>> import polars as pl
>>> import narwhals as nw
>>> s_native = pl.Series([1.0, 2.0, float("nan"), None])
>>> result = nw.from_native(s_native, series_only=True).fill_nan(0)
>>> result.to_native()
shape: (4,)
Series: '' [f64]
[
   1.0
   2.0
   0.0
   null
]

fill_null

fill_null(
    value: Self | NonNestedLiteral = None,
    strategy: FillNullStrategy | None = None,
    limit: int | None = None,
) -> Self

Fill null values using the specified value.

Parameters:

Name	Type	Description	Default
`value`	`Self \| NonNestedLiteral`	Value used to fill null values.	`None`
`strategy`	`FillNullStrategy \| 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 other libraries. See null_handling for reference.
For pandas Series of object dtype, fill_null will not automatically change the Series' dtype as pandas used to do. Explicitly call cast if you want the dtype to change.

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

filter(predicate: Any) -> Self

Filter elements in the Series based on a 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

from_iterable `classmethod`

from_iterable(
    name: str,
    values: Iterable[Any],
    dtype: IntoDType | None = None,
    *,
    backend: IntoBackend[EagerAllowed]
) -> Series[Any]

Construct a Series from an iterable.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of resulting Series.	required
`values`	`Iterable[Any]`	One-dimensional data represented as an iterable.	required
`dtype`	`IntoDType \| None`	(Narwhals) dtype. If not provided, the native library may auto-infer it from `values`.	`None`
`backend`	`IntoBackend[EagerAllowed]`	specifies which eager backend instantiate to. `backend` can be specified in various ways As `Implementation.<BACKEND>` with `BACKEND` being `PANDAS`, `PYARROW`, `POLARS`, `MODIN` or `CUDF`. As a string: `"pandas"`, `"pyarrow"`, `"polars"`, `"modin"` or `"cudf"`. Directly as a module `pandas`, `pyarrow`, `polars`, `modin` or `cudf`.	required

Returns:

Type	Description
`Series[Any]`	A new Series

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>>
>>> values = [4, 1, 3, 2]
>>> nw.Series.from_iterable("a", values, dtype=nw.UInt32, backend="pandas")
┌──────────────────────┐
|   Narwhals Series    |
|----------------------|
|0    4                |
|1    1                |
|2    3                |
|3    2                |
|Name: a, dtype: uint32|
└──────────────────────┘

from_numpy `classmethod`

from_numpy(
    name: str,
    values: _1DArray,
    dtype: IntoDType | None = None,
    *,
    backend: IntoBackend[EagerAllowed]
) -> Series[Any]

Construct a Series from a NumPy ndarray.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of resulting Series.	required
`values`	`_1DArray`	One-dimensional data represented as a NumPy ndarray.	required
`dtype`	`IntoDType \| None`	(Narwhals) dtype. If not provided, the native library may auto-infer it from `values`.	`None`
`backend`	`IntoBackend[EagerAllowed]`	specifies which eager backend instantiate to. `backend` can be specified in various ways As `Implementation.<BACKEND>` with `BACKEND` being `PANDAS`, `PYARROW`, `POLARS`, `MODIN` or `CUDF`. As a string: `"pandas"`, `"pyarrow"`, `"polars"`, `"modin"` or `"cudf"`. Directly as a module `pandas`, `pyarrow`, `polars`, `modin` or `cudf`.	required

Examples:

>>> import numpy as np
>>> import polars as pl
>>> import narwhals as nw
>>>
>>> arr = np.arange(5, 10)
>>> nw.Series.from_numpy("arr", arr, dtype=nw.Int8, backend="polars")
┌──────────────────┐
| Narwhals Series  |
|------------------|
|shape: (5,)       |
|Series: 'arr' [i8]|
|[                 |
|        5         |
|        6         |
|        7         |
|        8         |
|        9         |
|]                 |
└──────────────────┘

gather_every

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`

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

head(n: int = 10) -> Self

Get the first n rows.

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of rows to return.	`10`

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

hist(
    bins: list[float] | 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] \| 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`

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

is_between(
    lower_bound: Any | Self,
    upper_bound: Any | Self,
    closed: ClosedInterval = "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`	`ClosedInterval`	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.

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_close

is_close(
    other: Self | NumericLiteral,
    *,
    abs_tol: float = 0.0,
    rel_tol: float = 1e-09,
    nans_equal: bool = False
) -> Self

Get a boolean mask of the values being close to the other values.

Two values a and b are considered close if the following condition holds:

\[ |a-b| \le max \{ \text{rel\_tol} \cdot max \{ |a|, |b| \}, \text{abs\_tol} \} \]

Parameters:

Name	Type	Description	Default
`other`	`Self \| NumericLiteral`	Values to compare with.	required
`abs_tol`	`float`	Absolute tolerance. This is the maximum allowed absolute difference between two values. Must be non-negative.	`0.0`
`rel_tol`	`float`	Relative tolerance. This is the maximum allowed difference between two values, relative to the larger absolute value. Must be in the range [0, 1).	`1e-09`
`nans_equal`	`bool`	Whether NaN values should be considered equal.	`False`

Notes

The implementation of this method is symmetric and mirrors the behavior of math.isclose. Specifically note that this behavior is different to numpy.isclose.

Examples:

>>> import pyarrow as pa
>>> import narwhals as nw
>>>
>>> data = [1.0, float("inf"), 1.41, None, float("nan")]
>>> s_native = pa.chunked_array([data])
>>> s = nw.from_native(s_native, series_only=True)
>>> s.is_close(1.4, abs_tol=0.1).to_native()
<pyarrow.lib.ChunkedArray object at ...>
[
  [
    false,
    false,
    true,
    null,
    false
  ]
]

is_duplicated

is_duplicated() -> Self

Get a mask of all duplicated rows in the Series.

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

is_empty() -> bool

Check 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

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.

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

is_first_distinct() -> Self

Return a boolean mask 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

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

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

is_last_distinct() -> Self

Return a boolean mask 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

is_nan() -> Self

Returns 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

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.

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

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`

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

is_unique() -> Self

Get a mask of all unique rows in the Series.

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

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].

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

kurtosis

kurtosis() -> float | None

Compute the kurtosis (Fisher's definition) without bias correction.

Kurtosis is the fourth central moment divided by the square of the variance. The Fisher's definition is used where 3.0 is subtracted from the result to give 0.0 for a normal distribution.

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).kurtosis()
0.2106571340718002

len

len() -> int

Return the number of elements in the Series.

Null values count towards the total.

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

log

log(base: float = math.e) -> Self

Compute the logarithm to a given base.

Parameters:

Name	Type	Description	Default
`base`	`float`	Given base, defaults to `e`	`e`

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series([1, 2, 4], name="a")
>>> s = nw.from_native(s_native, series_only=True)
>>> s.log(base=2)
┌───────────────────────┐
|    Narwhals Series    |
|-----------------------|
|0    0.0               |
|1    1.0               |
|2    2.0               |
|Name: a, dtype: float64|
└───────────────────────┘

max

max() -> Any

Get the maximum value in this 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

mean() -> float

Reduce this Series to the mean value.

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

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.

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

min() -> Any

Get the minimal value in this 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

mode(*, keep: Literal['all'] = 'all') -> Self

mode(*, keep: Literal['any']) -> NonNestedLiteral

mode(
    *, keep: ModeKeepStrategy = "all"
) -> Self | NonNestedLiteral

Compute the most occurring value(s).

Can return multiple values.

Note

For keep="any" a scalar is returned, while for keep="all" a Series in returned even in the case of unimodal values.

Parameters:

Name	Type	Description	Default
`keep`	`ModeKeepStrategy`	Whether to keep all modes or any mode found. Remark that `keep='any'` is not deterministic for multimodal values.	`'all'`

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

n_unique() -> int

Count the number of unique values.

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

null_count() -> int

Count the number of null values.

Notes

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

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

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

Pipe function call.

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(
    quantile: float,
    interpolation: RollingInterpolationMethod,
) -> 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`	`RollingInterpolationMethod`	Interpolation method.	required

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

rank(
    method: RankMethod = "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`	`RankMethod`	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`

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

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

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

replace_strict(
    old: Sequence[Any] | Mapping[Any, Any],
    new: Sequence[Any] | None = None,
    *,
    return_dtype: IntoDType | 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_strict(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`	`IntoDType \| 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`

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

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

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

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`

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

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.

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`

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

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

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

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`

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

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.

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`

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

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`

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

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`

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

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

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

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

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

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`

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

skew() -> float | None

Calculate 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.

sqrt

sqrt() -> Self

Compute the square root.

Examples:

>>> import pandas as pd
>>> import narwhals as nw
>>> s_native = pd.Series([1, 4, 9], name="a")
>>> s = nw.from_native(s_native, series_only=True)
>>> s.sqrt()
┌───────────────────────┐
|    Narwhals Series    |
|-----------------------|
|0    1.0               |
|1    2.0               |
|2    3.0               |
|Name: a, dtype: float64|
└───────────────────────┘

std

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`

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

sum() -> float

Reduce this Series to the sum value.

If there are no non-null elements, the result is zero.

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

tail(n: int = 10) -> Self

Get the last n rows.

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of rows to return.	`10`

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

to_arrow() -> pa.Array[Any]

Convert to arrow.

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

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`

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

to_frame() -> DataFrame[Any]

Convert to dataframe.

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

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.

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

to_numpy() -> _1DArray

Convert to numpy.

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

to_pandas() -> pd.Series[Any]

Convert to pandas 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

to_polars() -> pl.Series

Convert to polars 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

to_native() -> IntoSeriesT

Convert Narwhals series to native series.

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

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`

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

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 The original values as first column Either count or proportion as second column, depending on normalize parameter.	`False`

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

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

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

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
  ]
]

narwhals.Series

dtype property

implementation property

name property

shape property

__arrow_c_stream__

__getitem__

__iter__

abs

alias

all

any

arg_max

arg_min

arg_true

cast

clip

count

cum_count

cum_max

cum_min

cum_prod

cum_sum

diff

drop_nulls

ewm_mean

exp

fill_nan

fill_null

filter

from_iterable classmethod

from_numpy classmethod

gather_every

head

hist

is_between

is_close

is_duplicated

is_empty

is_finite

is_first_distinct

is_in

is_last_distinct

is_nan

is_null

is_sorted

is_unique

item

kurtosis

len

log

max

mean

median

min

mode

n_unique

null_count

pipe

quantile

rank

rename

replace_strict

rolling_mean

rolling_std

rolling_sum

rolling_var

round

sample

scatter

shift

sort

skew

sqrt

std

sum

tail

to_arrow

to_dummies

to_frame

`narwhals.Series`

dtype `property`

implementation `property`

name `property`

shape `property`

getitem

iter

from_iterable `classmethod`

from_numpy `classmethod`