Numeric and Boolean Expressions¶

These APIs are available on numeric and boolean expressions.

`NumericValue` ¶

Bases: Value

Source code in ibis/expr/types/numeric.py

@public
class NumericValue(Value):
    @staticmethod
    def __negate_op__():
        # TODO(kszucs): do we need this?
        return ops.Negate

    def negate(self) -> NumericValue:
        """Negate a numeric expression.

        Returns
        -------
        NumericValue
            A numeric value expression

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [-1, 0, 1]})
        >>> t.values.negate()
        ┏━━━━━━━━━━━━━━━━┓
        ┃ Negate(values) ┃
        ┡━━━━━━━━━━━━━━━━┩
        │ int64          │
        ├────────────────┤
        │              1 │
        │              0 │
        │             -1 │
        └────────────────┘
        """
        op = self.op()
        try:
            result = op.negate()
        except AttributeError:
            op_class = self.__negate_op__()
            result = op_class(self)

        return result.to_expr()

    def __neg__(self) -> NumericValue:
        """Negate `self`.

        Returns
        -------
        NumericValue
            `self` negated
        """
        return self.negate()

    def round(self, digits: int | IntegerValue | None = None) -> NumericValue:
        """Round values to an indicated number of decimal places.

        Parameters
        ----------
        digits
            The number of digits to round to.

            Here's how the `digits` parameter affects the expression output
            type:

            |   `digits`    | `self.type()` |  Output   |
            | :-----------: | :-----------: | :-------: |
            | `None` or `0` |   `decimal`   | `decimal` |
            |    Nonzero    |   `decimal`   | `decimal` |
            | `None` or `0` |   Floating    |  `int64`  |
            |    Nonzero    |   Floating    | `float64` |

        Returns
        -------
        NumericValue
            The rounded expression

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [1.22, 1.64, 2.15, 2.54]})
        >>> t
        ┏━━━━━━━━━┓
        ┃ values  ┃
        ┡━━━━━━━━━┩
        │ float64 │
        ├─────────┤
        │    1.22 │
        │    1.64 │
        │    2.15 │
        │    2.54 │
        └─────────┘
        >>> t.values.round()
        ┏━━━━━━━━━━━━━━━┓
        ┃ Round(values) ┃
        ┡━━━━━━━━━━━━━━━┩
        │ int64         │
        ├───────────────┤
        │             1 │
        │             2 │
        │             2 │
        │             3 │
        └───────────────┘
        >>> t.values.round(digits=1)
        ┏━━━━━━━━━━━━━━━━━━┓
        ┃ Round(values, 1) ┃
        ┡━━━━━━━━━━━━━━━━━━┩
        │ float64          │
        ├──────────────────┤
        │              1.2 │
        │              1.6 │
        │              2.2 │
        │              2.5 │
        └──────────────────┘
        """
        return ops.Round(self, digits).to_expr()

    def log(self, base: NumericValue | None = None) -> NumericValue:
        r"""Compute $\log_{\texttt{base}}\left(\texttt{self}\right)$.

        Parameters
        ----------
        base
            The base of the logarithm. If `None`, base `e` is used.

        Returns
        -------
        NumericValue
            Logarithm of `arg` with base `base`

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> from math import e
        >>> t = ibis.memtable({"values": [e, e**2, e**3]})
        >>> t.values.log()
        ┏━━━━━━━━━━━━━┓
        ┃ Log(values) ┃
        ┡━━━━━━━━━━━━━┩
        │ float64     │
        ├─────────────┤
        │         1.0 │
        │         2.0 │
        │         3.0 │
        └─────────────┘


        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [10, 100, 1000]})
        >>> t.values.log(base=10)
        ┏━━━━━━━━━━━━━━━━━┓
        ┃ Log(values, 10) ┃
        ┡━━━━━━━━━━━━━━━━━┩
        │ float64         │
        ├─────────────────┤
        │             1.0 │
        │             2.0 │
        │             3.0 │
        └─────────────────┘
        """
        return ops.Log(self, base).to_expr()

    def clip(
        self,
        lower: NumericValue | None = None,
        upper: NumericValue | None = None,
    ) -> NumericValue:
        """Trim values outside of `lower` and `upper` bounds.

        Parameters
        ----------
        lower
            Lower bound
        upper
            Upper bound

        Returns
        -------
        NumericValue
            Clipped input

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": range(8)})
        >>> t.values.clip(lower=3, upper=6)
        ┏━━━━━━━━━━━━━━━━━━━━┓
        ┃ Clip(values, 3, 6) ┃
        ┡━━━━━━━━━━━━━━━━━━━━┩
        │ int64              │
        ├────────────────────┤
        │                  3 │
        │                  3 │
        │                  3 │
        │                  3 │
        │                  4 │
        │                  5 │
        │                  6 │
        │                  6 │
        └────────────────────┘
        """
        if lower is None and upper is None:
            raise ValueError("at least one of lower and upper must be provided")

        return ops.Clip(self, lower, upper).to_expr()

    def abs(self) -> NumericValue:
        """Return the absolute value of `self`.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [-1, 2, -3, 4]})
        >>> t.values.abs()
        ┏━━━━━━━━━━━━━┓
        ┃ Abs(values) ┃
        ┡━━━━━━━━━━━━━┩
        │ int64       │
        ├─────────────┤
        │           1 │
        │           2 │
        │           3 │
        │           4 │
        └─────────────┘
        """
        return ops.Abs(self).to_expr()

    def ceil(self) -> DecimalValue | IntegerValue:
        """Return the ceiling of `self`.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [1, 1.1, 2, 2.1, 3.3]})
        >>> t.values.ceil()
        ┏━━━━━━━━━━━━━━┓
        ┃ Ceil(values) ┃
        ┡━━━━━━━━━━━━━━┩
        │ int64        │
        ├──────────────┤
        │            1 │
        │            2 │
        │            2 │
        │            3 │
        │            4 │
        └──────────────┘
        """
        return ops.Ceil(self).to_expr()

    def degrees(self) -> NumericValue:
        """Compute the degrees of `self` radians.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> from math import pi
        >>> t = ibis.memtable({"values": [0, pi / 2, pi, 3 * pi / 2, 2 * pi]})
        >>> t.values.degrees()
        ┏━━━━━━━━━━━━━━━━━┓
        ┃ Degrees(values) ┃
        ┡━━━━━━━━━━━━━━━━━┩
        │ float64         │
        ├─────────────────┤
        │             0.0 │
        │            90.0 │
        │           180.0 │
        │           270.0 │
        │           360.0 │
        └─────────────────┘
        """
        return ops.Degrees(self).to_expr()

    rad2deg = degrees

    def exp(self) -> NumericValue:
        r"""Compute $e^\texttt{self}$.

        Returns
        -------
        NumericValue
            $e^\texttt{self}$

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": range(4)})
        >>> t.values.exp()
        ┏━━━━━━━━━━━━━┓
        ┃ Exp(values) ┃
        ┡━━━━━━━━━━━━━┩
        │ float64     │
        ├─────────────┤
        │    1.000000 │
        │    2.718282 │
        │    7.389056 │
        │   20.085537 │
        └─────────────┘
        """
        return ops.Exp(self).to_expr()

    def floor(self) -> DecimalValue | IntegerValue:
        """Return the floor of an expression.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [1, 1.1, 2, 2.1, 3.3]})
        >>> t.values.floor()
        ┏━━━━━━━━━━━━━━━┓
        ┃ Floor(values) ┃
        ┡━━━━━━━━━━━━━━━┩
        │ int64         │
        ├───────────────┤
        │             1 │
        │             1 │
        │             2 │
        │             2 │
        │             3 │
        └───────────────┘

        """
        return ops.Floor(self).to_expr()

    def log2(self) -> NumericValue:
        r"""Compute $\log_{2}\left(\texttt{self}\right)$.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [1, 2, 4, 8]})
        >>> t.values.log2()
        ┏━━━━━━━━━━━━━━┓
        ┃ Log2(values) ┃
        ┡━━━━━━━━━━━━━━┩
        │ float64      │
        ├──────────────┤
        │          0.0 │
        │          1.0 │
        │          2.0 │
        │          3.0 │
        └──────────────┘
        """
        return ops.Log2(self).to_expr()

    def log10(self) -> NumericValue:
        r"""Compute $\log_{10}\left(\texttt{self}\right)$.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [1, 10, 100]})
        >>> t.values.log10()
        ┏━━━━━━━━━━━━━━━┓
        ┃ Log10(values) ┃
        ┡━━━━━━━━━━━━━━━┩
        │ float64       │
        ├───────────────┤
        │           0.0 │
        │           1.0 │
        │           2.0 │
        └───────────────┘
        """
        return ops.Log10(self).to_expr()

    def ln(self) -> NumericValue:
        r"""Compute $\ln\left(\texttt{self}\right)$.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [1, 2.718281828, 3]})
        >>> t.values.ln()
        ┏━━━━━━━━━━━━┓
        ┃ Ln(values) ┃
        ┡━━━━━━━━━━━━┩
        │ float64    │
        ├────────────┤
        │   0.000000 │
        │   1.000000 │
        │   1.098612 │
        └────────────┘
        """
        return ops.Ln(self).to_expr()

    def radians(self) -> NumericValue:
        """Compute radians from `self` degrees.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [0, 90, 180, 270, 360]})
        >>> t.values.radians()
        ┏━━━━━━━━━━━━━━━━━┓
        ┃ Radians(values) ┃
        ┡━━━━━━━━━━━━━━━━━┩
        │ float64         │
        ├─────────────────┤
        │        0.000000 │
        │        1.570796 │
        │        3.141593 │
        │        4.712389 │
        │        6.283185 │
        └─────────────────┘
        """
        return ops.Radians(self).to_expr()

    deg2rad = radians

    def sign(self) -> NumericValue:
        """Return the sign of the input.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [-1, 2, -3, 4]})
        >>> t.values.sign()
        ┏━━━━━━━━━━━━━━┓
        ┃ Sign(values) ┃
        ┡━━━━━━━━━━━━━━┩
        │ int64        │
        ├──────────────┤
        │           -1 │
        │            1 │
        │           -1 │
        │            1 │
        └──────────────┘
        """
        return ops.Sign(self).to_expr()

    def sqrt(self) -> NumericValue:
        """Compute the square root of `self`.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [1, 4, 9, 16]})
        >>> t.values.sqrt()
        ┏━━━━━━━━━━━━━━┓
        ┃ Sqrt(values) ┃
        ┡━━━━━━━━━━━━━━┩
        │ float64      │
        ├──────────────┤
        │          1.0 │
        │          2.0 │
        │          3.0 │
        │          4.0 │
        └──────────────┘
        """
        return ops.Sqrt(self).to_expr()

    def nullifzero(self) -> NumericValue:
        """Return `NULL` if an expression is zero."""
        return ops.NullIfZero(self).to_expr()

    def zeroifnull(self) -> NumericValue:
        """Return zero if an expression is `NULL`."""
        return ops.ZeroIfNull(self).to_expr()

    def acos(self) -> NumericValue:
        """Compute the arc cosine of `self`.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [-1, 0, 1]})
        >>> t.values.acos()
        ┏━━━━━━━━━━━━━━┓
        ┃ Acos(values) ┃
        ┡━━━━━━━━━━━━━━┩
        │ float64      │
        ├──────────────┤
        │     3.141593 │
        │     1.570796 │
        │     0.000000 │
        └──────────────┘

        """
        return ops.Acos(self).to_expr()

    def asin(self) -> NumericValue:
        """Compute the arc sine of `self`.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [-1, 0, 1]})
        >>> t.values.asin()
        ┏━━━━━━━━━━━━━━┓
        ┃ Asin(values) ┃
        ┡━━━━━━━━━━━━━━┩
        │ float64      │
        ├──────────────┤
        │    -1.570796 │
        │     0.000000 │
        │     1.570796 │
        └──────────────┘
        """
        return ops.Asin(self).to_expr()

    def atan(self) -> NumericValue:
        """Compute the arc tangent of `self`.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [-1, 0, 1]})
        >>> t.values.atan()
        ┏━━━━━━━━━━━━━━┓
        ┃ Atan(values) ┃
        ┡━━━━━━━━━━━━━━┩
        │ float64      │
        ├──────────────┤
        │    -0.785398 │
        │     0.000000 │
        │     0.785398 │
        └──────────────┘
        """
        return ops.Atan(self).to_expr()

    def atan2(self, other: NumericValue) -> NumericValue:
        """Compute the two-argument version of arc tangent.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [-1, 0, 1]})
        >>> t.values.atan2(0)
        ┏━━━━━━━━━━━━━━━━━━┓
        ┃ Atan2(values, 0) ┃
        ┡━━━━━━━━━━━━━━━━━━┩
        │ float64          │
        ├──────────────────┤
        │        -1.570796 │
        │         0.000000 │
        │         1.570796 │
        └──────────────────┘
        """
        return ops.Atan2(self, other).to_expr()

    def cos(self) -> NumericValue:
        """Compute the cosine of `self`.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [-1, 0, 1]})
        >>> t.values.cos()
        ┏━━━━━━━━━━━━━┓
        ┃ Cos(values) ┃
        ┡━━━━━━━━━━━━━┩
        │ float64     │
        ├─────────────┤
        │    0.540302 │
        │    1.000000 │
        │    0.540302 │
        └─────────────┘
        """
        return ops.Cos(self).to_expr()

    def cot(self) -> NumericValue:
        """Compute the cotangent of `self`.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [-1, 0, 1]})
        >>> t.values.cot()
        ┏━━━━━━━━━━━━━┓
        ┃ Cot(values) ┃
        ┡━━━━━━━━━━━━━┩
        │ float64     │
        ├─────────────┤
        │   -0.642093 │
        │         inf │
        │    0.642093 │
        └─────────────┘
        """
        return ops.Cot(self).to_expr()

    def sin(self) -> NumericValue:
        """Compute the sine of `self`.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [-1, 0, 1]})
        >>> t.values.sin()
        ┏━━━━━━━━━━━━━┓
        ┃ Sin(values) ┃
        ┡━━━━━━━━━━━━━┩
        │ float64     │
        ├─────────────┤
        │   -0.841471 │
        │    0.000000 │
        │    0.841471 │
        └─────────────┘
        """
        return ops.Sin(self).to_expr()

    def tan(self) -> NumericValue:
        """Compute the tangent of `self`.

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"values": [-1, 0, 1]})
        >>> t.values.tan()
        ┏━━━━━━━━━━━━━┓
        ┃ Tan(values) ┃
        ┡━━━━━━━━━━━━━┩
        │ float64     │
        ├─────────────┤
        │   -1.557408 │
        │    0.000000 │
        │    1.557408 │
        └─────────────┘
        """
        return ops.Tan(self).to_expr()

    def __add__(self, other: NumericValue) -> NumericValue | NotImplemented:
        """Add `self` with `other`."""
        return _binop(ops.Add, self, other)

    add = radd = __radd__ = __add__

    def __sub__(self, other: NumericValue) -> NumericValue | NotImplemented:
        """Subtract `other` from `self`."""
        return _binop(ops.Subtract, self, other)

    sub = __sub__

    def __rsub__(self, other: NumericValue) -> NumericValue | NotImplemented:
        """Subtract `self` from `other`."""
        return _binop(ops.Subtract, other, self)

    rsub = __rsub__

    def __mul__(self, other: NumericValue) -> NumericValue | NotImplemented:
        """Multiply `self` and `other`."""
        return _binop(ops.Multiply, self, other)

    mul = rmul = __rmul__ = __mul__

    def __truediv__(self, other):
        """Divide `self` by `other`."""
        return _binop(ops.Divide, self, other)

    div = __div__ = __truediv__

    def __rtruediv__(self, other: NumericValue) -> NumericValue | NotImplemented:
        """Divide `other` by `self`."""
        return _binop(ops.Divide, other, self)

    rdiv = __rdiv__ = __rtruediv__

    def __floordiv__(
        self,
        other: NumericValue,
    ) -> NumericValue | NotImplemented:
        """Floor divide `self` by `other`."""
        return _binop(ops.FloorDivide, self, other)

    floordiv = __floordiv__

    def __rfloordiv__(
        self,
        other: NumericValue,
    ) -> NumericValue | NotImplemented:
        """Floor divide `other` by `self`."""
        return _binop(ops.FloorDivide, other, self)

    rfloordiv = __rfloordiv__

    def __pow__(self, other: NumericValue) -> NumericValue | NotImplemented:
        """Raise `self` to the `other`th power."""
        return _binop(ops.Power, self, other)

    pow = __pow__

    def __rpow__(self, other: NumericValue) -> NumericValue | NotImplemented:
        """Raise `other` to the `self`th power."""
        return _binop(ops.Power, other, self)

    rpow = __rpow__

    def __mod__(self, other: NumericValue) -> NumericValue | NotImplemented:
        """Compute `self` modulo `other`."""
        return _binop(ops.Modulus, self, other)

    mod = __mod__

    def __rmod__(self, other: NumericValue) -> NumericValue | NotImplemented:
        """Compute `other` modulo `self`."""

        return _binop(ops.Modulus, other, self)

    rmod = __rmod__

    def point(self, right: int | float | NumericValue) -> ir.PointValue:
        """Return a point constructed from the coordinate values.

        Constant coordinates result in construction of a `POINT` literal or
        column.

        Parameters
        ----------
        right
            Y coordinate

        Returns
        -------
        PointValue
            Points
        """
        return ops.GeoPoint(self, right).to_expr()

