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
orArrayNumericExpression
)Returns: NumericExpression
orArrayNumericExpression
.
-
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: - x (
NumericExpression
) - y (
NumericExpression
) - tolerance (
NumericExpression
) - absolute (
BooleanExpression
) – If True, computeabs(x - y) <= tolerance
. Otherwise, computeabs(x - y) <= max(tolerance * max(abs(x), abs(y)), 2 ** -1022)
. - nan_same (
BooleanExpression
) – If True, thenNaN == NaN
will evaluate to True. Otherwise, it will return False.
Returns: - x (
-
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 typetfloat64
)Returns: Expression
of typetfloat64
-
hail.expr.functions.
is_nan
(x) → hail.expr.expressions.typed_expressions.BooleanExpression[source]¶ Returns
True
if the argument isnan
(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 returnFalse
onnan
sincenan
is a defined value. Additionally, this method will return missing if x is missing.Parameters: x (float or Expression
of typetfloat64
) – Expression to test.Returns: BooleanExpression
–True
if x isnan
,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 typetfloat64
)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 typetfloat64
)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: - x (float or
Expression
of typetfloat64
) - base (float or
Expression
of typetfloat64
)
Returns: Expression
of typetfloat64
- x (float or
-
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 typetfloat64
)Returns: Expression
of typetfloat64
-
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
orFloat64Expression
)Returns: Float32Expression
orFloat64Expression
-
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
orFloat64Expression
)Returns: Float32Expression
orFloat64Expression
-
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 typetfloat64
)Returns: Expression
of typetfloat64
-
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
tonan
.Parameters: x ( NumericExpression
orArrayNumericExpression
)Returns: NumericExpression
orArrayNumericExpression
.
-
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 isFalse
, then any missing element causes the result to be missing.Parameters: - exprs (
ArrayExpression
orSetExpression
or varargs ofNumericExpression
) – Single numeric array or set, or multiple numeric values. - filter_missing (
bool
) – Remove missing elements from the collection before computing product.
Returns: - exprs (
-
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 isFalse
, then any missing element causes the result to be missing.Parameters: - exprs (
ArrayExpression
orSetExpression
or varargs ofNumericExpression
) – Single numeric array or set, or multiple numeric values. - filter_missing (
bool
) – Remove missing elements from the collection before computing product.
Returns: - exprs (
-
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 isFalse
, then any missing element causes the result to be missing.Parameters: - collection (
ArrayExpression
orSetExpression
) – Collection expression with numeric element type. - filter_missing (
bool
) – Remove missing elements from the collection before computing product.
Returns: Expression
of typetfloat64
- collection (
-
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
orSetExpression
) – 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 isFalse
, then any missing element causes the result to be missing.Parameters: - collection (
ArrayExpression
orSetExpression
) – Collection expression with numeric element type. - filter_missing (
bool
) – Remove missing elements from the collection before computing product.
Returns: - collection (
-
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 isFalse
, then any missing element causes the result to be missing.Parameters: - collection (
ArrayExpression
orSetExpression
) – Collection expression with numeric element type. - filter_missing (
bool
) – Remove missing elements from the collection before computing product.
Returns: - collection (
-
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 isFalse
, 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: - a (
-
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 isTrue
, then the result is missing.If the array is empty, then the result is missing.
Note
Missing elements are ignored.
Parameters: - array (
ArrayNumericExpression
) - unique (bool)
Returns: Expression
of typetint32
- array (
-
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 isTrue
, then the result is missing.If the array is empty, then the result is missing.
Note
Missing elements are ignored.
Parameters: - array (
ArrayNumericExpression
) - unique (bool)
Returns: Expression
of typetint32
- array (
-
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: - x (
Expression
of typearray<tfloat64>
) - y (
Expression
of typearray<tfloat64>
)
Returns: - x (
-
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: - f (function ( (arg) ->
Float64Expression
)) – Must return aFloat64Expression
. - min (
Float64Expression
) - max (
Float64Expression
)
Returns: Float64Expression
– The root of the function f.- f (function ( (arg) ->