Numeric Expressions¶

These APIs are available on numeric and boolean expressions.

`numeric` ¶

Classes¶

`DecimalValue (NumericValue)` ¶

Methods¶

`precision(self)` ¶

Return the precision of arg.

Returns:

Type	Description
`IntegerValue`	The precision of the expression.

`scale(self)` ¶

Return the scale of arg.

Returns:

Type	Description
`IntegerValue`	The scale of the expression.

`FloatingValue (NumericValue)` ¶

Methods¶

`isinf(self)` ¶

Return whether the value is infinity.

`isnan(self)` ¶

Return whether the value is NaN.

`IntegerColumn (NumericColumn, IntegerValue)` ¶

Methods¶

`bit_and(self, where=None)` ¶

Aggregate the column using the bitwise and operator.

`bit_or(self, where=None)` ¶

Aggregate the column using the bitwise or operator.

`bit_xor(self, where=None)` ¶

Aggregate the column using the bitwise exclusive or operator.

`IntegerValue (NumericValue)` ¶

Methods¶

`convert_base(self, 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

`to_interval(self, 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
`ir.IntervalValue`	An interval in units of `unit`

`to_timestamp(self, 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
`ir.TimestampValue`	`self` converted to a timestamp

`NumericColumn (AnyColumn, NumericValue)` ¶

Methods¶

`bucket(self, 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
`ir.CategoryColumn`	A categorical column expression

`corr(self, 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(self, 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`

`histogram(self, nbins=None, binwidth=None, base=None, closed='left', aux_hash=None)` ¶

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`	Histogram base	`None`
`closed`	`Literal['left', 'right']`	Which side of each interval is closed	`'left'`
`aux_hash`	`str \| None`	Auxiliary hash value to add to bucket names	`None`

Returns:

Type	Description
`ir.CategoryColumn`	Coded value expression

`mean(self, 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(self, quantile, interpolation='linear')` ¶

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']

This optional 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.

'linear'

Returns:

Type	Description
`NumericScalar`	Quantile of the input

`std(self, 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(self, 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(self, exact_nunique=False, prefix='', suffix='')` ¶

Compute a set of summary metrics from the input numeric value 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(self, 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`

`NumericValue (AnyValue)` ¶

Methods¶

`abs(self)` ¶

Return the absolute value of self.

`acos(self)` ¶

Compute the arc cosine of self.

`add(self, other)` ¶

Add self with other.

`asin(self)` ¶

Compute the arc sine of self.

`atan(self)` ¶

Compute the arc tangent of self.

`atan2(self, other)` ¶

Compute the two-argument version of arc tangent.

`ceil(self)` ¶

Return the ceiling of self.

`clip(self, 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(self)` ¶

Compute the cosine of self.

`cot(self)` ¶

Compute the cotangent of self.

`deg2rad(self)` ¶

Compute radians from self degrees.

`degrees(self)` ¶

Compute the degrees of self radians.

`div(self, other)` ¶

Divide self by other.

`exp(self)` ¶

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

Returns:

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

`floor(self)` ¶

Return the floor of an expression.

`floordiv(self, other)` ¶

Floor divide self by other.

`ln(self)` ¶

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

`log(self, 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(self)` ¶

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

`log2(self)` ¶

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

`mod(self, other)` ¶

Compute self modulo other.

`mul(self, other)` ¶

Multiply self and other.

`negate(self)` ¶

Negate a numeric expression.

Returns:

Type	Description
`NumericValue`	A numeric value expression

`nullifzero(self)` ¶

Return NULL if an expression is zero.

`point(self, 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
`ir.PointValue`	Points

`pow(self, other)` ¶

Raise self to the otherth power.

`rad2deg(self)` ¶

Compute the degrees of self radians.

`radd(self, other)` ¶

Add self with other.

`radians(self)` ¶

Compute radians from self degrees.

`rdiv(self, other)` ¶

Divide other by self.

`rfloordiv(self, other)` ¶

Floor divide other by self.

`rmod(self, other)` ¶

Compute other modulo self.

`rmul(self, other)` ¶

Multiply self and other.

`round(self, 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

`rpow(self, other)` ¶

Raise other to the selfth power.

`rsub(self, other)` ¶

Substract self from other.

`sign(self)` ¶

Return the sign of the input.

`sin(self)` ¶

Compute the sine of self.

`sqrt(self)` ¶

Compute the square root of self.

`sub(self, other)` ¶

Substract other from self.

`tan(self)` ¶

Compute the tangent of self.

`zeroifnull(self)` ¶

Return zero if an expression is NULL.

`logical` ¶

Classes¶

`BooleanValue (NumericValue)` ¶

Methods¶

`ifelse(self, true_expr, false_expr)` ¶

Construct a ternary conditional expression.

Parameters:

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

Examples:

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

Returns:

Type	Description
`ir.ValueExpr`	The value of `true_expr` if `arg` is `True` else `false_expr`

Last update: February 3, 2022

Numeric Expressions¶

numeric ¶

Classes¶

DecimalValue (NumericValue) ¶

Methods¶

precision(self) ¶

scale(self) ¶

FloatingValue (NumericValue) ¶

Methods¶

isinf(self) ¶

isnan(self) ¶

IntegerColumn (NumericColumn, IntegerValue) ¶

Methods¶

bit_and(self, where=None) ¶

bit_or(self, where=None) ¶

bit_xor(self, where=None) ¶

IntegerValue (NumericValue) ¶

Methods¶

convert_base(self, from_base, to_base) ¶

to_interval(self, unit='s') ¶

to_timestamp(self, unit='s') ¶

NumericColumn (AnyColumn, NumericValue) ¶

Methods¶

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

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

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

histogram(self, nbins=None, binwidth=None, base=None, closed='left', aux_hash=None) ¶

mean(self, where=None) ¶

quantile(self, quantile, interpolation='linear') ¶

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

sum(self, where=None) ¶

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

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

NumericValue (AnyValue) ¶

Methods¶

abs(self) ¶

acos(self) ¶

add(self, other) ¶

asin(self) ¶

atan(self) ¶

atan2(self, other) ¶

ceil(self) ¶

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

cos(self) ¶

cot(self) ¶

deg2rad(self) ¶

degrees(self) ¶

div(self, other) ¶

exp(self) ¶

floor(self) ¶

floordiv(self, other) ¶

ln(self) ¶

log(self, base=None) ¶

log10(self) ¶

log2(self) ¶

mod(self, other) ¶

mul(self, other) ¶

negate(self) ¶

nullifzero(self) ¶

point(self, right) ¶

pow(self, other) ¶

rad2deg(self) ¶

radd(self, other) ¶

radians(self) ¶

rdiv(self, other) ¶

rfloordiv(self, other) ¶

rmod(self, other) ¶

rmul(self, other) ¶

round(self, digits=None) ¶

rpow(self, other) ¶

rsub(self, other) ¶

sign(self) ¶

sin(self) ¶

sqrt(self) ¶

sub(self, other) ¶

tan(self) ¶

zeroifnull(self) ¶

logical ¶

Classes¶

BooleanValue (NumericValue) ¶

`numeric` ¶

`DecimalValue (NumericValue)` ¶

`precision(self)` ¶

`scale(self)` ¶

`FloatingValue (NumericValue)` ¶

`isinf(self)` ¶

`isnan(self)` ¶

`IntegerColumn (NumericColumn, IntegerValue)` ¶

`bit_and(self, where=None)` ¶

`bit_or(self, where=None)` ¶

`bit_xor(self, where=None)` ¶

`IntegerValue (NumericValue)` ¶

`convert_base(self, from_base, to_base)` ¶

`to_interval(self, unit='s')` ¶

`to_timestamp(self, unit='s')` ¶

`NumericColumn (AnyColumn, NumericValue)` ¶

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

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

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

`histogram(self, nbins=None, binwidth=None, base=None, closed='left', aux_hash=None)` ¶

`mean(self, where=None)` ¶

`quantile(self, quantile, interpolation='linear')` ¶

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

`sum(self, where=None)` ¶

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

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

`NumericValue (AnyValue)` ¶

`abs(self)` ¶

`acos(self)` ¶

`add(self, other)` ¶

`asin(self)` ¶

`atan(self)` ¶

`atan2(self, other)` ¶

`ceil(self)` ¶

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

`cos(self)` ¶

`cot(self)` ¶

`deg2rad(self)` ¶

`degrees(self)` ¶

`div(self, other)` ¶

`exp(self)` ¶

`floor(self)` ¶

`floordiv(self, other)` ¶

`ln(self)` ¶

`log(self, base=None)` ¶

`log10(self)` ¶

`log2(self)` ¶

`mod(self, other)` ¶

`mul(self, other)` ¶

`negate(self)` ¶

`nullifzero(self)` ¶

`point(self, right)` ¶

`pow(self, other)` ¶

`rad2deg(self)` ¶

`radd(self, other)` ¶

`radians(self)` ¶

`rdiv(self, other)` ¶

`rfloordiv(self, other)` ¶

`rmod(self, other)` ¶

`rmul(self, other)` ¶

`round(self, digits=None)` ¶

`rpow(self, other)` ¶

`rsub(self, other)` ¶

`sign(self)` ¶

`sin(self)` ¶

`sqrt(self)` ¶

`sub(self, other)` ¶

`tan(self)` ¶

`zeroifnull(self)` ¶

`logical` ¶

`BooleanValue (NumericValue)` ¶

`ifelse(self, true_expr, false_expr)` ¶