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
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.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 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()) >>> expr.value 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)) >>> expr.value 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
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.- 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.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
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.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: 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.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: 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.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
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
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.or_missing(True, 5).value 5
>>> hl.or_missing(False, 5).value 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.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: - 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)) >>> expr.value 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_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 nextwhen()
ordefault()
. 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()) >>> expr.value 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.
-