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.

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.

<a id="h-polars-dataframe-sum-horizontal-introduction"></a>

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

<a id="h-parameters-of-the-polars-dataframe-sum-horizontal"></a>

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.

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

Return Value

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

<a id="h-usage-of-polars-dataframe-sum-horizontal-method"></a>

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.

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.

<a id="h-sum-more-than-two-columns"></a>

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           │
└─────────────┴─────────┴─────────┴───────────────┘

<a id="h-add-row-wise-sum-based-on-a-condition"></a>

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            │
└─────────────┴─────────┴─────────┴────────────────┘

<a id="h-use-sum-horizontal-inside-an-expression-pipeline"></a>

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   │
└─────────────┴─────────┴─────────┴───────┘

<a id="h-include-null-values-default-behavior"></a>

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   │
└─────────────┴─────────┴─────────┴───────┘

<a id="h-handle-nulls-with-fill-null-first"></a>

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   │
└─────────────┴─────────┴─────────┴───────┘

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

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!!

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

Related Articles

• Polars DataFrame slice() – Usage & Examples
• Polars DataFrame width Usage & Examples
• Polars DataFrame height – Explained by Examples
• Polars DataFrame clone() – Explained by Examples
• Polars DataFrame clear() Usage & Examples
• Polars DataFrame row() Usage & Examples
• Polars DataFrame shift() Usage & Examples
• Polars DataFrame product() Usage with Examples
• Polars DataFrame fill_nan() Usage & Examples
• Polars DataFrame replace_column() – by Examples

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

References

• https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.var.html