docs(python): suggest forward fill in cumsum/cummax (#6061)

pola-rs · Jan 5, 2023 · 5bf8e31 · 5bf8e31
1 parent 09ed10a
commit 5bf8e31
Showing 1 changed file with 54 additions and 0 deletions.
diff --git a/py-polars/polars/internals/expr/expr.py b/py-polars/polars/internals/expr/expr.py
@@ -1282,6 +1282,33 @@ def cumsum(self, reverse: bool = False) -> Expr:
         │ 10  ┆ 4         │
         └─────┴───────────┘
 
+        Null values are excluded, but can also be filled by calling ``forward_fill``.
+        >>> df = pl.DataFrame({"values": [None, 10, None, 8, 9, None, 16, None]})
+        >>> df.with_columns(
+        ...     [
+        ...         pl.col("values").cumsum().alias("value_cumsum"),
+        ...         pl.col("values")
+        ...         .cumsum()
+        ...         .forward_fill()
+        ...         .alias("value_cumsum_all_filled"),
+        ...     ]
+        ... )
+        shape: (8, 3)
+        ┌────────┬──────────────┬─────────────────────────┐
+        │ values ┆ value_cumsum ┆ value_cumsum_all_filled │
+        │ ---    ┆ ---          ┆ ---                     │
+        │ i64    ┆ i64          ┆ i64                     │
+        ╞════════╪══════════════╪═════════════════════════╡
+        │ null   ┆ null         ┆ null                    │
+        │ 10     ┆ 10           ┆ 10                      │
+        │ null   ┆ null         ┆ 10                      │
+        │ 8      ┆ 18           ┆ 18                      │
+        │ 9      ┆ 27           ┆ 27                      │
+        │ null   ┆ null         ┆ 27                      │
+        │ 16     ┆ 43           ┆ 43                      │
+        │ null   ┆ null         ┆ 43                      │
+        └────────┴──────────────┴─────────────────────────┘
+
         """
         return wrap_expr(self._pyexpr.cumsum(reverse))
 
@@ -1386,6 +1413,33 @@ def cummax(self, reverse: bool = False) -> Expr:
         │ 4   ┆ 4         │
         └─────┴───────────┘
 
+        Null values are excluded, but can also be filled by calling ``forward_fill``.
+        >>> df = pl.DataFrame({"values": [None, 10, None, 8, 9, None, 16, None]})
+        >>> df.with_columns(
+        ...     [
+        ...         pl.col("values").cummax().alias("value_cummax"),
+        ...         pl.col("values")
+        ...         .cummax()
+        ...         .forward_fill()
+        ...         .alias("value_cummax_all_filled"),
+        ...     ]
+        ... )
+        shape: (8, 3)
+        ┌────────┬──────────────┬─────────────────────────┐
+        │ values ┆ value_cummax ┆ value_cummax_all_filled │
+        │ ---    ┆ ---          ┆ ---                     │
+        │ i64    ┆ i64          ┆ i64                     │
+        ╞════════╪══════════════╪═════════════════════════╡
+        │ null   ┆ null         ┆ null                    │
+        │ 10     ┆ 10           ┆ 10                      │
+        │ null   ┆ null         ┆ 10                      │
+        │ 8      ┆ 10           ┆ 10                      │
+        │ 9      ┆ 10           ┆ 10                      │
+        │ null   ┆ null         ┆ 10                      │
+        │ 16     ┆ 16           ┆ 16                      │
+        │ null   ┆ null         ┆ 16                      │
+        └────────┴──────────────┴─────────────────────────┘
+
         """
         return wrap_expr(self._pyexpr.cummax(reverse))