Numeric functions

Numeric functions

abs(x) Take the absolute value of a numeric value or array.
approx_equal(x, y[, tolerance, absolute, …]) Tests whether two numbers are approximately equal.
exp(x) Computes e raised to the power x.
is_nan(x) Returns True if the argument is nan (not a number).
is_finite(x) Returns True if the argument is a finite floating-point number.
is_infinite(x) Returns True if the argument is positive or negative infinity.
log(x[, base]) Take the logarithm of the x with base base.
log10(x) Take the logarithm of the x with base 10.
sign(x) Returns the sign of a numeric value or array.
sqrt(x) Returns the square root of x.
int(x) Convert to a 32-bit integer expression.
int32(x) Convert to a 32-bit integer expression.
int64(x) Convert to a 64-bit integer expression.
float(x) Convert to a 64-bit floating point expression.
float32(x) Convert to a 32-bit floating point expression.
float64(x) Convert to a 64-bit floating point expression.
floor(x) The largest integral value that is less than or equal to x.
ceil(x) The smallest integral value that is greater than or equal to x.
uniroot(f, min, max) Finds a root of the function f within the interval [min, max].

Numeric collection functions

min(*exprs, filter_missing) Returns the minimum of a collection or of given numeric expressions.
max(*exprs, filter_missing) Returns the maximum element of a collection or of given numeric expressions.
mean(collection, filter_missing) Returns the mean of all values in the collection.
median(collection) Returns the median value in the collection.
product(collection, filter_missing) Returns the product of values in the collection.
sum(collection, filter_missing) Returns the sum of values in the collection.
cumulative_sum(a, filter_missing) Returns an array of the cumulative sum of values in the array.
argmin(array, unique) Return the index of the minimum value in the array.
argmax(array, unique) Return the index of the maximum value in the array.
corr(x, y) Compute the Pearson correlation coefficient between x and y.
hail.expr.functions.abs(x)[source]

Take the absolute value of a numeric value or array.

Examples

>>> hl.eval(hl.abs(-5))
5
>>> hl.eval(hl.abs([1.0, -2.5, -5.1]))
[1.0, 2.5, 5.1]
Parameters:x (NumericExpression or ArrayNumericExpression)
Returns:NumericExpression or ArrayNumericExpression.
hail.expr.functions.approx_equal(x, y, tolerance=1e-06, absolute=False, nan_same=False)[source]

Tests whether two numbers are approximately equal.

Examples

>>> hl.eval(hl.approx_equal(0.25, 0.2500001))
True
>>> hl.eval(hl.approx_equal(0.25, 0.251, tolerance=1e-3, absolute=True))
False
Parameters:
Returns:

BooleanExpression

hail.expr.functions.exp(x) → hail.expr.expressions.typed_expressions.Float64Expression[source]

Computes e raised to the power x.

Examples

>>> hl.eval(hl.exp(2))
7.38905609893065
Parameters:x (float or Expression of type tfloat64)
Returns:Expression of type tfloat64
hail.expr.functions.is_nan(x) → hail.expr.expressions.typed_expressions.BooleanExpression[source]

Returns True if the argument is nan (not a number).

Examples

>>> hl.eval(hl.is_nan(0))
False
>>> hl.eval(hl.is_nan(hl.literal(0) / 0))
True
>>> hl.eval(hl.is_nan(hl.literal(0) / hl.null(hl.tfloat64)))
None

Notes

Note that is_missing() will return False on nan since nan is a defined value. Additionally, this method will return missing if x is missing.

Parameters:x (float or Expression of type tfloat64) – Expression to test.
Returns:BooleanExpressionTrue if x is nan, False otherwise.
hail.expr.functions.is_finite(x) → hail.expr.expressions.typed_expressions.BooleanExpression[source]

Returns True if the argument is a finite floating-point number.

Examples

>>> hl.eval(hl.is_finite(0))
True
>>> hl.eval(hl.is_finite(float('nan')))
False
>>> hl.eval(hl.is_finite(float('inf')))
False
>>> hl.eval(hl.is_finite(hl.null('float32')))
None

Notes

This method will return missing, not True, if x is missing.

Parameters:x (float or Expression of type tfloat64)
Returns:BooleanExpression
hail.expr.functions.is_infinite(x) → hail.expr.expressions.typed_expressions.BooleanExpression[source]

Returns True if the argument is positive or negative infinity.

Examples

>>> hl.eval(hl.is_infinite(0))
False
>>> hl.eval(hl.is_infinite(float('nan')))
False
>>> hl.eval(hl.is_infinite(float('inf')))
True
>>> hl.eval(hl.is_infinite(hl.null('float32')))
None

