`narwhals.Series`

Narwhals Series, backed by a native series.

The native dataframe might be pandas.Series, polars.Series, ...

This class is not meant to be instantiated directly - instead, use narwhals.from_native, making sure to pass allow_series=True or series_only=True.

`dtype: Any` `property`

Get the data type of the Series.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 3]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.dtype

We can then pass either pandas or Polars to func:

>>> func(s_pd)
Int64
>>> func(s_pl)
Int64

`name: str` `property`

Get the name of the Series.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 3]
>>> s_pd = pd.Series(s, name="foo")
>>> s_pl = pl.Series("foo", s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.name

We can then pass either pandas or Polars to func:

>>> func(s_pd)
'foo'
>>> func(s_pl)
'foo'

`shape: tuple[int]` `property`

Get the shape of the Series.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 3]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.shape

We can then pass either pandas or Polars to func:

>>> func(s_pd)
(3,)
>>> func(s_pl)
(3,)

`alias(name)`

Rename the Series.

Parameters:

Name	Type	Description	Default
`name`	`str`	The new name.	required

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 3]
>>> s_pd = pd.Series(s, name="foo")
>>> s_pl = pl.Series("foo", s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.alias("bar")

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    1
1    2
2    3
Name: bar, dtype: int64
>>> func(s_pl)
shape: (3,)
Series: 'bar' [i64]
[
   1
   2
   3
]

`all()`

Return whether all values in the Series are True.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [True, False, True]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.all()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
False
>>> func(s_pl)
False

`any()`

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

Notes

Only works on Series of data type Boolean.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [False, True, False]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.any()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
True
>>> func(s_pl)
True

`cast(dtype)`

Cast between data types.

Parameters:

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

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [True, False, True]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.cast(nw.Int64)

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    1
1    0
2    1
dtype: int64
>>> func(s_pl)
shape: (3,)
Series: '' [i64]
[
   1
   0
   1
]

`cum_sum()`

Calculate the cumulative sum.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [2, 4, 3]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.cum_sum()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    2
1    6
2    9
dtype: int64
>>> func(s_pl)
shape: (3,)
Series: '' [i64]
[
   2
   6
   9
]

`diff()`

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_any.diff().fill_null(0).cast(nw.Int64)

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [2, 4, 3]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.diff()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    NaN
1    2.0
2   -1.0
dtype: float64
>>> func(s_pl)
shape: (3,)
Series: '' [i64]
[
   null
   2
   -1
]

`drop_nulls()`

Drop all null values.

`fill_null(value)`

Fill null values using the specified value.

Parameters:

Name	Type	Description	Default
`value`	`Any`	Value used to fill null values.	required

Notes

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

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, None]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.fill_null(5)

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    1.0
1    2.0
2    5.0
dtype: float64
>>> func(s_pl)
shape: (3,)
Series: '' [i64]
[
   1
   2
   5
]

`filter(other)`

Filter elements in the Series based on a condition.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [4, 10, 15, 34, 50]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.filter(s_any > 10)

We can then pass either pandas or Polars to func:

>>> func(s_pd)
2    15
3    34
4    50
dtype: int64
>>> func(s_pl)
shape: (3,)
Series: '' [i64]
[
   15
   34
   50
]

`head(n=10)`

Get the first n rows.

Arguments n : int Number of rows to return.

Examples:

>>> import narwhals as nw
>>> import pandas as pd
>>> import polars as pl
>>> data = list(range(10))
>>> s_pd = pd.Series(data)
>>> s_pl = pl.Series(data)

Let's define a dataframe-agnostic function that returns the first 3 rows:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.head(3)

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    0
1    1
2    2
dtype: int64

>>> func(s_pl)
shape: (3,)
Series: '' [i64]
[
   0
   1
   2
]

`is_between(lower_bound, upper_bound, closed='both')`

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

Parameters:

