Core language functions¶
|
Captures and broadcasts a Python variable or object as an expression. |
|
Deprecated in favor of |
|
Expression for an if/else statement; tests a condition and returns one of two options based on the result. |
|
Build a conditional tree on the value of an expression. |
|
Chain multiple if-else statements with a |
|
Bind a temporary variable and use it in a function. |
|
Bind a temporary variable and use it in a function. |
|
Creates an expression representing a missing value of a specified type. |
|
Deprecated in favor of |
|
Returns the string representation of x. |
|
Returns |
|
Returns |
|
Returns the first non-missing value of args. |
|
If a is missing, return b. |
|
Returns value if predicate is |
|
Returns an array of integers from start to stop by step. |
|
Query records from a table corresponding to a given point or range of keys. |
-
hail.expr.functions.
literal
(x, dtype=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() +-------+------------------+ | 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
orMatrixTable
.- Parameters
x – Object to capture and broadcast as an expression.
- Returns
-
hail.expr.functions.
cond
(condition, consequent, alternate, missing_false=False)[source]¶ 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 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.
-
hail.expr.functions.
if_else
(condition, consequent, alternate, missing_false=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.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 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.
-
hail.expr.functions.
switch
(expr)[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
-
hail.expr.functions.
case
(missing_false=False)[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
-
hail.expr.functions.
bind
(f, *exprs, _ctx=None)[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.
-
hail.expr.functions.
rbind
(*exprs, _ctx=None)[source]¶ 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)[source]¶ 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
- Returns
Expression
– A missing expression of type t.
-
hail.expr.functions.
null
(t)[source]¶ 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
- Returns
Expression
– A missing expression of type t.
-
hail.expr.functions.
str
(x)[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
-
hail.expr.functions.
is_missing
(expression)[source]¶ 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)[source]¶ 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)[source]¶ 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
- Parameters
args (variable-length args of
Expression
)- Returns
-
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.missing(hl.tint32), 7)) 7
See also
- Parameters
a (
Expression
)b (
Expression
)
- Returns
-
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.
-
hail.expr.functions.
range
(start, stop=None, step=1)[source]¶ 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 typetint32
) – Start of range.stop (int or
Expression
of typetint32
) – End of range.step (int or
Expression
of typetint32
) – Step of range.
- Returns
-
hail.expr.functions.
query_table
(path, point_or_interval)[source]¶ 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
Class for chaining multiple if-else statements. |
|
Class for generating conditional trees based on value of an expression. |