Notes

This method will return missing, not False, if x is missing.

Parameters:x (float or Expression of type tfloat64)
Returns:BooleanExpression
hail.expr.functions.log(x, base=None) → hail.expr.expressions.typed_expressions.Float64Expression[source]

Take the logarithm of the x with base base.

Examples

>>> hl.eval(hl.log(10))
2.302585092994046
>>> hl.eval(hl.log(10, 10))
1.0
>>> hl.eval(hl.log(1024, 2))
10.0

Notes

If the base argument is not supplied, then the natural logarithm is used.

Parameters:
Returns:

Expression of type tfloat64

hail.expr.functions.log10(x) → hail.expr.expressions.typed_expressions.Float64Expression[source]

Take the logarithm of the x with base 10.

Examples

>>> hl.eval(hl.log10(1000))
3.0
>>> hl.eval(hl.log10(0.0001123))
-3.949620243738542
Parameters:x (float or Expression of type tfloat64)
Returns:Expression of type tfloat64
hail.expr.functions.floor(x)[source]

The largest integral value that is less than or equal to x.

Examples

>>> hl.eval(hl.floor(3.1))
3.0
Parameters:x (Float32Expression or Float64Expression)
Returns:Float32Expression or Float64Expression
hail.expr.functions.ceil(x)[source]

The smallest integral value that is greater than or equal to x.

Examples

>>> hl.eval(hl.ceil(3.1))
4.0
Parameters:x (Float32Expression or Float64Expression)
Returns:Float32Expression or Float64Expression
hail.expr.functions.sqrt(x) → hail.expr.expressions.typed_expressions.Float64Expression[source]

Returns the square root of x.

Examples

>>> hl.eval(hl.sqrt(3))
1.7320508075688772

Notes

It is also possible to exponentiate expression with standard Python syntax, e.g. x ** 0.5.

Parameters:x (float or Expression of type tfloat64)
Returns:Expression of type tfloat64
hail.expr.functions.sign(x)[source]

Returns the sign of a numeric value or array.

Examples

>>> hl.eval(hl.sign(-1.23))
-1.0
>>> hl.eval(hl.sign([-4, 0, 5]))
[-1, 0, 1]
>>> hl.eval(hl.sign([0.0, 3.14]))
[0.0, 1.0]
>>> hl.eval(hl.sign(float('nan')))  
nan

Notes

The sign function preserves type and maps nan to nan.

Parameters:x (NumericExpression or ArrayNumericExpression)
Returns:NumericExpression or ArrayNumericExpression.
hail.expr.functions.min(*exprs, filter_missing: bool = True) → hail.expr.expressions.typed_expressions.NumericExpression[source]

Returns the minimum of a collection or of given numeric expressions.

Examples

Take the minimum value of an array:

>>> hl.eval(hl.min([2, 3, 5, 6, 7, 9]))
2

Take the minimum value:

>>> hl.eval(hl.min(12, 50, 2))
2

Notes

Like the Python builtin min function, this function can either take a single iterable expression (an array or set of numeric elements), or variable-length arguments of numeric expressions.

Note

Missing arguments / array elements are ignored if filter_missing is True. If filter_missing is False, then any missing element causes the result to be missing.

Parameters:
Returns:

NumericExpression

hail.expr.functions.max(*exprs, filter_missing: bool = True) → hail.expr.expressions.typed_expressions.NumericExpression[source]

Returns the maximum element of a collection or of given numeric expressions.

Examples

Take the maximum value of an array:

>>> hl.eval(hl.max([1, 3, 5, 6, 7, 9]))
9

Take the maximum value of values:

>>> hl.eval(hl.max(1, 50, 2))
50

Notes

Like the Python builtin max function, this function can either take a single iterable expression (an array or set of numeric elements), or variable-length arguments of numeric expressions.

Note

Missing arguments / array elements are ignored if filter_missing is True. If filter_missing is False, then any missing element causes the result to be missing.

Parameters:
Returns:

NumericExpression

hail.expr.functions.mean(collection, filter_missing: bool = True) → hail.expr.expressions.typed_expressions.Float64Expression[source]

Returns the mean of all values in the collection.

Examples

>>> a = [1, 3, 5, 6, 7, 9]
>>> hl.eval(hl.mean(a))
5.2

Note

Missing elements are ignored if filter_missing is True. If filter_missing is False, then any missing element causes the result to be missing.

Parameters:
  • collection (ArrayExpression or SetExpression) – Collection expression with numeric element type.
  • filter_missing (bool) – Remove missing elements from the collection before computing product.
Returns:

Expression of type tfloat64

hail.expr.functions.median(collection) → hail.expr.expressions.typed_expressions.NumericExpression[source]

Returns the median value in the collection.

Examples

>>> a = [1, 3, 5, 6, 7, 9]
>>> hl.eval(hl.median(a))
5

Note

Missing elements are ignored.

Parameters:collection (ArrayExpression or SetExpression) – Collection expression with numeric element type.
Returns:NumericExpression
hail.expr.functions.product(collection, filter_missing: bool = True) → hail.expr.expressions.typed_expressions.NumericExpression[source]

Returns the product of values in the collection.

Examples

>>> a = [1, 3, 5, 6, 7, 9]
>>> hl.eval(hl.product(a))
5670

Note

Missing elements are ignored if filter_missing is True. If filter_missing is False, then any missing element causes the result to be missing.

Parameters:
  • collection (ArrayExpression or SetExpression) – Collection expression with numeric element type.
  • filter_missing (bool) – Remove missing elements from the collection before computing product.
Returns:

NumericExpression

hail.expr.functions.sum(collection, filter_missing: bool = True) → hail.expr.expressions.typed_expressions.NumericExpression[source]

Returns the sum of values in the collection.

Examples

>>> a = [1, 3, 5, 6, 7, 9]
>>> hl.eval(hl.sum(a))
31

Note

Missing elements are ignored if filter_missing is True. If filter_missing is False, then any missing element causes the result to be missing.

Parameters:
  • collection (ArrayExpression or SetExpression) – Collection expression with numeric element type.
  • filter_missing (bool) – Remove missing elements from the collection before computing product.
Returns:

NumericExpression

hail.expr.functions.cumulative_sum(a, filter_missing: bool = True) → hail.expr.expressions.typed_expressions.ArrayNumericExpression[source]

Returns an array of the cumulative sum of values in the array.

Examples

>>> a = [1, 3, 5, 6, 7, 9]
>>> hl.eval(hl.cumulative_sum(a))
[1, 4, 9, 15, 22, 31]

Note

Missing elements are ignored if filter_missing is True. If filter_missing is False, then any missing element causes the result to be missing.

Parameters:
  • a (ArrayNumericExpression) – Array expression with numeric element type.
  • filter_missing (bool) – Remove missing elements from the collection before computing product.
Returns:

ArrayNumericExpression

hail.expr.functions.argmin(array, unique: bool = False) → hail.expr.expressions.typed_expressions.Int32Expression[source]

Return the index of the minimum value in the array.

Examples

>>> hl.eval(hl.argmin([0.2, 0.3, 0.6]))
0
>>> hl.eval(hl.argmin([0.4, 0.2, 0.2]))
1
>>> hl.eval(hl.argmin([0.4, 0.2, 0.2], unique=True))
None

Notes

Returns the index of the minimum value in the array.

If two or more elements are tied for minimum, then the unique parameter will determine the result. If unique is False, then the first index will be returned. If unique is True, then the result is missing.

If the array is empty, then the result is missing.

Note

Missing elements are ignored.

Parameters:
Returns:

Expression of type tint32

hail.expr.functions.argmax(array, unique: bool = False) → hail.expr.expressions.typed_expressions.Int32Expression[source]

Return the index of the maximum value in the array.

Examples

>>> hl.eval(hl.argmax([0.2, 0.2, 0.6]))
2
>>> hl.eval(hl.argmax([0.4, 0.4, 0.2]))
0
>>> hl.eval(hl.argmax([0.4, 0.4, 0.2], unique=True))
None

Notes

Returns the index of the maximum value in the array.

If two or more elements are tied for maximum, then the unique parameter will determine the result. If unique is False, then the first index will be returned. If unique is True, then the result is missing.

If the array is empty, then the result is missing.

Note

Missing elements are ignored.

Parameters:
Returns:

Expression of type tint32

hail.expr.functions.corr(x, y) → hail.expr.expressions.typed_expressions.Float64Expression[source]

Compute the Pearson correlation coefficient between x and y.

Examples

>>> hl.eval(hl.corr([1, 2, 4], [2, 3, 1]))
-0.6546536707079772

Notes

Only indices where both x and y are non-missing will be included in the calculation.

If x and y have length zero, then the result is missing.

Parameters:
Returns:

Float64Expression

hail.expr.functions.uniroot(f: Callable, min, max)[source]

Finds a root of the function f within the interval [min, max].

Examples

>>> hl.eval(hl.uniroot(lambda x: x - 1, -5, 5))
1.0

Notes

f(min) and f(max) must not have the same sign.

If no root can be found, the result of this call will be NA (missing).

Parameters:
Returns:

Float64Expression – The root of the function f.