Skip to content

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