Skip to content

Commit 2650f7c

Browse files
IndexSeekIndexSeek
authored
docs(examples): add cumsum, cummean, and sum examples (#10474)
1 parent 550a018 commit 2650f7c

File tree

1 file changed

+123
-2
lines changed

1 file changed

+123
-2
lines changed

‎ibis/expr/types/numeric.py

Lines changed: 123 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -893,7 +893,49 @@ def mean(
893893
return ops.Mean(self, where=self._bind_to_parent_table(where)).to_expr()
894894

895895
def cummean(self, *, where=None, group_by=None, order_by=None) -> NumericColumn:
896-
"""Return the cumulative mean of the input."""
896+
"""Return the cumulative mean of the input.
897+
898+
Examples
899+
--------
900+
>>> import ibis
901+
>>> ibis.options.interactive = True
902+
>>> t = ibis.memtable(
903+
... {
904+
... "id": [1, 2, 3, 4, 5, 6],
905+
... "grouper": ["a", "a", "a", "b", "b", "c"],
906+
... "values": [3, 2, 1, 2, 3, 2],
907+
... }
908+
... )
909+
>>> t.mutate(cummean=t.values.cummean()).order_by("id")
910+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┓
911+
┃ id ┃ grouper ┃ values ┃ cummean ┃
912+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━┩
913+
│ int64 │ string │ int64 │ float64 │
914+
├───────┼─────────┼────────┼──────────┤
915+
│ 1 │ a │ 3 │ 3.000000 │
916+
│ 2 │ a │ 2 │ 2.500000 │
917+
│ 3 │ a │ 1 │ 2.000000 │
918+
│ 4 │ b │ 2 │ 2.000000 │
919+
│ 5 │ b │ 3 │ 2.200000 │
920+
│ 6 │ c │ 2 │ 2.166667 │
921+
└───────┴─────────┴────────┴──────────┘
922+
923+
>>> t.mutate(cummean=t.values.cummean(where=t.grouper != "c", group_by="grouper")).order_by(
924+
... "id"
925+
... )
926+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┓
927+
┃ id ┃ grouper ┃ values ┃ cummean ┃
928+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━┩
929+
│ int64 │ string │ int64 │ float64 │
930+
├───────┼─────────┼────────┼─────────┤
931+
│ 1 │ a │ 3 │ 3.0 │
932+
│ 2 │ a │ 2 │ 2.5 │
933+
│ 3 │ a │ 1 │ 2.0 │
934+
│ 4 │ b │ 2 │ 2.0 │
935+
│ 5 │ b │ 3 │ 2.5 │
936+
│ 6 │ c │ 2 │ NULL │
937+
└───────┴─────────┴────────┴─────────┘
938+
"""
897939
return self.mean(where=where).over(
898940
ibis.cumulative_window(group_by=group_by, order_by=order_by)
899941
)
@@ -913,11 +955,90 @@ def sum(
913955
-------
914956
NumericScalar
915957
The sum of the input expression
958+
959+
Examples
960+
--------
961+
>>> import ibis
962+
>>> ibis.options.interactive = True
963+
>>> t = ibis.memtable(
964+
... {
965+
... "id": [1, 2, 3, 4, 5, 6],
966+
... "grouper": ["a", "a", "a", "b", "b", "c"],
967+
... "values": [3, 2, 1, 2, 3, 2],
968+
... }
969+
... )
970+
>>> t.mutate(sum_col=t.values.sum())
971+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┓
972+
┃ id ┃ grouper ┃ values ┃ sum_col ┃
973+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━┩
974+
│ int64 │ string │ int64 │ int64 │
975+
├───────┼─────────┼────────┼─────────┤
976+
│ 1 │ a │ 3 │ 13 │
977+
│ 2 │ a │ 2 │ 13 │
978+
│ 3 │ a │ 1 │ 13 │
979+
│ 4 │ b │ 2 │ 13 │
980+
│ 5 │ b │ 3 │ 13 │
981+
│ 6 │ c │ 2 │ 13 │
982+
└───────┴─────────┴────────┴─────────┘
983+
984+
>>> t.mutate(sum_col=t.values.sum(where=t.grouper != "c"))
985+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┓
986+
┃ id ┃ grouper ┃ values ┃ sum_col ┃
987+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━┩
988+
│ int64 │ string │ int64 │ int64 │
989+
├───────┼─────────┼────────┼─────────┤
990+
│ 1 │ a │ 3 │ 11 │
991+
│ 2 │ a │ 2 │ 11 │
992+
│ 3 │ a │ 1 │ 11 │
993+
│ 4 │ b │ 2 │ 11 │
994+
│ 5 │ b │ 3 │ 11 │
995+
│ 6 │ c │ 2 │ 11 │
996+
└───────┴─────────┴────────┴─────────┘
916997
"""
917998
return ops.Sum(self, where=self._bind_to_parent_table(where)).to_expr()
918999

9191000
def cumsum(self, *, where=None, group_by=None, order_by=None) -> NumericColumn:
920-
"""Return the cumulative sum of the input."""
1001+
"""Return the cumulative sum of the input.
1002+
1003+
Examples
1004+
--------
1005+
>>> import ibis
1006+
>>> ibis.options.interactive = True
1007+
>>> t = ibis.memtable(
1008+
... {
1009+
... "id": [1, 2, 3, 4, 5, 6],
1010+
... "grouper": ["a", "a", "a", "b", "b", "c"],
1011+
... "values": [3, 2, 1, 2, 3, 2],
1012+
... }
1013+
... )
1014+
>>> t.mutate(cumsum=t.values.cumsum())
1015+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┓
1016+
┃ id ┃ grouper ┃ values ┃ cumsum ┃
1017+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━┩
1018+
│ int64 │ string │ int64 │ int64 │
1019+
├───────┼─────────┼────────┼────────┤
1020+
│ 1 │ a │ 3 │ 3 │
1021+
│ 2 │ a │ 2 │ 5 │
1022+
│ 3 │ a │ 1 │ 6 │
1023+
│ 4 │ b │ 2 │ 8 │
1024+
│ 5 │ b │ 3 │ 11 │
1025+
│ 6 │ c │ 2 │ 13 │
1026+
└───────┴─────────┴────────┴────────┘
1027+
1028+
>>> t.mutate(cumsum=t.values.cumsum(where=t.grouper != "c"))
1029+
┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━┓
1030+
┃ id ┃ grouper ┃ values ┃ cumsum ┃
1031+
┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━┩
1032+
│ int64 │ string │ int64 │ int64 │
1033+
├───────┼─────────┼────────┼────────┤
1034+
│ 1 │ a │ 3 │ 3 │
1035+
│ 2 │ a │ 2 │ 5 │
1036+
│ 3 │ a │ 1 │ 6 │
1037+
│ 4 │ b │ 2 │ 8 │
1038+
│ 5 │ b │ 3 │ 11 │
1039+
│ 6 │ c │ 2 │ 11 │
1040+
└───────┴─────────┴────────┴────────┘
1041+
"""
9211042
return self.sum(where=where).over(
9221043
ibis.cumulative_window(group_by=group_by, order_by=order_by)
9231044
)

0 commit comments

Comments
 (0)