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.

tndarray

Hail type for n-dimensional arrays.

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.

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

Returns a prettily formatted string representation of the type.

Parameters

indent (int) – Spaces to indent.

Returns

str

subst()[source]
typecheck(value)[source]

Check that value matches a type.

Parameters

value – Value to check.

Raises

TypeError

unify(t)[source]
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 / union / 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 ">"
ndarray = ("tndarray" / "ndarray") _ "<" type, identifier ">"
set = ("tset" / "set") _ "<" type ">"
dict = ("tdict" / "dict") _ "<" type "," type ">"
struct = ("tstruct" / "struct") _ "{" (fields / _) "}"
union = ("tunion" / "union") _ "{" (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.

clear()[source]
element_type

Array element type.

Returns

HailType – Element type.

subst()[source]
unify(t)[source]
class hail.expr.types.tndarray(element_type, ndim)[source]

Hail type for n-dimensional arrays.

Danger

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

In Python, these are represented as NumPy ndarray.

Notes

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

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

  • ndim (int32) – Number of dimensions.

See also

NDArrayExpression, ndarray()

clear()[source]
element_type

NDArray element type.

Returns

HailType – Element type.

ndim

NDArray number of dimensions.

Returns

int – Number of dimensions.

subst()[source]
unify(t)[source]
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.

clear()[source]
element_type

Set element type.

Returns

HailType – Element type.

subst()[source]
unify(t)[source]
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
clear()[source]
element_type
key_type

Dict key type.

Returns

HailType – Key type.

subst()[source]
unify(t)[source]
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.

clear()[source]
fields

Struct field names.

Returns

tuple of str – Tuple of struct field names.

subst()[source]
unify(t)[source]
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

clear()[source]
subst()[source]
types

Tuple element types.

Returns

tuple of HailType

unify(t)[source]
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.

clear()[source]
reference_genome

Reference genome.

Returns

ReferenceGenome – Reference genome.

subst()[source]
unify(t)[source]
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.

clear()[source]
point_type

Interval point type.

Returns

HailType – Interval point type.

subst()[source]
unify(t)[source]