Built with Tutify.io

    AIStudyLabs

    Polars Series head() Method with Examples

    Polars Series head() Method with Examples

    In Polars, the head() function is used to retrieve the first n elements from a Series object. By default, it returns the first ten rows, but you can customize the number by specifying an integer as an argument. This method is particularly helpful when you want to inspect the beginning portion of a Series without needing to view the entire dataset, which is especially useful for large datasets.

    In this article, I will explain the head() method in Polars Series, covering its syntax, parameters, usage, and how to returns a new Polars Series containing the first n elements from the original Series.

    Key Points –

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

    Polars Series head() Introduction

    Let’s know the syntax of the series head() method.

    
# Syntax of series head()
Series.head(n: int = 10) → Series

    <a id="h-parameters-of-the-nbsp-polars-series-head"></a>

    Parameters of the Polars Series head()

    It allows only one parameter.

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

    Return Value

    This function returns a new Polars Series containing the first n elements.

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

    Usage of Polars Series head() Method

    The head() method in a Polars Series is used to return the first few elements of the Series. By default, it returns the first 10 values, but you can specify any number using the n parameter.

    Now, let’s create a Polars Series.

    
import polars as pl

# Sample Series
ser = pl.Series("values", [5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60])
print("Original Series:\n", ser)

    Yields below output.

    When you use the head() method on a Polars Series without providing any arguments, it will return the first 10 elements by default.

    
# Default behavior of head()
print("Default head():\n", ser.head())

    Here,

    <a id="h-using-series-head-to-get-the-first-3-elements"></a>

    Using Series head() to Get the First 3 Elements

    To retrieve the first 3 elements of a Polars Series using the head() method, you simply pass 3 as an argument to the method.

    
# Get first 3 elements using head()
print("First 3 elements:\n", ser.head(3))

# Get the first 3 elements
result = ser.head(3)
print("Last 3 elements:\n", result)

# Output:
# First 3 elements:
# shape: (3,)
# Series: 'values' [i64]
# [
#	5
#	10
#	15
#]

    Here,

    <a id="h-using-head-0-returns-an-empty-series"></a>

    Using head(0) Returns an Empty Series

    Using head(0) in Polars will return an empty Series. This is because the head() method retrieves the first n elements, and when n is set to 0, it essentially asks for zero elements, resulting in no data being returned.

    
print("head(0) result:\n", ser.head(0))

# Output:
# head(0) result:
# shape: (0,)
# Series: 'values' [i64]
# [
# ]

    Here,

    <a id="h-using-the-series-head-with-negative-numbers"></a>

    Using the Series head() with Negative Numbers

    If you pass a negative number to the head() method, it returns all elements except the last n, similar to slicing from the start up to -n. The head() method is designed to retrieve the first n elements of a Series, and it behaves the same way regardless of whether the Series contains positive or negative values. The method doesn't interpret the sign of the values; it simply returns the top n elements based on their position in the Series.

    
import polars as pl

# Sample Series with negative numbers
ser = pl.Series("values", [-5, -10, -15, -20, -25, -30, -35, -40, -45, -50, -55, -60])

# Get first 3 elements using head()
print("First 3 elements with negative numbers:\n", ser.head(3))

# Output:
# First 3 elements with negative numbers:
# shape: (3,)
# Series: 'values' [i64]
# [
#	-5
#	-10
#	-15
# ]

    Here,

    <a id="h-using-head-on-a-string-series"></a>

    Using head() on a String Series

    When using head() on a String Series in Polars, the method behaves the same as it does with numeric Series. It allows you to retrieve the first n elements from the Series, where n specifies how many of the top elements you want to return. If you don't specify n, it defaults to 10.

    
import polars as pl

# Create a Series with string values
ser = pl.Series("fruits", ["apple", "banana", "cherry", "date", "elderberry", "fig", "grape"])

# Get the first 4 strings using head()
print("First 4 fruits:\n", ser.head(4))

# Output:
# First 4 fruits:
# shape: (4,)
# Series: 'fruits' [str]
# [
#	"apple"
#	"banana"
#	"cherry"
#	"date"
# ]

    Here,

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

    Conclusion

    In conclusion, the head() method in Polars is a straightforward but effective function for quickly viewing the first few elements of a Series. It lets you retrieve the top n values, with the default being the first 10 elements. Whether the Series contains positive, negative, or zero values, the method consistently returns the first n elements in the order they appear in the Series.

    Happy Learning!!

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

    Related Articles

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

    Reference