docs(python): provide additional examples for diff methods (#6630)

pola-rs · Feb 2, 2023 · 9193880 · 9193880
1 parent 6bfc0d1
commit 9193880
Show file tree

Hide file tree

Showing 4 changed files with 117 additions and 18 deletions.
diff --git a/py-polars/polars/internals/expr/expr.py b/py-polars/polars/internals/expr/expr.py
@@ -4630,21 +4630,45 @@ def diff(self, n: int = 1, null_behavior: NullBehavior = "ignore") -> Expr:
 
         Examples
         --------
-        >>> df = pl.DataFrame(
-        ...     {
-        ...         "a": [20, 10, 30],
-        ...     }
-        ... )
-        >>> df.select(pl.col("a").diff())
+        >>> df = pl.DataFrame({"int": [20, 10, 30, 25, 35]})
+        >>> df.with_columns(change=pl.col("int").diff())
+        shape: (5, 2)
+        ┌─────┬────────┐
+        │ int ┆ change │
+        │ --- ┆ ---    │
+        │ i64 ┆ i64    │
+        ╞═════╪════════╡
+        │ 20  ┆ null   │
+        │ 10  ┆ -10    │
+        │ 30  ┆ 20     │
+        │ 25  ┆ -5     │
+        │ 35  ┆ 10     │
+        └─────┴────────┘
+
+        >>> df.with_columns(change=pl.col("int").diff(n=2))
+        shape: (5, 2)
+        ┌─────┬────────┐
+        │ int ┆ change │
+        │ --- ┆ ---    │
+        │ i64 ┆ i64    │
+        ╞═════╪════════╡
+        │ 20  ┆ null   │
+        │ 10  ┆ null   │
+        │ 30  ┆ 10     │
+        │ 25  ┆ 15     │
+        │ 35  ┆ 5      │
+        └─────┴────────┘
+
+        >>> df.select(pl.col("int").diff(n=2, null_behavior="drop").alias("diff"))
         shape: (3, 1)
         ┌──────┐
-        │ a    │
+        │ diff │
         │ ---  │
         │ i64  │
         ╞══════╡
-        │ null │
-        │ -10  │
-        │ 20   │
+        │ 10   │
+        │ 15   │
+        │ 5    │
         └──────┘
 
         """

diff --git a/py-polars/polars/internals/expr/list.py b/py-polars/polars/internals/expr/list.py
@@ -483,14 +483,39 @@ def diff(self, n: int = 1, null_behavior: NullBehavior = "ignore") -> pli.Expr:
 
         Examples
         --------
-        >>> s = pl.Series("a", [[1, 2, 3, 4], [10, 2, 1]])
-        >>> s.arr.diff()
-        shape: (2,)
-        Series: 'a' [list[i64]]
-        [
-            [null, 1, ... 1]
-            [null, -8, -1]
-        ]
+        >>> df = pl.DataFrame({"n": [[1, 2, 3, 4], [10, 2, 1]]})
+        >>> df.select(pl.col("n").arr.diff())
+        shape: (2, 1)
+        ┌──────────────────┐
+        │ n                │
+        │ ---              │
+        │ list[i64]        │
+        ╞══════════════════╡
+        │ [null, 1, ... 1] │
+        │ [null, -8, -1]   │
+        └──────────────────┘
+
+        >>> df.select(pl.col("n").arr.diff(n=2))
+        shape: (2, 1)
+        ┌─────────────────────┐
+        │ n                   │
+        │ ---                 │
+        │ list[i64]           │
+        ╞═════════════════════╡
+        │ [null, null, ... 2] │
+        │ [null, null, -9]    │
+        └─────────────────────┘
+
+        >>> df.select(pl.col("n").arr.diff(n=2, null_behavior="drop"))
+        shape: (2, 1)
+        ┌───────────┐
+        │ n         │
+        │ ---       │
+        │ list[i64] │
+        ╞═══════════╡
+        │ [2, 2]    │
+        │ [-9]      │
+        └───────────┘
 
         """
         return pli.wrap_expr(self._pyexpr.lst_diff(n, null_behavior))

diff --git a/py-polars/polars/internals/series/list.py b/py-polars/polars/internals/series/list.py
@@ -199,6 +199,22 @@ def diff(self, n: int = 1, null_behavior: NullBehavior = "ignore") -> pli.Series
             [null, -8, -1]
         ]
 
+        >>> s.arr.diff(n=2)
+        shape: (2,)
+        Series: 'a' [list[i64]]
+        [
+            [null, null, ... 2]
+            [null, null, -9]
+        ]
+
+        >>> s.arr.diff(n=2, null_behavior="drop")
+        shape: (2,)
+        Series: 'a' [list[i64]]
+        [
+            [2, 2]
+            [-9]
+        ]
+
         """
 
     def shift(self, periods: int = 1) -> pli.Series:

diff --git a/py-polars/polars/internals/series/series.py b/py-polars/polars/internals/series/series.py
@@ -4365,6 +4365,40 @@ def diff(self, n: int = 1, null_behavior: NullBehavior = "ignore") -> Series:
         null_behavior : {'ignore', 'drop'}
             How to handle null values.
 
+        Examples
+        --------
+        >>> s = pl.Series("s", values=[20, 10, 30, 25, 35], dtype=pl.Int8)
+        >>> s.diff()
+        shape: (5,)
+        Series: 's' [i8]
+        [
+            null
+            -10
+            20
+            -5
+            10
+        ]
+
+        >>> s.diff(n=2)
+        shape: (5,)
+        Series: 's' [i8]
+        [
+            null
+            null
+            10
+            15
+            5
+        ]
+
+        >>> s.diff(n=2, null_behavior="drop")
+        shape: (3,)
+        Series: 's' [i8]
+        [
+            10
+            15
+            5
+        ]
+
         """
 
     def pct_change(self, n: int = 1) -> Series: