Core language functions¶
eval (expression) |
Evaluate a Hail expression, returning the result. |
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.
eval
(expression)[source]¶ Evaluate a Hail expression, returning the result.
This method is extremely useful for learning about Hail expressions and understanding how to compose them.
The expression must have no indices, but can refer to the globals of a
Table
orMatrixTable
.Examples
Evaluate a conditional:
>>> x = 6 >>> hl.eval(hl.cond(x % 2 == 0, 'Even', 'Odd')) 'Even'
Parameters: expression Returns: Any
-
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
orMatrixTable
.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.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 toFalse
, 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 isTrue
. - alternate (
Expression
) – Branch to return if the condition isFalse
. - missing_false (
bool
) – IfTrue
, treat missing condition asFalse
.
Returns: Expression
– One of consequent, alternate, or missing, based on condition.- 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()) >>> hl.eval(expr) 3
See also
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)) >>> hl.eval(expr) 2
Parameters: missing_false ( bool
) – Treat missing predicates asFalse
.See also
Returns: CaseBuilder
.
-
hail.expr.functions.
bind
(f: Callable, *exprs)[source]¶ 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.- f (function ( (args) ->
-
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.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
orHailType
) – 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.eval(hl.str(hl.struct(a=5, b=7))) '{"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.eval(hl.is_missing(5)) False
>>> hl.eval(hl.is_missing(hl.null(hl.tstr))) True
>>> hl.eval(hl.is_missing(hl.null(hl.tbool) & True)) True
Parameters: expression – Expression to test. Returns: BooleanExpression
–True
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.eval(hl.is_defined(5)) True
>>> hl.eval(hl.is_defined(hl.null(hl.tstr))) False
>>> hl.eval(hl.is_defined(hl.null(hl.tbool) & True)) False
Parameters: expression – Expression to test. Returns: BooleanExpression
–True
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.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
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.eval(hl.or_else(5, 7)) 5
>>> hl.eval(hl.or_else(hl.null(hl.tint32), 7)) 7
See also
Parameters: - a (
Expression
) - b (
Expression
)
Returns: - a (
-
hail.expr.functions.
or_missing
(predicate, value)[source]¶ 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 isTrue
.
Returns: Expression
– This expression has the same type as b.- predicate (
-
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.eval(hl.range(0, 10)) [0, 1, 2, 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.
Parameters: - start (int or
Expression
of typetint32
) – Start of range. - stop (int or
Expression
of typetint32
) – End of range. - step (int or
Expression
of typetint32
) – Step of range.
Returns: ArrayInt32Expression
- start (int or
-
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)) >>> hl.eval(expr) 2
Notes
All expressions appearing as the then parameters to
when()
ordefault()
method calls must be the same type.Parameters: missing_false ( bool
) – Treat missing predicates asFalse
.-
default
(then)[source]¶ Finish the case statement by adding a default case.
Notes
If no condition from a
when()
call isTrue
, then then is returned.Parameters: then ( Expression
)Returns: Expression
-
or_error
(message)[source]¶ Finish the case statement by throwing an error with the given message.
Notes
If no condition from a
CaseBuilder.when()
call isTrue
, then an error is thrown.Parameters: message ( str
)Returns: Expression
-
or_missing
()[source]¶ Finish the case statement by returning missing.
Notes
If no condition from a
CaseBuilder.when()
call isTrue
, 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 asFalse
. A condition that evaluates to missing will return a missing result, not proceed to the next case. Always test missingness first in aCaseBuilder
.Parameters: - condition (
BooleanExpression
) - then (
Expression
)
Returns: CaseBuilder
– Mutates and returns self.- condition (
-
-
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()) >>> hl.eval(expr) 3
Notes
All expressions appearing as the then parameters to
when()
ordefault()
method calls must be the same type.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
andNA != NA
returnNA
. Usewhen_missing()
to test missingness.Parameters: - value (
Expression
) - then (
Expression
)
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.
-