>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"values": [-1, 2, -3, 4]})
>>> t.values.abs()
┏━━━━━━━━━━━━━┓ ┃ Abs(values) ┃ ┡━━━━━━━━━━━━━┩ │ int64 │ ├─────────────┤ │ 1 │ │ 2 │ │ 3 │ │ 4 │ └─────────────┘
Integer, floating point, decimal, and boolean expressions.
NumericValue(self, arg)
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()
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.
NULL
values are preserved and are not replaced with bounds.
Name | Type | Description | Default |
---|---|---|---|
lower |
NumericValue | None | Lower bound | None |
upper |
NumericValue | None | Upper bound | None |
Type | Description |
---|---|
NumericValue | Clipped input |
>>> 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()
Compute the cosine of self
.
cot()
Compute the cotangent of self
.
degrees()
Compute the degrees of self
radians.
>>> 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()
Compute \(e^\texttt{self}\).
Type | Description |
---|---|
NumericValue | \(e^\texttt{self}\) |
floor()
Return the floor of an expression.
ln()
Compute \(\ln\left(\texttt{self}\right)\).
log(base=None)
Compute \(\log_{\texttt{base}}\left(\texttt{self}\right)\).
Name | Type | Description | Default |
---|---|---|---|
base |
NumericValue | None | The base of the logarithm. If None , base e is used. |
None |
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.
Type | Description |
---|---|
NumericValue | A numeric value expression |
point(right)
Return a point constructed from the coordinate values.
Constant coordinates result in construction of a POINT
literal or column.
Name | Type | Description | Default |
---|---|---|---|
right |
int | float | NumericValue | Y coordinate | required |
Type | Description |
---|---|
PointValue |
Points |
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.examples.zones.fetch()
>>> t.x_cent.point(t.y_cent)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ GeoPoint(x_cent, y_cent) ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ point:geometry │ ├──────────────────────────────────┤ │ <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()
Compute radians from self
degrees.
>>> 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(digits=None)
Round values to an indicated number of decimal places.
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 |
Type | Description |
---|---|
NumericValue | The rounded expression |
>>> 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 │ └─────────┘
┏━━━━━━━━━━━━━━━┓ ┃ Round(values) ┃ ┡━━━━━━━━━━━━━━━┩ │ int64 │ ├───────────────┤ │ 1 │ │ 2 │ │ 2 │ │ 3 │ └───────────────┘
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
.
NumericColumn(self, arg)
Name | Description |
---|---|
approx_quantile | Compute one or more approximate quantiles of a column. |
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. |
approx_quantile(quantile, where=None)
Compute one or more approximate quantiles of a column.
Whether the result is an approximation depends on the backend.
Name | Type | Description | Default |
---|---|---|---|
quantile |
float | ir .NumericValue | Sequence[ir .NumericValue | float] |
0 <= quantile <= 1 , or an array of such values indicating the quantile or quantiles to compute |
required |
where |
ir .BooleanValue | None |
Boolean filter for input values | None |
Type | Description |
---|---|
Scalar | Quantile of the input |
Compute the approximate 0.50 quantile of bill_depth_mm
.
Compute multiple approximate quantiles in one call - in this case the result is an array.
bucket(buckets, closed='left', close_extreme=True, include_under=False, include_over=False)
Compute a discrete binning of a numeric array.
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 |
Type | Description |
---|---|
IntegerColumn | A categorical column expression |
corr(right, where=None, how='sample')
Return the correlation of two numeric columns.
Name | Type | Description | Default |
---|---|---|---|
right |
NumericColumn | Numeric column | required |
where |
ir .BooleanValue | None |
Filter | None |
how |
Literal[‘sample’, ‘pop’] | Population or sample correlation | 'sample' |
Type | Description |
---|---|
NumericScalar |
The correlation of left and right |
cov(right, where=None, how='sample')
Return the covariance of two numeric columns.
Name | Type | Description | Default |
---|---|---|---|
right |
NumericColumn | Numeric column | required |
where |
ir .BooleanValue | None |
Filter | None |
how |
Literal[‘sample’, ‘pop’] | Population or sample covariance | 'sample' |
Type | Description |
---|---|
NumericScalar |
The covariance of self and right |
cummean(where=None, group_by=None, order_by=None)
Return the cumulative mean of the input.
cumsum(where=None, group_by=None, order_by=None)
Return the cumulative sum of the input.
histogram(nbins=None, binwidth=None, base=None, eps=1e-13)
Compute a histogram with fixed width bins.
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 |
Type | Description |
---|---|
Column | Bucketed column |
mean(where=None)
Return the mean of a numeric column.
Name | Type | Description | Default |
---|---|---|---|
where |
ir .BooleanValue | None |
Filter | None |
Type | Description |
---|---|
NumericScalar |
The mean of the input expression |
std(where=None, how='sample')
Return the standard deviation of a numeric column.
Name | Type | Description | Default |
---|---|---|---|
where |
ir .BooleanValue | None |
Filter | None |
how |
Literal[‘sample’, ‘pop’] | Sample or population standard deviation | 'sample' |
Type | Description |
---|---|
NumericScalar |
Standard deviation of arg |
sum(where=None)
Return the sum of a numeric column.
Name | Type | Description | Default |
---|---|---|---|
where |
ir .BooleanValue | None |
Filter | None |
Type | Description |
---|---|
NumericScalar |
The sum of the input expression |
var(where=None, how='sample')
Return the variance of a numeric column.
Name | Type | Description | Default |
---|---|---|---|
where |
ir .BooleanValue | None |
Filter | None |
how |
Literal[‘sample’, ‘pop’] | Sample or population variance | 'sample' |
Type | Description |
---|---|
NumericScalar |
Standard deviation of arg |
IntegerValue(self, arg)
Name | Description |
---|---|
as_interval | Convert an integer to an interval. |
as_timestamp | Convert an integral UNIX timestamp to a timestamp expression. |
convert_base | Convert an integer from one base to another. |
label | Label a set of integer values with strings. |
as_interval(unit='s')
Convert an integer to an interval.
Name | Type | Description | Default |
---|---|---|---|
unit |
Literal[‘Y’, ‘M’, ‘W’, ‘D’, ‘h’, ‘m’, ‘s’, ‘ms’, ‘us’, ‘ns’] | Unit for the resulting interval | 's' |
Type | Description |
---|---|
IntervalValue |
An interval in units of unit |
as_timestamp(unit)
Convert an integral UNIX timestamp to a timestamp expression.
Name | Type | Description | Default |
---|---|---|---|
unit |
Literal[‘s’, ‘ms’, ‘us’] | The resolution of arg |
required |
Type | Description |
---|---|
TimestampValue |
self converted to a timestamp |
convert_base(from_base, to_base)
Convert an integer from one base to another.
Name | Type | Description | Default |
---|---|---|---|
from_base |
IntegerValue | Numeric base of expression | required |
to_base |
IntegerValue | New base | required |
Type | Description |
---|---|
IntegerValue | Converted expression |
label(labels, nulls=None)
Label a set of integer values with strings.
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 |
Type | Description |
---|---|
StringValue |
self labeled with labels |
>>> 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 │ └───────┴─────────┘
IntegerColumn(self, arg)
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(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(self, arg)
Name | Description |
---|---|
isinf | Return whether the value is infinity. |
isnan | Return whether the value is NaN. |
isinf()
Return whether the value is infinity.
isnan()
Return whether the value is NaN.
DecimalValue(self, arg)
BooleanValue(self, arg)
Name | Description |
---|---|
ifelse | Construct a ternary conditional expression. |
negate | Negate a boolean expression. |
ifelse(true_expr, false_expr)
Construct a ternary conditional expression.
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 |
Type | Description |
---|---|
Value |
The value of true_expr if arg is True else false_expr |
>>> 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 │ └────────────────────────────────┘
negate()
Negate a boolean expression.
Type | Description |
---|---|
BooleanValue | A boolean value expression |
BooleanColumn(self, arg)
Name | Description |
---|---|
all | Return whether all elements are True . |
any | Return whether at least one element is True . |
cumall | Accumulate the all aggregate. |
cumany | Accumulate the any aggregate. |
notall | Return whether not all elements are True . |
notany | Return whether no elements are True . |
all(where=None)
Return whether all elements are True
.
Name | Type | Description | Default |
---|---|---|---|
where |
BooleanValue | None | Optional filter for the aggregation | None |
Type | Description |
---|---|
BooleanValue | Whether all elements are True |
any(where=None)
Return whether at least one element is True
.
If the expression does not reference any foreign tables, the result will be a scalar reduction, otherwise it will be a deferred expression constructing an exists subquery when passed to a table method.
Name | Type | Description | Default |
---|---|---|---|
where |
BooleanValue | None | Optional filter for the aggregation | None |
Type | Description |
---|---|
BooleanValue | Whether at least one element is True . |
Consider the following ibis expressions
import ibis
t = ibis.table(dict(a="string"))
s = ibis.table(dict(a="string"))
cond = (t.a == s.a).any()
Without knowing the table to use as the outer query there are two ways to turn this expression into a SQL EXISTS
predicate, depending on which of t
or s
is filtered on.
Filtering from t
:
Filtering from s
:
Notably the correlated subquery cannot stand on its own.
cumall(where=None, group_by=None, order_by=None)
Accumulate the all
aggregate.
Type | Description |
---|---|
BooleanColumn | A boolean column with the cumulative all aggregate. |
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"arr": [1, 2, 3, 4]})
>>> ((t.arr > 1) & (t.arr >= 1)).cumall()
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ All(And(Greater(arr, 1), GreaterEqual(arr, 1))) ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ boolean │ ├─────────────────────────────────────────────────┤ │ False │ │ False │ │ False │ │ False │ └─────────────────────────────────────────────────┘
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ All(And(Greater(arr, 0), GreaterEqual(arr, 1))) ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ boolean │ ├─────────────────────────────────────────────────┤ │ True │ │ True │ │ True │ │ True │ └─────────────────────────────────────────────────┘
cumany(where=None, group_by=None, order_by=None)
Accumulate the any
aggregate.
Type | Description |
---|---|
BooleanColumn | A boolean column with the cumulative any aggregate. |
>>> import ibis
>>> ibis.options.interactive = True
>>> t = ibis.memtable({"arr": [1, 2, 3, 4]})
>>> ((t.arr > 1) | (t.arr >= 1)).cumany()
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Any(Or(Greater(arr, 1), GreaterEqual(arr, 1))) ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ boolean │ ├────────────────────────────────────────────────┤ │ True │ │ True │ │ True │ │ True │ └────────────────────────────────────────────────┘
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Any(And(Greater(arr, 1), GreaterEqual(arr, 1))) ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ boolean │ ├─────────────────────────────────────────────────┤ │ False │ │ True │ │ True │ │ True │ └─────────────────────────────────────────────────┘
notall(where=None)
Return whether not all elements are True
.
Name | Type | Description | Default |
---|---|---|---|
where |
BooleanValue | None | Optional filter for the aggregation | None |
Type | Description |
---|---|
BooleanValue | Whether not all elements are True |
notany(where=None)
Return whether no elements are True
.
Name | Type | Description | Default |
---|---|---|---|
where |
BooleanValue | None | Optional filter for the aggregation | None |
Type | Description |
---|---|
BooleanValue | Whether no elements are True . |
ibis.and_(*predicates)
Combine multiple predicates using &
.
Name | Type | Description | Default |
---|---|---|---|
predicates |
ir .BooleanValue |
Boolean value expressions | () |
Type | Description |
---|---|
BooleanValue |
A new predicate that evaluates to True if all composing predicates are True. If no predicates were provided, returns True. |
ibis.or_(*predicates)
Combine multiple predicates using |
.
Name | Type | Description | Default |
---|---|---|---|
predicates |
ir .BooleanValue |
Boolean value expressions | () |
Type | Description |
---|---|
BooleanValue |
A new predicate that evaluates to True if any composing predicates are True. If no predicates were provided, returns False. |
ibis.random()
Return a random floating point number in the range [0.0, 1.0).
Similar to random.random
in the Python standard library.
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 │
└───────┴──────────┴──────────┘
Type | Description |
---|---|
FloatingScalar |
Random float value expression |
e
pi