Name	Type	Description	Default
`lower_bound`	`Any`	Lower bound value.	required
`upper_bound`	`Any`	Upper bound value.	required
`closed`	`str`	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 pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s_pd = pd.Series([1, 2, 3, 4, 5])
>>> s_pl = pl.Series([1, 2, 3, 4, 5])

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.is_between(2, 4, "right")

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    False
1    False
2     True
3     True
4    False
dtype: bool
>>> func(s_pl)
shape: (5,)
Series: '' [bool]
[
   false
   false
   true
   true
   false
]

`is_duplicated()`

Get a mask of all duplicated rows in the Series.

Examples:

>>> import narwhals as nw
>>> import pandas as pd
>>> import polars as pl
>>> s_pd = pd.Series([1, 2, 3, 1])
>>> s_pl = pl.Series([1, 2, 3, 1])

Let's define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.is_duplicated()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0     True
1    False
2    False
3     True
dtype: bool
>>> func(s_pl)
shape: (4,)
Series: '' [bool]
[
    true
    false
    false
    true
]

`is_empty()`

Check if the series is empty.

Examples:

>>> import narwhals as nw
>>> import pandas as pd
>>> import polars as pl

Let's define a dataframe-agnostic function that filters rows in which "foo" values are greater than 10, and then checks if the result is empty or not:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.filter(s_any > 10).is_empty()

We can then pass either pandas or Polars to func:

>>> s_pd = pd.Series([1, 2, 3])
>>> s_pl = pl.Series([1, 2, 3])
>>> func(s_pd), func(s_pl)
(True, True)

>>> s_pd = pd.Series([100, 2, 3])
>>> s_pl = pl.Series([100, 2, 3])
>>> func(s_pd), func(s_pl)
(False, False)

`is_first_distinct()`

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

Examples:

>>> import narwhals as nw
>>> import pandas as pd
>>> import polars as pl
>>> s_pd = pd.Series([1, 1, 2, 3, 2])
>>> s_pl = pl.Series([1, 1, 2, 3, 2])

Let's define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.is_first_distinct()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0     True
1    False
2     True
3     True
4    False
dtype: bool

>>> func(s_pl)
shape: (5,)
Series: '' [bool]
[
    true
    false
    true
    true
    false
]

`is_in(other)`

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 pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s_pd = pd.Series([1, 2, 3])
>>> s_pl = pl.Series([1, 2, 3])

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.is_in([3, 2, 8])

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    False
1     True
2     True
dtype: bool
>>> func(s_pl)
shape: (3,)
Series: '' [bool]
[
   false
   true
   true
]

`is_last_distinct()`

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

Examples:

>>> import narwhals as nw
>>> import pandas as pd
>>> import polars as pl
>>> s_pd = pd.Series([1, 1, 2, 3, 2])
>>> s_pl = pl.Series([1, 1, 2, 3, 2])

Let's define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.is_last_distinct()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    False
1     True
2    False
3     True
4     True
dtype: bool

>>> func(s_pl)
shape: (5,)
Series: '' [bool]
[
    false
    true
    false
    true
    true
]

`is_null()`

Returns a boolean Series indicating which values are null.

Notes

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

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, None]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.is_null()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    False
1    False
2     True
dtype: bool
>>> func(s_pl)
shape: (3,)
Series: '' [bool]
[
   false
   false
   true
]

`is_sorted(*, descending=False)`

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 narwhals as nw
>>> import pandas as pd
>>> import polars as pl
>>> unsorted_data = [1, 3, 2]
>>> sorted_data = [3, 2, 1]

Let's define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any, descending=False):
...     return s_any.is_sorted(descending=descending)

We can then pass either pandas or Polars to func:

>>> func(pl.Series(unsorted_data))
False
>>> func(pl.Series(sorted_data), descending=True)
True
>>> func(pd.Series(unsorted_data))
False
>>> func(pd.Series(sorted_data), descending=True)
True

`is_unique()`

Get a mask of all unique rows in the Series.

Examples:

