Numeric functions

Numeric functions

abs(x)

Take the absolute value of a numeric value, array or ndarray.

approx_equal(x, y[, tolerance, absolute, ...])

Tests whether two numbers are approximately equal.

bit_and(x, y)

Bitwise and x and y.

bit_or(x, y)

Bitwise or x and y.

bit_xor(x, y)

Bitwise exclusive-or x and y.

bit_lshift(x, y)

Bitwise left-shift x by y.

bit_rshift(x, y[, logical])

Bitwise right-shift x by y.

bit_not(x)

Bitwise invert x.

bit_count(x)

Count the number of 1s in the in the two's complement binary representation of x.

exp(x)

expit(x)

is_nan(x)

is_finite(x)

is_infinite(x)

log(x[, base])

Take the logarithm of the x with base base.

log10(x)

logit(x)

sign(x)

Returns the sign of a numeric value, array or ndarray.

sqrt(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)

ceil(x)

uniroot(f, min, max, *[, max_iter, epsilon, ...])

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

Numeric collection functions

min(*exprs[, filter_missing])

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

nanmin(*exprs[, filter_missing])

Returns the minimum value of a collection or of given arguments, excluding NaN.

max(*exprs[, filter_missing])

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

nanmax(*exprs[, filter_missing])

Returns the maximum value of a collection or of given arguments, excluding NaN.

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.

binary_search(array, elem)

Binary search array for the insertion point of elem.
hail.expr.functions.abs(x)[source]

Take the absolute value of a numeric value, array or ndarray.

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, ArrayNumericExpression or NDArrayNumericExpression)

Returns:

NumericExpression, ArrayNumericExpression or NDArrayNumericExpression.

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.bit_and(x, y)[source]

Bitwise and x and y.

Examples

>>> hl.eval(hl.bit_and(5, 3))
1

Notes

See the Python wiki for more information about bit operators.

Parameters:
Returns:

Int32Expression or Int64Expression

hail.expr.functions.bit_or(x, y)[source]

Bitwise or x and y.

Examples

>>> hl.eval(hl.bit_or(5, 3))
7

Notes

See the Python wiki for more information about bit operators.

Parameters:
Returns:

Int32Expression or Int64Expression

hail.expr.functions.bit_xor(x, y)[source]

Bitwise exclusive-or x and y.

Examples

>>> hl.eval(hl.bit_xor(5, 3))
6

Notes

See the Python wiki for more information about bit operators.

Parameters:
Returns:

Int32Expression or Int64Expression

hail.expr.functions.bit_lshift(x, y)[source]

Bitwise left-shift x by y.

Examples

>>> hl.eval(hl.bit_lshift(5, 3))
40

>>> hl.eval(hl.bit_lshift(1, 8))
256

Unlike Python, Hail integers are fixed-size (32 or 64 bits), and bits extended beyond will be ignored:

>>> hl.eval(hl.bit_lshift(1, 31))
-2147483648

>>> hl.eval(hl.bit_lshift(1, 32))
0

>>> hl.eval(hl.bit_lshift(hl.int64(1), 32))
4294967296

>>> hl.eval(hl.bit_lshift(hl.int64(1), 64))
0

Notes

See the Python wiki for more information about bit operators.

Parameters:
Returns:

Int32Expression or Int64Expression

hail.expr.functions.bit_rshift(x, y, logical=False)[source]

Bitwise right-shift x by y.

Examples

>>> hl.eval(hl.bit_rshift(256, 3))
32

With logical=False (default), the sign is preserved:

>>> hl.eval(hl.bit_rshift(-1, 1))
-1

With logical=True, the sign bit is treated as any other:

>>> hl.eval(hl.bit_rshift(-1, 1, logical=True))
2147483647

Notes

If logical is False, then the shift is a sign-preserving right shift. If logical is True, then the shift is logical, with the sign bit treated as any other bit.

See the Python wiki for more information about bit operators.

Parameters:
Returns:

Int32Expression or Int64Expression

hail.expr.functions.bit_not(x)[source]

Bitwise invert x.

Examples

>>> hl.eval(hl.bit_not(0))
-1

Notes

See the Python wiki for more information about bit operators.

Parameters:

x (Int32Expression or Int64Expression)

Returns:

Int32Expression or Int64Expression

hail.expr.functions.bit_count(x)[source]

Count the number of 1s in the in the two’s complement binary representation of x.

Examples

The binary representation of 7 is 111, so:

>>> hl.eval(hl.bit_count(7))
3
Parameters:

x (Int32Expression or Int64Expression)

Returns:

Int32Expression

