DictExpression¶
-
class
hail.expr.
DictExpression
[source]¶ Expression of type
tdict
.>>> d = hl.literal({'Alice': 43, 'Bob': 33, 'Charles': 44})
Attributes
The data type of the expression.
Methods
Returns whether a given key is present in the dictionary.
Returns the value associated with key k or a default value if that key is not present.
Returns an array of tuples containing key/value pairs in the dictionary.
Returns the set of keys in the dictionary.
Returns an array with all keys in the dictionary.
Transform values of the dictionary according to a function.
Returns the size of the dictionary.
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
BooleanExpression
–True
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
BooleanExpression
–True
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
-
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
BooleanExpression
–True
if item is a key of the dictionary,False
otherwise.
-
describe
(handler=<built-in function print>)¶ Print information about type, index, and dependencies.
-
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
-
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
-
size
()[source]¶ Returns the size of the dictionary.
Examples
>>> hl.eval(d.size()) 3
- Returns
Expression
of typetint32
– 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
-
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.
-