gnomad.utils.constraint.context
Functions to annotate the context Table for constraint.
Covers mutation rates, mutation types, trinucleotide context, methylation levels, and GERP cutoffs.
|
Get mutation rate annotation expression from the mutation rate Table. |
Annotate SNP mutation rate for the input Table. |
|
Annotate mutation types. |
|
Trim heptamer context to create trimer context. |
|
Return the deduplicated context by collapsing DNA strands. |
|
|
Transform methylation level into a 0 to 2 scale. |
|
Assemble context Table with necessary annotations for constraint calculations. |
Find GERP cutoffs at the given percentile thresholds. |
Functions to annotate the context Table for constraint.
Covers mutation rates, mutation types, trinucleotide context, methylation levels, and GERP cutoffs.
- gnomad.utils.constraint.context.get_mu_annotation_expr(ht, mutation_ht, mu_expr='mu_snp')[source]
Get mutation rate annotation expression from the mutation rate Table.
Note
Function expects that ht includes mutation_ht’s key fields. Note that these annotations don’t need to be the keys of ht. The standard keys used are: ‘context’, ‘ref’, ‘alt’, and ‘methylation_level’.
This function converts the mutation rate Table into a dictionary and uses the mutation rate HT key fields in the input Table to get the mutation rate annotation expression. The dictionary is used instead of joining the mutation rate Table to the input Table to avoid unnecessary shuffling given the small size of the mutation rate Table.
- Parameters:
ht (
Table) – Input Table that will be annotated with the returned mutation rate expression.mutation_ht (
Table) – Mutation rate Table.mu_expr (
Union[str,Float64Expression]) – Mutation rate expression or annotation name in mutation_ht. Default is ‘mu_snp’.
- Return type:
- Returns:
Mutation rate annotation expression.
- gnomad.utils.constraint.context.annotate_with_mu(ht, mutation_ht, mu_annotation='mu_snp')[source]
Annotate SNP mutation rate for the input Table.
Note
Function expects that ht includes mutation_ht’s key fields. Note that these annotations don’t need to be the keys of ht. The standard keys used are: ‘context’, ‘ref’, ‘alt’, and ‘methylation_level’.
- gnomad.utils.constraint.context.annotate_mutation_type(t, context_length=None, num_scan_context_length=100)[source]
Annotate mutation types.
- The following annotations are added to the output Table:
cpg
transition
mutation_type - one of “CpG”, “non-CpG transition”, or “transversion”
mutation_type_model
..note:
This function uses the term ‘mutation_type’ because ‘variant_type’ is already used in this repo to indicate a variant’s multiallelic and SNP/indel status.
- Parameters:
t (
Union[MatrixTable,Table]) – Input Table or MatrixTable.context_length (
Optional[int]) – Length of the ‘context’ annotation in ‘t’. If this is not specified, the value will be determined by examining the first num_scan_context_length values of the ‘context’ annotation. Default is None.num_scan_context_length (
Optional[int]) – Number of values in the ‘context’ annotation to use for determining context_length if it is not specified. If set to None, all values in ‘context’ will be used. Default is 100.
- Return type:
Union[MatrixTable,Table]- Returns:
Table with mutation type annotations added.
- gnomad.utils.constraint.context.trimer_from_heptamer(t)[source]
Trim heptamer context to create trimer context.
- Parameters:
t (
Union[MatrixTable,Table]) – Input MatrixTable or Table with context annotation.- Return type:
Union[MatrixTable,Table]- Returns:
MatrixTable or Table with trimer context annotated.
- gnomad.utils.constraint.context.collapse_strand(t)[source]
Return the deduplicated context by collapsing DNA strands.
Function returns the reverse complement for ‘ref, ‘alt’, and ‘context’ if the reference allele is either ‘G’ or ‘T’.
- The following annotations are added to the output Table:
was_flipped - whether the ‘ref, ‘alt’, and ‘context’ were flipped (reverse complement taken)
- Parameters:
ht – Input Table.
t (
Union[Table,MatrixTable]) –
- Return type:
Union[Table,MatrixTable]- Returns:
Table with deduplicated context annotation (ref, alt, context, was_flipped).
- gnomad.utils.constraint.context.transform_methylation_level(methylation_expr='methylation_level', methylation_cutoffs=(0, 5), ht=None)[source]
Transform methylation level into a 0 to 2 scale.
The methylation level is transformed to a 0-2 scale based on the provided cutoffs. The methylation level is assigned a value of 2 if it is greater than the second cutoff, 1 if it is greater than the first cutoff (but less than or equal to the second), and 0 otherwise.
- Parameters:
methylation_expr (
Union[str,NumericExpression]) – Methylation level expression or annotation name in ht. If methylation_expr is a string, ht must be provided.methylation_cutoffs (
Tuple[Union[int,float],Union[int,float]]) – Tuple of two integers/floats representing the cutoffs for the methylation level transformation. Default is (0, 5).ht (
Optional[Table]) – Input Table. Default is None.
- Return type:
Union[Table,NumericExpression]- Returns:
Table with methylation level annotation added or methylation level expression.
- gnomad.utils.constraint.context.assemble_constraint_context_ht(ht, methylation_ht=None, gerp_ht=None, coverage_hts=None, an_hts=None, freq_hts=None, filter_hts=None, transformation_funcs=None)[source]
Assemble context Table with necessary annotations for constraint calculations.
Note
Checks for ‘was_split’ annotation in Table. If not present, splits multiallelic sites.
The following annotations are added to the output Table:
ref: Reference allele.
alt: Alternate allele.
context: Trimer context.
annotations added by annotate_mutation_type(), collapse_strand(), and add_most_severe_csq_to_tc_within_vep_root().
Depending on the annotations provided, the following annotations may also be added:
‘methylation_level’: Methylation level annotation will be added if methylation_ht is provided.
‘gerp’: GERP annotation will be added if gerp_ht is provided.
‘coverage’: Coverage annotations will be added if coverage_hts is provided.
‘AN’: Allele number annotations will be added if an_hts is provided.
‘freq’: Frequency annotations will be added if freq_hts is provided.
‘filters’: Filter annotations will be added if filter_hts is provided.
The transformation_funcs parameter can be used to transform the HTs before adding annotations. The keys should be the annotation names (‘coverage’, ‘gerp’, etc.) and the values should be functions that take the annotation Table and the ht that is being annotated as input and return the transformed and keyed annotation. If not provided, the following default transformations are used:
‘methylation_level’: Uses the ‘methylation_level’ annotation in the Methylation Table after transforming the methylation level to a 0-2 scale using transform_grch37_methylation() or transform_grch38_methylation().
‘gerp’: Uses the ‘S’ annotation in the GERP Table. If ‘S’ is missing, it defaults to 0.
‘coverage’: If necessary, pulls out the first element of coverage statistics (which includes all samples). Relevant to v4, where coverage stats include additional elements to stratify by UK Biobank subset and platforms.
‘AN’: Uses the ‘AN’ annotation in the allele number Table.
‘freq’: Uses the ‘freq’ annotation in the frequency Table.
‘filters’: Uses the ‘filters’ annotation in the filter Table.
The following global annotations may also be added to the output Table:
‘an_globals’: Global allele number annotations ‘strata_sample_count’ and ‘strata_meta’ will be added if an_hts is provided.
‘freq_globals’: Global frequency annotations ‘freq_meta_sample_count’ and ‘freq_meta’ will be added if freq_hts is provided.
- Parameters:
ht (
Table) – Input context Table with VEP annotation.methylation_ht (
Table) – Optional Table with methylation annotation. Default is None.gerp_ht (
Table) – Optional Table with GERP annotation. Default is None.coverage_hts (
Dict[str,Table]) – An optional Dictionary with key as one of ‘exomes’ or ‘genomes’ and values as corresponding coverage Tables. Default is None.an_hts (
Dict[str,Table]) – A Dictionary with key as one of ‘exomes’ or ‘genomes’ and values as corresponding allele number Tables. Default is None.transformation_funcs (
Optional[Dict[str,Callable]]) – An optional Dictionary to transform the HTs before adding annotations. Default is None, which will use some default transformations as described above.freq_hts (
Dict[str,Table]) –filter_hts (
Dict[str,Table]) –
- Return type:
- Returns:
Table with sites split and necessary annotations.
- gnomad.utils.constraint.context.calculate_gerp_cutoffs(ht, gerp_expr=None, lower_percentile=0.05, upper_percentile=0.95)[source]
Find GERP cutoffs at the given percentile thresholds.
Note
Uses
hl.agg.approx_quantiles, so results are approximate.- Parameters:
ht (
Table) – Input Table.gerp_expr (
Optional[Float64Expression]) – GERP score expression. Default isht.gerp.lower_percentile (
float) – Lower percentile threshold (0-1). Default is 0.05.upper_percentile (
float) – Upper percentile threshold (0-1). Default is 0.95.
- Return type:
Tuple[float,float]- Returns:
Tuple of (lower cutoff, upper cutoff) GERP scores.