Functions¶

`abs()` ¶

Return the absolute value of self.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 2, -3, 4]})
>>> t.values.abs()
┏━━━━━━━━━━━━━┓
┃ Abs(values) ┃
┡━━━━━━━━━━━━━┩
│ int64       │
├─────────────┤
│           1 │
│           2 │
│           3 │
│           4 │
└─────────────┘

Source code in ibis/expr/types/numeric.py

def abs(self) -> NumericValue:
    """Return the absolute value of `self`.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [-1, 2, -3, 4]})
    >>> t.values.abs()
    ┏━━━━━━━━━━━━━┓
    ┃ Abs(values) ┃
    ┡━━━━━━━━━━━━━┩
    │ int64       │
    ├─────────────┤
    │           1 │
    │           2 │
    │           3 │
    │           4 │
    └─────────────┘
    """
    return ops.Abs(self).to_expr()

`acos()` ¶

Compute the arc cosine of self.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.acos()
┏━━━━━━━━━━━━━━┓
┃ Acos(values) ┃
┡━━━━━━━━━━━━━━┩
│ float64      │
├──────────────┤
│     3.141593 │
│     1.570796 │
│     0.000000 │
└──────────────┘

Source code in ibis/expr/types/numeric.py

def acos(self) -> NumericValue:
    """Compute the arc cosine of `self`.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [-1, 0, 1]})
    >>> t.values.acos()
    ┏━━━━━━━━━━━━━━┓
    ┃ Acos(values) ┃
    ┡━━━━━━━━━━━━━━┩
    │ float64      │
    ├──────────────┤
    │     3.141593 │
    │     1.570796 │
    │     0.000000 │
    └──────────────┘

    """
    return ops.Acos(self).to_expr()

`asin()` ¶

Compute the arc sine of self.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.asin()
┏━━━━━━━━━━━━━━┓
┃ Asin(values) ┃
┡━━━━━━━━━━━━━━┩
│ float64      │
├──────────────┤
│    -1.570796 │
│     0.000000 │
│     1.570796 │
└──────────────┘

Source code in ibis/expr/types/numeric.py

def asin(self) -> NumericValue:
    """Compute the arc sine of `self`.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [-1, 0, 1]})
    >>> t.values.asin()
    ┏━━━━━━━━━━━━━━┓
    ┃ Asin(values) ┃
    ┡━━━━━━━━━━━━━━┩
    │ float64      │
    ├──────────────┤
    │    -1.570796 │
    │     0.000000 │
    │     1.570796 │
    └──────────────┘
    """
    return ops.Asin(self).to_expr()

`atan()` ¶

Compute the arc tangent of self.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.atan()
┏━━━━━━━━━━━━━━┓
┃ Atan(values) ┃
┡━━━━━━━━━━━━━━┩
│ float64      │
├──────────────┤
│    -0.785398 │
│     0.000000 │
│     0.785398 │
└──────────────┘

Source code in ibis/expr/types/numeric.py

def atan(self) -> NumericValue:
    """Compute the arc tangent of `self`.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [-1, 0, 1]})
    >>> t.values.atan()
    ┏━━━━━━━━━━━━━━┓
    ┃ Atan(values) ┃
    ┡━━━━━━━━━━━━━━┩
    │ float64      │
    ├──────────────┤
    │    -0.785398 │
    │     0.000000 │
    │     0.785398 │
    └──────────────┘
    """
    return ops.Atan(self).to_expr()

`atan2(other)` ¶

