DictExpression

class hail.expr.DictExpression[source]

Expression of type tdict.

>>> d = hl.literal({'Alice': 43, 'Bob': 33, 'Charles': 44})

Attributes

dtype

The data type of the expression.

Methods

contains

Returns whether a given key is present in the dictionary.

get

Returns the value associated with key k or a default value if that key is not present.

items

Returns an array of tuples containing key/value pairs in the dictionary.

key_set

Returns the set of keys in the dictionary.

keys

Returns an array with all keys in the dictionary.

map_values

Transform values of the dictionary according to a function.

size

Returns the size of the dictionary.

values

Returns an array with all values in the dictionary.

__eq__(other)

Returns True if the two expressions are equal.

Examples

>>> x = hl.literal(5)
>>> y = hl.literal(5)
>>> z = hl.literal(1)
>>> hl.eval(x == y)
True
>>> hl.eval(x == z)
False

Notes

This method will fail with an error if the two expressions are not of comparable types.

Parameters

other (Expression) – Expression for equality comparison.

Returns

BooleanExpressionTrue if the two expressions are equal.

__ge__(other)

Return self>=value.

__getitem__(item)[source]

Get the value associated with key item.

Examples

>>> hl.eval(d['Alice'])
43

Notes

Raises an error if item is not a key of the dictionary. Use DictExpression.get() to return missing instead of an error.

Parameters

item (Expression) – Key expression.

Returns

Expression – Value associated with key item.

__gt__(other)

Return self>value.

__le__(other)

Return self<=value.

__lt__(other)

Return self<value.

__ne__(other)

Returns True if the two expressions are not equal.

Examples

>>> x = hl.literal(5)
>>> y = hl.literal(5)
>>> z = hl.literal(1)
>>> hl.eval(x != y)
False
>>> hl.eval(x != z)
True

Notes

This method will fail with an error if the two expressions are not of comparable types.

Parameters

other (Expression) – Expression for inequality comparison.

Returns

BooleanExpressionTrue if the two expressions are not equal.

collect(_localize=True)

Collect all records of an expression into a local list.

Examples

Collect all the values from C1:

>>> table1.C1.collect()
[2, 2, 10, 11]

Warning

Extremely experimental.

Warning

The list of records may be very large.

Returns

list

contains(item)[source]

Returns whether a given key is present in the dictionary.

Examples

>>> hl.eval(d.contains('Alice'))
True
>>> hl.eval(d.contains('Anne'))
False
Parameters

item (Expression) – Key to test for inclusion.

Returns

BooleanExpressionTrue if item is a key of the dictionary, False otherwise.

describe(handler=<built-in function print>)

Print information about type, index, and dependencies.

property dtype

The data type of the expression.

Returns

HailType

export(path, delimiter='\t', missing='NA', header=True)

Export a field to a text file.

Examples

>>> small_mt.GT.export('output/gt.tsv')
>>> with open('output/gt.tsv', 'r') as f:
...     for line in f:
...         print(line, end='')
locus   alleles 0       1       2       3
1:1     ["A","C"]       1/1     1/1     0/1     0/1
1:2     ["A","C"]       1/1     1/1     0/0     1/1
1:3     ["A","C"]       0/0     0/0     0/1     0/0
1:4     ["A","C"]       1/1     0/1     1/1     0/1
>>> small_mt.GT.export('output/gt-no-header.tsv', header=False)
>>> with open('output/gt-no-header.tsv', 'r') as f:
...     for line in f:
...         print(line, end='')
1:1     ["A","C"]       1/1     1/1     0/1     0/1
1:2     ["A","C"]       1/1     1/1     0/0     1/1
1:3     ["A","C"]       0/0     0/0     0/1     0/0
1:4     ["A","C"]       1/1     0/1     1/1     0/1
>>> small_mt.pop.export('output/pops.tsv')
>>> with open('output/pops.tsv', 'r') as f:
...     for line in f:
...         print(line, end='')
sample_idx      pop
0       0
1       0
2       2
3       0
>>> small_mt.ancestral_af.export('output/ancestral_af.tsv')
>>> with open('output/ancestral_af.tsv', 'r') as f:
...     for line in f:
...         print(line, end='')
locus   alleles ancestral_af
1:1     ["A","C"]       5.6562e-01
1:2     ["A","C"]       3.6521e-01
1:3     ["A","C"]       2.6421e-01
1:4     ["A","C"]       6.5715e-01
>>> small_mt.bn.export('output/bn.tsv')
>>> with open('output/bn.tsv', 'r') as f:
...     for line in f:
...         print(line, end='')
bn
{"n_populations":3,"n_samples":4,"n_variants":4,"n_partitions":8,"pop_dist":[1,1,1],"fst":[0.1,0.1,0.1],"mixture":false}

