Collection functions

Collection constructors

dict(collection) Creates a dictionary.
array(collection) Construct an array expression.
empty_array(t, hail.expr.functions.str]) Returns an empty array of elements of a type t.
set(collection) Convert a set expression.
empty_set(t, hail.expr.functions.str]) Returns an empty set of elements of a type t.

Collection functions

len(x) Returns the size of a collection or string.
map(f, collection) Transform each element of a collection.
flatmap(f, collection) Map each element of the collection to a new collection, and flatten the results.
zip(*arrays, fill_missing) Zip together arrays into a single array.
zip_with_index(a) Returns an array of (index, element) tuples.
flatten(collection) Flatten a nested collection by concatenating sub-collections.
any(f, collection) Returns True if f returns True for any element.
all(f, collection) Returns True if f returns True for every element.
filter(f, collection) Returns a new collection containing elements where f returns True.
sorted(collection, key[, reverse]) Returns a sorted array.
find(f, collection) Returns the first element where f returns True.
group_by(f, collection) Group collection elements into a dict according to a lambda function.
fold(f, zero, collection) Reduces a collection with the given function f, provided the initial value zero.
array_scan(f, zero, a) Map each element of a to cumulative value of function f, with initial value zero.
reversed(x) Reverses the elements of a collection.
hail.expr.functions.len(x) → hail.expr.expressions.typed_expressions.Int32Expression[source]

Returns the size of a collection or string.

Examples

>>> a = ['The', 'quick', 'brown', 'fox']
>>> s = {1, 3, 5, 6, 7, 9}
>>> hl.eval(hl.len(a))
4
>>> hl.eval(hl.len(s))
6
>>> hl.eval(hl.len("12345"))
5
Parameters:x (ArrayExpression or SetExpression or DictExpression or StringExpression) – String or collection expression.
Returns:Expression of type tint32
hail.expr.functions.map(f: Callable, collection)[source]

Transform each element of a collection.

Examples

>>> a = ['The', 'quick', 'brown', 'fox']
>>> hl.eval(hl.map(lambda x: hl.len(x), a))
[3, 5, 5, 3]
Parameters:
Returns:

ArrayExpression or SetExpression. – Collection where each element has been transformed by f.

hail.expr.functions.flatmap(f: Callable, collection)[source]

Map each element of the collection to a new collection, and flatten the results.

Examples

>>> a = [[0, 1], [1, 2], [4, 5, 6, 7]]
>>> hl.eval(hl.flatmap(lambda x: x[1:], a))
[1, 2, 5, 6, 7]
Parameters:
  • f (function ( (arg) -> CollectionExpression)) – Function from the element type of the collection to the type of the collection. For instance, flatmap on a set<str> should take a str and return a set.
  • collection (ArrayExpression or SetExpression) – Collection expression.
Returns:

ArrayExpression or SetExpression

hail.expr.functions.zip(*arrays, fill_missing: bool = False) → hail.expr.expressions.typed_expressions.ArrayExpression[source]

Zip together arrays into a single array.

Examples

>>> hl.eval(hl.zip([1], [10, 20], [100, 200, 300]))
[(1, 10, 100)]
>>> hl.eval(hl.zip([1], [10, 20], [100, 200, 300], fill_missing=True))
[(1, 10, 100), (None, 20, 200), (None, None, 300)]

Notes

The element type of the resulting array is a ttuple with a field for each array.

Parameters:
  • arrays (: variable-length args of ArrayExpression) – Array expressions.
  • fill_missing (bool) – If False, return an array with length equal to the shortest length of the arrays. If True, return an array equal to the longest length of the arrays, by extending the shorter arrays with missing values.
Returns:

ArrayExpression

hail.expr.functions.zip_with_index(a)[source]

Returns an array of (index, element) tuples.

Examples

>>> hl.eval(hl.zip_with_index(['A', 'B', 'C']))
[(0, 'A'), (1, 'B'), (2, 'C')]
Parameters:a (ArrayExpression)
Returns:ArrayExpression – Array of (index, element) tuples.
hail.expr.functions.flatten(collection)[source]

Flatten a nested collection by concatenating sub-collections.

Examples

>>> a = [[1, 2], [2, 3]]
>>> hl.eval(hl.flatten(a))
[1, 2, 2, 3]
Parameters:collection (ArrayExpression or SetExpression) – Collection with element type tarray or tset.
Returns:collection (ArrayExpression or SetExpression)
hail.expr.functions.any(f: Callable, collection) → hail.expr.expressions.typed_expressions.BooleanExpression[source]

Returns True if f returns True for any element.

Examples

>>> a = ['The', 'quick', 'brown', 'fox']
>>> s = {1, 3, 5, 6, 7, 9}
>>> hl.eval(hl.any(lambda x: x[-1] == 'x', a))
True
>>> hl.eval(hl.any(lambda x: x % 4 == 0, s))
False

