def transmission_disequilibrium_test(dataset, pedigree) -> Table:
r"""Performs the transmission disequilibrium test on trios.
.. include:: ../_templates/req_tstring.rst
.. include:: ../_templates/req_tvariant.rst
.. include:: ../_templates/req_biallelic.rst
Examples
--------
Compute TDT association statistics and show the first two results:
>>> pedigree = hl.Pedigree.read('data/tdt_trios.fam')
>>> tdt_table = hl.transmission_disequilibrium_test(tdt_dataset, pedigree)
>>> tdt_table.show(2) # doctest: +NOTEST
+---------------+------------+-------+-------+----------+----------+
| locus | alleles | t | u | chi_sq | p_value |
+---------------+------------+-------+-------+----------+----------+
| locus<GRCh37> | array<str> | int64 | int64 | float64 | float64 |
+---------------+------------+-------+-------+----------+----------+
| 1:246714629 | ["C","A"] | 0 | 4 | 4.00e+00 | 4.55e-02 |
| 2:167262169 | ["T","C"] | NA | NA | NA | NA |
+---------------+------------+-------+-------+----------+----------+
Export variants with p-values below 0.001:
>>> tdt_table = tdt_table.filter(tdt_table.p_value < 0.001)
>>> tdt_table.export("output/tdt_results.tsv")
Notes
-----
The
`transmission disequilibrium test <https://en.wikipedia.org/wiki/Transmission_disequilibrium_test#The_case_of_trios:_one_affected_child_per_family>`__
compares the number of times the alternate allele is transmitted (t) versus
not transmitted (u) from a heterozgyous parent to an affected child. The null
hypothesis holds that each case is equally likely. The TDT statistic is given by
.. math::
(t - u)^2 \over (t + u)
and asymptotically follows a chi-squared distribution with one degree of
freedom under the null hypothesis.
:func:`transmission_disequilibrium_test` only considers complete trios (two
parents and a proband with defined sex) and only returns results for the
autosome, as defined by :meth:`~hail.genetics.Locus.in_autosome`, and
chromosome X. Transmissions and non-transmissions are counted only for the
configurations of genotypes and copy state in the table below, in order to
filter out Mendel errors and configurations where transmission is
guaranteed. The copy state of a locus with respect to a trio is defined as
follows:
- Auto -- in autosome or in PAR of X or female child
- HemiX -- in non-PAR of X and male child
Here PAR is the `pseudoautosomal region
<https://en.wikipedia.org/wiki/Pseudoautosomal_region>`__
of X and Y defined by :class:`.ReferenceGenome`, which many variant callers
map to chromosome X.
+--------+--------+--------+------------+---+---+
| Kid | Dad | Mom | Copy State | t | u |
+========+========+========+============+===+===+
| HomRef | Het | Het | Auto | 0 | 2 |
+--------+--------+--------+------------+---+---+
| HomRef | HomRef | Het | Auto | 0 | 1 |
+--------+--------+--------+------------+---+---+
| HomRef | Het | HomRef | Auto | 0 | 1 |
+--------+--------+--------+------------+---+---+
| Het | Het | Het | Auto | 1 | 1 |
+--------+--------+--------+------------+---+---+
| Het | HomRef | Het | Auto | 1 | 0 |
+--------+--------+--------+------------+---+---+
| Het | Het | HomRef | Auto | 1 | 0 |
+--------+--------+--------+------------+---+---+
| Het | HomVar | Het | Auto | 0 | 1 |
+--------+--------+--------+------------+---+---+
| Het | Het | HomVar | Auto | 0 | 1 |
+--------+--------+--------+------------+---+---+
| HomVar | Het | Het | Auto | 2 | 0 |
+--------+--------+--------+------------+---+---+
| HomVar | Het | HomVar | Auto | 1 | 0 |
+--------+--------+--------+------------+---+---+
| HomVar | HomVar | Het | Auto | 1 | 0 |
+--------+--------+--------+------------+---+---+
| HomRef | HomRef | Het | HemiX | 0 | 1 |
+--------+--------+--------+------------+---+---+
| HomRef | HomVar | Het | HemiX | 0 | 1 |
+--------+--------+--------+------------+---+---+
| HomVar | HomRef | Het | HemiX | 1 | 0 |
+--------+--------+--------+------------+---+---+
| HomVar | HomVar | Het | HemiX | 1 | 0 |
+--------+--------+--------+------------+---+---+
:func:`tdt` produces a table with the following columns:
- `locus` (:class:`.tlocus`) -- Locus.
- `alleles` (:class:`.tarray` of :py:data:`.tstr`) -- Alleles.
- `t` (:py:data:`.tint32`) -- Number of transmitted alternate alleles.
- `u` (:py:data:`.tint32`) -- Number of untransmitted alternate alleles.
- `chi_sq` (:py:data:`.tfloat64`) -- TDT statistic.
- `p_value` (:py:data:`.tfloat64`) -- p-value.
Parameters
----------
dataset : :class:`.MatrixTable`
Dataset.
pedigree : :class:`~hail.genetics.Pedigree`
Sample pedigree.
Returns
-------
:class:`.Table`
Table of TDT results.
"""
dataset = require_biallelic(dataset, 'transmission_disequilibrium_test')
dataset = dataset.annotate_rows(auto_or_x_par = dataset.locus.in_autosome() | dataset.locus.in_x_par())
dataset = dataset.filter_rows(dataset.auto_or_x_par | dataset.locus.in_x_nonpar())
hom_ref = 0
het = 1
hom_var = 2
auto = 2
hemi_x = 1
# kid, dad, mom, copy, t, u
config_counts = [(hom_ref, het, het, auto, 0, 2),
(hom_ref, hom_ref, het, auto, 0, 1),
(hom_ref, het, hom_ref, auto, 0, 1),
( het, het, het, auto, 1, 1),
( het, hom_ref, het, auto, 1, 0),
( het, het, hom_ref, auto, 1, 0),
( het, hom_var, het, auto, 0, 1),
( het, het, hom_var, auto, 0, 1),
(hom_var, het, het, auto, 2, 0),
(hom_var, het, hom_var, auto, 1, 0),
(hom_var, hom_var, het, auto, 1, 0),
(hom_ref, hom_ref, het, hemi_x, 0, 1),
(hom_ref, hom_var, het, hemi_x, 0, 1),
(hom_var, hom_ref, het, hemi_x, 1, 0),
(hom_var, hom_var, het, hemi_x, 1, 0)]
count_map = hl.literal({(c[0], c[1], c[2], c[3]): [c[4], c[5]] for c in config_counts})
tri = trio_matrix(dataset, pedigree, complete_trios=True)
# this filter removes mendel error of het father in x_nonpar. It also avoids
# building and looking up config in common case that neither parent is het
father_is_het = tri.father_entry.GT.is_het()
parent_is_valid_het = ((father_is_het & tri.auto_or_x_par) |
(tri.mother_entry.GT.is_het() & ~father_is_het))
copy_state = hl.cond(tri.auto_or_x_par | tri.is_female, 2, 1)
config = (tri.proband_entry.GT.n_alt_alleles(),
tri.father_entry.GT.n_alt_alleles(),
tri.mother_entry.GT.n_alt_alleles(),
copy_state)
tri = tri.annotate_rows(counts = agg.filter(parent_is_valid_het, agg.array_sum(count_map.get(config))))
tab = tri.rows().select('counts')
tab = tab.transmute(t = tab.counts[0], u = tab.counts[1])
tab = tab.annotate(chi_sq = ((tab.t - tab.u) ** 2) / (tab.t + tab.u))
tab = tab.annotate(p_value = hl.pchisqtail(tab.chi_sq, 1.0))
return tab.cache()
def transmission_disequilibrium_test(dataset, pedigree) -> Table:
r"""Performs the transmission disequilibrium test on trios.
.. include:: ../_templates/req_tstring.rst
.. include:: ../_templates/req_tvariant.rst
.. include:: ../_templates/req_biallelic.rst
Examples
--------
Compute TDT association statistics and show the first two results:
>>> pedigree = hl.Pedigree.read('data/tdt_trios.fam')
>>> tdt_table = hl.transmission_disequilibrium_test(tdt_dataset, pedigree)
>>> tdt_table.show(2) # doctest: +NOTEST
+---------------+------------+-------+-------+----------+----------+
| locus | alleles | t | u | chi_sq | p_value |
+---------------+------------+-------+-------+----------+----------+
| locus<GRCh37> | array<str> | int64 | int64 | float64 | float64 |
+---------------+------------+-------+-------+----------+----------+
| 1:246714629 | ["C","A"] | 0 | 4 | 4.00e+00 | 4.55e-02 |
| 2:167262169 | ["T","C"] | NA | NA | NA | NA |
+---------------+------------+-------+-------+----------+----------+
Export variants with p-values below 0.001:
>>> tdt_table = tdt_table.filter(tdt_table.p_value < 0.001)
>>> tdt_table.export("output/tdt_results.tsv")
Notes
-----
The
`transmission disequilibrium test <https://en.wikipedia.org/wiki/Transmission_disequilibrium_test#The_case_of_trios:_one_affected_child_per_family>`__
compares the number of times the alternate allele is transmitted (t) versus
not transmitted (u) from a heterozgyous parent to an affected child. The null
hypothesis holds that each case is equally likely. The TDT statistic is given by
.. math::
(t - u)^2 \over (t + u)
and asymptotically follows a chi-squared distribution with one degree of
freedom under the null hypothesis.
:func:`transmission_disequilibrium_test` only considers complete trios (two
parents and a proband with defined sex) and only returns results for the
autosome, as defined by :meth:`~hail.genetics.Locus.in_autosome`, and
chromosome X. Transmissions and non-transmissions are counted only for the
configurations of genotypes and copy state in the table below, in order to
filter out Mendel errors and configurations where transmission is
guaranteed. The copy state of a locus with respect to a trio is defined as
follows:
- Auto -- in autosome or in PAR of X or female child
- HemiX -- in non-PAR of X and male child
Here PAR is the `pseudoautosomal region
<https://en.wikipedia.org/wiki/Pseudoautosomal_region>`__
of X and Y defined by :class:`.ReferenceGenome`, which many variant callers
map to chromosome X.
+--------+--------+--------+------------+---+---+
| Kid | Dad | Mom | Copy State | t | u |
+========+========+========+============+===+===+
| HomRef | Het | Het | Auto | 0 | 2 |
+--------+--------+--------+------------+---+---+
| HomRef | HomRef | Het | Auto | 0 | 1 |
+--------+--------+--------+------------+---+---+
| HomRef | Het | HomRef | Auto | 0 | 1 |
+--------+--------+--------+------------+---+---+
| Het | Het | Het | Auto | 1 | 1 |
+--------+--------+--------+------------+---+---+
| Het | HomRef | Het | Auto | 1 | 0 |
+--------+--------+--------+------------+---+---+
| Het | Het | HomRef | Auto | 1 | 0 |
+--------+--------+--------+------------+---+---+
| Het | HomVar | Het | Auto | 0 | 1 |
+--------+--------+--------+------------+---+---+
| Het | Het | HomVar | Auto | 0 | 1 |
+--------+--------+--------+------------+---+---+
| HomVar | Het | Het | Auto | 2 | 0 |
+--------+--------+--------+------------+---+---+
| HomVar | Het | HomVar | Auto | 1 | 0 |
+--------+--------+--------+------------+---+---+
| HomVar | HomVar | Het | Auto | 1 | 0 |
+--------+--------+--------+------------+---+---+
| HomRef | HomRef | Het | HemiX | 0 | 1 |
+--------+--------+--------+------------+---+---+
| HomRef | HomVar | Het | HemiX | 0 | 1 |
+--------+--------+--------+------------+---+---+
| HomVar | HomRef | Het | HemiX | 1 | 0 |
+--------+--------+--------+------------+---+---+
| HomVar | HomVar | Het | HemiX | 1 | 0 |
+--------+--------+--------+------------+---+---+
:func:`tdt` produces a table with the following columns:
- `locus` (:class:`.tlocus`) -- Locus.
- `alleles` (:class:`.tarray` of :py:data:`.tstr`) -- Alleles.
- `t` (:py:data:`.tint32`) -- Number of transmitted alternate alleles.
- `u` (:py:data:`.tint32`) -- Number of untransmitted alternate alleles.
- `chi_sq` (:py:data:`.tfloat64`) -- TDT statistic.
- `p_value` (:py:data:`.tfloat64`) -- p-value.
Parameters
----------
dataset : :class:`.MatrixTable`
Dataset.
pedigree : :class:`~hail.genetics.Pedigree`
Sample pedigree.
Returns
-------
:class:`.Table`
Table of TDT results.
"""
dataset = require_biallelic(dataset, 'transmission_disequilibrium_test')
dataset = dataset.annotate_rows(auto_or_x_par=dataset.locus.in_autosome()
| dataset.locus.in_x_par())
dataset = dataset.filter_rows(dataset.auto_or_x_par
| dataset.locus.in_x_nonpar())
hom_ref = 0
het = 1
hom_var = 2
auto = 2
hemi_x = 1
# kid, dad, mom, copy, t, u
config_counts = [(hom_ref, het, het, auto, 0, 2),
(hom_ref, hom_ref, het, auto, 0, 1),
(hom_ref, het, hom_ref, auto, 0, 1),
(het, het, het, auto, 1, 1),
(het, hom_ref, het, auto, 1, 0),
(het, het, hom_ref, auto, 1, 0),
(het, hom_var, het, auto, 0, 1),
(het, het, hom_var, auto, 0, 1),
(hom_var, het, het, auto, 2, 0),
(hom_var, het, hom_var, auto, 1, 0),
(hom_var, hom_var, het, auto, 1, 0),
(hom_ref, hom_ref, het, hemi_x, 0, 1),
(hom_ref, hom_var, het, hemi_x, 0, 1),
(hom_var, hom_ref, het, hemi_x, 1, 0),
(hom_var, hom_var, het, hemi_x, 1, 0)]
count_map = hl.literal({(c[0], c[1], c[2], c[3]): [c[4], c[5]]
for c in config_counts})
tri = trio_matrix(dataset, pedigree, complete_trios=True)
# this filter removes mendel error of het father in x_nonpar. It also avoids
# building and looking up config in common case that neither parent is het
father_is_het = tri.father_entry.GT.is_het()
parent_is_valid_het = ((father_is_het & tri.auto_or_x_par) |
(tri.mother_entry.GT.is_het() & ~father_is_het))
copy_state = hl.cond(tri.auto_or_x_par | tri.is_female, 2, 1)
config = (tri.proband_entry.GT.n_alt_alleles(),
tri.father_entry.GT.n_alt_alleles(),
tri.mother_entry.GT.n_alt_alleles(), copy_state)
tri = tri.annotate_rows(counts=agg.filter(
parent_is_valid_het, agg.array_sum(count_map.get(config))))
tab = tri.rows().select('counts')
tab = tab.transmute(t=tab.counts[0], u=tab.counts[1])
tab = tab.annotate(chi_sq=((tab.t - tab.u)**2) / (tab.t + tab.u))
tab = tab.annotate(p_value=hl.pchisqtail(tab.chi_sq, 1.0))
return tab.cache()
def tx_annotate_mt(mt,
gtex,
filter_to_genes=None,
gene_column_in_mt=None,
filter_to_csqs=None,
out_tx_annotation_tsv=None,
out_tx_annotation_kt=None,
filter_to_homs=False):
"""
Annotate variants in the input MatrixTable with transcript-based expression values accross GTEx. Returns Table.
:param MatrixTable mt:
:param MatrixTable gtex: Input GTEx summary MatrixTable, must have transcript_id column to key by
:param None or set filter_to_genes: Default None. If you'd like to filter the mt before annotating
(decreases time) feed in a list or set of genes
:param str gene_column_in_mt: Must be set if filter_to_genes != None.
Column in matrix table that contains gene information within vep.transcript_consequences.
often ["gene_id", "gene_symbol"]
:param Nonr or list filter_to_csqs: Default None. If you'd like to filter the mt before annotating
(decreases time) feed in a list or set of consequence terms.
Example = ["stop_gained","splice_donor_variant", "splice_acceptor_variant","frameshift_variant"]
:param None or str out_tx_annotation_tsv: Default None.
If you'd like to write out the results table as a tsv, provide a tsv path
:param None or str out_tx_annotation_kt: Default None.
If you'd like to write out the results table as a Hail 0.2 table, provide a .kt path
:param bool filter_to_homs: Default False
If True, filter to variants with at least one homozygote in dataset
:return: Table with columns: variant, worst_csq, ensg, LOFTEE LOF, LOFTEE LOF Flag, transcript-aware expression
by GTEx Tissue
:rtype: Table with variants annotated with transcript-aware tissue expression
"""
# Create a Table copy of GTEx, key'd by transcript_id
gtex_table = gtex.rows().key_by("transcript_id")
# Explode the mt for the transcript consequences to be able to key by transcript ID
mt = mt.explode_rows(mt.vep.transcript_consequences)
# Add worst csq to the mt
mt = simplify_worst_csq(mt)
mt_kt = mt.rows()
if filter_to_genes:
print("Filtering to genes of interest")
mt_kt = filter_table_to_gene_list(mt_kt, filter_to_genes,
gene_column_in_mt)
if filter_to_csqs:
print("Filtering to csqs in %s" % (",".join(filter_to_csqs)))
mt_kt = filter_table_to_csqs(mt_kt, filter_to_csqs)
if filter_to_homs:
print(
"Filtering to variants with at least 1 homozygote sample in dataset"
)
mt_kt = mt_kt.filter(mt_kt.info.Hom[mt_kt.a_index - 1] > 0)
# Annotate mt with the gtex values (ie. join them)
mt_kt = mt_kt.annotate(
tx_data=gtex_table[mt_kt.vep.transcript_consequences.transcript_id])
# Group by gene, worst_csq and variant, and do a pairwise-sum
grouped_table = (mt_kt.group_by(
worst_csq=mt_kt.worst_csq,
ensg=mt_kt.vep.transcript_consequences.gene_id,
locus=mt_kt.locus,
alleles=mt_kt.alleles,
lof=mt_kt.vep.transcript_consequences.lof,
lof_flag=mt_kt.vep.transcript_consequences.lof_flags).aggregate(
tx_annotation=agg.array_sum(mt_kt.tx_data.agg_expression)))
# Expand the columns from the arrays and add tissues as headers
tissue_ids = gtex.aggregate_cols(agg.collect(gtex.tissue))
d = {tiss: i for i, tiss in enumerate(tissue_ids)}
# This is currently a hack but Tim will fix it at which point I can remove "replace"s
tx_annotation_table = grouped_table.annotate(
**{
tissue_id.replace("-", "_").replace(" ", "_").replace("(", "_").
replace(")", "_"): grouped_table.tx_annotation[d[tissue_id]]
for tissue_id in tissue_ids
})
if out_tx_annotation_tsv:
print("Writing tsv file to %s" % out_tx_annotation_tsv)
tx_annotation_table.export(out_tx_annotation_tsv)
if out_tx_annotation_kt:
print("Writing Table to %s" % out_tx_annotation_kt)
tx_annotation_table.write(out_tx_annotation_kt)
return tx_annotation_table