Skip to content

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