Numeric and Boolean Expressions¶

These APIs are available on numeric and boolean expressions.

`NumericValue` ¶

Bases: Value

Functions¶

`add(other)` ¶

Add self with other.

`floordiv(other)` ¶

Floor divide self by other.

`mod(other)` ¶

Compute self modulo other.

`mul(other)` ¶

Multiply self and other.

`neg()` ¶

Negate self.

Returns:

Type	Description
`NumericValue`	`self` negated

`pow(other)` ¶

Raise self to the otherth power.

`rfloordiv(other)` ¶

Floor divide other by self.

`rmod(other)` ¶

Compute other modulo self.

`rpow(other)` ¶

Raise other to the selfth power.

`rsub(other)` ¶

Substract self from other.

`rtruediv(other)` ¶

Divide other by self.

`sub(other)` ¶

Substract other from self.

`truediv(other)` ¶

Divide self by other.

`abs()` ¶

Return the absolute value of self.

`acos()` ¶

Compute the arc cosine of self.

`asin()` ¶

Compute the arc sine of self.

`atan()` ¶

Compute the arc tangent of self.

`atan2(other)` ¶

Compute the two-argument version of arc tangent.

`ceil()` ¶

Return the ceiling of self.

`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

`cos()` ¶

Compute the cosine of self.

`cot()` ¶

Compute the cotangent of self.

`degrees()` ¶

Compute the degrees of self radians.

`exp()` ¶

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

Returns:

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

`floor()` ¶

Return the floor of an expression.

`ln()` ¶

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

`log(base=None)` ¶

Return the logarithm using a specified base.

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`

`log10()` ¶

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

`log2()` ¶

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

`negate()` ¶

Negate a numeric expression.

Returns:

Type	Description
`NumericValue`	A numeric value expression

`nullifzero()` ¶

Return NULL if an expression is zero.

`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

`radians()` ¶

Compute radians from self degrees.

`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

`sign()` ¶

Return the sign of the input.

`sin()` ¶

Compute the sine of self.

`sqrt()` ¶

Compute the square root of self.

`tan()` ¶

Compute the tangent of self.

`zeroifnull()` ¶

Return zero if an expression is NULL.

`NumericColumn` ¶

Bases: Column, NumericValue

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

`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`

`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`

`cummean()` ¶

Return the cumulative mean of the input.

`cumsum()` ¶

Return the cumulative sum of the input.

`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

`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

`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

`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`

`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

`summary(exact_nunique=False, prefix='', suffix='')` ¶

Compute summary metrics from the input numeric expression.

Parameters:

Name	Type	Description	Default
`exact_nunique`	`bool`	Compute the exact number of distinct values. Typically slower if `True`.	`False`
`prefix`	`str`	String prefix for metric names	`''`
`suffix`	`str`	String suffix for metric names	`''`

Returns:

Type	Description
`list[NumericScalar]`	Metrics list

`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`

`IntegerValue` ¶

Bases: NumericValue

Functions¶

`and(other)` ¶

Bitwise and self with other.

`invert()` ¶

Bitwise not of self.

Returns:

Type	Description
`IntegerValue`	Inverted bits of `self`.

`lshift(other)` ¶

Bitwise left shift self with other.

`or(other)` ¶

Bitwise or self with other.

`rlshift(other)` ¶

Bitwise left shift self with other.

`rrshift(other)` ¶

Bitwise right shift self with other.

`rshift(other)` ¶

Bitwise right shift self with other.

`xor(other)` ¶

Bitwise xor self with other.

`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

`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       │
└───────┴─────────┘

`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`

`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

`IntegerColumn` ¶

Bases: NumericColumn, IntegerValue

Functions¶

`bit_and(where=None)` ¶

Aggregate the column using the bitwise and operator.

`bit_or(where=None)` ¶

Aggregate the column using the bitwise or operator.

`bit_xor(where=None)` ¶

Aggregate the column using the bitwise exclusive or operator.

`FloatingValue` ¶

Bases: NumericValue

Functions¶

`isinf()` ¶

Return whether the value is infinity.

`isnan()` ¶

Return whether the value is NaN.

`DecimalValue` ¶

Bases: NumericValue

`BooleanValue` ¶

Bases: NumericValue

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`	required

Returns:

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

Examples:

>>> import ibis
>>> t = ibis.table([("is_person", "boolean")], name="t")
>>> expr = t.is_person.ifelse("yes", "no")
>>> print(ibis.impala.compile(expr.name("tmp")))
SELECT if(t0.`is_person`, 'yes', 'no') AS `tmp`
FROM t t0

Last update: August 5, 2022

Numeric and Boolean Expressions¶

NumericValue ¶

Functions¶

__add__(other) ¶

__floordiv__(other) ¶

__mod__(other) ¶

__mul__(other) ¶

__neg__() ¶

__pow__(other) ¶

__rfloordiv__(other) ¶

__rmod__(other) ¶

__rpow__(other) ¶

__rsub__(other) ¶

__rtruediv__(other) ¶

__sub__(other) ¶

__truediv__(other) ¶

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) ¶

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

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

sum(where=None) ¶

summary(exact_nunique=False, prefix='', suffix='') ¶

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

IntegerValue ¶

Functions¶

__and__(other) ¶

__invert__() ¶

__lshift__(other) ¶

__or__(other) ¶

__rlshift__(other) ¶

__rrshift__(other) ¶

__rshift__(other) ¶

__xor__(other) ¶

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 ¶

`NumericValue` ¶

`add(other)` ¶

`floordiv(other)` ¶

`mod(other)` ¶

`mul(other)` ¶

`neg()` ¶

`pow(other)` ¶

`rfloordiv(other)` ¶

`rmod(other)` ¶

`rpow(other)` ¶

`rsub(other)` ¶

`rtruediv(other)` ¶

`sub(other)` ¶

`truediv(other)` ¶

`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)` ¶

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

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

`sum(where=None)` ¶

`summary(exact_nunique=False, prefix='', suffix='')` ¶

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

`IntegerValue` ¶

`and(other)` ¶

`invert()` ¶

`lshift(other)` ¶

`or(other)` ¶

`rlshift(other)` ¶

`rrshift(other)` ¶

`rshift(other)` ¶

`xor(other)` ¶

`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)` ¶