Notes

For entry-indexed expressions, if there is one column key field, the result of calling str() on that field is used as the column header. Otherwise, each compound column key is converted to JSON and used as a column header. For example:

>>> small_mt = small_mt.key_cols_by(s=small_mt.sample_idx, family='fam1')
>>> small_mt.GT.export('output/gt-no-header.tsv')
>>> with open('output/gt-no-header.tsv', 'r') as f:
...     for line in f:
...         print(line, end='')
locus   alleles {"s":0,"family":"fam1"} {"s":1,"family":"fam1"} {"s":2,"family":"fam1"} {"s":3,"family":"fam1"}
1:1     ["A","C"]       1/1     1/1     0/1     0/1
1:2     ["A","C"]       1/1     1/1     0/0     1/1
1:3     ["A","C"]       0/0     0/0     0/1     0/0
1:4     ["A","C"]       1/1     0/1     1/1     0/1
Parameters
  • path (str) – The path to which to export.

  • delimiter (str) – The string for delimiting columns.

  • missing (str) – The string to output for missing values.

  • header (bool) – When True include a header line.

get(item, default=None)[source]

Returns the value associated with key k or a default value if that key is not present.

Examples

>>> hl.eval(d.get('Alice'))
43
>>> hl.eval(d.get('Anne'))
None
>>> hl.eval(d.get('Anne', 0))
0
Parameters
  • item (Expression) – Key.

  • default (Expression) – Default value. Must be same type as dictionary values.

Returns

Expression – The value associated with item, or default.

items()[source]

Returns an array of tuples containing key/value pairs in the dictionary.

Examples

>>> hl.eval(d.items())  
[('Alice', 430), ('Bob', 330), ('Charles', 440)]
Returns

ArrayExpression – All key/value pairs in the dictionary.

key_set()[source]

Returns the set of keys in the dictionary.

Examples

>>> hl.eval(d.key_set())  
{'Alice', 'Bob', 'Charles'}
Returns

SetExpression – Set of all keys.

keys()[source]

Returns an array with all keys in the dictionary.

Examples

>>> hl.eval(d.keys())  
['Bob', 'Charles', 'Alice']
Returns

ArrayExpression – Array of all keys.

map_values(f)[source]

Transform values of the dictionary according to a function.

Examples

>>> hl.eval(d.map_values(lambda x: x * 10))  
{'Alice': 430, 'Bob': 330, 'Charles': 440}
Parameters

f (function ( (arg) -> Expression)) – Function to apply to each value.

Returns

DictExpression – Dictionary with transformed values.

show(n=None, width=None, truncate=None, types=True, handler=None, n_rows=None, n_cols=None)

Print the first few records of the expression to the console.

If the expression refers to a value on a keyed axis of a table or matrix table, then the accompanying keys will be shown along with the records.

Examples

>>> table1.SEX.show()
+-------+-----+
|    ID | SEX |
+-------+-----+
| int32 | str |
+-------+-----+
|     1 | "M" |
|     2 | "M" |
|     3 | "F" |
|     4 | "F" |
+-------+-----+
>>> hl.literal(123).show()
+--------+
| <expr> |
+--------+
|  int32 |
+--------+
|    123 |
+--------+

Notes

The output can be passed piped to another output source using the handler argument:

>>> ht.foo.show(handler=lambda x: logging.info(x))  
Parameters
  • n (int) – Maximum number of rows to show.

  • width (int) – Horizontal width at which to break columns.

  • truncate (int, optional) – Truncate each field to the given number of characters. If None, truncate fields to the given width.

  • types (bool) – Print an extra header line with the type of each field.

size()[source]

Returns the size of the dictionary.

Examples

>>> hl.eval(d.size())
3
Returns

Expression of type tint32 – Size of the dictionary.

summarize(handler=None)

Compute and print summary information about the expression.

Danger

This functionality is experimental. It may not be tested as well as other parts of Hail and the interface is subject to change.

take(n, _localize=True)

Collect the first n records of an expression.

Examples

Take the first three rows:

>>> table1.X.take(3)
[5, 6, 7]

Warning

Extremely experimental.

Parameters

n (int) – Number of records to take.

Returns

list

values()[source]

Returns an array with all values in the dictionary.

Examples

>>> hl.eval(d.values())  
[33, 44, 43]
Returns

ArrayExpression – All values in the dictionary.