Compute the two-argument version of arc tangent.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.atan2(0)
┏━━━━━━━━━━━━━━━━━━┓
┃ Atan2(values, 0) ┃
┡━━━━━━━━━━━━━━━━━━┩
│ float64          │
├──────────────────┤
│        -1.570796 │
│         0.000000 │
│         1.570796 │
└──────────────────┘

Source code in ibis/expr/types/numeric.py

def atan2(self, other: NumericValue) -> NumericValue:
    """Compute the two-argument version of arc tangent.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [-1, 0, 1]})
    >>> t.values.atan2(0)
    ┏━━━━━━━━━━━━━━━━━━┓
    ┃ Atan2(values, 0) ┃
    ┡━━━━━━━━━━━━━━━━━━┩
    │ float64          │
    ├──────────────────┤
    │        -1.570796 │
    │         0.000000 │
    │         1.570796 │
    └──────────────────┘
    """
    return ops.Atan2(self, other).to_expr()

`ceil()` ¶

Return the ceiling of self.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1, 1.1, 2, 2.1, 3.3]})
>>> t.values.ceil()
┏━━━━━━━━━━━━━━┓
┃ Ceil(values) ┃
┡━━━━━━━━━━━━━━┩
│ int64        │
├──────────────┤
│            1 │
│            2 │
│            2 │
│            3 │
│            4 │
└──────────────┘

Source code in ibis/expr/types/numeric.py

def ceil(self) -> DecimalValue | IntegerValue:
    """Return the ceiling of `self`.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [1, 1.1, 2, 2.1, 3.3]})
    >>> t.values.ceil()
    ┏━━━━━━━━━━━━━━┓
    ┃ Ceil(values) ┃
    ┡━━━━━━━━━━━━━━┩
    │ int64        │
    ├──────────────┤
    │            1 │
    │            2 │
    │            2 │
    │            3 │
    │            4 │
    └──────────────┘
    """
    return ops.Ceil(self).to_expr()

`clip(lower=None, upper=None)` ¶

Trim values outside of lower and upper bounds.

Parameters:

Name	Type	Description	Default
`lower`	`NumericValue \| None`	Lower bound	`None`
`upper`	`NumericValue \| None`	Upper bound	`None`

Returns:

Type	Description
`NumericValue`	Clipped input

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": range(8)})
>>> t.values.clip(lower=3, upper=6)
┏━━━━━━━━━━━━━━━━━━━━┓
┃ Clip(values, 3, 6) ┃
┡━━━━━━━━━━━━━━━━━━━━┩
│ int64              │
├────────────────────┤
│                  3 │
│                  3 │
│                  3 │
│                  3 │
│                  4 │
│                  5 │
│                  6 │
│                  6 │
└────────────────────┘

Source code in ibis/expr/types/numeric.py

def clip(
    self,
    lower: NumericValue | None = None,
    upper: NumericValue | None = None,
) -> NumericValue:
    """Trim values outside of `lower` and `upper` bounds.

    Parameters
    ----------
    lower
        Lower bound
    upper
        Upper bound

    Returns
    -------
    NumericValue
        Clipped input

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": range(8)})
    >>> t.values.clip(lower=3, upper=6)
    ┏━━━━━━━━━━━━━━━━━━━━┓
    ┃ Clip(values, 3, 6) ┃
    ┡━━━━━━━━━━━━━━━━━━━━┩
    │ int64              │
    ├────────────────────┤
    │                  3 │
    │                  3 │
    │                  3 │
    │                  3 │
    │                  4 │
    │                  5 │
    │                  6 │
    │                  6 │
    └────────────────────┘
    """
    if lower is None and upper is None:
        raise ValueError("at least one of lower and upper must be provided")

    return ops.Clip(self, lower, upper).to_expr()

`cos()` ¶

Compute the cosine of self.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.cos()
┏━━━━━━━━━━━━━┓
┃ Cos(values) ┃
┡━━━━━━━━━━━━━┩
│ float64     │
├─────────────┤
│    0.540302 │
│    1.000000 │
│    0.540302 │
└─────────────┘

Source code in ibis/expr/types/numeric.py

def cos(self) -> NumericValue:
    """Compute the cosine of `self`.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [-1, 0, 1]})
    >>> t.values.cos()
    ┏━━━━━━━━━━━━━┓
    ┃ Cos(values) ┃
    ┡━━━━━━━━━━━━━┩
    │ float64     │
    ├─────────────┤
    │    0.540302 │
    │    1.000000 │
    │    0.540302 │
    └─────────────┘
    """
    return ops.Cos(self).to_expr()

`cot()` ¶

Compute the cotangent of self.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.cot()
┏━━━━━━━━━━━━━┓
┃ Cot(values) ┃
┡━━━━━━━━━━━━━┩
│ float64     │
├─────────────┤
│   -0.642093 │
│         inf │
│    0.642093 │
└─────────────┘

Source code in ibis/expr/types/numeric.py

def cot(self) -> NumericValue:
    """Compute the cotangent of `self`.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [-1, 0, 1]})
    >>> t.values.cot()
    ┏━━━━━━━━━━━━━┓
    ┃ Cot(values) ┃
    ┡━━━━━━━━━━━━━┩
    │ float64     │
    ├─────────────┤
    │   -0.642093 │
    │         inf │
    │    0.642093 │
    └─────────────┘
    """
    return ops.Cot(self).to_expr()

`degrees()` ¶

Compute the degrees of self radians.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> from math import pi
>>> t = ibis.memtable({"values": [0, pi / 2, pi, 3 * pi / 2, 2 * pi]})
>>> t.values.degrees()
┏━━━━━━━━━━━━━━━━━┓
┃ Degrees(values) ┃
┡━━━━━━━━━━━━━━━━━┩
│ float64         │
├─────────────────┤
│             0.0 │
│            90.0 │
│           180.0 │
│           270.0 │
│           360.0 │
└─────────────────┘

Source code in ibis/expr/types/numeric.py

def degrees(self) -> NumericValue:
    """Compute the degrees of `self` radians.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> from math import pi
    >>> t = ibis.memtable({"values": [0, pi / 2, pi, 3 * pi / 2, 2 * pi]})
    >>> t.values.degrees()
    ┏━━━━━━━━━━━━━━━━━┓
    ┃ Degrees(values) ┃
    ┡━━━━━━━━━━━━━━━━━┩
    │ float64         │
    ├─────────────────┤
    │             0.0 │
    │            90.0 │
    │           180.0 │
    │           270.0 │
    │           360.0 │
    └─────────────────┘
    """
    return ops.Degrees(self).to_expr()

`exp()` ¶

Compute \(e^\texttt{self}\).

Returns:

Type	Description
`NumericValue`	\(e^\texttt{self}\)

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": range(4)})
>>> t.values.exp()
┏━━━━━━━━━━━━━┓
┃ Exp(values) ┃
┡━━━━━━━━━━━━━┩
│ float64     │
├─────────────┤
│    1.000000 │
│    2.718282 │
│    7.389056 │
│   20.085537 │
└─────────────┘

Source code in ibis/expr/types/numeric.py

def exp(self) -> NumericValue:
    r"""Compute $e^\texttt{self}$.

    Returns
    -------
    NumericValue
        $e^\texttt{self}$

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": range(4)})
    >>> t.values.exp()
    ┏━━━━━━━━━━━━━┓
    ┃ Exp(values) ┃
    ┡━━━━━━━━━━━━━┩
    │ float64     │
    ├─────────────┤
    │    1.000000 │
    │    2.718282 │
    │    7.389056 │
    │   20.085537 │
    └─────────────┘
    """
    return ops.Exp(self).to_expr()

`floor()` ¶

Return the floor of an expression.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1, 1.1, 2, 2.1, 3.3]})
>>> t.values.floor()
┏━━━━━━━━━━━━━━━┓
┃ Floor(values) ┃
┡━━━━━━━━━━━━━━━┩
│ int64         │
├───────────────┤
│             1 │
│             1 │
│             2 │
│             2 │
│             3 │
└───────────────┘

Source code in ibis/expr/types/numeric.py

def floor(self) -> DecimalValue | IntegerValue:
    """Return the floor of an expression.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [1, 1.1, 2, 2.1, 3.3]})
    >>> t.values.floor()
    ┏━━━━━━━━━━━━━━━┓
    ┃ Floor(values) ┃
    ┡━━━━━━━━━━━━━━━┩
    │ int64         │
    ├───────────────┤
    │             1 │
    │             1 │
    │             2 │
    │             2 │
    │             3 │
    └───────────────┘

    """
    return ops.Floor(self).to_expr()

`ln()` ¶

Compute \(\ln\left(\texttt{self}\right)\).

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1, 2.718281828, 3]})
>>> t.values.ln()
┏━━━━━━━━━━━━┓
┃ Ln(values) ┃
┡━━━━━━━━━━━━┩
│ float64    │
├────────────┤
│   0.000000 │
│   1.000000 │
│   1.098612 │
└────────────┘

Source code in ibis/expr/types/numeric.py

def ln(self) -> NumericValue:
    r"""Compute $\ln\left(\texttt{self}\right)$.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [1, 2.718281828, 3]})
    >>> t.values.ln()
    ┏━━━━━━━━━━━━┓
    ┃ Ln(values) ┃
    ┡━━━━━━━━━━━━┩
    │ float64    │
    ├────────────┤
    │   0.000000 │
    │   1.000000 │
    │   1.098612 │
    └────────────┘
    """
    return ops.Ln(self).to_expr()

`log(base=None)` ¶

Compute \(\log_{\texttt{base}}\left(\texttt{self}\right)\).

Parameters:

Name	Type	Description	Default
`base`	`NumericValue \| None`	The base of the logarithm. If `None`, base `e` is used.	`None`

Returns:

Type	Description
`NumericValue`	Logarithm of `arg` with base `base`

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> from math import e
>>> t = ibis.memtable({"values": [e, e**2, e**3]})
>>> t.values.log()
┏━━━━━━━━━━━━━┓
┃ Log(values) ┃
┡━━━━━━━━━━━━━┩
│ float64     │
├─────────────┤
│         1.0 │
│         2.0 │
│         3.0 │
└─────────────┘

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [10, 100, 1000]})
>>> t.values.log(base=10)
┏━━━━━━━━━━━━━━━━━┓
┃ Log(values, 10) ┃
┡━━━━━━━━━━━━━━━━━┩
│ float64         │
├─────────────────┤
│             1.0 │
│             2.0 │
│             3.0 │
└─────────────────┘

Source code in ibis/expr/types/numeric.py

