# Numeric and Boolean Expressions¶

These APIs are available on numeric and boolean expressions.

##  NumericValue (Value) ¶

### 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.

##  NumericColumn (Column, 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

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

##  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.

##  FloatingValue (NumericValue) ¶

### Methods¶

#### isinf(self)¶

Return whether the value is infinity.

#### isnan(self)¶

Return whether the value is NaN.

##  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.

##  BooleanValue (NumericValue) ¶

### Methods¶

#### ifelse(self, 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

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.Value

The value of true_expr if arg is True else false_expr

Last update: August 5, 2022