Polars Series Shape Usage & Examples

In Polars, Series.shape represents the dimensions of the Series as a tuple. Since a Polars Series is one-dimensional, Series.shape returns a tuple with a single element indicating the number of items in that Series.

In this article, I will explain the Polars Series shape attribute by covering its syntax, parameters, and usage, and show how it returns a tuple containing a single integer that represents the number of elements in the Series.

Key Points –

• Series.shape returns a tuple indicating the number of elements in the Series.
• It always returns a one-element tuple because a Series is one-dimensional.
• The single value in the tuple indicates the number of elements in the Series.
• The shape is useful for quickly checking the length of a Series.
• It does not give information about the number of columns, as Series is 1-dimensional.
• shape is a property, not a method, so no parentheses are needed when accessing it.
• The shape remains consistent even if the Series has null or missing values.
• Knowing the shape is useful for validation, debugging, and data analysis workflows.

<a id="h-polars-series-shape-introduction"></a>

Polars Series Shape Introduction

Let’s know the syntax of the series shape

# Syntax of series shape
property Series.shape: tuple[int]

<a id="h-parameters-of-the-series-shape"></a>

Parameters of the Series shape

Following are the parameters of the series shape

• The tuple contains a single integer, e.g., (10,) means the Series has 10 elements.

<a id="h-return-value"></a>

Return Value

This function returns a tuple of one integer representing the number of elements in the Series.

<a id="h-usage-of-polars-series-shape"></a>

Usage of Polars Series Shape

It returns a tuple containing the number of elements in the Series. Since a Series is 1-dimensional, it’s a tuple with one integer, e.g., (5,).

First, let’s create a Polars Series.

import polars as pl

# Sample Series
ser = pl.Series("numbers", [10, 20, 30, 40])
print("Original Series:\n", ser)

Yields below output.

The shape attribute provides the dimensions of a Series. Because a Series is one-dimensional, shape returns a tuple containing a single value, the number of elements in the Series.

# Get and print the shape of the Series
print("Shape of Series:", ser.shape)

Here,

• series.shape returns a tuple with one integer.
• This integer is the number of elements in the Series.
• The shape (4,) means the Series contains 4 elements.

<a id="h-empty-series-shape"></a>

Empty Series Shape

Using Polars Series.shape with an empty Series returns the dimensions of the Series, which has no elements. An empty Series contains zero elements and is commonly used as a placeholder or a starting point before populating it with data.

import polars as pl

# Create an empty Series
empty_series = pl.Series("empty", [])

# Print the empty Series
print("Empty Series:\n", empty_series)

print("Shape:", empty_series.shape)

# Output:
# Empty Series:
# shape: (0,)
# Series: 'empty' [null]
# [
# ]
Shape: (0,)

Here,

• The Series has no elements.
• shape returns (0,), a tuple showing zero length.

<a id="h-series-with-strings"></a>

Series with Strings

Using Polars Series.shape with a Series of strings shows the size of the Series. Polars Series can store various data types, including strings. Here’s how to create a string-based Series and check its shape.

import polars as pl

# Create a Series of strings
ser = pl.Series("Courses", ["spark", "pandas", "bigdata", "Hyperion"])
print("Shape of Series:", ser.shape)

# Output:
# Shape of Series: (4,)

Here,

• The Series contains 4 string elements.
• shape returns (4,) showing the Series length.

<a id="h-series-with-nulls"></a>

Series with Nulls

Polars Series.shape counts the total number of elements in a Series, including any null (missing) values. Polars Series can hold nulls, which are useful for representing incomplete or missing data.

import polars as pl

# Create a Series with some null values
series_with_nulls = pl.Series("data", [2, None, 4, None, 6])

# Print the Series
print("Series with nulls:\n", series_with_nulls)
print("Shape:", series_with_nulls.shape)

# Output:
# Series with nulls:
# shape: (5,)
# Series: 'data' [i64]
# [
#	2
#	null
#	4
#	null
#	6
# ]
# Shape: (5,)

Here,

• The Series has 5 elements total, including nulls.
• shape counts all elements, nulls included, so it returns (5,).

<a id="h-conclusion"></a>

Conclusion

In conclusion, the shape attribute in a Polars Series offers a straightforward and reliable way to determine the size of the Series by returning a tuple that reflects the number of elements it includes. Regardless of whether the Series holds strings, numbers, or null values, shape consistently provides a tuple representing its length.

Happy Learning!!

<a id="h-related-articles"></a>

Related Articles

• Polars Series sum() Method with Examples
• Polars Series Unique Values
• Polars Replace String in Multiple Columns
• Polars Series sort() Usage & Examples
• Polars Series describe() – Usage & Examples
• Polars Series shift() Function with Examples
• Polars Series min() – Explained by Examples
• Polars Series clear() – Explained by Examples
• Polars Series sample() Function with Examples
• Polars Series list.join() Function with Examples
• Polars Series explode() – Explained by Examples
• Polars Series struct.schema() – Explained by Examples

<a id="h-reference"></a>

Reference

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