From 5f091d8981f4942d6333e58c6e3c508fb2272298 Mon Sep 17 00:00:00 2001
From: Tyler White <50381805+IndexSeek@users.noreply.github.com>
Date: Mon, 4 Nov 2024 23:40:48 +0000
Subject: [PATCH] docs(examples): count, percent_rank, cume_dist, ntile example
 usage

---
 ibis/expr/types/generic.py | 82 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 80 insertions(+), 2 deletions(-)

diff --git a/ibis/expr/types/generic.py b/ibis/expr/types/generic.py
index 7ba45962d450..75601a554ad1 100644
--- a/ibis/expr/types/generic.py
+++ b/ibis/expr/types/generic.py
@@ -2123,6 +2123,25 @@ def count(self, where: ir.BooleanValue | None = None) -> ir.IntegerScalar:
         -------
         IntegerScalar
             Number of elements in an expression
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> t = ibis.memtable(
+        ...     {
+        ...         "id": [1, 2, 3, 4, 5, 6],
+        ...         "color": ["Red", "Green", "Blue", "Blue", "Red", "Blue"],
+        ...     }
+        ... )
+        >>> t.count()
+        ┌───┐
+        │ 6 │
+        └───┘
+        >>> t.count(where=t.color == "Blue")
+        ┌───┐
+        │ 3 │
+        └───┘
         """
         return ops.Count(self, where=self._bind_to_parent_table(where)).to_expr()
 
@@ -2352,11 +2371,51 @@ def dense_rank(self) -> ir.IntegerColumn:
         return ibis.dense_rank().over(order_by=self)
 
     def percent_rank(self) -> Column:
-        """Return the relative rank of the values in the column."""
+        """Return the relative rank of the values in the column.
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> t = ibis.memtable({"values": [1, 2, 1, 2, 3, 2]})
+        >>> t.mutate(percent_rank=t.values.percent_rank())
+        ┏━━━━━━━━┳━━━━━━━━━━━━━━┓
+        ┃ values ┃ percent_rank ┃
+        ┡━━━━━━━━╇━━━━━━━━━━━━━━┩
+        │ int64  │ float64      │
+        ├────────┼──────────────┤
+        │      1 │          0.0 │
+        │      1 │          0.0 │
+        │      2 │          0.4 │
+        │      2 │          0.4 │
+        │      2 │          0.4 │
+        │      3 │          1.0 │
+        └────────┴──────────────┘
+        """
         return ibis.percent_rank().over(order_by=self)
 
     def cume_dist(self) -> Column:
-        """Return the cumulative distribution over a window."""
+        """Return the cumulative distribution over a window.
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> t = ibis.memtable({"values": [1, 2, 1, 2, 3, 2]})
+        >>> t.mutate(cume_dist=t.values.cume_dist())
+        ┏━━━━━━━━┳━━━━━━━━━━━┓
+        ┃ values ┃ cume_dist ┃
+        ┡━━━━━━━━╇━━━━━━━━━━━┩
+        │ int64  │ float64   │
+        ├────────┼───────────┤
+        │      1 │  0.333333 │
+        │      1 │  0.333333 │
+        │      2 │  0.833333 │
+        │      2 │  0.833333 │
+        │      2 │  0.833333 │
+        │      3 │  1.000000 │
+        └────────┴───────────┘
+        """
         return ibis.cume_dist().over(order_by=self)
 
     def ntile(self, buckets: int | ir.IntegerValue) -> ir.IntegerColumn:
@@ -2366,6 +2425,25 @@ def ntile(self, buckets: int | ir.IntegerValue) -> ir.IntegerColumn:
         ----------
         buckets
             Number of buckets to partition into
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> t = ibis.memtable({"values": [1, 2, 1, 2, 3, 2]})
+        >>> t.mutate(ntile=t.values.ntile(3))
+        ┏━━━━━━━━┳━━━━━━━┓
+        ┃ values ┃ ntile ┃
+        ┡━━━━━━━━╇━━━━━━━┩
+        │ int64  │ int64 │
+        ├────────┼───────┤
+        │      1 │     0 │
+        │      1 │     0 │
+        │      2 │     1 │
+        │      2 │     1 │
+        │      2 │     2 │
+        │      3 │     2 │
+        └────────┴───────┘
         """
         return ibis.ntile(buckets).over(order_by=self)