Polars Series sort() Usage & Examples

In Polars, you can sort a Series using the sort() method, which arranges the values in ascending order by default. If you want to sort in descending order, you can pass descending=True. This method returns a new Series with the elements reordered based on their values. It is applied to a single Series and allows you to control the sorting direction as needed.

In this article, I will explain the sort() method in the Polars Series by using its syntax, parameters, and usage, and demonstrating how it returns a new Series with values reordered based on their magnitude. This method is applied to a single Series and lets you define the sorting order.

Key Points –

sort() arranges the elements of a Polars Series in ascending order by default.
Use descending=True to sort the Series in descending order.
The method supports sorting numerical, boolean, string, and datetime values.
The nulls_last parameter controls the placement of null values in the result.
Setting nulls_last=True places null values after all non-null values (default behavior).
Setting nulls_last=False places null values before all non-null values.
In string Series, sorting is done in lexicographical (dictionary) order.
The method returns a new Series; it does not modify the original Series.

Polars Series sort() Introduction

Let’s know the syntax of the sort() method.


# Syntax of series sort()
Series.sort(
*,
descending: bool = False,
nulls_last: bool = False,
multithreaded: bool = True,
in_place: bool = False,
) → Self

Parameters of the Series sort()

Following are the parameters of series sort() method.

descending (bool, default False) - If True, sorts the Series in descending order (largest to smallest). If False (default), sorts in ascending order.
nulls_last (bool, default False) - If True, places null values at the end of the sorted Series. If False (default), places null values at the beginning.
multithreaded (bool, default True) - If True, uses multiple threads for sorting (parallel processing). If False, performs sorting on a single thread.
in_place (bool, default False) - If True, sorts the Series in place, modifying the original Series. If False (default), returns a new sorted Series.

Return Value

This function returns a new Series (or modifies the original if in_place=True) with the sorted values.

Usage of Polars Series sort() Method

The sort() method in a Polars Series arranges the elements of the Series in a specific order, ascending by default or descending if specified. It returns a new Series where the values are reordered based on their magnitude or lexicographic order (for strings), without modifying the original Series.

First, let’s create a Polars Series.


import polars as pl

# Sample Series
ser = pl.Series("integers", [12, 20, 8, 17, 5, 10])
print("Original Series:\n", ser)

Yields below output.

To sort the integers in ascending order (the default behavior) in a Polars Series, simply use the sort() method without any parameters.


# Sorting integers in ascending order 
sorted_ser = ser.sort()
print("Sorted Series (Ascending):\n", sorted_ser)

In the above example, the ser Series is sorted from smallest to largest, which is the default behavior of sort().

Sorting Integers (Descending)

To sort the integers in descending order (from largest to smallest), you can pass the descending=True parameter in the sort() method in Polars.


# Sorting integers in descending order
sorted_ser = ser.sort(descending=True)
print("Sorted Series (Descending):\n", sorted_ser)

# Output:
# Sorted Series (Descending):
# shape: (6,)
# Series: 'integers' [i64]
# [
#	20
#	17
#	12
#	10
#	8
#	5
# ]

Sorting a Boolean Series

To sort a Boolean Series, you can use the same approach as with integers. In a Boolean Series, True is treated as greater than False, so by default, sorting will place False values first and True values last in ascending order.


import polars as pl

# Sample Boolean Series
bool_ser = pl.Series("bools", [True, False, True, None, False])

# Sorting Boolean Series in ascending order (default)
sorted_ser = bool_ser.sort()
print("\nSorted Boolean Series (Ascending):\n", sorted_ser)

# Output:
# Sorted Boolean Series (Ascending):
# shape: (5,)
# Series: 'bools' [bool]
# [
#	null
#	false
#	false
#	true
#	true
# ]

Sorting a Series with Strings

Sorting a Polars Series with strings follows a similar approach to sorting numerical or boolean values, but with lexicographical (alphabetical) order. In string sorting, the values are compared based on their order in the dictionary.

Sorting in Ascending Order (default behavior)

The default sorting is in ascending lexicographical order. Strings will be sorted alphabetically, and null values will appear last unless specified otherwise.


import polars as pl

# Sample String Series with words and null values
string_ser = pl.Series("tech", ["spark", "pyspark", "hyperion", None, "java", "c"])

# Sorting in ascending order (default behavior)
sorted_string = string_ser.sort()
print("Sorted String Series (Ascending):\n", sorted_string)

# Output:
# Sorted String Series (Ascending):
# shape: (6,)
# Series: 'tech' [str]
# [
#	null
#	"c"
#	"hyperion"
#	"java"
#	"pyspark"
#	"spark"
# ]

Sorting in Descending Order

If you want to sort the strings in reverse (descending) order, you can use the descending=True parameter. In descending order, strings will be sorted in reverse alphabetical order, and null will still appear at the end.


# Sorting in descending order
sorted_string = string_ser.sort(descending=True)
print("Sorted String Series (Descending):\n", sorted_string)

# Output:
# Sorted String Series (Descending):
# shape: (6,)
# Series: 'tech' [str]
# [
#	null
#	"spark"
#	"pyspark"
#	"java"
#	"hyperion"
#	"c"
# ]

Sorting with nulls_last (default is True)

By default, null values will be placed at the end of the sorted Series. However, you can explicitly use the nulls_last=True parameter for this behavior.


# Sorting with nulls_last (default is True)
sorted_string = string_ser.sort(nulls_last=True)
print("Sorted String Series (Nulls Last):\n", sorted_string)

# Output:
# Sorted String Series (Nulls Last):
# shape: (6,)
# Series: 'tech' [str]
# [
#	"c"
#	"hyperion"
#	"java"
#	"pyspark"
#	"spark"
#	null
# ]

Sorting with nulls_first

When sorting a Polars Series that contains null values, you can use the nulls_last parameter to control whether nulls appear at the beginning or at the end of the sorted Series.


# Sorting with nulls_first
sorted_string = string_ser.sort(nulls_last=False)
print("Sorted String Series (Nulls First):\n", sorted_string)

# Output:
# Sorted String Series (Nulls First):
# shape: (6,)
# Series: 'tech' [str]
# [
#	null
#	"c"
#	"hyperion"
#	"java"
#	"pyspark"
#	"spark"
# ]

Sorting Integers Descending with Nulls Last

To sort the integers in descending order and place any null values at the end, first include a null in the Series, then use the sort() method with both descending=True and nulls_last=True.


import polars as pl

# Sample Series with a null value
ser_with_null = pl.Series("integers", [12, 20, None, 8, 17, 5, 10])

# Sort in descending order with nulls last
sorted_ser = ser_with_null.sort(descending=True, nulls_last=True)
print("Sorted Series (Descending with Nulls Last):\n", sorted_ser)

# Output:
# Sorted Series (Descending with Nulls Last):
# shape: (7,)
# Series: 'integers' [i64]
# [
#	20
#	17
#	12
#	10
#	8
#	5
#	null
# ]

In the above example, this ensures that nulls do not interfere with the numeric sort order and are always at the end.

Conclusion

In conclusion, the sort() method in Polars Series is a powerful and flexible tool for ordering data. Whether you're working with numbers, booleans, or strings, you can easily sort values in ascending or descending order, handle nulls explicitly, and obtain a new, sorted Series without modifying the original.

Happy Learning!!

Reference

https://docs.pola.rs/api/python/stable/reference/series/api/polars.Series.slice.html