docs(examples): add mean, bucket, histogram examples

ibis-project · Nov 13, 2024 · 3a1bb36 · 3a1bb36
1 parent 4492ad2
commit 3a1bb36
Showing 1 changed file with 115 additions and 0 deletions.
diff --git a/ibis/expr/types/numeric.py b/ibis/expr/types/numeric.py
@@ -887,6 +887,45 @@ def mean(
         -------
         NumericScalar
             The mean of the input expression
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> t = ibis.memtable(
+        ...     {
+        ...         "id": [1, 2, 3, 4, 5, 6],
+        ...         "grouper": ["a", "a", "a", "b", "b", "c"],
+        ...         "values": [3, 2, 1, 2, 3, 2],
+        ...     }
+        ... )
+        >>> t.mutate(mean_col=t.values.mean())
+        ┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┓
+        ┃ id    ┃ grouper ┃ values ┃ mean_col ┃
+        ┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━┩
+        │ int64 │ string  │ int64  │ float64  │
+        ├───────┼─────────┼────────┼──────────┤
+        │     1 │ a       │      3 │ 2.166667 │
+        │     2 │ a       │      2 │ 2.166667 │
+        │     3 │ a       │      1 │ 2.166667 │
+        │     4 │ b       │      2 │ 2.166667 │
+        │     5 │ b       │      3 │ 2.166667 │
+        │     6 │ c       │      2 │ 2.166667 │
+        └───────┴─────────┴────────┴──────────┘
+
+        >>> t.mutate(mean_col=t.values.mean(where=t.grouper != "c"))
+        ┏━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┓
+        ┃ id    ┃ grouper ┃ values ┃ mean_col ┃
+        ┡━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━┩
+        │ int64 │ string  │ int64  │ float64  │
+        ├───────┼─────────┼────────┼──────────┤
+        │     1 │ a       │      3 │      2.2 │
+        │     2 │ a       │      2 │      2.2 │
+        │     3 │ a       │      1 │      2.2 │
+        │     4 │ b       │      2 │      2.2 │
+        │     5 │ b       │      3 │      2.2 │
+        │     6 │ c       │      2 │      2.2 │
+        └───────┴─────────┴────────┴──────────┘
         """
         # TODO(kszucs): remove the alias from the reduction method in favor
         # of default name generated by ops.Value operations
@@ -1076,6 +1115,35 @@ def bucket(
         -------
         IntegerColumn
             A categorical column expression
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> t = ibis.memtable(
+        ...     {
+        ...         "values": [-1, 3, 5, 6, 8, 10, 11],
+        ...     }
+        ... )
+        >>> buckets = [0, 5, 10]
+        >>> t.mutate(
+        ...     bucket_closed_left=t.values.bucket(buckets),
+        ...     bucket_closed_right=t.values.bucket(buckets, closed="right"),
+        ...     bucket_over_under=t.values.bucket(buckets, include_over=True, include_under=True),
+        ... )
+        ┏━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┓
+        ┃ values ┃ bucket_closed_left ┃ bucket_closed_right ┃ bucket_over_under ┃
+        ┡━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━┩
+        │ int64  │ int8               │ int8                │ int8              │
+        ├────────┼────────────────────┼─────────────────────┼───────────────────┤
+        │     -1 │               NULL │                NULL │                 0 │
+        │      3 │                  0 │                   0 │                 1 │
+        │      5 │                  1 │                   0 │                 2 │
+        │      6 │                  1 │                   1 │                 2 │
+        │      8 │                  1 │                   1 │                 2 │
+        │     10 │                  1 │                   1 │                 2 │
+        │     11 │               NULL │                NULL │                 3 │
+        └────────┴────────────────────┴─────────────────────┴───────────────────┘
         """
         return ops.Bucket(
             self,
@@ -1111,6 +1179,53 @@ def histogram(
         -------
         Column
             Bucketed column
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> t = ibis.memtable(
+        ...     {
+        ...         "values": [-1, 3, 5, 6, 8, 10, 11, 23, 25],
+        ...     }
+        ... )
+
+        Compute a histogram with 5 bins.
+
+        >>> t.mutate(histogram=t.values.histogram(nbins=5))
+        ┏━━━━━━━━┳━━━━━━━━━━━┓
+        ┃ values ┃ histogram ┃
+        ┡━━━━━━━━╇━━━━━━━━━━━┩
+        │ int64  │ int64     │
+        ├────────┼───────────┤
+        │     -1 │         0 │
+        │      3 │         0 │
+        │      5 │         1 │
+        │      6 │         1 │
+        │      8 │         1 │
+        │     10 │         2 │
+        │     11 │         2 │
+        │     23 │         4 │
+        │     25 │         4 │
+        └────────┴───────────┘
+
+        Compute a histogram with a fixed bin width of 10.
+        >>> t.mutate(histogram=t.values.histogram(binwidth=10))
+        ┏━━━━━━━━┳━━━━━━━━━━━┓
+        ┃ values ┃ histogram ┃
+        ┡━━━━━━━━╇━━━━━━━━━━━┩
+        │ int64  │ int64     │
+        ├────────┼───────────┤
+        │     -1 │         0 │
+        │      3 │         0 │
+        │      5 │         0 │
+        │      6 │         0 │
+        │      8 │         0 │
+        │     10 │         1 │
+        │     11 │         1 │
+        │     23 │         2 │
+        │     25 │         2 │
+        └────────┴───────────┘
         """
 
         if nbins is not None and binwidth is not None: