Core language functions

literal(x, dtype, str, NoneType] = None) Captures and broadcasts a Python variable or object as an expression.
cond(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) Bind a temporary variable and use it in a function.
null(t, str]) Creates an expression representing a missing value of a specified type.
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.
hail.expr.functions.literal(x: Any, dtype: Union[hail.expr.types.HailType, str, NoneType] = None)[source]

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()
+-------+----------------+
| index | 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: bool = False)[source]

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

Examples

>>> x = 5
>>> hl.cond(x < 2, 'Hi', 'Bye').value
'Bye'
>>> a = hl.literal([1, 2, 3, 4])
>>> hl.cond(hl.len(a) > 0, 2.0 * a, a / 2.0).value
[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) → hail.expr.builders.SwitchBuilder[source]

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())
>>> expr.value
3
Parameters:expr (Expression) – Value to match against.
Returns:SwitchBuilder
hail.expr.functions.case(missing_false: bool = False) → hail.expr.builders.CaseBuilder[source]

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))
>>> expr.value
2
Parameters:missing_false (bool) – Treat missing predicates as False.
Returns:CaseBuilder.
hail.expr.functions.bind(f: Callable, *exprs)[source]

Bind a temporary variable and use it in a function.

Examples

Expressions are “inlined”, leading to perhaps unexpected behavior when randomness is involved. For example, let us define a variable x from the rand_unif() method:

>>> x = hl.rand_unif(0, 1)

Note that evaluating x multiple times returns different results. The value of evaluating x is unknown when the expression is defined.

>>> x.value
0.3189309481038456
>>> x.value
0.20842918568366375

What if we evaluate x multiple times?

>>> hl.array([x, x, x]).value
[0.49582541026815163, 0.8549329234134524, 0.7016124997911775]

The random number generator is called separately for each inclusion of x. This method, bind(), is the solution to this problem!

>>> hl.bind(lambda y: [y, y, y], x).value
[0.7897028763765286, 0.7897028763765286, 0.7897028763765286]

bind() also can take multiple arguments:

>>> hl.bind(lambda x, y: x / y, x, x).value
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.null(t: Union[hail.expr.types.HailType, str])[source]

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

Examples

>>> hl.null(hl.tarray(hl.tstr)).value
None
>>> hl.null('array<str>').value
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) → hail.expr.expressions.typed_expressions.StringExpression[source]

Returns the string representation of x.

Examples

>>> hl.str(hl.struct(a=5, b=7)).value
'{"a": 5, "b": 7}'
Parameters:x
Returns:StringExpression
hail.expr.functions.is_missing(expression) → hail.expr.expressions.typed_expressions.BooleanExpression[source]

Returns True if the argument is missing.

Examples

>>> hl.is_missing(5).value
False
>>> hl.is_missing(hl.null(hl.tstr)).value
True
>>> hl.is_missing(hl.null(hl.tbool) & True).value
True
Parameters:expression – Expression to test.
Returns:BooleanExpressionTrue if expression is missing, False otherwise.
hail.expr.functions.is_defined(expression) → hail.expr.expressions.typed_expressions.BooleanExpression[source]

Returns True if the argument is not missing.

Examples

>>> hl.is_defined(5).value
True
>>> hl.is_defined(hl.null(hl.tstr)).value
False
>>> hl.is_defined(hl.null(hl.tbool) & True).value
False
Parameters:expression – Expression to test.
Returns:BooleanExpressionTrue if expression is not missing, False otherwise.
hail.expr.functions.coalesce(*args)[source]

Returns the first non-missing value of args.

Examples

>>> x1 = hl.null('int')
>>> x2 = 2
>>> hl.coalesce(x1, x2).value
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)[source]

If a is missing, return b.

Examples

>>> hl.or_else(5, 7).value
5
>>> hl.or_else(hl.null(hl.tint32), 7).value
7

See also

coalesce()

Parameters:
Returns:

Expression

hail.expr.functions.or_missing(predicate, value)[source]

Returns value if predicate is True, otherwise returns missing.

Examples

>>> hl.or_missing(True, 5).value
5
>>> hl.or_missing(False, 5).value
None
Parameters:
Returns:

Expression – This expression has the same type as b.

hail.expr.functions.range(start, stop, step=1) → hail.expr.expressions.typed_expressions.ArrayNumericExpression[source]

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

Examples

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

Notes

The range includes start, but excludes stop.

Parameters:
Returns:

ArrayInt32Expression

class hail.expr.builders.CaseBuilder(missing_false=False)[source]

Class for chaining multiple if-else statements.

Examples

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

Notes

All expressions appearing as the then parameters to when() or default() method calls must be the same type.

Parameters:missing_false (bool) – Treat missing predicates as False.

See also

case(), cond(), switch()

default(then)[source]

Finish the case statement by adding a default case.

Notes

If no condition from a when() call is True, then then is returned.

Parameters:then (Expression)
Returns:Expression
or_missing()[source]

Finish the case statement by returning missing.

Notes

If no condition from a CaseBuilder.when() call is True, then the result is missing.

Parameters:then (Expression)
Returns:Expression
when(condition, then) → CaseBuilder[source]

Add a branch. If condition is True, then returns then.

Warning

Missingness is treated similarly to cond(). Missingness is not treated as False. A condition that evaluates to missing will return a missing result, not proceed to the next when() or default(). Always test missingness first in a CaseBuilder.

Parameters:
Returns:

CaseBuilder – Mutates and returns self.

class hail.expr.builders.SwitchBuilder(base)[source]

Class for generating conditional trees based on 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())
>>> expr.value
3

Notes

All expressions appearing as the then parameters to when() or default() method calls must be the same type.

See also

case(), cond(), switch()

Parameters:expr (Expression) – Value to match against.
default(then)[source]

Finish the switch statement by adding a default case.

Notes

If no value from a when() call is matched, then then is returned.

Parameters:then (Expression)
Returns:Expression
or_missing()[source]

Finish the switch statement by returning missing.

Notes

If no value from a when() call is matched, then the result is missing.

Parameters:then (Expression)
Returns:Expression
when(value, then) → SwitchBuilder[source]
Add a value test. If the base expression is equal to value, then
returns then.

Warning

Missingness always compares to missing. Both NA == NA and NA != NA return NA. Use when_missing() to test missingness.

Parameters:
Returns:

SwitchBuilder – Mutates and returns self.

when_missing(then) → SwitchBuilder[source]

Add a test for missingness. If the base expression is missing, returns then.

Parameters:then (Expression)
Returns:SwitchBuilder – Mutates and returns self.