Types

Now we’ll build up the Hail interface from the ground up starting with types.

In [1]:
import hail as hl
hl.init()
Running on Apache Spark version 2.2.0
SparkUI available at http://172.31.20.142:4040
Welcome to
     __  __     <>__
    / /_/ /__  __/ /
   / __  / _ `/ / /
  /_/ /_/\_,_/_/_/   version devel-f7631a0c96cd
NOTE: This is a beta version. Interfaces may change
  during the beta period. We recommend pulling
  the latest changes weekly.

The Hail interface is statically typed. That means each expression has a type, and that type constriants the set of values that expression can produce.

What are the Hail types?

There are three kinds of types: primitive types, container types, and domain-specific types.

The primitive types are:

The container types are:

The domain-specific types are:

Hail types are usually printed as above, but when accessing them in the module, they all start with t:

In [2]:
hl.tint32
Out[2]:
dtype('int32')
In [3]:
hl.tdict(hl.tstr, hl.tarray(hl.tint32))
Out[3]:
dtype('dict<str, array<int32>>')

If you prefer the strings, you can parse them with dtype.

In [4]:
hl.dtype('dict<str, array<int32>>')
Out[4]:
dtype('dict<str, array<int32>>')

In general, you won’t need to mention types explicitly, but there are a few cases:

  • To specify column types in import_table, (although this function can also impute types automatically).
  • When converting a Python value to a Hail expression with literal (although again the type can often be determined automatically).
  • A few constructor functions, like null.

Expression types

Each Expression has a type that can be accessed with the attribute dtype.

In [5]:
e = hl.dict({'a': 5, 'b': 7})
e
Out[5]:
<DictExpression of type dict<str, int32>>
In [6]:
e.dtype
Out[6]:
dtype('dict<str, int32>')

If the rules for computing the type of an expression are violated, Hail with throw a type error. For example, the types of the branches of a conditional must be the same. The Hail conditional function is called cond.

In [7]:
x = hl.int32(10)
y = hl.int32(20)

try:
    hl.cond(x < y,
            5,
            'foo')
except Exception as e:
    print(f'ERROR: {e}')
ERROR: 'cond' requires the 'consequent' and 'alternate' arguments to have the same type
    consequent: type 'int32'
    alternate:  type 'str'