Numeric and Boolean expressions

Integer, floating point, decimal, and boolean expressions.

NumericValue

NumericValue(self, arg)

Methods

Name Description
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 Compute the two-argument version of arc tangent.
ceil Return the ceiling of self.
clip Trim values outside of lower and upper bounds.
cos Compute the cosine of self.
cot Compute the cotangent of self.
degrees Compute the degrees of self radians.
exp Compute \(e^\texttt{self}\).
floor Return the floor of an expression.
ln Compute \(\ln\left(\texttt{self}\right)\).
log Compute \(\log_{\texttt{base}}\left(\texttt{self}\right)\).
log10 Compute \(\log_{10}\left(\texttt{self}\right)\).
log2 Compute \(\log_{2}\left(\texttt{self}\right)\).
negate Negate a numeric expression.
point Return a point constructed from the coordinate values.
radians Compute radians from self degrees.
round Round values to an indicated number of decimal places.
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.

abs

abs()

Return the absolute value of self.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 2, -3, 4]})
>>> t.values.abs()
┏━━━━━━━━━━━━━┓
┃ Abs(values) ┃
┡━━━━━━━━━━━━━┩
│ int64       │
├─────────────┤
│           1 │
│           2 │
│           3 │
│           4 │
└─────────────┘

acos

acos()

Compute the arc cosine of self.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.acos()
┏━━━━━━━━━━━━━━┓
┃ Acos(values) ┃
┡━━━━━━━━━━━━━━┩
│ float64      │
├──────────────┤
│     3.141593 │
│     1.570796 │
│     0.000000 │
└──────────────┘

asin

asin()

Compute the arc sine of self.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.asin()
┏━━━━━━━━━━━━━━┓
┃ Asin(values) ┃
┡━━━━━━━━━━━━━━┩
│ float64      │
├──────────────┤
│    -1.570796 │
│     0.000000 │
│     1.570796 │
└──────────────┘

atan

atan()

Compute the arc tangent of self.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.atan()
┏━━━━━━━━━━━━━━┓
┃ Atan(values) ┃
┡━━━━━━━━━━━━━━┩
│ float64      │
├──────────────┤
│    -0.785398 │
│     0.000000 │
│     0.785398 │
└──────────────┘

atan2

atan2(other)

Compute the two-argument version of arc tangent.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.atan2(0)
┏━━━━━━━━━━━━━━━━━━┓
┃ Atan2(values, 0) ┃
┡━━━━━━━━━━━━━━━━━━┩
│ float64          │
├──────────────────┤
│        -1.570796 │
│         0.000000 │
│         1.570796 │
└──────────────────┘

ceil

ceil()

Return the ceiling of self.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1, 1.1, 2, 2.1, 3.3]})
>>> t.values.ceil()
┏━━━━━━━━━━━━━━┓
┃ Ceil(values) ┃
┡━━━━━━━━━━━━━━┩
│ int64        │
├──────────────┤
│            1 │
│            2 │
│            2 │
│            3 │
│            4 │
└──────────────┘

clip

clip(lower=None, upper=None)

Trim values outside of lower and upper bounds.

NULL values are preserved and are not replaced with bounds.

Parameters

Name Type Description Default
lower NumericValue | None Lower bound None
upper NumericValue | None Upper bound None

Returns

Type Description
NumericValue Clipped input

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable(
...     {"values": [None, 2, 3, None, 5, None, None, 8]},
...     schema=dict(values="int"),
... )
>>> t.values.clip(lower=3, upper=6)
┏━━━━━━━━━━━━━━━━━━━━┓
┃ Clip(values, 3, 6) ┃
┡━━━━━━━━━━━━━━━━━━━━┩
│ int64              │
├────────────────────┤
│               NULL │
│                  3 │
│                  3 │
│               NULL │
│                  5 │
│               NULL │
│               NULL │
│                  6 │
└────────────────────┘

cos

cos()

