Skip to content

Commit 452f807

Browse files
IndexSeekcpcloud
IndexSeek
authored and
cpcloud
committed
docs(examples): cummin, cummax, lead, lag, nth example usage
1 parent 4f15905 commit 452f807

File tree

1 file changed

+176
-2
lines changed

1 file changed

+176
-2
lines changed

‎ibis/expr/types/generic.py

Lines changed: 176 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2448,13 +2448,95 @@ def ntile(self, buckets: int | ir.IntegerValue) -> ir.IntegerColumn:
24482448
return ibis.ntile(buckets).over(order_by=self)
24492449

24502450
def cummin(self, *, where=None, group_by=None, order_by=None) -> Column:
2451-
"""Return the cumulative min over a window."""
2451+
"""Return the cumulative min over a window.
2452+
2453+
Examples
2454+
--------
2455+
>>> import ibis
2456+
>>> ibis.options.interactive = True
2457+
>>> t = ibis.memtable(
2458+
... {
2459+
... "id": [1, 2, 3, 4, 5, 6],
2460+
... "grouper": ["a", "a", "a", "b", "b", "c"],
2461+
... "values": [3, 2, 1, 2, 3, 2],
2462+
... }
2463+
... )
2464+
>>> t.mutate(cummin=t.values.cummin())
2465+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┓
2466+
┃ id ┃ grouper ┃ values ┃ cummin ┃
2467+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━┩
2468+
│ int64 │ string │ int64 │ int64 │
2469+
├───────┼─────────┼────────┼────────┤
2470+
│ 1 │ a │ 3 │ 3 │
2471+
│ 2 │ a │ 2 │ 2 │
2472+
│ 3 │ a │ 1 │ 1 │
2473+
│ 4 │ b │ 2 │ 1 │
2474+
│ 5 │ b │ 3 │ 1 │
2475+
│ 6 │ c │ 2 │ 1 │
2476+
└───────┴─────────┴────────┴────────┘
2477+
>>> t.mutate(cummin=t.values.cummin(where=t.grouper != "c", group_by=t.grouper)).order_by(
2478+
... t.id
2479+
... )
2480+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┓
2481+
┃ id ┃ grouper ┃ values ┃ cummin ┃
2482+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━┩
2483+
│ int64 │ string │ int64 │ int64 │
2484+
├───────┼─────────┼────────┼────────┤
2485+
│ 1 │ a │ 3 │ 3 │
2486+
│ 2 │ a │ 2 │ 2 │
2487+
│ 3 │ a │ 1 │ 1 │
2488+
│ 4 │ b │ 2 │ 2 │
2489+
│ 5 │ b │ 3 │ 2 │
2490+
│ 6 │ c │ 2 │ NULL │
2491+
└───────┴─────────┴────────┴────────┘
2492+
"""
24522493
return self.min(where=where).over(
24532494
ibis.cumulative_window(group_by=group_by, order_by=order_by)
24542495
)
24552496