def log(self, base: NumericValue | None = None) -> NumericValue:
    r"""Compute $\log_{\texttt{base}}\left(\texttt{self}\right)$.

    Parameters
    ----------
    base
        The base of the logarithm. If `None`, base `e` is used.

    Returns
    -------
    NumericValue
        Logarithm of `arg` with base `base`

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> from math import e
    >>> t = ibis.memtable({"values": [e, e**2, e**3]})
    >>> t.values.log()
    ┏━━━━━━━━━━━━━┓
    ┃ Log(values) ┃
    ┡━━━━━━━━━━━━━┩
    │ float64     │
    ├─────────────┤
    │         1.0 │
    │         2.0 │
    │         3.0 │
    └─────────────┘


    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [10, 100, 1000]})
    >>> t.values.log(base=10)
    ┏━━━━━━━━━━━━━━━━━┓
    ┃ Log(values, 10) ┃
    ┡━━━━━━━━━━━━━━━━━┩
    │ float64         │
    ├─────────────────┤
    │             1.0 │
    │             2.0 │
    │             3.0 │
    └─────────────────┘
    """
    return ops.Log(self, base).to_expr()

`log10()` ¶

Compute \(\log_{10}\left(\texttt{self}\right)\).

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1, 10, 100]})
>>> t.values.log10()
┏━━━━━━━━━━━━━━━┓
┃ Log10(values) ┃
┡━━━━━━━━━━━━━━━┩
│ float64       │
├───────────────┤
│           0.0 │
│           1.0 │
│           2.0 │
└───────────────┘

Source code in ibis/expr/types/numeric.py

def log10(self) -> NumericValue:
    r"""Compute $\log_{10}\left(\texttt{self}\right)$.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [1, 10, 100]})
    >>> t.values.log10()
    ┏━━━━━━━━━━━━━━━┓
    ┃ Log10(values) ┃
    ┡━━━━━━━━━━━━━━━┩
    │ float64       │
    ├───────────────┤
    │           0.0 │
    │           1.0 │
    │           2.0 │
    └───────────────┘
    """
    return ops.Log10(self).to_expr()

`log2()` ¶

Compute \(\log_{2}\left(\texttt{self}\right)\).

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1, 2, 4, 8]})
>>> t.values.log2()
┏━━━━━━━━━━━━━━┓
┃ Log2(values) ┃
┡━━━━━━━━━━━━━━┩
│ float64      │
├──────────────┤
│          0.0 │
│          1.0 │
│          2.0 │
│          3.0 │
└──────────────┘

Source code in ibis/expr/types/numeric.py

def log2(self) -> NumericValue:
    r"""Compute $\log_{2}\left(\texttt{self}\right)$.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [1, 2, 4, 8]})
    >>> t.values.log2()
    ┏━━━━━━━━━━━━━━┓
    ┃ Log2(values) ┃
    ┡━━━━━━━━━━━━━━┩
    │ float64      │
    ├──────────────┤
    │          0.0 │
    │          1.0 │
    │          2.0 │
    │          3.0 │
    └──────────────┘
    """
    return ops.Log2(self).to_expr()

`negate()` ¶

Negate a numeric expression.

Returns:

Type	Description
`NumericValue`	A numeric value expression

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.negate()
┏━━━━━━━━━━━━━━━━┓
┃ Negate(values) ┃
┡━━━━━━━━━━━━━━━━┩
│ int64          │
├────────────────┤
│              1 │
│              0 │
│             -1 │
└────────────────┘

Source code in ibis/expr/types/numeric.py

def negate(self) -> NumericValue:
    """Negate a numeric expression.

    Returns
    -------
    NumericValue
        A numeric value expression

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [-1, 0, 1]})
    >>> t.values.negate()
    ┏━━━━━━━━━━━━━━━━┓
    ┃ Negate(values) ┃
    ┡━━━━━━━━━━━━━━━━┩
    │ int64          │
    ├────────────────┤
    │              1 │
    │              0 │
    │             -1 │
    └────────────────┘
    """
    op = self.op()
    try:
        result = op.negate()
    except AttributeError:
        op_class = self.__negate_op__()
        result = op_class(self)

    return result.to_expr()

`nullifzero()` ¶

Return NULL if an expression is zero.

Source code in ibis/expr/types/numeric.py

def nullifzero(self) -> NumericValue:
    """Return `NULL` if an expression is zero."""
    return ops.NullIfZero(self).to_expr()

`point(right)` ¶

Return a point constructed from the coordinate values.

Constant coordinates result in construction of a POINT literal or column.

Parameters:

Name	Type	Description	Default
`right`	`int \| float \| NumericValue`	Y coordinate	required

Returns:

Type	Description
`PointValue`	Points

Source code in ibis/expr/types/numeric.py

def point(self, right: int | float | NumericValue) -> ir.PointValue:
    """Return a point constructed from the coordinate values.

    Constant coordinates result in construction of a `POINT` literal or
    column.

    Parameters
    ----------
    right
        Y coordinate

    Returns
    -------
    PointValue
        Points
    """
    return ops.GeoPoint(self, right).to_expr()

`radians()` ¶

Compute radians from self degrees.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [0, 90, 180, 270, 360]})
>>> t.values.radians()
┏━━━━━━━━━━━━━━━━━┓
┃ Radians(values) ┃
┡━━━━━━━━━━━━━━━━━┩
│ float64         │
├─────────────────┤
│        0.000000 │
│        1.570796 │
│        3.141593 │
│        4.712389 │
│        6.283185 │
└─────────────────┘

Source code in ibis/expr/types/numeric.py

def radians(self) -> NumericValue:
    """Compute radians from `self` degrees.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [0, 90, 180, 270, 360]})
    >>> t.values.radians()
    ┏━━━━━━━━━━━━━━━━━┓
    ┃ Radians(values) ┃
    ┡━━━━━━━━━━━━━━━━━┩
    │ float64         │
    ├─────────────────┤
    │        0.000000 │
    │        1.570796 │
    │        3.141593 │
    │        4.712389 │
    │        6.283185 │
    └─────────────────┘
    """
    return ops.Radians(self).to_expr()

`round(digits=None)` ¶

Round values to an indicated number of decimal places.

Parameters:

Name Type Description Default

digits

int | IntegerValue | None

The number of digits to round to.

Here's how the digits parameter affects the expression output type:

`digits`	`self.type()`	Output
`None` or `0`	`decimal`	`decimal`
Nonzero	`decimal`	`decimal`
`None` or `0`	Floating	`int64`
Nonzero	Floating	`float64`

None

Returns:

Type	Description
`NumericValue`	The rounded expression

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1.22, 1.64, 2.15, 2.54]})
>>> t
┏━━━━━━━━━┓
┃ values  ┃
┡━━━━━━━━━┩
│ float64 │
├─────────┤
│    1.22 │
│    1.64 │
│    2.15 │
│    2.54 │
└─────────┘
>>> t.values.round()
┏━━━━━━━━━━━━━━━┓
┃ Round(values) ┃
┡━━━━━━━━━━━━━━━┩
│ int64         │
├───────────────┤
│             1 │
│             2 │
│             2 │
│             3 │
└───────────────┘
>>> t.values.round(digits=1)
┏━━━━━━━━━━━━━━━━━━┓
┃ Round(values, 1) ┃
┡━━━━━━━━━━━━━━━━━━┩
│ float64          │
├──────────────────┤
│              1.2 │
│              1.6 │
│              2.2 │
│              2.5 │
└──────────────────┘

Source code in ibis/expr/types/numeric.py

def round(self, digits: int | IntegerValue | None = None) -> NumericValue:
    """Round values to an indicated number of decimal places.

    Parameters
    ----------
    digits
        The number of digits to round to.

        Here's how the `digits` parameter affects the expression output
        type:

        |   `digits`    | `self.type()` |  Output   |
        | :-----------: | :-----------: | :-------: |
        | `None` or `0` |   `decimal`   | `decimal` |
        |    Nonzero    |   `decimal`   | `decimal` |
        | `None` or `0` |   Floating    |  `int64`  |
        |    Nonzero    |   Floating    | `float64` |

    Returns
    -------
    NumericValue
        The rounded expression

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [1.22, 1.64, 2.15, 2.54]})
    >>> t
    ┏━━━━━━━━━┓
    ┃ values  ┃
    ┡━━━━━━━━━┩
    │ float64 │
    ├─────────┤
    │    1.22 │
    │    1.64 │
    │    2.15 │
    │    2.54 │
    └─────────┘
    >>> t.values.round()
    ┏━━━━━━━━━━━━━━━┓
    ┃ Round(values) ┃
    ┡━━━━━━━━━━━━━━━┩
    │ int64         │
    ├───────────────┤
    │             1 │
    │             2 │
    │             2 │
    │             3 │
    └───────────────┘
    >>> t.values.round(digits=1)
    ┏━━━━━━━━━━━━━━━━━━┓
    ┃ Round(values, 1) ┃
    ┡━━━━━━━━━━━━━━━━━━┩
    │ float64          │
    ├──────────────────┤
    │              1.2 │
    │              1.6 │
    │              2.2 │
    │              2.5 │
    └──────────────────┘
    """
    return ops.Round(self, digits).to_expr()

`sign()` ¶

Return the sign of the input.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 2, -3, 4]})
>>> t.values.sign()
┏━━━━━━━━━━━━━━┓
┃ Sign(values) ┃
┡━━━━━━━━━━━━━━┩
│ int64        │
├──────────────┤
│           -1 │
│            1 │
│           -1 │
│            1 │
└──────────────┘

Source code in ibis/expr/types/numeric.py

def sign(self) -> NumericValue:
    """Return the sign of the input.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [-1, 2, -3, 4]})
    >>> t.values.sign()
    ┏━━━━━━━━━━━━━━┓
    ┃ Sign(values) ┃
    ┡━━━━━━━━━━━━━━┩
    │ int64        │
    ├──────────────┤
    │           -1 │
    │            1 │
    │           -1 │
    │            1 │
    └──────────────┘
    """
    return ops.Sign(self).to_expr()

`sin()` ¶

Compute the sine of self.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.sin()
┏━━━━━━━━━━━━━┓
┃ Sin(values) ┃
┡━━━━━━━━━━━━━┩
│ float64     │
├─────────────┤
│   -0.841471 │
│    0.000000 │
│    0.841471 │
└─────────────┘

Source code in ibis/expr/types/numeric.py

def sin(self) -> NumericValue:
    """Compute the sine of `self`.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [-1, 0, 1]})
    >>> t.values.sin()
    ┏━━━━━━━━━━━━━┓
    ┃ Sin(values) ┃
    ┡━━━━━━━━━━━━━┩
    │ float64     │
    ├─────────────┤
    │   -0.841471 │
    │    0.000000 │
    │    0.841471 │
    └─────────────┘
    """
    return ops.Sin(self).to_expr()