Compute the cosine of self.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.cos()
┏━━━━━━━━━━━━━┓
┃ Cos(values) ┃
┡━━━━━━━━━━━━━┩
│ float64     │
├─────────────┤
│    0.540302 │
│    1.000000 │
│    0.540302 │
└─────────────┘

cot

cot()

Compute the cotangent of self.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.cot()
┏━━━━━━━━━━━━━┓
┃ Cot(values) ┃
┡━━━━━━━━━━━━━┩
│ float64     │
├─────────────┤
│   -0.642093 │
│         inf │
│    0.642093 │
└─────────────┘

degrees

degrees()

Compute the degrees of self radians.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> from math import pi
>>> t = ibis.memtable({"values": [0, pi / 2, pi, 3 * pi / 2, 2 * pi]})
>>> t.values.degrees()
┏━━━━━━━━━━━━━━━━━┓
┃ Degrees(values) ┃
┡━━━━━━━━━━━━━━━━━┩
│ float64         │
├─────────────────┤
│             0.0 │
│            90.0 │
│           180.0 │
│           270.0 │
│           360.0 │
└─────────────────┘

exp

exp()

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

Returns

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

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": range(4)})
>>> t.values.exp()
┏━━━━━━━━━━━━━┓
┃ Exp(values) ┃
┡━━━━━━━━━━━━━┩
│ float64     │
├─────────────┤
│    1.000000 │
│    2.718282 │
│    7.389056 │
│   20.085537 │
└─────────────┘

floor

floor()

Return the floor of an expression.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1, 1.1, 2, 2.1, 3.3]})
>>> t.values.floor()
┏━━━━━━━━━━━━━━━┓
┃ Floor(values) ┃
┡━━━━━━━━━━━━━━━┩
│ int64         │
├───────────────┤
│             1 │
│             1 │
│             2 │
│             2 │
│             3 │
└───────────────┘

ln

ln()

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

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1, 2.718281828, 3]})
>>> t.values.ln()
┏━━━━━━━━━━━━┓
┃ Ln(values) ┃
┡━━━━━━━━━━━━┩
│ float64    │
├────────────┤
│   0.000000 │
│   1.000000 │
│   1.098612 │
└────────────┘

log

log(base=None)

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

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

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> from math import e
>>> t = ibis.memtable({"values": [e, e**2, e**3]})
>>> t.values.log()
┏━━━━━━━━━━━━━┓
┃ Log(values) ┃
┡━━━━━━━━━━━━━┩
│ float64     │
├─────────────┤
│         1.0 │
│         2.0 │
│         3.0 │
└─────────────┘

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [10, 100, 1000]})
>>> t.values.log(base=10)
┏━━━━━━━━━━━━━━━━━┓
┃ Log(values, 10) ┃
┡━━━━━━━━━━━━━━━━━┩
│ float64         │
├─────────────────┤
│             1.0 │
│             2.0 │
│             3.0 │
└─────────────────┘

log10

log10()

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

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1, 10, 100]})
>>> t.values.log10()
┏━━━━━━━━━━━━━━━┓
┃ Log10(values) ┃
┡━━━━━━━━━━━━━━━┩
│ float64       │
├───────────────┤
│           0.0 │
│           1.0 │
│           2.0 │
└───────────────┘

log2

log2()

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

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1, 2, 4, 8]})
>>> t.values.log2()
┏━━━━━━━━━━━━━━┓
┃ Log2(values) ┃
┡━━━━━━━━━━━━━━┩
│ float64      │
├──────────────┤
│          0.0 │
│          1.0 │
│          2.0 │
│          3.0 │
└──────────────┘

negate

negate()

Negate a numeric expression.

Returns

Type Description
NumericValue A numeric value expression

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.negate()
┏━━━━━━━━━━━━━━━━┓
┃ Negate(values) ┃
┡━━━━━━━━━━━━━━━━┩
│ int64          │
├────────────────┤
│              1 │
│              0 │
│             -1 │
└────────────────┘

