gnomad.utils.constraint.metrics

Functions to compute constraint metrics.

Covers pLI, the o/e confidence interval, z-scores, flags, and GENCODE annotations.

gnomad.utils.constraint.metrics.compute_pli(ht, ...)

Compute the pLI score using the observed and expected variant counts.

gnomad.utils.constraint.metrics.oe_confidence_interval(...)

Compute a confidence interval around the observed/expected ratio.

gnomad.utils.constraint.metrics.calculate_raw_z_score(...)

Compute the signed raw z-score using observed and expected variant counts.

gnomad.utils.constraint.metrics.get_constraint_flags(...)

Determine the constraint flags that define why constraint will not be calculated.

gnomad.utils.constraint.metrics.calculate_raw_z_score_sd(...)

Calculate the standard deviation of the raw z-score.

gnomad.utils.constraint.metrics.add_gencode_transcript_annotations(ht, ...)

Add GENCODE annotations to Table based on transcript id.

Functions to compute constraint metrics.

Covers pLI, the o/e confidence interval, z-scores, flags, and GENCODE annotations.

gnomad.utils.constraint.metrics.compute_pli(ht, obs_expr, exp_expr, expected_values=None, min_diff_convergence=0.001)[source]

Compute the pLI score using the observed and expected variant counts.

Full details on pLI can be found in the ExAC paper: Lek, M., Karczewski, K., Minikel, E. et al. Analysis of protein-coding genetic variation in 60,706 humans. Nature 536, 285–291 (2016).

pLI is the probability of being loss-of-function intolerant, and this function computes that probability using the expectation-maximization (EM) algorithm.

We assume a 3 state model, where each gene fits into one of three categories with respect loss-of-function variation sensitivity:

  • Null: where protein truncating variation is completely tolerated by natural selection.

  • Recessive (Rec): where heterozygous pLoFs are tolerated but homozygous pLoFs are not.

  • Haploinsufficient (LI): where heterozygous pLoFs are not tolerated.

The function requires the expected amount of loss-of-function depletion for each of these states. The default provided is based on the observed depletion of protein-truncating variation in the Blekhman autosomal recessive and ClinGen dosage sensitivity gene sets (Supplementary Information Table 12 of the above reference):

  • Null: 1.0, assume tolerant genes have the expected amount of truncating variation.

  • Rec: 0.463, derived from the empirical mean observed/expected rate of truncating variation for recessive disease genes (0.463).

  • LI: 0.089, derived from the empirical mean observed/expected rate of truncating variation for severe haploinsufficient genes.

The output StructExpression will include the following annotations:

  • pLI: Probability of loss-of-function intolerance; probability that transcript falls into distribution of haploinsufficient genes.

  • pNull: Probability that transcript falls into distribution of unconstrained genes.

  • pRec: Probability that transcript falls into distribution of recessive genes.

Parameters:
  • ht (Table) – Input Table containing obs_expr and exp_expr.

  • obs_expr (Int64Expression) – Expression for the number of observed variants on each gene or transcript in ht.

  • exp_expr (Float64Expression) – Expression for the number of expected variants on each gene or transcript in ht.

  • expected_values (Optional[Dict[str, float]]) – Dictionary containing the expected values for ‘Null’, ‘Rec’, and ‘LI’ to use as starting values.

  • min_diff_convergence (float) – Minimum iteration change in LI to consider the EM model convergence criteria as met. Default is 0.001.

Return type:

StructExpression

Returns:

StructExpression for pLI scores.

gnomad.utils.constraint.metrics.oe_confidence_interval(obs_expr, exp_expr, alpha=0.05, method='gamma')[source]

Compute a confidence interval around the observed/expected ratio.

Two methods are available:

  • "gamma" (default): uses hl.qgamma to compute exact quantiles of the Gamma posterior. Fast and precise.

  • "poisson": sweeps a discretized Poisson likelihood over the OE parameter space [0, 2). Retained for backwards compatibility.

Note

The default changed from the discretized Poisson computation to "gamma", so calls that do not pass method return different bounds than before. "gamma" requires Hail >= 0.2.137, which added hl.qgamma; on older Hail versions pass method="poisson".