`sqrt()` ¶

Compute the square root of self.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1, 4, 9, 16]})
>>> t.values.sqrt()
┏━━━━━━━━━━━━━━┓
┃ Sqrt(values) ┃
┡━━━━━━━━━━━━━━┩
│ float64      │
├──────────────┤
│          1.0 │
│          2.0 │
│          3.0 │
│          4.0 │
└──────────────┘

Source code in ibis/expr/types/numeric.py

def sqrt(self) -> NumericValue:
    """Compute the square root of `self`.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [1, 4, 9, 16]})
    >>> t.values.sqrt()
    ┏━━━━━━━━━━━━━━┓
    ┃ Sqrt(values) ┃
    ┡━━━━━━━━━━━━━━┩
    │ float64      │
    ├──────────────┤
    │          1.0 │
    │          2.0 │
    │          3.0 │
    │          4.0 │
    └──────────────┘
    """
    return ops.Sqrt(self).to_expr()

`tan()` ¶

Compute the tangent of self.

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.tan()
┏━━━━━━━━━━━━━┓
┃ Tan(values) ┃
┡━━━━━━━━━━━━━┩
│ float64     │
├─────────────┤
│   -1.557408 │
│    0.000000 │
│    1.557408 │
└─────────────┘

Source code in ibis/expr/types/numeric.py

def tan(self) -> NumericValue:
    """Compute the tangent of `self`.

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"values": [-1, 0, 1]})
    >>> t.values.tan()
    ┏━━━━━━━━━━━━━┓
    ┃ Tan(values) ┃
    ┡━━━━━━━━━━━━━┩
    │ float64     │
    ├─────────────┤
    │   -1.557408 │
    │    0.000000 │
    │    1.557408 │
    └─────────────┘
    """
    return ops.Tan(self).to_expr()

`zeroifnull()` ¶

Return zero if an expression is NULL.

Source code in ibis/expr/types/numeric.py

def zeroifnull(self) -> NumericValue:
    """Return zero if an expression is `NULL`."""
    return ops.ZeroIfNull(self).to_expr()

`NumericColumn` ¶

Bases: Column, NumericValue

Source code in ibis/expr/types/numeric.py

@public
class NumericColumn(Column, NumericValue):
    def median(self, where: ir.BooleanValue | None = None) -> NumericScalar:
        """Return the median of the column.

        Parameters
        ----------
        where
            Optional boolean expression. If given, only the values where
            `where` evaluates to true will be considered for the median.

        Returns
        -------
        NumericScalar
            Median of the column
        """
        return ops.Median(self, where=where).to_expr()

    def quantile(
        self,
        quantile: Sequence[NumericValue | float],
        interpolation: Literal[
            "linear",
            "lower",
            "higher",
            "midpoint",
            "nearest",
        ]
        | None = None,
        where: ir.BooleanValue | None = None,
    ) -> NumericScalar:
        """Return value at the given quantile.

        Parameters
        ----------
        quantile
            `0 <= quantile <= 1`, the quantile(s) to compute
        interpolation
            !!! warning "This parameter is backend dependent and may have no effect"

            This parameter specifies the interpolation method to use, when the
            desired quantile lies between two data points `i` and `j`:

            * linear: `i + (j - i) * fraction`, where `fraction` is the
              fractional part of the index surrounded by `i` and `j`.
            * lower: `i`.
            * higher: `j`.
            * nearest: `i` or `j` whichever is nearest.
            * midpoint: (`i` + `j`) / 2.
        where
            Boolean filter for input values

        Returns
        -------
        NumericScalar
            Quantile of the input
        """
        if isinstance(quantile, collections.abc.Sequence):
            op = ops.MultiQuantile
        else:
            op = ops.Quantile
        return op(self, quantile, interpolation, where=where).to_expr()

    def std(
        self,
        where: ir.BooleanValue | None = None,
        how: Literal["sample", "pop"] = "sample",
    ) -> NumericScalar:
        """Return the standard deviation of a numeric column.

        Parameters
        ----------
        where
            Filter
        how
            Sample or population standard deviation

        Returns
        -------
        NumericScalar
            Standard deviation of `arg`
        """
        return ops.StandardDev(self, how=how, where=where).to_expr()

    def var(
        self,
        where: ir.BooleanValue | None = None,
        how: Literal["sample", "pop"] = "sample",
    ) -> NumericScalar:
        """Return the variance of a numeric column.

        Parameters
        ----------
        where
            Filter
        how
            Sample or population variance

        Returns
        -------
        NumericScalar
            Standard deviation of `arg`
        """
        return ops.Variance(self, how=how, where=where).to_expr()

    def corr(
        self,
        right: NumericColumn,
        where: ir.BooleanValue | None = None,
        how: Literal['sample', 'pop'] = 'sample',
    ) -> NumericScalar:
        """Return the correlation of two numeric columns.

        Parameters
        ----------
        right
            Numeric column
        where
            Filter
        how
            Population or sample correlation

        Returns
        -------
        NumericScalar
            The correlation of `left` and `right`
        """
        return ops.Correlation(self, right, how=how, where=where).to_expr()

    def cov(
        self,
        right: NumericColumn,
        where: ir.BooleanValue | None = None,
        how: Literal['sample', 'pop'] = 'sample',
    ) -> NumericScalar:
        """Return the covariance of two numeric columns.

        Parameters
        ----------
        right
            Numeric column
        where
            Filter
        how
            Population or sample covariance

        Returns
        -------
        NumericScalar
            The covariance of `self` and `right`
        """
        return ops.Covariance(self, right, how=how, where=where).to_expr()

    def mean(
        self,
        where: ir.BooleanValue | None = None,
    ) -> NumericScalar:
        """Return the mean of a numeric column.

        Parameters
        ----------
        where
            Filter

        Returns
        -------
        NumericScalar
            The mean of the input expression
        """
        # TODO(kszucs): remove the alias from the reduction method in favor
        # of default name generated by ops.Value operations
        return ops.Mean(self, where=where).to_expr()

    def cummean(self) -> NumericColumn:
        """Return the cumulative mean of the input."""
        return ops.CumulativeMean(self).to_expr()

    def sum(
        self,
        where: ir.BooleanValue | None = None,
    ) -> NumericScalar:
        """Return the sum of a numeric column.

        Parameters
        ----------
        where
            Filter

        Returns
        -------
        NumericScalar
            The sum of the input expression
        """
        return ops.Sum(self, where=where).to_expr()

    def cumsum(self) -> NumericColumn:
        """Return the cumulative sum of the input."""
        return ops.CumulativeSum(self).to_expr()

    def bucket(
        self,
        buckets: Sequence[int],
        closed: Literal["left", "right"] = "left",
        close_extreme: bool = True,
        include_under: bool = False,
        include_over: bool = False,
    ) -> ir.IntegerColumn:
        """Compute a discrete binning of a numeric array.

        Parameters
        ----------
        buckets
            List of buckets
        closed
            Which side of each interval is closed. For example:

            ```python
            buckets = [0, 100, 200]
            closed = "left"  # 100 falls in 2nd bucket
            closed = "right"  # 100 falls in 1st bucket
            ```
        close_extreme
            Whether the extreme values fall in the last bucket
        include_over
            Include values greater than the last bucket in the last bucket
        include_under
            Include values less than the first bucket in the first bucket

        Returns
        -------
        IntegerColumn
            A categorical column expression
        """
        return ops.Bucket(
            self,
            buckets,
            closed=closed,
            close_extreme=close_extreme,
            include_under=include_under,
            include_over=include_over,
        ).to_expr()

    def histogram(
        self,
        nbins: int | None = None,
        binwidth: float | None = None,
        base: float | None = None,
        eps: float = 1e-13,
    ):
        """Compute a histogram with fixed width bins.

        Parameters
        ----------
        nbins
            If supplied, will be used to compute the binwidth
        binwidth
            If not supplied, computed from the data (actual max and min values)
        base
            The value of the first histogram bin. Defaults to the minimum value
            of `column`.
        eps
            Allowed floating point epsilon for histogram base

        Returns
        -------
        Column
            Bucketed column
        """

        if nbins is not None and binwidth is not None:
            raise ValueError(
                f"Cannot pass both `nbins` (got {nbins}) and `binwidth` (got {binwidth})"
            )

        if binwidth is None or base is None:
            import ibis

            if nbins is None:
                raise ValueError("`nbins` is required if `binwidth` is not provided")

            empty_window = ibis.window()

            if base is None:
                base = self.min().over(empty_window) - eps

            binwidth = (self.max().over(empty_window) - base) / (nbins - 1)

        return ((self - base) / binwidth).floor()

Functions¶

`bucket(buckets, closed='left', close_extreme=True, include_under=False, include_over=False)` ¶

Compute a discrete binning of a numeric array.

Parameters:

Name	Type	Description	Default
`buckets`	`Sequence[int]`	List of buckets	required
`closed`	`Literal['left', 'right']`	Which side of each interval is closed. For example: `buckets = [0, 100, 200] closed = "left" # 100 falls in 2nd bucket closed = "right" # 100 falls in 1st bucket`	`'left'`
`close_extreme`	`bool`	Whether the extreme values fall in the last bucket	`True`
`include_over`	`bool`	Include values greater than the last bucket in the last bucket	`False`
`include_under`	`bool`	Include values less than the first bucket in the first bucket	`False`

Returns:

Type	Description
`IntegerColumn`	A categorical column expression

Source code in ibis/expr/types/numeric.py

def bucket(
    self,
    buckets: Sequence[int],
    closed: Literal["left", "right"] = "left",
    close_extreme: bool = True,
    include_under: bool = False,
    include_over: bool = False,
) -> ir.IntegerColumn:
    """Compute a discrete binning of a numeric array.

    Parameters
    ----------
    buckets
        List of buckets
    closed
        Which side of each interval is closed. For example:

        ```python
        buckets = [0, 100, 200]
        closed = "left"  # 100 falls in 2nd bucket
        closed = "right"  # 100 falls in 1st bucket
        ```
    close_extreme
        Whether the extreme values fall in the last bucket
    include_over
        Include values greater than the last bucket in the last bucket
    include_under
        Include values less than the first bucket in the first bucket

    Returns
    -------
    IntegerColumn
        A categorical column expression
    """
    return ops.Bucket(
        self,
        buckets,
        closed=closed,
        close_extreme=close_extreme,
        include_under=include_under,
        include_over=include_over,
    ).to_expr()

`corr(right, where=None, how='sample')` ¶

Return the correlation of two numeric columns.

Parameters:

