Polars DataFrame sum_horizontal() Method with Examples

  • Post author:
  • Post category:Polars
  • Post last modified:April 9, 2025
  • Reading time:10 mins read
You are currently viewing Polars DataFrame sum_horizontal() Method with Examples

In Polars, the sum_horizontal() function is used to sum values across columns (i.e., horizontally across a row), rather than down a column (which would be a vertical sum like sum()). In this article, I will explain the Polars DataFrame sum_horizontal() method, covering its syntax, parameters, and practical usage. This function returns a Polars Series representing the row-wise sum across specified columns or expressions.

Advertisements

Key Points –

  • Performs row-wise summation across columns (horizontal direction).
  • Available as both a DataFrame method and as part of the expression API.
  • Returns a Series where each value is the sum of that row’s values.
  • By default, it ignores null values (ignore_nulls=True).
  • If ignore_nulls=False, any null in a row causes the result to be null for that row.
  • Does not modify the original DataFrame unless used inside a transformation.
  • Requires explicit null handling using methods like fill_null() to avoid null results in row-wise sums.
  • Can be used in expression pipelines like with_columns() to add new computed columns.

Polars DataFrame sum_horizontal() Introduction

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


# Syntax of sum_horizontal()
DataFrame.sum_horizontal(*, ignore_nulls: bool = True) → Series

Parameters of the Polars DataFrame sum_horizontal()

It allows only one parameter.

  • ignore_nulls (optional, default = True)
    • True: Ignores null values while summing.
    • False: Returns null if any value in the row is null.

Return Value

This function returns a Polars Series containing the row-wise sum across the DataFrame (or selected expressions).

Usage of Polars DataFrame sum_horizontal() Method

The sum_horizontal() function computes the row-wise sum across multiple columns. Unlike the regular sum() which operates column-wise (i.e., down each column), sum_horizontal() adds values across columns for each individual row.

To run some examples of the Polars DataFrame sum_horizontal() function, let’s create a Polars DataFrame.


import polars as pl

studentdetails = {
       "Mathematics" :[80,90,85,72,95],
       "Science" :[85,95,80,90,92],
       "English" :[90,85,80,75,95]
              }
df = pl.DataFrame(studentdetails)
print("Original DataFrame:\n", df)

Yields below output.

polars sum horizontal

To calculate a basic row-wise sum in Polars and add it as a new column (e.g., Total), you can use the with_columns() method along with pl.sum_horizontal() function.


# Add row-wise sum as a new column
df2 = df.with_columns(
    pl.sum_horizontal(["Mathematics", "Science", "English"]).alias("Total")
)
print("DataFrame with Row-wise Sum:\n", df2)

Yields below output.

polars sum horizontal

Sum More Than Two Columns

To compute the row-wise sum of more than two columns in Polars, you can continue using pl.sum_horizontal() and simply list all the columns you want to sum.


# Row-wise sum of Science and English
df2 = df.with_columns(
    pl.sum_horizontal(["Science", "English"]).alias("Sci_Eng_Total")
)
print("DataFrame with Partial Row-wise Sum:\n", df2)

# Output:
# DataFrame with Partial Row-wise Sum:
# shape: (5, 4)
┌─────────────┬─────────┬─────────┬───────────────┐
│ Mathematics ┆ Science ┆ English ┆ Sci_Eng_Total │
│ ---         ┆ ---     ┆ ---     ┆ ---           │
│ i64         ┆ i64     ┆ i64     ┆ i64           │
╞═════════════╪═════════╪═════════╪═══════════════╡
│ 80          ┆ 85      ┆ 90      ┆ 175           │
│ 90          ┆ 95      ┆ 85      ┆ 180           │
│ 85          ┆ 80      ┆ 80      ┆ 160           │
│ 72          ┆ 90      ┆ 75      ┆ 165           │
│ 95          ┆ 92      ┆ 95      ┆ 187           │
└─────────────┴─────────┴─────────┴───────────────┘

Add Row-wise Sum Based on a Condition

To perform a conditional row-wise sum in Polars, apply conditional logic to each column using pl.when().then().otherwise(), and then use pl.sum_horizontal() to compute the sum across those transformed values.


# Conditional row-wise sum: include only scores >= 85
df = df.with_columns(
    pl.sum_horizontal([
        pl.when(pl.col("Mathematics") >= 85).then(pl.col("Mathematics")).otherwise(0),
        pl.when(pl.col("Science") >= 85).then(pl.col("Science")).otherwise(0),
        pl.when(pl.col("English") >= 85).then(pl.col("English")).otherwise(0),
    ]).alias("HighScoreTotal"))
print("DataFrame with Conditional Row-wise Sum:\n", df)