hail.expr.functions.exp(x)[source]
hail.expr.functions.expit(x)[source]
hail.expr.functions.is_nan(x)[source]
hail.expr.functions.is_finite(x)[source]
hail.expr.functions.is_infinite(x)[source]
hail.expr.functions.log(x, base=None)[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)[source]
hail.expr.functions.logit(x)[source]
hail.expr.functions.floor(x)[source]
hail.expr.functions.ceil(x)[source]
hail.expr.functions.sqrt(x)[source]
hail.expr.functions.sign(x)[source]

Returns the sign of a numeric value, array or ndarray.

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, ArrayNumericExpression or NDArrayNumericExpression)

Returns:

NumericExpression, ArrayNumericExpression or NDArrayNumericExpression.

hail.expr.functions.min(*exprs, filter_missing=True)[source]

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

Examples

Take the minimum value of an array:

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

Take the minimum value of arguments:

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

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

If filter_missing is True, then the result is the minimum of non-missing arguments or elements. If filter_missing is False, then any missing argument or element causes the result to be missing.

If any element or argument is NaN, then the result is NaN.

See also

nanmin(), max(), nanmax()

Parameters:
Returns:

NumericExpression

hail.expr.functions.nanmin(*exprs, filter_missing=True)[source]

Returns the minimum value of a collection or of given arguments, excluding NaN.

Examples

Compute the minimum value of an array:

>>> hl.eval(hl.nanmin([1.1, 50.1, float('nan')]))
1.1

Take the minimum value of arguments:

>>> hl.eval(hl.nanmin(1.1, 50.1, float('nan')))
1.1

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

If filter_missing is True, then the result is the minimum of non-missing arguments or elements. If filter_missing is False, then any missing argument or element causes the result to be missing.

NaN arguments / array elements are ignored; the minimum value of NaN and any non-NaN value x is x.

See also

min(), max(), nanmax()

Parameters:
Returns:

NumericExpression

hail.expr.functions.max(*exprs, filter_missing=True)[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

If filter_missing is True, then the result is the maximum of non-missing arguments or elements. If filter_missing is False, then any missing argument or element causes the result to be missing.

If any element or argument is NaN, then the result is NaN.

See also

nanmax(), min(), nanmin()

Parameters:
Returns:

NumericExpression

hail.expr.functions.nanmax(*exprs, filter_missing=True)[source]

Returns the maximum value of a collection or of given arguments, excluding NaN.

Examples

Compute the maximum value of an array:

>>> hl.eval(hl.nanmax([1.1, 50.1, float('nan')]))
50.1

Take the maximum value of arguments:

>>> hl.eval(hl.nanmax(1.1, 50.1, float('nan')))
50.1

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

If filter_missing is True, then the result is the maximum of non-missing arguments or elements. If filter_missing is False, then any missing argument or element causes the result to be missing.

NaN arguments / array elements are ignored; the maximum value of NaN and any non-NaN value x is x.

See also

max(), min(), nanmin()

Parameters:
Returns:

NumericExpression

hail.expr.functions.mean(collection, filter_missing=True)[source]

Returns the mean of all values in the collection.

Examples

>>> a = [1, 3, 5, 6, 7, 9]

>>> hl.eval(hl.mean(a))
5.166666666666667

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)[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=True)[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=True)[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=True)[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=False)[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=False)[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)[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, min, max, *, max_iter=1000, epsilon=2.220446049250313e-16, tolerance=0.0001220703)[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).

uniroot() returns an estimate for a root with accuracy 4 * epsilon * abs(x) + tolerance.

4*EPSILON*abs(x) + tol

Parameters:

  • f (function ( (arg) -> Float64Expression)) – Must return a Float64Expression.

  • min (Float64Expression)

  • max (Float64Expression)

  • max_iter (int) – The maximum number of iterations before giving up.

  • epsilon (float) – The scaling factor in the accuracy of the root found.

  • tolerance (float) – The constant factor in approximate accuracy of the root found.

Returns:

Float64Expression – The root of the function f.

Binary search array for the insertion point of elem.

Parameters:
Returns:

Int32Expression

Notes

This function assumes that array is sorted in ascending order, and does not perform any sortedness check. Missing values sort last.

The returned index is the lower bound on the insertion point of elem into the ordered array, or the index of the first element in array not smaller than elem. This is a value between 0 and the length of array, inclusive (if all elements in array are smaller than elem, the returned value is the length of array or the index of the first missing value, if one exists).

If either elem or array is missing, the result is missing.

Examples

>>> a = hl.array([0, 2, 4, 8])

>>> hl.eval(hl.binary_search(a, -1))
0

>>> hl.eval(hl.binary_search(a, 1))
1

>>> hl.eval(hl.binary_search(a, 10))
4