Notes

This method returns False for empty collections.

Parameters:
Returns:

BooleanExpression. – True if f returns True for any element, False otherwise.

hail.expr.functions.all(f: Callable, collection) → hail.expr.expressions.typed_expressions.BooleanExpression[source]

Returns True if f returns True for every element.

Examples

>>> a = ['The', 'quick', 'brown', 'fox']
>>> s = {1, 3, 5, 6, 7, 9}
>>> hl.eval(hl.all(lambda x: hl.len(x) > 3, a))
False
>>> hl.eval(hl.all(lambda x: x < 10, s))
True

Notes

This method returns True if the collection is empty.

Parameters:
Returns:

BooleanExpression. – True if f returns True for every element, False otherwise.

hail.expr.functions.filter(f: Callable, collection)[source]

Returns a new collection containing elements where f returns True.

Examples

>>> a = [1, 2, 3, 4]
>>> s = {'Alice', 'Bob', 'Charlie'}
>>> hl.eval(hl.filter(lambda x: x % 2 == 0, a))
[2, 4]
>>> hl.eval(hl.filter(lambda x: ~(x[-1] == 'e'), s))
{'Bob'}

Notes

Returns a same-type expression; evaluated on a SetExpression, returns a SetExpression. Evaluated on an ArrayExpression, returns an ArrayExpression.

Parameters:
Returns:

ArrayExpression or SetExpression – Expression of the same type as collection.

hail.expr.functions.sorted(collection, key: Optional[Callable] = None, reverse=False) → hail.expr.expressions.typed_expressions.ArrayExpression[source]

Returns a sorted array.

Examples

>>> a = ['Charlie', 'Alice', 'Bob']
>>> hl.eval(hl.sorted(a))
['Alice', 'Bob', 'Charlie']
>>> hl.eval(hl.sorted(a, reverse=True))
['Charlie', 'Bob', 'Alice']
>>> hl.eval(hl.sorted(a, key=lambda x: hl.len(x)))
['Bob', 'Alice', 'Charlie']

Notes

The ordered types are tstr and numeric types.

Parameters:
  • collection (ArrayExpression) – Array to sort.
  • key (function ( (arg) -> Expression), optional) – Function to evaluate for each element to compute sort key.
  • reverse (BooleanExpression) – Sort in descending order.
Returns:

ArrayExpression – Sorted array.

hail.expr.functions.find(f: Callable, collection)[source]

Returns the first element where f returns True.

Examples

>>> a = ['The', 'quick', 'brown', 'fox']
>>> s = {1, 3, 5, 6, 7, 9}
>>> hl.eval(hl.find(lambda x: x[-1] == 'x', a))
'fox'
>>> hl.eval(hl.find(lambda x: x % 4 == 0, s))
None

Notes

If f returns False for every element, then the result is missing.

Sets are unordered. If collection is of type tset, then the element returned comes from no guaranteed ordering.

Parameters:
Returns:

Expression – Expression whose type is the element type of the collection.

hail.expr.functions.group_by(f: Callable, collection) → hail.expr.expressions.typed_expressions.DictExpression[source]

Group collection elements into a dict according to a lambda function.

Examples

>>> a = ['The', 'quick', 'brown', 'fox']
>>> hl.eval(hl.group_by(lambda x: hl.len(x), a))
{5: ['quick', 'brown'], 3: ['The', 'fox']}
Parameters:
  • f (function ( (arg) -> Expression)) – Function to evaluate for each element of the collection to produce a key for the resulting dictionary.
  • collection (ArrayExpression or SetExpression) – Collection expression.
Returns:

DictExpression. – Dictionary keyed by results of f.

hail.expr.functions.fold(f: Callable, zero, collection) → hail.expr.expressions.base_expression.Expression[source]

Reduces a collection with the given function f, provided the initial value zero.

Examples

>>> a = [0, 1, 2]
>>> hl.eval(hl.fold(lambda i, j: i + j, 0, a))
3
Parameters:
Returns:

Expression

hail.expr.functions.array_scan(f: Callable, zero, a) → hail.expr.expressions.typed_expressions.ArrayExpression[source]

Map each element of a to cumulative value of function f, with initial value zero.

Examples

>>> a = [0, 1, 2]
>>> hl.eval(hl.array_scan(lambda i, j: i + j, 0, a))
[0, 0, 1, 3]
Parameters:
Returns:

ArrayExpression.

hail.expr.functions.reversed(x)[source]

Reverses the elements of a collection.

Examples

>>> a = ['The', 'quick', 'brown', 'fox']
>>> hl.eval(hl.reversed(a))
['fox', 'brown', 'quick', 'The']
Parameters:x (ArrayExpression or StringExpression) – Array or string expression.
Returns:Expression