point

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

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.examples.zones.fetch()
>>> t.x_cent.point(t.y_cent)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ GeoPoint(x_cent, y_cent)         ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ point                            │
├──────────────────────────────────┤
│ <POINT (935996.821 191376.75)>   │
│ <POINT (1031085.719 164018.754)> │
│ <POINT (1026452.617 254265.479)> │
│ <POINT (990633.981 202959.782)>  │
│ <POINT (931871.37 140681.351)>   │
│ <POINT (964319.735 157998.936)>  │
│ <POINT (1006496.679 216719.218)> │
│ <POINT (1005551.571 222936.088)> │
│ <POINT (1043002.677 212969.849)> │
│ <POINT (1042223.605 186706.496)> │
│ …                                │
└──────────────────────────────────┘

radians

radians()

Compute radians from self degrees.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [0, 90, 180, 270, 360]})
>>> t.values.radians()
┏━━━━━━━━━━━━━━━━━┓
┃ Radians(values) ┃
┡━━━━━━━━━━━━━━━━━┩
│ float64         │
├─────────────────┤
│        0.000000 │
│        1.570796 │
│        3.141593 │
│        4.712389 │
│        6.283185 │
└─────────────────┘

round

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 is False-y; self.type() is decimal → decimal - digits is nonzero; self.type() is decimal → decimal - digits is False-y; self.type() is Floating → int64 - digits is nonzero; self.type() is Floating → float64 None

Returns

Type Description
NumericValue The rounded expression

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1.22, 1.64, 2.15, 2.54]})
>>> t
┏━━━━━━━━━┓
┃ values  ┃
┡━━━━━━━━━┩
│ float64 │
├─────────┤
│    1.22 │
│    1.64 │
│    2.15 │
│    2.54 │
└─────────┘

>>> t.values.round()
┏━━━━━━━━━━━━━━━┓
┃ Round(values) ┃
┡━━━━━━━━━━━━━━━┩
│ int64         │
├───────────────┤
│             1 │
│             2 │
│             2 │
│             3 │
└───────────────┘

>>> t.values.round(digits=1)
┏━━━━━━━━━━━━━━━━━━┓
┃ Round(values, 1) ┃
┡━━━━━━━━━━━━━━━━━━┩
│ float64          │
├──────────────────┤
│              1.2 │
│              1.6 │
│              2.2 │
│              2.5 │
└──────────────────┘

sign

sign()

Return the sign of the input.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 2, -3, 4]})
>>> t.values.sign()
┏━━━━━━━━━━━━━━┓
┃ Sign(values) ┃
┡━━━━━━━━━━━━━━┩
│ int64        │
├──────────────┤
│           -1 │
│            1 │
│           -1 │
│            1 │
└──────────────┘

sin

sin()

Compute the sine of self.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.sin()
┏━━━━━━━━━━━━━┓
┃ Sin(values) ┃
┡━━━━━━━━━━━━━┩
│ float64     │
├─────────────┤
│   -0.841471 │
│    0.000000 │
│    0.841471 │
└─────────────┘

sqrt

sqrt()

Compute the square root of self.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [1, 4, 9, 16]})
>>> t.values.sqrt()
┏━━━━━━━━━━━━━━┓
┃ Sqrt(values) ┃
┡━━━━━━━━━━━━━━┩
│ float64      │
├──────────────┤
│          1.0 │
│          2.0 │
│          3.0 │
│          4.0 │
└──────────────┘

tan

tan()

Compute the tangent of self.

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 0, 1]})
>>> t.values.tan()
┏━━━━━━━━━━━━━┓
┃ Tan(values) ┃
┡━━━━━━━━━━━━━┩
│ float64     │
├─────────────┤
│   -1.557408 │
│    0.000000 │
│    1.557408 │
└─────────────┘

NumericColumn

NumericColumn(self, arg)

Methods