Name	Type	Description	Default
`right`	`NumericColumn`	Numeric column	required
`where`	`ir.BooleanValue \| None`	Filter	`None`
`how`	`Literal['sample', 'pop']`	Population or sample correlation	`'sample'`

Returns:

Type	Description
`NumericScalar`	The correlation of `left` and `right`

Source code in ibis/expr/types/numeric.py

def corr(
    self,
    right: NumericColumn,
    where: ir.BooleanValue | None = None,
    how: Literal['sample', 'pop'] = 'sample',
) -> NumericScalar:
    """Return the correlation of two numeric columns.

    Parameters
    ----------
    right
        Numeric column
    where
        Filter
    how
        Population or sample correlation

    Returns
    -------
    NumericScalar
        The correlation of `left` and `right`
    """
    return ops.Correlation(self, right, how=how, where=where).to_expr()

`cov(right, where=None, how='sample')` ¶

Return the covariance of two numeric columns.

Parameters:

Name	Type	Description	Default
`right`	`NumericColumn`	Numeric column	required
`where`	`ir.BooleanValue \| None`	Filter	`None`
`how`	`Literal['sample', 'pop']`	Population or sample covariance	`'sample'`

Returns:

Type	Description
`NumericScalar`	The covariance of `self` and `right`

Source code in ibis/expr/types/numeric.py

def cov(
    self,
    right: NumericColumn,
    where: ir.BooleanValue | None = None,
    how: Literal['sample', 'pop'] = 'sample',
) -> NumericScalar:
    """Return the covariance of two numeric columns.

    Parameters
    ----------
    right
        Numeric column
    where
        Filter
    how
        Population or sample covariance

    Returns
    -------
    NumericScalar
        The covariance of `self` and `right`
    """
    return ops.Covariance(self, right, how=how, where=where).to_expr()

`cummean()` ¶

Return the cumulative mean of the input.

Source code in ibis/expr/types/numeric.py

def cummean(self) -> NumericColumn:
    """Return the cumulative mean of the input."""
    return ops.CumulativeMean(self).to_expr()

`cumsum()` ¶

Return the cumulative sum of the input.

Source code in ibis/expr/types/numeric.py

def cumsum(self) -> NumericColumn:
    """Return the cumulative sum of the input."""
    return ops.CumulativeSum(self).to_expr()

`histogram(nbins=None, binwidth=None, base=None, eps=1e-13)` ¶

Compute a histogram with fixed width bins.

Parameters:

Name	Type	Description	Default
`nbins`	`int \| None`	If supplied, will be used to compute the binwidth	`None`
`binwidth`	`float \| None`	If not supplied, computed from the data (actual max and min values)	`None`
`base`	`float \| None`	The value of the first histogram bin. Defaults to the minimum value of `column`.	`None`
`eps`	`float`	Allowed floating point epsilon for histogram base	`1e-13`

Returns:

Type	Description
`Column`	Bucketed column

Source code in ibis/expr/types/numeric.py

def histogram(
    self,
    nbins: int | None = None,
    binwidth: float | None = None,
    base: float | None = None,
    eps: float = 1e-13,
):
    """Compute a histogram with fixed width bins.

    Parameters
    ----------
    nbins
        If supplied, will be used to compute the binwidth
    binwidth
        If not supplied, computed from the data (actual max and min values)
    base
        The value of the first histogram bin. Defaults to the minimum value
        of `column`.
    eps
        Allowed floating point epsilon for histogram base

    Returns
    -------
    Column
        Bucketed column
    """

    if nbins is not None and binwidth is not None:
        raise ValueError(
            f"Cannot pass both `nbins` (got {nbins}) and `binwidth` (got {binwidth})"
        )

    if binwidth is None or base is None:
        import ibis

        if nbins is None:
            raise ValueError("`nbins` is required if `binwidth` is not provided")

        empty_window = ibis.window()

        if base is None:
            base = self.min().over(empty_window) - eps

        binwidth = (self.max().over(empty_window) - base) / (nbins - 1)

    return ((self - base) / binwidth).floor()

`mean(where=None)` ¶

Return the mean of a numeric column.

Parameters:

Name	Type	Description	Default
`where`	`ir.BooleanValue \| None`	Filter	`None`

Returns:

Type	Description
`NumericScalar`	The mean of the input expression

Source code in ibis/expr/types/numeric.py

def mean(
    self,
    where: ir.BooleanValue | None = None,
) -> NumericScalar:
    """Return the mean of a numeric column.

    Parameters
    ----------
    where
        Filter

    Returns
    -------
    NumericScalar
        The mean of the input expression
    """
    # TODO(kszucs): remove the alias from the reduction method in favor
    # of default name generated by ops.Value operations
    return ops.Mean(self, where=where).to_expr()

`median(where=None)` ¶

Return the median of the column.

Parameters:

Name	Type	Description	Default
`where`	`ir.BooleanValue \| None`	Optional boolean expression. If given, only the values where `where` evaluates to true will be considered for the median.	`None`

Returns:

Type	Description
`NumericScalar`	Median of the column

Source code in ibis/expr/types/numeric.py

def median(self, where: ir.BooleanValue | None = None) -> NumericScalar:
    """Return the median of the column.

    Parameters
    ----------
    where
        Optional boolean expression. If given, only the values where
        `where` evaluates to true will be considered for the median.

    Returns
    -------
    NumericScalar
        Median of the column
    """
    return ops.Median(self, where=where).to_expr()

`quantile(quantile, interpolation=None, where=None)` ¶

Return value at the given quantile.

Parameters:

Name	Type	Description	Default
`quantile`	`Sequence[NumericValue \| float]`	`0 <= quantile <= 1`, the quantile(s) to compute	required
`interpolation`	`Literal['linear', 'lower', 'higher', 'midpoint', 'nearest'] \| None`	This parameter is backend dependent and may have no effect This parameter specifies the interpolation method to use, when the desired quantile lies between two data points `i` and `j`: linear: `i + (j - i) * fraction`, where `fraction` is the fractional part of the index surrounded by `i` and `j`. lower: `i`. higher: `j`. nearest: `i` or `j` whichever is nearest. midpoint: (`i` + `j`) / 2.	`None`
`where`	`ir.BooleanValue \| None`	Boolean filter for input values	`None`

Returns:

Type	Description
`NumericScalar`	Quantile of the input

Source code in ibis/expr/types/numeric.py

def quantile(
    self,
    quantile: Sequence[NumericValue | float],
    interpolation: Literal[
        "linear",
        "lower",
        "higher",
        "midpoint",
        "nearest",
    ]
    | None = None,
    where: ir.BooleanValue | None = None,
) -> NumericScalar:
    """Return value at the given quantile.

    Parameters
    ----------
    quantile
        `0 <= quantile <= 1`, the quantile(s) to compute
    interpolation
        !!! warning "This parameter is backend dependent and may have no effect"

        This parameter specifies the interpolation method to use, when the
        desired quantile lies between two data points `i` and `j`:

        * linear: `i + (j - i) * fraction`, where `fraction` is the
          fractional part of the index surrounded by `i` and `j`.
        * lower: `i`.
        * higher: `j`.
        * nearest: `i` or `j` whichever is nearest.
        * midpoint: (`i` + `j`) / 2.
    where
        Boolean filter for input values

    Returns
    -------
    NumericScalar
        Quantile of the input
    """
    if isinstance(quantile, collections.abc.Sequence):
        op = ops.MultiQuantile
    else:
        op = ops.Quantile
    return op(self, quantile, interpolation, where=where).to_expr()

`std(where=None, how='sample')` ¶

Return the standard deviation of a numeric column.

Parameters:

Name	Type	Description	Default
`where`	`ir.BooleanValue \| None`	Filter	`None`
`how`	`Literal['sample', 'pop']`	Sample or population standard deviation	`'sample'`

Returns:

Type	Description
`NumericScalar`	Standard deviation of `arg`

Source code in ibis/expr/types/numeric.py

def std(
    self,
    where: ir.BooleanValue | None = None,
    how: Literal["sample", "pop"] = "sample",
) -> NumericScalar:
    """Return the standard deviation of a numeric column.

    Parameters
    ----------
    where
        Filter
    how
        Sample or population standard deviation

    Returns
    -------
    NumericScalar
        Standard deviation of `arg`
    """
    return ops.StandardDev(self, how=how, where=where).to_expr()

`sum(where=None)` ¶

Return the sum of a numeric column.

Parameters:

Name	Type	Description	Default
`where`	`ir.BooleanValue \| None`	Filter	`None`

Returns:

Type	Description
`NumericScalar`	The sum of the input expression

Source code in ibis/expr/types/numeric.py

def sum(
    self,
    where: ir.BooleanValue | None = None,
) -> NumericScalar:
    """Return the sum of a numeric column.

    Parameters
    ----------
    where
        Filter

    Returns
    -------
    NumericScalar
        The sum of the input expression
    """
    return ops.Sum(self, where=where).to_expr()

`var(where=None, how='sample')` ¶

Return the variance of a numeric column.

Parameters:

Name	Type	Description	Default
`where`	`ir.BooleanValue \| None`	Filter	`None`
`how`	`Literal['sample', 'pop']`	Sample or population variance	`'sample'`

Returns:

Type	Description
`NumericScalar`	Standard deviation of `arg`

Source code in ibis/expr/types/numeric.py

def var(
    self,
    where: ir.BooleanValue | None = None,
    how: Literal["sample", "pop"] = "sample",
) -> NumericScalar:
    """Return the variance of a numeric column.

    Parameters
    ----------
    where
        Filter
    how
        Sample or population variance

    Returns
    -------
    NumericScalar
        Standard deviation of `arg`
    """
    return ops.Variance(self, how=how, where=where).to_expr()

`IntegerValue` ¶

Bases: NumericValue

Source code in ibis/expr/types/numeric.py

