Types

Fields and expressions in Hail have types. Throughout the documentation, you will find type descriptions like array<str> or tlocus. It is generally more important to know how to use expressions of various types than to know how to manipulate the types themselves, but some operations like null() require type arguments.

Constructing types can be done either by using the type objects and classes (prefixed by “t”) or by parsing from strings. As an example, we will construct a tstruct with each option:

>>> t = hl.tstruct(a = hl.tint32, b = hl.tstr, c = hl.tarray(hl.tfloat64))
>>> t
dtype('struct{a: int32, b: str, c: array<float64>}')

>>> t = hl.dtype('struct{a: int32, b: str, c: array<float64>}')
>>> t
dtype('struct{a: int32, b: str, c: array<float64>}')
HailType Hail type superclass.
dtype Parse a type from its string representation.
tint Alias for tint32.
tint32 Hail type for signed 32-bit integers.
tint64 Hail type for signed 64-bit integers.
tfloat Alias for tfloat64.
tfloat32 Hail type for 32-bit floating point numbers.
tfloat64 Hail type for 64-bit floating point numbers.
tstr Hail type for text strings.
tbool Hail type for Boolean (True or False) values.
tarray Hail type for variable-length arrays of elements.
tset Hail type for collections of distinct elements.
tdict Hail type for key-value maps.
ttuple Hail type for tuples.
tlocus Hail type for a genomic coordinate with a contig and a position.
tinterval Hail type for intervals of ordered values.
tcall Hail type for a diploid genotype.
tstruct Hail type for structured groups of heterogeneous fields.
class hail.expr.types.HailType[source]

Hail type superclass.

pretty(indent=0, increment=4)[source]

Returns a prettily formatted string representation of the type.

Parameters:indent (int) – Spaces to indent.
Returns:str
typecheck(value)[source]

Check that value matches a type.

Parameters:value – Value to check.
Raises:TypeError
hail.expr.types.dtype(type_str)[source]

Parse a type from its string representation.

Examples

>>> hl.dtype('int')
dtype('int32')
>>> hl.dtype('float')
dtype('float64')
>>> hl.dtype('array<int32>')
dtype('array<int32>')
>>> hl.dtype('dict<str, bool>')
dtype('dict<str, bool>')
>>> hl.dtype('struct{a: int32, `field with spaces`: int64}')
dtype('struct{a: int32, `field with spaces`: int64}')

Notes

This function is able to reverse str(t) on a HailType.

The grammar is defined as follows:

type = _ (array / set / dict / struct / tuple / interval / int64 / int32 / float32 / float64 / bool / str / call / str / locus) _
int64 = "int64" / "tint64"
int32 = "int32" / "tint32" / "int" / "tint"
float32 = "float32" / "tfloat32"
float64 = "float64" / "tfloat64" / "tfloat" / "float"
bool = "tbool" / "bool"
call = "tcall" / "call"
str = "tstr" / "str"
locus = ("tlocus" / "locus") _ "[" identifier "]"
array = ("tarray" / "array") _ "<" type ">"
set = ("tset" / "set") _ "<" type ">"
dict = ("tdict" / "dict") _ "<" type "," type ">"
struct = ("tstruct" / "struct") _ "{" (fields / _) "}"
tuple = ("ttuple" / "tuple") _ "(" ((type ("," type)*) / _) ")"
fields = field ("," field)*
field = identifier ":" type
interval = ("tinterval" / "interval") _ "<" type ">"
identifier = _ (simple_identifier / escaped_identifier) _
simple_identifier = ~"\w+"
escaped_identifier = ~"`([^`\\\\]|\\\\.)*`"
_ = ~"\s*"
Parameters:type_str (str) – String representation of type.
Returns:HailType
hail.expr.types.tint = dtype('int32')

Alias for tint32.

hail.expr.types.tint32 = dtype('int32')

Hail type for signed 32-bit integers.

Their values can range from \(-2^{31}\) to \(2^{31} - 1\) (approximately 2.15 billion).

In Python, these are represented as int.

hail.expr.types.tint64 = dtype('int64')

Hail type for signed 64-bit integers.

Their values can range from \(-2^{63}\) to \(2^{63} - 1\).

In Python, these are represented as int.

hail.expr.types.tfloat = dtype('float64')

Alias for tfloat64.

hail.expr.types.tfloat32 = dtype('float32')

Hail type for 32-bit floating point numbers.

In Python, these are represented as float.

hail.expr.types.tfloat64 = dtype('float64')

Hail type for 64-bit floating point numbers.

In Python, these are represented as float.

hail.expr.types.tstr = dtype('str')

Hail type for text strings.

In Python, these are represented as strings.

hail.expr.types.tbool = dtype('bool')

Hail type for Boolean (True or False) values.

In Python, these are represented as bool.

class hail.expr.types.tarray(element_type)[source]

Hail type for variable-length arrays of elements.

In Python, these are represented as list.

Notes

Arrays contain elements of only one type, which is parameterized by element_type.

Parameters:element_type (HailType) – Element type of array.
element_type

Array element type.

Returns:HailType – Element type.
class hail.expr.types.tset(element_type)[source]

Hail type for collections of distinct elements.

In Python, these are represented as set.

Notes

Sets contain elements of only one type, which is parameterized by element_type.

Parameters:element_type (HailType) – Element type of set.
element_type

Set element type.

Returns:HailType – Element type.
class hail.expr.types.tdict(key_type, value_type)[source]

Hail type for key-value maps.

In Python, these are represented as dict.

Notes

Dicts parameterize the type of both their keys and values with key_type and value_type.

Parameters:
key_type

Dict key type.

Returns:HailType – Key type.
value_type

Dict value type.

Returns:HailType – Value type.
class hail.expr.types.tstruct(**field_types)[source]

Hail type for structured groups of heterogeneous fields.

In Python, these are represented as Struct.

Parameters:field_types (keyword args of HailType) – Fields.
fields

Struct fields.

Returns:tuple of Field – Struct fields.
class hail.expr.types.ttuple(*types)[source]

Hail type for tuples.

In Python, these are represented as tuple.

Parameters:types (varargs of HailType) – Element types.

See also

TupleExpression

types

Tuple element types.

Returns:tuple of HailType
hail.expr.types.tcall = dtype('call')

Hail type for a diploid genotype.

In Python, these are represented by Call.

class hail.expr.types.tlocus(reference_genome='default')[source]

Hail type for a genomic coordinate with a contig and a position.

In Python, these are represented by Locus.

Parameters:reference_genome (ReferenceGenome or str) – Reference genome to use.
reference_genome

Reference genome.

Returns:ReferenceGenome – Reference genome.
class hail.expr.types.tinterval(point_type)[source]

Hail type for intervals of ordered values.

In Python, these are represented by Interval.

Parameters:point_type (HailType) – Interval point type.
point_type

Interval point type.

Returns:HailType – Interval point type.