Name Description
bucket Compute a discrete binning of a numeric array.
corr Return the correlation of two numeric columns.
cov Return the covariance of two numeric columns.
cummean Return the cumulative mean of the input.
cumsum Return the cumulative sum of the input.
histogram Compute a histogram with fixed width bins.
mean Return the mean of a numeric column.
std Return the standard deviation of a numeric column.
sum Return the sum of a numeric column.
var Return the variance of a numeric column.

bucket

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: python 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

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

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

cummean(where=None, group_by=None, order_by=None)

Return the cumulative mean of the input.

cumsum

cumsum(where=None, group_by=None, order_by=None)

Return the cumulative sum of the input.

histogram

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

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

std

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

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

var

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

IntegerValue(self, arg)

Methods

Name Description
convert_base Convert an integer from one base to another.
label Label a set of integer values with strings.
to_interval Convert an integer to an interval.
to_timestamp Convert an integral UNIX timestamp to a timestamp expression.

convert_base

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

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

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

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

IntegerColumn(self, arg)

Methods

Name Description
bit_and Aggregate the column using the bitwise and operator.
bit_or Aggregate the column using the bitwise or operator.
bit_xor Aggregate the column using the bitwise exclusive or operator.

bit_and

bit_and(where=None)

Aggregate the column using the bitwise and operator.

bit_or

bit_or(where=None)

Aggregate the column using the bitwise or operator.

bit_xor

bit_xor(where=None)

Aggregate the column using the bitwise exclusive or operator.

FloatingValue

FloatingValue(self, arg)

Methods

Name Description
isinf Return whether the value is infinity.
isnan Return whether the value is NaN.

isinf

isinf()

Return whether the value is infinity.

isnan

isnan()

Return whether the value is NaN.

DecimalValue

DecimalValue(self, arg)

BooleanValue

BooleanValue(self, arg)

Methods

Name Description
ifelse Construct a ternary conditional expression.

ifelse

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 or NULL required

Returns

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

Examples

>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"is_person": [True, False, True, None]})
>>> t.is_person.ifelse("yes", "no")
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ IfElse(is_person, 'yes', 'no') ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ string                         │
├────────────────────────────────┤
│ yes                            │
│ no                             │
│ yes                            │
│ no                             │
└────────────────────────────────┘

and_

ibis.and_(*predicates)

Combine multiple predicates using &.

Parameters

Name Type Description Default
predicates ir.BooleanValue Boolean value expressions ()

Returns

Type Description
BooleanValue A new predicate that evaluates to True if all composing predicates are True. If no predicates were provided, returns True.

or_

ibis.or_(*predicates)

Combine multiple predicates using |.

Parameters

Name Type Description Default
predicates ir.BooleanValue Boolean value expressions ()

Returns

Type Description
BooleanValue A new predicate that evaluates to True if any composing predicates are True. If no predicates were provided, returns False.

random

ibis.random()

Return a random floating point number in the range [0.0, 1.0).

Similar to random.random in the Python standard library.

Repeated use of random

ibis.random() will generate a column of distinct random numbers even if the same instance of ibis.random() is re-used.

When Ibis compiles an expression to SQL, each place where random is used will render as a separate call to the given backend’s random number generator.

>>> from ibis.interactive import *
>>> t = ibis.memtable({"a": range(5)})
>>> r_a = ibis.random()
>>> t.mutate(random_1=r_a, random_2=r_a)  # doctest: +SKIP
┏━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┓
┃ a     ┃ random_1 ┃ random_2 ┃
┡━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━┩
│ int64 │ float64  │ float64  │
├───────┼──────────┼──────────┤
│     0 │ 0.191130 │ 0.098715 │
│     1 │ 0.255262 │ 0.828454 │
│     2 │ 0.011804 │ 0.392275 │
│     3 │ 0.309941 │ 0.347300 │
│     4 │ 0.482783 │ 0.095562 │
└───────┴──────────┴──────────┘

Returns

Type Description
FloatingScalar Random float value expression
Back to top