24562497
def cummax(self, *, where=None, group_by=None, order_by=None) -> Column:
2457-
"""Return the cumulative max over a window."""
2498+
"""Return the cumulative max over a window.
2499+
2500+
Examples
2501+
--------
2502+
>>> import ibis
2503+
>>> ibis.options.interactive = True
2504+
>>> t = ibis.memtable(
2505+
... {
2506+
... "id": [1, 2, 3, 4, 5, 6],
2507+
... "grouper": ["a", "a", "a", "b", "b", "c"],
2508+
... "values": [3, 2, 1, 2, 3, 2],
2509+
... }
2510+
... )
2511+
>>> t.mutate(cummax=t.values.cummax())
2512+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┓
2513+
┃ id ┃ grouper ┃ values ┃ cummax ┃
2514+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━┩
2515+
│ int64 │ string │ int64 │ int64 │
2516+
├───────┼─────────┼────────┼────────┤
2517+
│ 1 │ a │ 3 │ 3 │
2518+
│ 2 │ a │ 2 │ 3 │
2519+
│ 3 │ a │ 1 │ 3 │
2520+
│ 4 │ b │ 2 │ 3 │
2521+
│ 5 │ b │ 3 │ 3 │
2522+
│ 6 │ c │ 2 │ 3 │
2523+
└───────┴─────────┴────────┴────────┘
2524+
>>> t.mutate(cummax=t.values.cummax(where=t.grouper != "c", group_by=t.grouper)).order_by(
2525+
... t.id
2526+
... )
2527+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┓
2528+
┃ id ┃ grouper ┃ values ┃ cummax ┃
2529+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━┩
2530+
│ int64 │ string │ int64 │ int64 │
2531+
├───────┼─────────┼────────┼────────┤
2532+
│ 1 │ a │ 3 │ 3 │
2533+
│ 2 │ a │ 2 │ 3 │
2534+
│ 3 │ a │ 1 │ 3 │
2535+
│ 4 │ b │ 2 │ 2 │
2536+
│ 5 │ b │ 3 │ 3 │
2537+
│ 6 │ c │ 2 │ NULL │
2538+
└───────┴─────────┴────────┴────────┘
2539+
"""
24582540
return self.max(where=where).over(
24592541
ibis.cumulative_window(group_by=group_by, order_by=order_by)
24602542
)
@@ -2472,6 +2554,36 @@ def lag(
24722554
Index of row to select
24732555
default
24742556
Value used if no row exists at `offset`
2557+
2558+
Examples
2559+
--------
2560+
>>> import ibis
2561+
>>> ibis.options.interactive = True
2562+
>>> t = ibis.memtable(
2563+
... {"year": [2007, 2008, 2009, 2010], "total": [1899.6, 1928.2, 2037.9, 1955.2]}
2564+
... )
2565+
>>> t.mutate(total_lead=t.total.lag())
2566+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━┓
2567+
┃ year ┃ total ┃ total_lead ┃
2568+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━┩
2569+
│ int64 │ float64 │ float64 │
2570+
├───────┼─────────┼────────────┤
2571+
│ 2007 │ 1899.6 │ NULL │
2572+
│ 2008 │ 1928.2 │ 1899.6 │
2573+
│ 2009 │ 2037.9 │ 1928.2 │
2574+
│ 2010 │ 1955.2 │ 2037.9 │
2575+
└───────┴─────────┴────────────┘
2576+
>>> t.mutate(total_lead=t.total.lag(2, 0))
2577+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━┓
2578+
┃ year ┃ total ┃ total_lead ┃
2579+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━┩
2580+
│ int64 │ float64 │ float64 │
2581+
├───────┼─────────┼────────────┤
2582+
│ 2007 │ 1899.6 │ 0.0 │
2583+
│ 2008 │ 1928.2 │ 0.0 │
2584+
│ 2009 │ 2037.9 │ 1899.6 │
2585+
│ 2010 │ 1955.2 │ 1928.2 │
2586+
└───────┴─────────┴────────────┘
24752587
"""
24762588
return ops.Lag(self, offset, default).to_expr()
24772589

@@ -2488,6 +2600,36 @@ def lead(
24882600
Index of row to select
24892601
default
24902602
Value used if no row exists at `offset`
2603+
2604+
Examples
2605+
--------
2606+
>>> import ibis
2607+
>>> ibis.options.interactive = True
2608+
>>> t = ibis.memtable(
2609+
... {"year": [2007, 2008, 2009, 2010], "total": [1899.6, 1928.2, 2037.9, 1955.2]}
2610+
... )
2611+
>>> t.mutate(total_lead=t.total.lead())
2612+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━┓
2613+
┃ year ┃ total ┃ total_lead ┃
2614+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━┩
2615+
│ int64 │ float64 │ float64 │
2616+
├───────┼─────────┼────────────┤
2617+
│ 2007 │ 1899.6 │ 1928.2 │
2618+
│ 2008 │ 1928.2 │ 2037.9 │
2619+
│ 2009 │ 2037.9 │ 1955.2 │
2620+
│ 2010 │ 1955.2 │ NULL │
2621+
└───────┴─────────┴────────────┘
2622+
>>> t.mutate(total_lead=t.total.lead(2, 0))
2623+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━┓
2624+
┃ year ┃ total ┃ total_lead ┃
2625+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━┩
2626+
│ int64 │ float64 │ float64 │
2627+
├───────┼─────────┼────────────┤
2628+
│ 2007 │ 1899.6 │ 2037.9 │
2629+
│ 2008 │ 1928.2 │ 1955.2 │
2630+
│ 2009 │ 2037.9 │ 0.0 │
2631+
│ 2010 │ 1955.2 │ 0.0 │
2632+
└───────┴─────────┴────────────┘
24912633
"""
24922634
return ops.Lead(self, offset, default).to_expr()
24932635

@@ -2507,6 +2649,38 @@ def nth(self, n: int | ir.IntegerValue) -> Column:
25072649
-------
25082650
Column
25092651
The nth value over a window
2652+
2653+
Examples
2654+
--------
2655+
>>> import ibis
2656+
>>> ibis.options.interactive = True
2657+
>>> t = ibis.memtable({"values": [1, 2, 3, 4, 5, 6]})
2658+
>>> t.mutate(nth=t.values.nth(2))
2659+
┏━━━━━━━━┳━━━━━━━┓
2660+
┃ values ┃ nth ┃
2661+
┡━━━━━━━━╇━━━━━━━┩
2662+
│ int64 │ int64 │
2663+
├────────┼───────┤
2664+
│ 1 │ 3 │
2665+
│ 2 │ 3 │
2666+
│ 3 │ 3 │
2667+
│ 4 │ 3 │
2668+
│ 5 │ 3 │
2669+
│ 6 │ 3 │
2670+
└────────┴───────┘
2671+
>>> t.mutate(nth=t.values.nth(7))
2672+
┏━━━━━━━━┳━━━━━━━┓
2673+
┃ values ┃ nth ┃
2674+
┡━━━━━━━━╇━━━━━━━┩
2675+
│ int64 │ int64 │
2676+
├────────┼───────┤
2677+
│ 1 │ NULL │
2678+
│ 2 │ NULL │
2679+
│ 3 │ NULL │
2680+
│ 4 │ NULL │
2681+
│ 5 │ NULL │
2682+
│ 6 │ NULL │
2683+
└────────┴───────┘
25102684
"""
25112685
return ops.NthValue(self, n).to_expr()
25122686

0 commit comments

Comments
 (0)