@public
class IntegerValue(NumericValue):
    def to_timestamp(
        self,
        unit: Literal["s", "ms", "us"] = "s",
    ) -> ir.TimestampValue:
        """Convert an integral UNIX timestamp to a timestamp expression.

        Parameters
        ----------
        unit
            The resolution of `arg`

        Returns
        -------
        TimestampValue
            `self` converted to a timestamp
        """
        return ops.TimestampFromUNIX(self, unit).to_expr()

    def to_interval(
        self,
        unit: Literal["Y", "M", "W", "D", "h", "m", "s", "ms", "us", "ns"] = "s",
    ) -> ir.IntervalValue:
        """Convert an integer to an interval.

        Parameters
        ----------
        unit
            Unit for the resulting interval

        Returns
        -------
        IntervalValue
            An interval in units of `unit`
        """
        return ops.IntervalFromInteger(self, unit).to_expr()

    def convert_base(
        self,
        from_base: IntegerValue,
        to_base: IntegerValue,
    ) -> IntegerValue:
        """Convert an integer from one base to another.

        Parameters
        ----------
        from_base
            Numeric base of expression
        to_base
            New base

        Returns
        -------
        IntegerValue
            Converted expression
        """
        return ops.BaseConvert(self, from_base, to_base).to_expr()

    def __and__(self, other: IntegerValue) -> IntegerValue | NotImplemented:
        """Bitwise and `self` with `other`."""
        from ibis.expr import operations as ops

        return _binop(ops.BitwiseAnd, self, other)

    __rand__ = __and__

    def __or__(self, other: IntegerValue) -> IntegerValue | NotImplemented:
        """Bitwise or `self` with `other`."""
        from ibis.expr import operations as ops

        return _binop(ops.BitwiseOr, self, other)

    __ror__ = __or__

    def __xor__(self, other: IntegerValue) -> IntegerValue | NotImplemented:
        """Bitwise xor `self` with `other`."""
        from ibis.expr import operations as ops

        return _binop(ops.BitwiseXor, self, other)

    __rxor__ = __xor__

    def __lshift__(self, other: IntegerValue) -> IntegerValue | NotImplemented:
        """Bitwise left shift `self` with `other`."""
        from ibis.expr import operations as ops

        return _binop(ops.BitwiseLeftShift, self, other)

    def __rlshift__(self, other: IntegerValue) -> IntegerValue | NotImplemented:
        """Bitwise left shift `self` with `other`."""
        from ibis.expr import operations as ops

        return _binop(ops.BitwiseLeftShift, other, self)

    def __rshift__(self, other: IntegerValue) -> IntegerValue | NotImplemented:
        """Bitwise right shift `self` with `other`."""
        from ibis.expr import operations as ops

        return _binop(ops.BitwiseRightShift, self, other)

    def __rrshift__(self, other: IntegerValue) -> IntegerValue | NotImplemented:
        """Bitwise right shift `self` with `other`."""
        from ibis.expr import operations as ops

        return _binop(ops.BitwiseRightShift, other, self)

    def __invert__(self) -> IntegerValue:
        """Bitwise not of `self`.

        Returns
        -------
        IntegerValue
            Inverted bits of `self`.
        """
        from ibis.expr import operations as ops

        try:
            node = ops.BitwiseNot(self)
        except (IbisTypeError, NotImplementedError):
            return NotImplemented
        else:
            return node.to_expr()

    def label(self, labels: Iterable[str], nulls: str | None = None) -> ir.StringValue:
        """Label a set of integer values with strings.

        Parameters
        ----------
        labels
            An iterable of string labels. Each integer value in `self` will be mapped to
            a value in `labels`.
        nulls
            String label to use for `NULL` values

        Returns
        -------
        StringValue
            `self` labeled with `labels`

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"a": [0, 1, 0, 2]})
        >>> t.select(t.a, labeled=t.a.label(["a", "b", "c"]))
        ┏━━━━━━━┳━━━━━━━━━┓
        ┃ a     ┃ labeled ┃
        ┡━━━━━━━╇━━━━━━━━━┩
        │ int64 │ string  │
        ├───────┼─────────┤
        │     0 │ a       │
        │     1 │ b       │
        │     0 │ a       │
        │     2 │ c       │
        └───────┴─────────┘
        """
        return (
            functools.reduce(
                lambda stmt, inputs: stmt.when(*inputs), enumerate(labels), self.case()
            )
            .else_(nulls)
            .end()
        )

Functions¶

`convert_base(from_base, to_base)` ¶

Convert an integer from one base to another.

Parameters:

Name	Type	Description	Default
`from_base`	`IntegerValue`	Numeric base of expression	required
`to_base`	`IntegerValue`	New base	required

Returns:

Type	Description
`IntegerValue`	Converted expression

Source code in ibis/expr/types/numeric.py

def convert_base(
    self,
    from_base: IntegerValue,
    to_base: IntegerValue,
) -> IntegerValue:
    """Convert an integer from one base to another.

    Parameters
    ----------
    from_base
        Numeric base of expression
    to_base
        New base

    Returns
    -------
    IntegerValue
        Converted expression
    """
    return ops.BaseConvert(self, from_base, to_base).to_expr()

`label(labels, nulls=None)` ¶

Label a set of integer values with strings.

Parameters:

Name	Type	Description	Default
`labels`	`Iterable[str]`	An iterable of string labels. Each integer value in `self` will be mapped to a value in `labels`.	required
`nulls`	`str \| None`	String label to use for `NULL` values	`None`

Returns:

Type	Description
`StringValue`	`self` labeled with `labels`

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"a": [0, 1, 0, 2]})
>>> t.select(t.a, labeled=t.a.label(["a", "b", "c"]))
┏━━━━━━━┳━━━━━━━━━┓
┃ a     ┃ labeled ┃
┡━━━━━━━╇━━━━━━━━━┩
│ int64 │ string  │
├───────┼─────────┤
│     0 │ a       │
│     1 │ b       │
│     0 │ a       │
│     2 │ c       │
└───────┴─────────┘

Source code in ibis/expr/types/numeric.py

def label(self, labels: Iterable[str], nulls: str | None = None) -> ir.StringValue:
    """Label a set of integer values with strings.

    Parameters
    ----------
    labels
        An iterable of string labels. Each integer value in `self` will be mapped to
        a value in `labels`.
    nulls
        String label to use for `NULL` values

    Returns
    -------
    StringValue
        `self` labeled with `labels`

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"a": [0, 1, 0, 2]})
    >>> t.select(t.a, labeled=t.a.label(["a", "b", "c"]))
    ┏━━━━━━━┳━━━━━━━━━┓
    ┃ a     ┃ labeled ┃
    ┡━━━━━━━╇━━━━━━━━━┩
    │ int64 │ string  │
    ├───────┼─────────┤
    │     0 │ a       │
    │     1 │ b       │
    │     0 │ a       │
    │     2 │ c       │
    └───────┴─────────┘
    """
    return (
        functools.reduce(
            lambda stmt, inputs: stmt.when(*inputs), enumerate(labels), self.case()
        )
        .else_(nulls)
        .end()
    )

`to_interval(unit='s')` ¶

Convert an integer to an interval.

Parameters:

Name	Type	Description	Default
`unit`	`Literal['Y', 'M', 'W', 'D', 'h', 'm', 's', 'ms', 'us', 'ns']`	Unit for the resulting interval	`'s'`

Returns:

Type	Description
`IntervalValue`	An interval in units of `unit`

Source code in ibis/expr/types/numeric.py

def to_interval(
    self,
    unit: Literal["Y", "M", "W", "D", "h", "m", "s", "ms", "us", "ns"] = "s",
) -> ir.IntervalValue:
    """Convert an integer to an interval.

    Parameters
    ----------
    unit
        Unit for the resulting interval

    Returns
    -------
    IntervalValue
        An interval in units of `unit`
    """
    return ops.IntervalFromInteger(self, unit).to_expr()

`to_timestamp(unit='s')` ¶

Convert an integral UNIX timestamp to a timestamp expression.

Parameters:

Name	Type	Description	Default
`unit`	`Literal['s', 'ms', 'us']`	The resolution of `arg`	`'s'`

Returns:

Type	Description
`TimestampValue`	`self` converted to a timestamp

Source code in ibis/expr/types/numeric.py

def to_timestamp(
    self,
    unit: Literal["s", "ms", "us"] = "s",
) -> ir.TimestampValue:
    """Convert an integral UNIX timestamp to a timestamp expression.

    Parameters
    ----------
    unit
        The resolution of `arg`

    Returns
    -------
    TimestampValue
        `self` converted to a timestamp
    """
    return ops.TimestampFromUNIX(self, unit).to_expr()

`IntegerColumn` ¶

Bases: NumericColumn, IntegerValue

Source code in ibis/expr/types/numeric.py

@public
class IntegerColumn(NumericColumn, IntegerValue):
    def bit_and(self, where: ir.BooleanValue | None = None) -> IntegerScalar:
        """Aggregate the column using the bitwise and operator."""
        return ops.BitAnd(self, where).to_expr()

    def bit_or(self, where: ir.BooleanValue | None = None) -> IntegerScalar:
        """Aggregate the column using the bitwise or operator."""
        return ops.BitOr(self, where).to_expr()

    def bit_xor(self, where: ir.BooleanValue | None = None) -> IntegerScalar:
        """Aggregate the column using the bitwise exclusive or operator."""
        return ops.BitXor(self, where).to_expr()

Functions¶

`bit_and(where=None)` ¶

Aggregate the column using the bitwise and operator.

Source code in ibis/expr/types/numeric.py

def bit_and(self, where: ir.BooleanValue | None = None) -> IntegerScalar:
    """Aggregate the column using the bitwise and operator."""
    return ops.BitAnd(self, where).to_expr()

`bit_or(where=None)` ¶

Aggregate the column using the bitwise or operator.

Source code in ibis/expr/types/numeric.py

def bit_or(self, where: ir.BooleanValue | None = None) -> IntegerScalar:
    """Aggregate the column using the bitwise or operator."""
    return ops.BitOr(self, where).to_expr()

`bit_xor(where=None)` ¶

Aggregate the column using the bitwise exclusive or operator.

Source code in ibis/expr/types/numeric.py

def bit_xor(self, where: ir.BooleanValue | None = None) -> IntegerScalar:
    """Aggregate the column using the bitwise exclusive or operator."""
    return ops.BitXor(self, where).to_expr()

`FloatingValue` ¶

Bases: NumericValue

Source code in ibis/expr/types/numeric.py

@public
class FloatingValue(NumericValue):
    def isnan(self) -> ir.BooleanValue:
        """Return whether the value is NaN."""
        return ops.IsNan(self).to_expr()

    def isinf(self) -> ir.BooleanValue:
        """Return whether the value is infinity."""
        return ops.IsInf(self).to_expr()

Functions¶

`isinf()` ¶

Return whether the value is infinity.

Source code in ibis/expr/types/numeric.py

def isinf(self) -> ir.BooleanValue:
    """Return whether the value is infinity."""
    return ops.IsInf(self).to_expr()

`isnan()` ¶

Return whether the value is NaN.

Source code in ibis/expr/types/numeric.py

def isnan(self) -> ir.BooleanValue:
    """Return whether the value is NaN."""
    return ops.IsNan(self).to_expr()

`DecimalValue` ¶

Bases: NumericValue

Source code in ibis/expr/types/numeric.py

