Collection functions¶
Collection constructors
dict (collection) |
Creates a dictionary. |
array (collection) |
Construct an array expression. |
empty_array (t, str]) |
Returns an empty array of elements of a type t. |
set (collection) |
Convert a set expression. |
empty_set (t, 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, NoneType] = None[, …]) |
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. |
-
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
orSetExpression
orDictExpression
orStringExpression
) – String or collection expression.Returns: Expression
of typetint32
-
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: - f (function ( (arg) ->
Expression
)) – Function to transform each element of the collection. - collection (
ArrayExpression
orSetExpression
) – Collection expression.
Returns: ArrayExpression
orSetExpression
. – Collection where each element has been transformed by f.- f (function ( (arg) ->
-
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 aset<str>
should take astr
and return aset
. - collection (
ArrayExpression
orSetExpression
) – Collection expression.
Returns: - f (function ( (arg) ->
-
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
) – IfFalse
, return an array with length equal to the shortest length of the arrays. IfTrue
, return an array equal to the longest length of the arrays, by extending the shorter arrays with missing values.
Returns: - arrays (: variable-length args of
-
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
orSetExpression
) – Collection with element typetarray
ortset
.Returns: collection ( ArrayExpression
orSetExpression
)
-
hail.expr.functions.
any
(f: Callable, collection) → hail.expr.expressions.typed_expressions.BooleanExpression[source]¶ Returns
True
if f returnsTrue
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: - f (function ( (arg) ->
BooleanExpression
)) – Function to evaluate for each element of the collection. Must return aBooleanExpression
. - collection (
ArrayExpression
orSetExpression
) – Collection expression.
Returns: BooleanExpression
. –True
if f returnsTrue
for any element,False
otherwise.- f (function ( (arg) ->
-
hail.expr.functions.
all
(f: Callable, collection) → hail.expr.expressions.typed_expressions.BooleanExpression[source]¶ Returns
True
if f returnsTrue
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: - f (function ( (arg) ->
BooleanExpression
)) – Function to evaluate for each element of the collection. Must return aBooleanExpression
. - collection (
ArrayExpression
orSetExpression
) – Collection expression.
Returns: BooleanExpression
. –True
if f returnsTrue
for every element,False
otherwise.- f (function ( (arg) ->
-
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 aSetExpression
. Evaluated on anArrayExpression
, returns anArrayExpression
.Parameters: - f (function ( (arg) ->
BooleanExpression
)) – Function to evaluate for each element of the collection. Must return aBooleanExpression
. - collection (
ArrayExpression
orSetExpression
.) – Array or set expression to filter.
Returns: ArrayExpression
orSetExpression
– Expression of the same type as collection.- f (function ( (arg) ->
-
hail.expr.functions.
sorted
(collection, key: Union[typing.Callable, NoneType] = 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=False)) ['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.- collection (
-
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: - f (function ( (arg) ->
BooleanExpression
)) – Function to evaluate for each element of the collection. Must return aBooleanExpression
. - collection (
ArrayExpression
orSetExpression
) – Collection expression.
Returns: Expression
– Expression whose type is the element type of the collection.- f (function ( (arg) ->
-
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
orSetExpression
) – Collection expression.
Returns: DictExpression
. – Dictionary keyed by results of f.- f (function ( (arg) ->
-
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: - f (function ( (
Expression
,Expression
) ->Expression
)) – Function which takes the cumulative value and the next element, and returns a new value. - zero (
Expression
) – Initial value to pass in as left argument of f. - collection (
ArrayExpression
orSetExpression
)
Returns: - f (function ( (
-
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: - f (function ( (
Expression
,Expression
) ->Expression
)) – Function which takes the cumulative value and the next element, and returns a new value. - zero (
Expression
) – Initial value to pass in as left argument of f. - a (
ArrayExpression
)
Returns: - f (function ( (