>>> import narwhals as nw
>>> import pandas as pd
>>> import polars as pl
>>> s_pd = pd.Series([1, 2, 3, 1])
>>> s_pl = pl.Series([1, 2, 3, 1])

Let's define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.is_unique()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    False
1     True
2     True
3    False
dtype: bool

>>> func(s_pl)
shape: (4,)
Series: '' [bool]
[
    false
     true
     true
    false
]

`item(index=None)`

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 narwhals as nw
>>> import pandas as pd
>>> import polars as pl

Let's define a dataframe-agnostic function that returns item at given index

>>> @nw.narwhalify
... def func(s_any, index=None):
...     return s_any.item(index)

We can then pass either pandas or Polars to func:

>>> func(pl.Series("a", [1]), None), func(pd.Series([1]), None)
(1, 1)

>>> func(pl.Series("a", [9, 8, 7]), -1), func(pl.Series([9, 8, 7]), -2)
(7, 8)

`len()`

Return the number of elements in the Series.

Null values count towards the total.

Examples:

>>> import narwhals as nw
>>> import pandas as pd
>>> import polars as pl
>>> data = [1, 2, None]
>>> s_pd = pd.Series(data)
>>> s_pl = pl.Series(data)

Let's define a dataframe-agnostic function that computes the len of the series:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.len()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
3
>>> func(s_pl)
3

`max()`

Get the maximum value in this Series.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 3]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.max()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
3
>>> func(s_pl)
3

`mean()`

Reduce this Series to the mean value.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 3]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.mean()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
2.0
>>> func(s_pl)
2.0

`min()`

Get the minimal value in this Series.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 3]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.min()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
1
>>> func(s_pl)
1

`null_count()`

Create a new Series that shows the null counts per column.

Notes

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

Examples:

>>> import narwhals as nw
>>> import pandas as pd
>>> import polars as pl
>>> s_pd = pd.Series([1, None, 3])
>>> s_pl = pl.Series([1, None, None])

Let's define a dataframe-agnostic function that returns the null count of the series:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.null_count()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
1
>>> func(s_pl)
2

`n_unique()`

Count the number of unique values.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 2, 3]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.n_unique()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
3
>>> func(s_pl)
3

`quantile(quantile, interpolation)`

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`		{'nearest', 'higher', 'lower', 'midpoint', 'linear'} Interpolation method.	required

Examples:

>>> import narwhals as nw
>>> import pandas as pd
>>> import polars as pl
>>> data = list(range(50))
>>> s_pd = pd.Series(data)
>>> s_pl = pl.Series(data)

Let's define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return [
...         s_any.quantile(quantile=q, interpolation="nearest")
...         for q in (0.1, 0.25, 0.5, 0.75, 0.9)
...     ]

We can then pass either pandas or Polars to func:

>>> func(s_pd)
[5, 12, 24, 37, 44]

>>> func(s_pl)
[5.0, 12.0, 25.0, 37.0, 44.0]

`round(decimals=0)`

Round underlying floating point data by decimals digits.

Arguments decimals: Number of decimals to round by.

Notes

For values exactly halfway between rounded decimal values pandas and Polars behave differently.

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 rounds 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 narwhals as nw
>>> import pandas as pd
>>> import polars as pl
>>> data = [1.12345, 2.56789, 3.901234]
>>> s_pd = pd.Series(data)
>>> s_pl = pl.Series(data)

Let's define a dataframe-agnostic function that rounds to the first decimal:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.round(1)

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    1.1
1    2.6
2    3.9
dtype: float64

>>> func(s_pl)
shape: (3,)
Series: '' [f64]
[
   1.1
   2.6
   3.9
]

`sample(n=None, fraction=None, *, with_replacement=False)`

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`

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 narwhals as nw
>>> import pandas as pd
>>> import polars as pl

>>> s_pd = pd.Series([1, 2, 3, 4])
>>> s_pl = pl.Series([1, 2, 3, 4])

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.sample(fraction=1.0, with_replacement=True)

