Statistical functions

chi_squared_test(c1, c2, c3, c4) Performs chi-squared test of independence on a 2x2 contingency table.
fisher_exact_test(c1, c2, c3, c4) Calculates the p-value, odds ratio, and 95% confidence interval using Fisher’s exact test for a 2x2 table.
contingency_table_test(c1, c2, c3, c4, …) Performs chi-squared or Fisher’s exact test of independence on a 2x2 contingency table.
dbeta(x, a, b) Returns the probability density at x of a beta distribution with parameters a (alpha) and b (beta).
dpois(x, lamb[, log_p]) Compute the (log) probability density at x of a Poisson distribution with rate parameter lamb.
hardy_weinberg_test(n_hom_ref, n_het, n_hom_var) Performs test of Hardy-Weinberg equilibrium.
binom_test(x, n, p, alternative) Performs a binomial test on p given x successes in n trials.
pchisqtail(x, df) Returns the probability under the right-tail starting at x for a chi-squared distribution with df degrees of freedom.
pnorm(x) The cumulative probability function of a standard normal distribution.
ppois(x, lamb[, lower_tail, log_p]) The cumulative probability function of a Poisson distribution.
qchisqtail(p, df) Inverts pchisqtail().
qnorm(p) Inverts pnorm().
qpois(p, lamb[, lower_tail, log_p]) Inverts ppois().
hail.expr.functions.chi_squared_test(c1, c2, c3, c4) → hail.expr.expressions.typed_expressions.StructExpression[source]

Performs chi-squared test of independence on a 2x2 contingency table.

Examples

>>> hl.eval(hl.chi_squared_test(10, 10, 10, 10))
Struct(p_value=1.0, odds_ratio=1.0)

>>> hl.eval(hl.chi_squared_test(51, 43, 22, 92))
Struct(p_value=1.4626257805267089e-07, odds_ratio=4.959830866807611)

Notes

The odds ratio is given by (c1 / c2) / (c3 / c4).

Returned fields may be nan or inf.

Parameters:
Returns:

StructExpression – A tstruct expression with two fields, p_value (tfloat64) and odds_ratio (tfloat64).
hail.expr.functions.fisher_exact_test(c1, c2, c3, c4) → hail.expr.expressions.typed_expressions.StructExpression[source]

Calculates the p-value, odds ratio, and 95% confidence interval using Fisher’s exact test for a 2x2 table.

Examples

>>> hl.eval(hl.fisher_exact_test(10, 10, 10, 10))
Struct(p_value=1.0000000000000002, odds_ratio=1.0,
       ci_95_lower=0.24385796914260355, ci_95_upper=4.100747675033819)

>>> hl.eval(hl.fisher_exact_test(51, 43, 22, 92))
Struct(p_value=2.1564999740157304e-07, odds_ratio=4.918058171469967,
       ci_95_lower=2.5659373368248444, ci_95_upper=9.677929632035475)

Notes

This method is identical to the version implemented in R with default parameters (two-sided, alpha = 0.05, null hypothesis that the odds ratio equals 1).

Returned fields may be nan or inf.

Parameters:
Returns:

