From 161c61f597b323e5f2c6b3085b545b9132514e2d Mon Sep 17 00:00:00 2001
From: Tyler White <50381805+IndexSeek@users.noreply.github.com>
Date: Wed, 13 Nov 2024 23:58:36 +0000
Subject: [PATCH] docs(examples): add std, var, corr, and cov usage examples

---
 ibis/expr/types/numeric.py | 114 +++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)

diff --git a/ibis/expr/types/numeric.py b/ibis/expr/types/numeric.py
index 076f412c5d07..9710400ecfff 100644
--- a/ibis/expr/types/numeric.py
+++ b/ibis/expr/types/numeric.py
@@ -786,6 +786,33 @@ def std(
         -------
         NumericScalar
             Standard deviation of `arg`
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> t = ibis.memtable(
+        ...     {
+        ...         "values": [1, 3, 3, 4, 5, 7],
+        ...     }
+        ... )
+        >>> t.values.std()
+        ┌──────────┐
+        │ 2.041241 │
+        └──────────┘
+        >>> t.mutate(std_col=t.values.std())
+        ┏━━━━━━━━┳━━━━━━━━━━┓
+        ┃ values ┃ std_col  ┃
+        ┡━━━━━━━━╇━━━━━━━━━━┩
+        │ int64  │ float64  │
+        ├────────┼──────────┤
+        │      1 │ 2.041241 │
+        │      3 │ 2.041241 │
+        │      3 │ 2.041241 │
+        │      4 │ 2.041241 │
+        │      5 │ 2.041241 │
+        │      7 │ 2.041241 │
+        └────────┴──────────┘
         """
         return ops.StandardDev(
             self, how=how, where=self._bind_to_parent_table(where)
@@ -809,6 +836,33 @@ def var(
         -------
         NumericScalar
             Standard deviation of `arg`
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> t = ibis.memtable(
+        ...     {
+        ...         "values": [1, 3, 3, 4, 5, 7],
+        ...     }
+        ... )
+        >>> t.values.var()
+        ┌──────────┐
+        │ 4.166667 │
+        └──────────┘
+        >>> t.mutate(var_col=t.values.var())
+        ┏━━━━━━━━┳━━━━━━━━━━┓
+        ┃ values ┃ var_col  ┃
+        ┡━━━━━━━━╇━━━━━━━━━━┩
+        │ int64  │ float64  │
+        ├────────┼──────────┤
+        │      1 │ 4.166667 │
+        │      3 │ 4.166667 │
+        │      3 │ 4.166667 │
+        │      4 │ 4.166667 │
+        │      5 │ 4.166667 │
+        │      7 │ 4.166667 │
+        └────────┴──────────┘
         """
         return ops.Variance(
             self, how=how, where=self._bind_to_parent_table(where)
@@ -835,6 +889,34 @@ def corr(
         -------
         NumericScalar
             The correlation of `left` and `right`
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> t = ibis.memtable(
+        ...     {
+        ...         "left": [1, 3, 3, 4, 5, 7],
+        ...         "right": [7, 5, 4, 3, 3, 1],
+        ...     }
+        ... )
+        >>> t.left.corr(t.right, how="pop")
+        ┌────────┐
+        │ -0.968 │
+        └────────┘
+        >>> t.mutate(corr_col=t.left.corr(t.right, how="pop"))
+        ┏━━━━━━━┳━━━━━━━┳━━━━━━━━━━┓
+        ┃ left  ┃ right ┃ corr_col ┃
+        ┡━━━━━━━╇━━━━━━━╇━━━━━━━━━━┩
+        │ int64 │ int64 │ float64  │
+        ├───────┼───────┼──────────┤
+        │     1 │     7 │   -0.968 │
+        │     3 │     5 │   -0.968 │
+        │     3 │     4 │   -0.968 │
+        │     4 │     3 │   -0.968 │
+        │     5 │     3 │   -0.968 │
+        │     7 │     1 │   -0.968 │
+        └───────┴───────┴──────────┘
         """
         return ops.Correlation(
             self,
@@ -864,6 +946,38 @@ def cov(
         -------
         NumericScalar
             The covariance of `self` and `right`
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> t = ibis.memtable(
+        ...     {
+        ...         "left": [1, 3, 3, 4, 5, 7],
+        ...         "right": [7, 5, 4, 3, 3, 1],
+        ...     }
+        ... )
+        >>> t.left.cov(t.right)
+        ┌───────────┐
+        │ -4.033333 │
+        └───────────┘
+        >>> t.left.cov(t.right, how="pop")
+        ┌───────────┐
+        │ -3.361111 │
+        └───────────┘
+        >>> t.mutate(cov_col=t.left.cov(t.right, how="pop"))
+        ┏━━━━━━━┳━━━━━━━┳━━━━━━━━━━━┓
+        ┃ left  ┃ right ┃ cov_col   ┃
+        ┡━━━━━━━╇━━━━━━━╇━━━━━━━━━━━┩
+        │ int64 │ int64 │ float64   │
+        ├───────┼───────┼───────────┤
+        │     1 │     7 │ -3.361111 │
+        │     3 │     5 │ -3.361111 │
+        │     3 │     4 │ -3.361111 │
+        │     4 │     3 │ -3.361111 │
+        │     5 │     3 │ -3.361111 │
+        │     7 │     1 │ -3.361111 │
+        └───────┴───────┴───────────┘
         """
         return ops.Covariance(
             self,