We can then pass either pandas or Polars to func:

>>> func(s_pd)
   a
2  3
1  2
3  4
3  4
>>> func(s_pl)
shape: (4,)
Series: '' [i64]
[
   1
   4
   3
   4
]

`shift(n)`

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_any.shift(1).fill_null(0).cast(nw.Int64)

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [2, 4, 3]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.shift(1)

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    NaN
1    2.0
2    4.0
dtype: float64
>>> func(s_pl)
shape: (3,)
Series: '' [i64]
[
   null
   2
   4
]

`sort(*, descending=False)`

Sort this Series. Place null values first.

Parameters:

Name	Type	Description	Default
`descending`	`bool`	Sort in descending order.	`False`

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [5, None, 1, 2]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define library agnostic functions:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.sort()

>>> @nw.narwhalify
... def func_descend(s_any):
...     return s_any.sort(descending=True)

We can then pass either pandas or Polars to func:

>>> func(s_pd)
1    NaN
2    1.0
3    2.0
0    5.0
dtype: float64
>>> func(s_pl)
shape: (4,)
Series: '' [i64]
[
   null
   1
   2
   5
]
>>> func_descend(s_pd)
1    NaN
0    5.0
3    2.0
2    1.0
dtype: float64
>>> func_descend(s_pl)
shape: (4,)
Series: '' [i64]
[
   null
   5
   2
   1
]

`std(*, ddof=1)`

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 pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 3]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.std()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
1.0
>>> func(s_pl)
1.0

`sum()`

Reduce this Series to the sum value.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 3]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.sum()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
6
>>> func(s_pl)
6

`tail(n=10)`

Get the last n rows.

Arguments n : int Number of rows to return.

Examples:

>>> import narwhals as nw
>>> import pandas as pd
>>> import polars as pl
>>> data = list(range(10))
>>> s_pd = pd.Series(data)
>>> s_pl = pl.Series(data)

Let's define a dataframe-agnostic function that returns the last 3 rows:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.tail(3)

We can then pass either pandas or Polars to func:

>>> func(s_pd)
7    7
8    8
9    9
dtype: int64
>>> func(s_pl)
shape: (3,)
Series: '' [i64]
[
   7
   8
   9
]

`to_frame()`

Convert to dataframe.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 3]
>>> s_pd = pd.Series(s, name="a")
>>> s_pl = pl.Series("a", s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.to_frame()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
   a
0  1
1  2
2  3
>>> func(s_pl)
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
└─────┘

`to_list()`

Convert to list.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 3]
>>> s_pd = pd.Series(s, name="a")
>>> s_pl = pl.Series("a", s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.to_list()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
[1, 2, 3]
>>> func(s_pl)
[1, 2, 3]

`to_numpy()`

Convert to numpy.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 3]
>>> s_pd = pd.Series(s, name="a")
>>> s_pl = pl.Series("a", s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.to_numpy()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
array([1, 2, 3]...)
>>> func(s_pl)
array([1, 2, 3]...)

`to_pandas()`

Convert to pandas.

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [1, 2, 3]
>>> s_pd = pd.Series(s, name="a")
>>> s_pl = pl.Series("a", s)

We define a library agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.to_pandas()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    1
1    2
2    3
Name: a, dtype: int64
>>> func(s_pl)
0    1
1    2
2    3
Name: a, dtype: int64

`unique()`

Returns unique values

Examples:

>>> import pandas as pd
>>> import polars as pl
>>> import narwhals as nw
>>> s = [2, 4, 4, 6]
>>> s_pd = pd.Series(s)
>>> s_pl = pl.Series(s)

Let's define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.unique()

We can then pass either pandas or Polars to func:

>>> func(s_pd)
0    2
1    4
2    6
dtype: int64
>>> func(s_pl)
shape: (3,)
Series: '' [i64]
[
   2
   4
   6
]

`value_counts(*, sort=False, parallel=False)`

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. Unused for pandas-like APIs.	`False`

Examples:

>>> import narwhals as nw
>>> import pandas as pd
>>> import polars as pl
>>> s_pd = pd.Series([1, 1, 2, 3, 2], name="s")
>>> s_pl = pl.Series(values=[1, 1, 2, 3, 2], name="s")

Let's define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s_any):
...     return s_any.value_counts(sort=True)

We can then pass either pandas or Polars to func:

>>> func(s_pd)
   s  count
0  1      2
1  2      2
2  3      1

>>> func(s_pl)
shape: (3, 2)
┌─────┬───────┐
│ s   ┆ count │
│ --- ┆ ---   │
│ i64 ┆ u32   │
╞═════╪═══════╡
│ 1   ┆ 2     │
│ 2   ┆ 2     │
│ 3   ┆ 1     │
└─────┴───────┘

`zip_with(mask, other)`

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.

Examples:

>>> import narwhals as nw
>>> import pandas as pd
>>> import polars as pl
>>> s1_pl = pl.Series([1, 2, 3, 4, 5])
>>> s2_pl = pl.Series([5, 4, 3, 2, 1])
>>> mask_pl = pl.Series([True, False, True, False, True])
>>> s1_pd = pd.Series([1, 2, 3, 4, 5])
>>> s2_pd = pd.Series([5, 4, 3, 2, 1])
>>> mask_pd = pd.Series([True, False, True, False, True])

Let's define a dataframe-agnostic function:

>>> @nw.narwhalify
... def func(s1_any, mask_any, s2_any):
...     return s1_any.zip_with(mask_any, s2_any)

We can then pass either pandas or Polars to func:

>>> func(s1_pl, mask_pl, s2_pl)
shape: (5,)
Series: '' [i64]
[
   1
   4
   3
   2
   5
]
>>> func(s1_pd, mask_pd, s2_pd)
0    1
1    4
2    3
3    2
4    5
dtype: int64

narwhals.Series

dtype: Any property

name: str property

shape: tuple[int] property

alias(name)

all()

any()

cast(dtype)

cum_sum()

diff()

drop_nulls()

fill_null(value)

filter(other)

head(n=10)

is_between(lower_bound, upper_bound, closed='both')

is_duplicated()

is_empty()

is_first_distinct()

is_in(other)

is_last_distinct()

is_null()

is_sorted(*, descending=False)

is_unique()

item(index=None)

len()

max()

mean()

min()

null_count()

n_unique()

quantile(quantile, interpolation)

round(decimals=0)

sample(n=None, fraction=None, *, with_replacement=False)

shift(n)

sort(*, descending=False)

std(*, ddof=1)

sum()

tail(n=10)

to_frame()

to_list()

to_numpy()

to_pandas()

unique()

value_counts(*, sort=False, parallel=False)

zip_with(mask, other)

`narwhals.Series`

`dtype: Any` `property`

`name: str` `property`

`shape: tuple[int]` `property`

`alias(name)`

`all()`

`any()`

`cast(dtype)`

`cum_sum()`

`diff()`

`drop_nulls()`

`fill_null(value)`

`filter(other)`

`head(n=10)`

`is_between(lower_bound, upper_bound, closed='both')`

`is_duplicated()`

`is_empty()`

`is_first_distinct()`

`is_in(other)`

`is_last_distinct()`

`is_null()`

`is_sorted(*, descending=False)`

`is_unique()`

`item(index=None)`

`len()`

`max()`

`mean()`

`min()`

`null_count()`

`n_unique()`

`quantile(quantile, interpolation)`

`round(decimals=0)`

`sample(n=None, fraction=None, *, with_replacement=False)`

`shift(n)`

`sort(*, descending=False)`

`std(*, ddof=1)`

`sum()`

`tail(n=10)`

`to_frame()`

`to_list()`

`to_numpy()`

`to_pandas()`

`unique()`

`value_counts(*, sort=False, parallel=False)`

`zip_with(mask, other)`