Parameters:
  • obs_expr (Int64Expression) – Observed variant count expression.

  • exp_expr (Float64Expression) – Expected variant count expression.

  • alpha (float) – Significance level for the confidence interval. Default is 0.05 (90% CI).

  • method (str) – CI method — "gamma" or "poisson". Default is "gamma".

Return type:

StructExpression

Returns:

Struct with lower and upper bounds.

gnomad.utils.constraint.metrics.calculate_raw_z_score(obs_expr, exp_expr)[source]

Compute the signed raw z-score using observed and expected variant counts.

The raw z-scores are positive when the transcript had fewer variants than expected, and are negative when transcripts had more variants than expected.

Parameters:
Return type:

Float64Expression

Returns:

Raw z-score expression.

gnomad.utils.constraint.metrics.get_constraint_flags(exp_expr, raw_z_expr, raw_z_lower_threshold=-5.0, raw_z_upper_threshold=5.0, flag_postfix='')[source]

Determine the constraint flags that define why constraint will not be calculated.

Flags which are added:
  • “no_exp_{flag_postfix}” - for genes that have missing or zero expected variants.

  • “outlier_{flag_postfix}” - for genes that are raw z-score outliers: (raw_z_expr < raw_z_lower_threshold) or (raw_z_expr > raw_z_upper_threshold).

Parameters:
  • exp_expr (Float64Expression) – Expression for the expected variant counts of pLoF, missense, or synonymous variants.

  • raw_z_expr (Float64Expression) – Expression for the signed raw z-score of pLoF, missense, or synonymous variants.

  • raw_z_lower_threshold (Union[float, Float64Expression, None]) – Lower threshold for the raw z-score. When raw_z_expr is less than this threshold it is considered an ‘outlier’. Default is -5.0.

  • raw_z_upper_threshold (Union[float, Float64Expression, None]) – Upper threshold for the raw z-score. When raw_z_expr is greater than this threshold it is considered an ‘outlier’. Default is 5.0.

  • flag_postfix (str) – Postfix to add to the end of the constraint flag names.

Return type:

Dict[str, Expression]

Returns:

Dictionary containing expressions for constraint flags.

gnomad.utils.constraint.metrics.calculate_raw_z_score_sd(raw_z_expr, flag_expr, mirror_neg_raw_z=True)[source]

Calculate the standard deviation of the raw z-score.

When using mirror_neg_raw_z is True, all the negative raw z-scores (defined by raw_z_expr) are combined with those same z-scores multiplied by -1 (to create a mirrored distribution).

Parameters:
  • raw_z_expr (Float64Expression) – Expression for the raw z-score.

  • flag_expr (StringExpression) – Expression for the constraint flags. z-score will not be calculated if flags are present.

  • mirror_neg_raw_z (bool) – Whether the standard deviation should be computed using a mirrored distribution of negative raw_z_expr.

Return type:

Expression

Returns:

StructExpression containing standard deviation of the raw z-score and the z-score.

gnomad.utils.constraint.metrics.add_gencode_transcript_annotations(ht, gencode_ht, annotations=('transcript_id_version', 'gene_id_version', 'level', 'transcript_type', 'start_position', 'end_position'), remove_y_par=True)[source]

Add GENCODE annotations to Table based on transcript id.

In addition to the annotations specified by annotations, the following computed annotations are always added:

  • chromosome

  • cds_length

  • num_coding_exons

Parameters:
  • ht (Table) – Input Table.

  • gencode_ht (Table) – Table with GENCODE annotations.

  • annotations (Union[List[str], Tuple[str, ...]]) – GENCODE annotations to add. Default is DEFAULT_GENCODE_ANNOTATIONS.

  • remove_y_par (bool) – Whether to remove features for the Y chromosome PAR regions. Default is True because the Y chromosome PAR regions are typically not included in the constraint calculations and both chrX and chrY will have the same ‘transcript_id’ field for these regions. This parameter can only be True if gencode_ht includes a ‘transcript_id_version’ field because Y_PAR (or PAR_Y, depending on the GENCODE release) is included in the version of the transcript, which has been stripped from the ‘transcript_id’ field.

Return type:

Table

Returns:

Table with transcript annotations from GENCODE added.