@public
class DecimalValue(NumericValue):
    pass

`BooleanValue` ¶

Bases: NumericValue

Source code in ibis/expr/types/logical.py

@public
class BooleanValue(NumericValue):
    def ifelse(self, true_expr: ir.Value, false_expr: ir.Value) -> ir.Value:
        """Construct a ternary conditional expression.

        Parameters
        ----------
        true_expr
            Expression to return if `self` evaluates to `True`
        false_expr
            Expression to return if `self` evaluates to `False` or `NULL`

        Returns
        -------
        Value
            The value of `true_expr` if `arg` is `True` else `false_expr`

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"is_person": [True, False, True, None]})
        >>> t.is_person.ifelse("yes", "no")
        ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
        ┃ Where(is_person, 'yes', 'no') ┃
        ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
        │ string                        │
        ├───────────────────────────────┤
        │ yes                           │
        │ no                            │
        │ yes                           │
        │ no                            │
        └───────────────────────────────┘
        """
        # Result will be the result of promotion of true/false exprs. These
        # might be conflicting types; same type resolution as case expressions
        # must be used.
        return ops.Where(self, true_expr, false_expr).to_expr()

    def __and__(self, other: BooleanValue) -> BooleanValue:
        """Construct a binary AND conditional expression with `self` and `other`.

        Parameters
        ----------
        self
            Left operand
        other
            Right operand

        Returns
        -------
        BooleanValue
            A Boolean expression

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"arr": [[1], [], [42, 42], None]})
        >>> t.arr.contains(42) & (t.arr.contains(1))
        ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
        ┃ And(ArrayContains(arr, 42), ArrayContains(arr, 1)) ┃
        ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
        │ boolean                                            │
        ├────────────────────────────────────────────────────┤
        │ False                                              │
        │ False                                              │
        │ False                                              │
        │ NULL                                               │
        └────────────────────────────────────────────────────┘

        >>> t.arr.contains(42) & (t.arr.contains(42))
        ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
        ┃ And(ArrayContains(arr, 42), ArrayContains(arr, 42)) ┃
        ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
        │ boolean                                             │
        ├─────────────────────────────────────────────────────┤
        │ False                                               │
        │ False                                               │
        │ True                                                │
        │ NULL                                                │
        └─────────────────────────────────────────────────────┘
        """
        return _binop(ops.And, self, other)

    __rand__ = __and__

    def __or__(self, other: BooleanValue) -> BooleanValue:
        """Construct a binary OR conditional expression with `self` and `other`.

        Parameters
        ----------
        self
            Left operand
        other
            Right operand

        Returns
        -------
        BooleanValue
            A Boolean expression

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"arr": [1, 2, 3, None]})
        >>> (t.arr > 1) | (t.arr > 2)
        ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
        ┃ Or(Greater(arr, 1), Greater(arr, 2)) ┃
        ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
        │ boolean                              │
        ├──────────────────────────────────────┤
        │ False                                │
        │ True                                 │
        │ True                                 │
        │ NULL                                 │
        └──────────────────────────────────────┘
        """
        return _binop(ops.Or, self, other)

    __ror__ = __or__

    def __xor__(self, other: BooleanValue) -> BooleanValue:
        """Construct a binary XOR conditional expression with `self` and `other`.

        Parameters
        ----------
        self
            Left operand
        other
            Right operand

        Returns
        -------
        BooleanValue
            A Boolean expression

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"arr": [1, 2, 3, None]})
        >>> t.arr == 2
        ┏━━━━━━━━━━━━━━━━┓
        ┃ Equals(arr, 2) ┃
        ┡━━━━━━━━━━━━━━━━┩
        │ boolean        │
        ├────────────────┤
        │ False          │
        │ True           │
        │ False          │
        │ NULL           │
        └────────────────┘

        >>> (t.arr > 2)
        ┏━━━━━━━━━━━━━━━━━┓
        ┃ Greater(arr, 2) ┃
        ┡━━━━━━━━━━━━━━━━━┩
        │ boolean         │
        ├─────────────────┤
        │ False           │
        │ False           │
        │ True            │
        │ NULL            │
        └─────────────────┘

        >>> (t.arr == 2) ^ (t.arr > 2)
        ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
        ┃ Xor(Equals(arr, 2), Greater(arr, 2)) ┃
        ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
        │ boolean                              │
        ├──────────────────────────────────────┤
        │ False                                │
        │ True                                 │
        │ True                                 │
        │ NULL                                 │
        └──────────────────────────────────────┘
        """

        return _binop(ops.Xor, self, other)

    __rxor__ = __xor__

    def __invert__(self) -> BooleanValue:
        """Construct a unary NOT conditional expression with `self`.

        Parameters
        ----------
        self
            Operand

        Returns
        -------
        BooleanValue
            A Boolean expression

        Examples
        --------
        >>> import ibis
        >>> ibis.options.interactive = True
        >>> t = ibis.memtable({"arr": [True, False, False, None]})
        >>> ~t.arr
        ┏━━━━━━━━━━┓
        ┃ Not(arr) ┃
        ┡━━━━━━━━━━┩
        │ boolean  │
        ├──────────┤
        │ False    │
        │ True     │
        │ True     │
        │ NULL     │
        └──────────┘
        """
        return self.negate()

    @staticmethod
    def __negate_op__():
        return ops.Not

Functions¶

`ifelse(true_expr, false_expr)` ¶

Construct a ternary conditional expression.

Parameters:

Name	Type	Description	Default
`true_expr`	`ir.Value`	Expression to return if `self` evaluates to `True`	required
`false_expr`	`ir.Value`	Expression to return if `self` evaluates to `False` or `NULL`	required

Returns:

Type	Description
`Value`	The value of `true_expr` if `arg` is `True` else `false_expr`

Examples:

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"is_person": [True, False, True, None]})
>>> t.is_person.ifelse("yes", "no")
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Where(is_person, 'yes', 'no') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ string                        │
├───────────────────────────────┤
│ yes                           │
│ no                            │
│ yes                           │
│ no                            │
└───────────────────────────────┘

Source code in ibis/expr/types/logical.py

def ifelse(self, true_expr: ir.Value, false_expr: ir.Value) -> ir.Value:
    """Construct a ternary conditional expression.

    Parameters
    ----------
    true_expr
        Expression to return if `self` evaluates to `True`
    false_expr
        Expression to return if `self` evaluates to `False` or `NULL`

    Returns
    -------
    Value
        The value of `true_expr` if `arg` is `True` else `false_expr`

    Examples
    --------
    >>> import ibis
    >>> ibis.options.interactive = True
    >>> t = ibis.memtable({"is_person": [True, False, True, None]})
    >>> t.is_person.ifelse("yes", "no")
    ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
    ┃ Where(is_person, 'yes', 'no') ┃
    ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
    │ string                        │
    ├───────────────────────────────┤
    │ yes                           │
    │ no                            │
    │ yes                           │
    │ no                            │
    └───────────────────────────────┘
    """
    # Result will be the result of promotion of true/false exprs. These
    # might be conflicting types; same type resolution as case expressions
    # must be used.
    return ops.Where(self, true_expr, false_expr).to_expr()

Last update: June 22, 2023

Numeric and Boolean Expressions¶

NumericValue ¶

Functions¶

abs() ¶

acos() ¶

asin() ¶

atan() ¶

atan2(other) ¶

ceil() ¶

clip(lower=None, upper=None) ¶

cos() ¶

cot() ¶

degrees() ¶

exp() ¶

floor() ¶

ln() ¶

log(base=None) ¶

log10() ¶

log2() ¶

negate() ¶

nullifzero() ¶

point(right) ¶

radians() ¶

round(digits=None) ¶

sign() ¶

sin() ¶

sqrt() ¶

tan() ¶

zeroifnull() ¶

NumericColumn ¶

Functions¶

bucket(buckets, closed='left', close_extreme=True, include_under=False, include_over=False) ¶

corr(right, where=None, how='sample') ¶

cov(right, where=None, how='sample') ¶

cummean() ¶

cumsum() ¶

histogram(nbins=None, binwidth=None, base=None, eps=1e-13) ¶

mean(where=None) ¶

median(where=None) ¶

quantile(quantile, interpolation=None, where=None) ¶

std(where=None, how='sample') ¶

sum(where=None) ¶

var(where=None, how='sample') ¶

IntegerValue ¶

Functions¶

convert_base(from_base, to_base) ¶

label(labels, nulls=None) ¶

to_interval(unit='s') ¶

to_timestamp(unit='s') ¶

IntegerColumn ¶

Functions¶

bit_and(where=None) ¶

bit_or(where=None) ¶

bit_xor(where=None) ¶

FloatingValue ¶

Functions¶

isinf() ¶

isnan() ¶

DecimalValue ¶

BooleanValue ¶

Functions¶

ifelse(true_expr, false_expr) ¶

`NumericValue` ¶

`abs()` ¶

`acos()` ¶

`asin()` ¶

`atan()` ¶

`atan2(other)` ¶

`ceil()` ¶

`clip(lower=None, upper=None)` ¶

`cos()` ¶

`cot()` ¶

`degrees()` ¶

`exp()` ¶

`floor()` ¶

`ln()` ¶

`log(base=None)` ¶

`log10()` ¶

`log2()` ¶

`negate()` ¶

`nullifzero()` ¶

`point(right)` ¶

`radians()` ¶

`round(digits=None)` ¶

`sign()` ¶

`sin()` ¶

`sqrt()` ¶

`tan()` ¶

`zeroifnull()` ¶

`NumericColumn` ¶

`bucket(buckets, closed='left', close_extreme=True, include_under=False, include_over=False)` ¶

`corr(right, where=None, how='sample')` ¶

`cov(right, where=None, how='sample')` ¶

`cummean()` ¶

`cumsum()` ¶

`histogram(nbins=None, binwidth=None, base=None, eps=1e-13)` ¶

`mean(where=None)` ¶

`median(where=None)` ¶

`quantile(quantile, interpolation=None, where=None)` ¶

`std(where=None, how='sample')` ¶

`sum(where=None)` ¶

`var(where=None, how='sample')` ¶

`IntegerValue` ¶

`convert_base(from_base, to_base)` ¶

`label(labels, nulls=None)` ¶

`to_interval(unit='s')` ¶

`to_timestamp(unit='s')` ¶

`IntegerColumn` ¶

`bit_and(where=None)` ¶

`bit_or(where=None)` ¶

`bit_xor(where=None)` ¶

`FloatingValue` ¶

`isinf()` ¶

`isnan()` ¶

`DecimalValue` ¶

`BooleanValue` ¶

`ifelse(true_expr, false_expr)` ¶