Core language functions

literal(x[, dtype])	Captures and broadcasts a Python variable or object as an expression.
cond(condition, consequent, alternate[, …])	Deprecated in favor of if_else().
if_else(condition, consequent, alternate[, …])	Expression for an if/else statement; tests a condition and returns one of two options based on the result.
switch(expr)	Build a conditional tree on the value of an expression.
case([missing_false])	Chain multiple if-else statements with a CaseBuilder.
bind(f, *exprs[, _ctx])	Bind a temporary variable and use it in a function.
rbind(*exprs[, _ctx])	Bind a temporary variable and use it in a function.
missing(t)	Creates an expression representing a missing value of a specified type.
null(t)	Deprecated in favor of missing().
str(x)	Returns the string representation of x.
is_missing(expression)	Returns True if the argument is missing.
is_defined(expression)	Returns True if the argument is not missing.
coalesce(*args)	Returns the first non-missing value of args.
or_else(a, b)	If a is missing, return b.
or_missing(predicate, value)	Returns value if predicate is True, otherwise returns missing.
range(start[, stop, step])	Returns an array of integers from start to stop by step.
query_table(path, point_or_interval)	Query records from a table corresponding to a given point or range of keys.

hail.expr.functions.literal(x, dtype=None)

Captures and broadcasts a Python variable or object as an expression.

Examples

>>> table = hl.utils.range_table(8)
>>> greetings = hl.literal({1: 'Good morning', 4: 'Good afternoon', 6 : 'Good evening'})
>>> table.annotate(greeting = greetings.get(table.idx)).show()
+-------+------------------+
|   idx | greeting         |
+-------+------------------+
| int32 | str              |
+-------+------------------+
|     0 | NA               |
|     1 | "Good morning"   |
|     2 | NA               |
|     3 | NA               |
|     4 | "Good afternoon" |
|     5 | NA               |
|     6 | "Good evening"   |
|     7 | NA               |
+-------+------------------+

Notes

Use this function to capture large Python objects for use in expressions. This function provides an alternative to adding an object as a global annotation on a Table or MatrixTable.

Parameters

x – Object to capture and broadcast as an expression.

Returns

Expression

hail.expr.functions.cond(condition, consequent, alternate, missing_false=False)

Deprecated in favor of if_else().

Expression for an if/else statement; tests a condition and returns one of two options based on the result.

Examples

>>> x = 5
>>> hl.eval(hl.cond(x < 2, 'Hi', 'Bye'))
'Bye'

>>> a = hl.literal([1, 2, 3, 4])
>>> hl.eval(hl.cond(hl.len(a) > 0, 2.0 * a, a / 2.0))
[2.0, 4.0, 6.0, 8.0]

Notes

If condition evaluates to True, returns consequent. If condition evaluates to False, returns alternate. If predicate is missing, returns missing.

Note

The type of consequent and alternate must be the same.

Parameters

• condition (BooleanExpression) – Condition to test.

• consequent (Expression) – Branch to return if the condition is True.

• alternate (Expression) – Branch to return if the condition is False.

• missing_false (bool) – If True, treat missing condition as False.

See also

case(), switch(), if_else()

Returns

Expression – One of consequent, alternate, or missing, based on condition.

hail.expr.functions.if_else(condition, consequent, alternate, missing_false=False)

Expression for an if/else statement; tests a condition and returns one of two options based on the result.

Examples

>>> x = 5
>>> hl.eval(hl.if_else(x < 2, 'Hi', 'Bye'))
'Bye'

>>> a = hl.literal([1, 2, 3, 4])
>>> hl.eval(hl.if_else(hl.len(a) > 0, 2.0 * a, a / 2.0))
[2.0, 4.0, 6.0, 8.0]

Notes

If condition evaluates to True, returns consequent. If condition evaluates to False, returns alternate. If predicate is missing, returns missing.

Note

The type of consequent and alternate must be the same.

Parameters

• condition (BooleanExpression) – Condition to test.

• consequent (Expression) – Branch to return if the condition is True.

• alternate (Expression) – Branch to return if the condition is False.

• missing_false (bool) – If True, treat missing condition as False.

See also

case(), switch()

Returns

Expression – One of consequent, alternate, or missing, based on condition.

hail.expr.functions.switch(expr)

Build a conditional tree on the value of an expression.

Examples

>>> csq = hl.literal('loss of function')
>>> expr = (hl.switch(csq)
...                  .when('synonymous', 1)
...                  .when('SYN', 1)
...                  .when('missense', 2)
...                  .when('MIS', 2)
...                  .when('loss of function', 3)
...                  .when('LOF', 3)
...                  .or_missing())
>>> hl.eval(expr)
3

See also

SwitchBuilder, case(), cond()

Parameters

expr (Expression) – Value to match against.

Returns

SwitchBuilder

hail.expr.functions.case(missing_false=False)

Chain multiple if-else statements with a CaseBuilder.

Examples

>>> x = hl.literal('foo bar baz')
>>> expr = (hl.case()
...                  .when(x[:3] == 'FOO', 1)
...                  .when(hl.len(x) == 11, 2)
...                  .when(x == 'secret phrase', 3)
...                  .default(0))
>>> hl.eval(expr)
2

Parameters

missing_false (bool) – Treat missing predicates as False.

See also

CaseBuilder, switch(), cond()

Returns

CaseBuilder.

hail.expr.functions.bind(f, *exprs, _ctx=None)

Bind a temporary variable and use it in a function.

Examples

>>> hl.eval(hl.bind(lambda x: x + 1, 1))
2

bind() also can take multiple arguments:

>>> hl.eval(hl.bind(lambda x, y: x / y, x, x))
1.0

Parameters

• f (function ( (args) -> Expression)) – Function of exprs.

• exprs (variable-length args of Expression) – Expressions to bind.

Returns

Expression – Result of evaluating f with exprs as arguments.

hail.expr.functions.rbind(*exprs, _ctx=None)

Bind a temporary variable and use it in a function.

This is bind() with flipped argument order.

Examples

>>> hl.eval(hl.rbind(1, lambda x: x + 1))
2

rbind() also can take multiple arguments:

>>> hl.eval(hl.rbind(4.0, 2.0, lambda x, y: x / y))
2.0

Parameters

• exprs (variable-length args of Expression) – Expressions to bind.

• f (function ( (args) -> Expression)) – Function of exprs.

Returns

Expression – Result of evaluating f with exprs as arguments.

hail.expr.functions.missing(t)

Creates an expression representing a missing value of a specified type.

Examples

>>> hl.eval(hl.missing(hl.tarray(hl.tstr)))
None

>>> hl.eval(hl.missing('array<str>'))
None

Notes

This method is useful for constructing an expression that includes missing values, since None cannot be interpreted as an expression.

Parameters

t (str or HailType) – Type of the missing expression.

Returns

Expression – A missing expression of type t.

hail.expr.functions.null(t)

Deprecated in favor of missing().

Creates an expression representing a missing value of a specified type.

Examples

>>> hl.eval(hl.null(hl.tarray(hl.tstr)))
None

>>> hl.eval(hl.null('array<str>'))
None

Notes

This method is useful for constructing an expression that includes missing values, since None cannot be interpreted as an expression.

Parameters

t (str or HailType) – Type of the missing expression.

Returns

Expression – A missing expression of type t.

hail.expr.functions.str(x)

Returns the string representation of x.

Examples

>>> hl.eval(hl.str(hl.struct(a=5, b=7)))
'{"a":5,"b":7}'

Parameters

x

Returns

StringExpression

hail.expr.functions.is_missing(expression)

Returns True if the argument is missing.

Examples

>>> hl.eval(hl.is_missing(5))
False

>>> hl.eval(hl.is_missing(hl.missing(hl.tstr)))
True

>>> hl.eval(hl.is_missing(hl.missing(hl.tbool) & True))
True

Parameters

expression – Expression to test.

Returns

BooleanExpression – True if expression is missing, False otherwise.

hail.expr.functions.is_defined(expression)

Returns True if the argument is not missing.

Examples

>>> hl.eval(hl.is_defined(5))
True

>>> hl.eval(hl.is_defined(hl.missing(hl.tstr)))
False

>>> hl.eval(hl.is_defined(hl.missing(hl.tbool) & True))
False

Parameters

expression – Expression to test.

Returns

BooleanExpression – True if expression is not missing, False otherwise.

hail.expr.functions.coalesce(*args)

Returns the first non-missing value of args.

Examples

>>> x1 = hl.missing('int')
>>> x2 = 2
>>> hl.eval(hl.coalesce(x1, x2))
2

Notes

All arguments must have the same type, or must be convertible to a common type (all numeric, for instance).

See also

or_else()

Parameters

args (variable-length args of Expression)

Returns

Expression

hail.expr.functions.or_else(a, b)

If a is missing, return b.

Examples

>>> hl.eval(hl.or_else(5, 7))
5

>>> hl.eval(hl.or_else(hl.missing(hl.tint32), 7))
7

See also

coalesce()

Parameters

• a (Expression)

• b (Expression)

Returns

Expression

hail.expr.functions.or_missing(predicate, value)

Returns value if predicate is True, otherwise returns missing.

Examples

>>> hl.eval(hl.or_missing(True, 5))
5

>>> hl.eval(hl.or_missing(False, 5))
None

Parameters

• predicate (BooleanExpression)

• value (Expression) – Value to return if predicate is True.

Returns

Expression – This expression has the same type as b.

hail.expr.functions.range(start, stop=None, step=1)

Returns an array of integers from start to stop by step.

Examples

>>> hl.eval(hl.range(10))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

>>> hl.eval(hl.range(3, 10))
[3, 4, 5, 6, 7, 8, 9]

>>> hl.eval(hl.range(0, 10, step=3))
[0, 3, 6, 9]

Notes

The range includes start, but excludes stop.

If provided exactly one argument, the argument is interpreted as stop and start is set to zero. This matches the behavior of Python’s range.

Parameters

• start (int or Expression of type tint32) – Start of range.

• stop (int or Expression of type tint32) – End of range.

• step (int or Expression of type tint32) – Step of range.

Returns

ArrayNumericExpression

hail.expr.functions.query_table(path, point_or_interval)

Query records from a table corresponding to a given point or range of keys.

Notes

This function does not dispatch to a distributed runtime; it can be used inside already-distributed queries such as in Table.annotate().

Warning

This function contains no safeguards against reading large amounts of data using a single thread.

Parameters

• path (str) – Table path.

• point_or_interval – Point or interval to query.

Returns

ArrayExpression

CaseBuilder	Class for chaining multiple if-else statements.
SwitchBuilder	Class for generating conditional trees based on value of an expression.