gnomad.utils.constraint.metrics
Functions to compute constraint metrics.
Covers pLI, the o/e confidence interval, z-scores, flags, and GENCODE annotations.
Compute the pLI score using the observed and expected variant counts. |
|
Compute a confidence interval around the observed/expected ratio. |
|
Compute the signed raw z-score using observed and expected variant counts. |
|
Determine the constraint flags that define why constraint will not be calculated. |
|
|
Calculate the standard deviation of the raw z-score. |
|
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:
- 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): useshl.qgammato 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 passmethodreturn different bounds than before."gamma"requires Hail >= 0.2.137, which addedhl.qgamma; on older Hail versions passmethod="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:
- Returns:
Struct with
lowerandupperbounds.
- 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:
obs_expr (
Int64Expression) – Observed variant count expression.exp_expr (
Float64Expression) – Expected variant count expression.
- Return type:
- 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:
- 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 isDEFAULT_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 ifgencode_htincludes 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:
- Returns:
Table with transcript annotations from GENCODE added.