StructExpression – A tstruct expression with four fields, p_value (tfloat64), odds_ratio (tfloat64), ci_95_lower (:py:data:.tfloat64`), and ci_95_upper (tfloat64).
hail.expr.functions.contingency_table_test(c1, c2, c3, c4, min_cell_count) → hail.expr.expressions.typed_expressions.StructExpression[source]

Performs chi-squared or Fisher’s exact test of independence on a 2x2 contingency table.

Examples

>>> hl.eval(hl.contingency_table_test(51, 43, 22, 92, min_cell_count=22))
Struct(p_value=1.4626257805267089e-07, odds_ratio=4.959830866807611)

>>> hl.eval(hl.contingency_table_test(51, 43, 22, 92, min_cell_count=23))
Struct(p_value=2.1564999740157304e-07, odds_ratio=4.918058171469967)

Notes

If all cell counts are at least min_cell_count, the chi-squared test is used. Otherwise, Fisher’s exact test is used.

Returned fields may be nan or inf.

Parameters:
Returns:

StructExpression – A tstruct expression with two fields, p_value (tfloat64) and odds_ratio (tfloat64).
hail.expr.functions.dbeta(x, a, b) → hail.expr.expressions.typed_expressions.Float64Expression[source]

Returns the probability density at x of a beta distribution with parameters a (alpha) and b (beta).

Examples

>>> hl.eval(hl.dbeta(.2, 5, 20))
4.900377563180943
Parameters:
  • x (float or Expression of type tfloat64) – Point in [0,1] at which to sample. If a < 1 then x must be positive. If b < 1 then x must be less than 1.
  • a (float or Expression of type tfloat64) – The alpha parameter in the beta distribution. The result is undefined for non-positive a.
  • b (float or Expression of type tfloat64) – The beta parameter in the beta distribution. The result is undefined for non-positive b.
Returns:

Float64Expression
hail.expr.functions.dpois(x, lamb, log_p=False) → hail.expr.expressions.typed_expressions.Float64Expression[source]

Compute the (log) probability density at x of a Poisson distribution with rate parameter lamb.

Examples

>>> hl.eval(hl.dpois(5, 3))
0.10081881344492458
Parameters:
Returns:

Expression of type tfloat64 – The (log) probability density.
hail.expr.functions.hardy_weinberg_test(n_hom_ref, n_het, n_hom_var) → hail.expr.expressions.typed_expressions.StructExpression[source]

Performs test of Hardy-Weinberg equilibrium.

Examples

>>> hl.eval(hl.hardy_weinberg_test(250, 500, 250))
Struct(het_freq_hwe=0.5002501250625313, p_value=0.9747844394217698)

>>> hl.eval(hl.hardy_weinberg_test(37, 200, 85))
Struct(het_freq_hwe=0.48964964307448583, p_value=1.1337210383168987e-06)

Notes

This method performs a two-sided exact test with mid-p-value correction of Hardy-Weinberg equilibrium via an efficient implementation of the Levene-Haldane distribution, which models the number of heterozygous individuals under equilibrium.

The mean of this distribution is (n_hom_ref * n_hom_var) / (2n - 1) where n = n_hom_ref + n_het + n_hom_var. So the expected frequency of heterozygotes under equilibrium, het_freq_hwe, is this mean divided by n.

Parameters:
  • n_hom_ref (int or Expression of type tint32) – Number of homozygous reference genotypes.
  • n_het (int or Expression of type tint32) – Number of heterozygous genotypes.
  • n_hom_var (int or Expression of type tint32) – Number of homozygous variant genotypes.
Returns:

StructExpression – A struct expression with two fields, het_freq_hwe (tfloat64) and p_value (tfloat64).
hail.expr.functions.binom_test(x, n, p, alternative: str) → hail.expr.expressions.typed_expressions.Float64Expression[source]

Performs a binomial test on p given x successes in n trials.

Examples

>>> hl.eval(hl.binom_test(5, 10, 0.5, 'less'))
0.6230468749999999

With alternative less, the p-value is the probability of at most x successes, i.e. the cumulative probability at x of the distribution Binom(n, p). With greater, the p-value is the probably of at least x successes. With two.sided, the p-value is the total probability of all outcomes with probability at most that of x.

Returns the p-value from the exact binomial test of the null hypothesis that success has probability p, given x successes in n trials.

Parameters:
  • x (int or Expression of type tint32) – Number of successes.
  • n (int or Expression of type tint32) – Number of trials.
  • p (float or Expression of type tfloat64) – Probability of success, between 0 and 1.
  • alternative – : One of, “two.sided”, “greater”, “less”.
Returns:

Expression of type tfloat64 – p-value.
hail.expr.functions.pchisqtail(x, df) → hail.expr.expressions.typed_expressions.Float64Expression[source]

Returns the probability under the right-tail starting at x for a chi-squared distribution with df degrees of freedom.

Examples

>>> hl.eval(hl.pchisqtail(5, 1))
0.025347318677468304
Parameters:
Returns:

Expression of type tfloat64
hail.expr.functions.pnorm(x) → hail.expr.expressions.typed_expressions.Float64Expression[source]

The cumulative probability function of a standard normal distribution.

Examples

>>> hl.eval(hl.pnorm(0))
0.5

>>> hl.eval(hl.pnorm(1))
0.8413447460685429

>>> hl.eval(hl.pnorm(2))
0.9772498680518208

Notes

Returns the left-tail probability p = Prob(:math:Z < x) with :math:Z a standard normal random variable.

Parameters:x (float or Expression of type tfloat64)
Returns:Expression of type tfloat64
hail.expr.functions.ppois(x, lamb, lower_tail=True, log_p=False) → hail.expr.expressions.typed_expressions.Float64Expression[source]

The cumulative probability function of a Poisson distribution.

Examples

>>> hl.eval(hl.ppois(2, 1))
0.9196986029286058

Notes

If lower_tail is true, returns Prob(\(X \leq\) x) where \(X\) is a Poisson random variable with rate parameter lamb. If lower_tail is false, returns Prob(\(X\) > x).

Parameters:
Returns:

Expression of type tfloat64
hail.expr.functions.qchisqtail(p, df) → hail.expr.expressions.typed_expressions.Float64Expression[source]

Inverts pchisqtail().

Examples

>>> hl.eval(hl.qchisqtail(0.01, 1))
6.634896601021213

Notes

Returns right-quantile x for which p = Prob(\(Z^2\) > x) with \(Z^2\) a chi-squared random variable with degrees of freedom specified by df. p must satisfy 0 < p <= 1.

Parameters:
Returns:

Expression of type tfloat64
hail.expr.functions.qnorm(p) → hail.expr.expressions.typed_expressions.Float64Expression[source]

Inverts pnorm().

Examples

>>> hl.eval(hl.qnorm(0.90))
1.2815515655446008

Notes

Returns left-quantile x for which p = Prob(\(Z\) < x) with \(Z\) a standard normal random variable. p must satisfy 0 < p < 1.

Parameters:p (float or Expression of type tfloat64) – Probability.
Returns:Expression of type tfloat64
hail.expr.functions.qpois(p, lamb, lower_tail=True, log_p=False) → hail.expr.expressions.typed_expressions.Float64Expression[source]

Inverts ppois().

Examples

>>> hl.eval(hl.qpois(0.99, 1))
4

Notes

Returns the smallest integer \(x\) such that Prob(\(X \leq x\)) \(\geq\) p where \(X\) is a Poisson random variable with rate parameter lambda.

Parameters:
Returns:

Expression of type tfloat64