# Output:
# DataFrame with Conditional Row-wise Sum:
# shape: (5, 4)
┌─────────────┬─────────┬─────────┬────────────────┐
│ Mathematics ┆ Science ┆ English ┆ HighScoreTotal │
│ ---         ┆ ---     ┆ ---     ┆ ---            │
│ i64         ┆ i64     ┆ i64     ┆ i64            │
╞═════════════╪═════════╪═════════╪════════════════╡
│ 80          ┆ 85      ┆ 90      ┆ 175            │
│ 90          ┆ 95      ┆ 85      ┆ 270            │
│ 85          ┆ 80      ┆ 80      ┆ 85             │
│ 72          ┆ 90      ┆ 75      ┆ 90             │
│ 95          ┆ 92      ┆ 95      ┆ 282            │
└─────────────┴─────────┴─────────┴────────────────┘

Use sum_horizontal Inside an Expression Pipeline

Using sum_horizontal() inside an expression pipeline is clean and powerful, especially when you’re chaining transformations.


# Expression pipeline to calculate row-wise total
df2 = (
    pl.DataFrame(studentdetails)
    .with_columns(
        pl.sum_horizontal(["Mathematics", "Science", "English"]).alias("Total")
    )
)
print("DataFrame using Expression Pipeline:\n", df2)

# Output:
# DataFrame using Expression Pipeline:
# shape: (5, 4)
┌─────────────┬─────────┬─────────┬───────┐
│ Mathematics ┆ Science ┆ English ┆ Total │
│ ---         ┆ ---     ┆ ---     ┆ ---   │
│ i64         ┆ i64     ┆ i64     ┆ i64   │
╞═════════════╪═════════╪═════════╪═══════╡
│ 80          ┆ 85      ┆ 90      ┆ 255   │
│ 90          ┆ 95      ┆ 85      ┆ 270   │
│ 85          ┆ 80      ┆ 80      ┆ 245   │
│ 72          ┆ 90      ┆ 75      ┆ 237   │
│ 95          ┆ 92      ┆ 95      ┆ 282   │
└─────────────┴─────────┴─────────┴───────┘

Include null Values (Default Behavior)

By default, when you include null (missing) values in pl.sum_horizontal(), Polars will return null for that row, rather than skipping or treating null as zero.


import polars as pl

studentdetails = {
    "Mathematics": [80, None, 85, 72, 95],
    "Science": [85, 95, None, 90, 92],
    "English": [90, 85, 80, None, 95]
}

df = pl.DataFrame(studentdetails)

# Default behavior: include nulls in sum_horizontal
df2 = df.with_columns(
    pl.sum_horizontal(["Mathematics", "Science", "English"]).alias("Total")
)
print("DataFrame with Row-wise Sum (default null handling):\n", df2)

# Output:
# DataFrame with Row-wise Sum (default null handling):
# shape: (5, 4)
┌─────────────┬─────────┬─────────┬───────┐
│ Mathematics ┆ Science ┆ English ┆ Total │
│ ---         ┆ ---     ┆ ---     ┆ ---   │
│ i64         ┆ i64     ┆ i64     ┆ i64   │
╞═════════════╪═════════╪═════════╪═══════╡
│ 80          ┆ 85      ┆ 90      ┆ 255   │
│ null        ┆ 95      ┆ 85      ┆ 180   │
│ 85          ┆ null    ┆ 80      ┆ 165   │
│ 72          ┆ 90      ┆ null    ┆ 162   │
│ 95          ┆ 92      ┆ 95      ┆ 282   │
└─────────────┴─────────┴─────────┴───────┘

Handle Nulls with fill_null() First

To include rows with null values in your row-wise sum and treat those nulls as zeros, you can first replace them using fill_null(0) before applying pl.sum_horizontal().


# Fill nulls with 0, then compute row-wise sum
df2 = df.with_columns(
    pl.sum_horizontal([
        pl.col("Mathematics").fill_null(0),
        pl.col("Science").fill_null(0),
        pl.col("English").fill_null(0)
    ]).alias("Total"))
print("DataFrame with Nulls Treated as Zeros:\n", df2)

# Output:
# DataFrame with Nulls Treated as Zeros:
# shape: (5, 4)
┌─────────────┬─────────┬─────────┬───────┐
│ Mathematics ┆ Science ┆ English ┆ Total │
│ ---         ┆ ---     ┆ ---     ┆ ---   │
│ i64         ┆ i64     ┆ i64     ┆ i64   │
╞═════════════╪═════════╪═════════╪═══════╡
│ 80          ┆ 85      ┆ 90      ┆ 255   │
│ null        ┆ 95      ┆ 85      ┆ 180   │
│ 85          ┆ null    ┆ 80      ┆ 165   │
│ 72          ┆ 90      ┆ null    ┆ 162   │
│ 95          ┆ 92      ┆ 95      ┆ 282   │
└─────────────┴─────────┴─────────┴───────┘

Conclusion

In summary, sum_horizontal() in Polars is a versatile and efficient method for performing row-wise summation across multiple columns. It’s especially useful when dealing with nulls, applying conditional logic, or integrating within an expression pipeline.

Happy Learning!!

References

Tags: