--- title: "Annotating post-mortem control samples with thanatome" author: - name: Daniel Pérez-Calixto affiliation: Instituto Nacional de Medicina Genómica (INMEGEN), Mexico City - name: Camila Barrios-Cervantes affiliation: INMEGEN - name: Enrique Hernandez-Lemus affiliation: INMEGEN - name: Hugo Tovar affiliation: INMEGEN date: "`r Sys.Date()`" output: BiocStyle::html_document: toc: true bibliography: references.bib vignette: > %\VignetteIndexEntry{Annotating post-mortem control samples with thanatome} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 5 ) ``` # Introduction Post-mortem tissue from GTEx [@gtex2020] and similar resources is the usual "normal" control when a tumour cohort has no adjacent normal tissue. Those donors died in different ways, which GTEx records with the four-point Hardy scale of the circumstances of death [@hardy1985]: on a ventilator in intensive care (Hardy scale 0), suddenly (Hardy 1-2) or after a slow illness (Hardy 3-4), and their organs were collected hours after death. Death and post-mortem ischemia leave transcriptional traces [@ferreira2018; @pozhitkov2017], and GTEx samples also carry technical contamination from neighbouring tissues [@nieuwenhuis2020]. `thanatome` carries consensus transcriptional signatures of those processes, derived from GTEx v8 across ten tissues, and uses them to annotate every sample of a cohort before any downstream analysis: - **ventilator**: ventilated versus non-ventilated donors; seen from outside GTEx it is the axis *perfused versus post-mortem*; - **agony**: slow versus fast deaths among non-ventilated donors; - **ischemia**, not a third axis but the component of the ventilator axis sensitive to post-mortem ischemic time, meaningful among perfused donors only. For each sample the package returns a score per axis, a position scaled between the two poles of the reference tissue, a state label and technical flags. The user can then plot the cohort, select samples with explicit criteria, or carry the scores into a design matrix. How this differs from existing tools: `sva` [@leek2012] and `RUVSeq` [@risso2014] estimate unwanted variation from the data at hand without saying what it is; `limma::removeBatchEffect()` removes a known covariate. `thanatome` supplies the covariate with a biological name, anchored to GTEx references, and reports what each sample looks like before any adjustment. The post-mortem interval predictors of @ferreira2018 estimate ischemic time; here ischemic time is one component of a wider description of the donor's death. # Installation ```{r install, eval = FALSE} if (!requireNamespace("BiocManager", quietly = TRUE)) { install.packages("BiocManager") } BiocManager::install("thanatome") ``` # Scoring a cohort The example data are 74 GTEx v8 ovary controls and 40 TCGA-OV primary tumours from recount3, with raw counts of the signature genes, the full library size of each sample and the Hardy scale of each donor. The controls are scored first; the tumours enter later, when the differential expression is repeated with different control subsets. ```{r score} suppressPackageStartupMessages({ library(thanatome) library(SummarizedExperiment) }) data(thanatome_example) thanatome_example ctl <- thanatome_example[, thanatome_example$group == "control"] table(hardy = ctl$hardy) ``` A reference of the same tissue is mandatory: the scores are means of per-gene z-scores, and a sample has no z-score on its own. The package carries the reference of ten GTEx tissues, built from recount3 counts [@wilks2021]; the example data come from recount3 too, so they match. For data quantified with another pipeline, pass your own cohort as `reference`: scores are rank-stable across pipelines but positions are not. ```{r score2} sc <- thanatome_score(ctl, reference = "ovary") cols <- c("ventilator", "ischemia", "agony", "position_ventilator", "position_agony", "state") sc[1:5, cols] ``` Because the example carries the Hardy scale, the function reports as an internal check how well each score recovers the label. These GTEx samples entered the consensus, the references and the poles, so the figures below are in-sample; the out-of-sample figures (signatures derived without the tissue) are AUC 0.87-0.94 for ventilator and 0.69-0.90 for agony. ```{r auc} metadata(sc)$auc metadata(sc)$state_agreement ``` The scaled position is 0 at the median of the ventilated donors of the reference tissue and 1 at the median of the non-ventilated ones (for agony, 0 = fast deaths, 1 = slow deaths). Values outside 0-1 are allowed: living tissue falls below 0 on the ventilator axis. For cohorts quantified or sequenced apart from GTEx, read such values as a direction, not a magnitude: in external datasets the side of the poles on which a cohort fell was stable, but its distance beyond them changed with the handling of the batch (see *External cohorts* in `?thanatome_score`). For that reason, when `x` carries the whole, unfiltered transcriptome its samples are quantile-normalised to the reference by default (`normalize`); pass the counts before any filtering of lowly expressed genes. The example carries only the signature genes, so it is scored without normalisation. # Looking at the samples ```{r plot} plot_thanatome(sc, hardy = ctl$hardy) ``` ```{r ranked} plot_thanatome(sc, type = "ranked") ``` # Selecting samples with explicit criteria `select_samples()` applies intervals on the positions, a set of allowed state labels and the technical flags, and reports what was excluded and why. No criterion on the death axes is applied by default (technical flags are excluded unless `flags = FALSE`): in the analyses behind the package no subset of post-mortem controls was closer to surgical or living tissue than the full set except, slightly, the ventilated donors, and every exclusion costs power. The two presets correspond to the criteria the evidence supports as explicit choices, each with its cost documented in the help page. The agony interval applies only to non-perfused samples, since the agony axis is defined among non-ventilated donors; ventilated donors pass it. ```{r select} sel <- select_samples(sc, agony = c(-Inf, 0.5)) sel$summary head(sel$excluded) keep <- ctl[, sel$keep] keep ``` To keep the annotation with the counts, `add_thanatome_score()` returns the `SummarizedExperiment` itself with the score columns added to its `colData` and the score metadata in `metadata(x)$thanatome`; the columns then travel into `DESeqDataSet`, `DGEList` or design matrices built from it, and `prefix` avoids clashes with existing columns. ```{r add} ctl_ann <- add_thanatome_score(ctl, reference = "ovary") table(ctl_ann$state, hardy = ctl_ann$hardy) ``` # Using the scores as covariates The scores can enter a design matrix or `limma::removeBatchEffect()` as continuous covariates. Two cautions apply: the axes vary only among post-mortem samples, so in a tumour-versus-control design adjust within controls or keep the group term; and the adjustment centres the controls at their mean, not at the living pole. ```{r covariates} cv <- death_covariates(sc) head(cv) ``` ```{r limma, eval = requireNamespace("limma", quietly = TRUE)} logcpm <- edgeR::cpm(assay(ctl), lib.size = ctl$lib_size, log = TRUE, prior.count = 1) adjusted <- limma::removeBatchEffect(logcpm, covariates = cv, design = matrix(1, ncol(logcpm), 1)) dim(adjusted) ``` The annotated object from `add_thanatome_score()` feeds the usual model formulas directly, for example to ask, within the controls, which genes follow the death axes, or to carry the axes into a `DESeqDataSet`: ```{r design} design <- model.matrix(~ ventilator + agony, data = colData(ctl_ann)) head(design) ``` ```{r deseq2, eval = requireNamespace("DESeq2", quietly = TRUE)} dds <- DESeq2::DESeqDataSet(ctl_ann, design = ~ ventilator + agony) dds ``` # Joint regression and the fraction explained With `method = "regression"` the sample's z profile is regressed jointly on the consensus vectors of the axes. This adds the coefficients and the fraction of the sample's deviation from the tissue centroid explained by the axes. Classification is the same as with the signature score; what the regression adds is the fraction explained. Over the signature genes it is 8-18 percent in median in GTEx; over the whole transcriptome it is under 1 percent, and it is only computed when the reference is a cohort that carries the whole transcriptome (the example carries the signature genes only, so `r2_total` is `NA` here). It is measured against the centroid of the reference tissue, so a sample at the centroid has a fraction near zero whatever its state, and it is larger in fast non-ventilated deaths than in the other two states. ```{r regression} rg <- thanatome_score(ctl, reference = "ovary", method = "regression") summary(rg$r2_signature) tapply(rg$r2_signature, ctl$hardy, median) ``` # A decision workflow for including or excluding controls The natural loop is: score the samples, filter, look at the differential expression or the master-regulator analysis, and filter again. Its weakness is that the last step selects on the outcome: a filter kept because "the DE looks better" is a filter fitted to the result. `compare_controls()` turns the loop into one pass. The candidate criteria are declared first; each one is run once; every result is compared with the one obtained with all controls **and** with random subsets of the same size, which are the yardstick for what losing samples does by itself. A criterion whose losses and gains do not exceed those of the random subsets acts through sample size, not through the death axes. The example carries only the signature genes, so the fraction of DEGs in the axes (`frac_deg_in_axes`) is close to 1 by construction; with a whole transcriptome it is the quantity of interest. The fits should mirror the real analysis: `design` takes the covariates of the user's DE as a formula over `colData` (for example `~ batch + sex`; the group term is added last and tested), and `BPPARAM` spreads the edgeR fits over workers. The random subsets are drawn before fitting, so with the same `set.seed()` the result does not depend on the backend. ```{r compare} set.seed(1) criteria <- list( perfused = list(preset = "perfused"), no_agony = list(preset = "no_agony") ) cc <- compare_controls(thanatome_example, group = "group", control = "control", criteria = criteria, reference = "ovary", n_random = 3) as.data.frame(cc$summary) ``` The same comparison can carry a master-regulator analysis: pass as `mra` a function that takes the DE table of one run and returns a named vector of regulator activities (a wrapper around viper or NaRnEA); the agreement of each criterion with the full set, and of the random subsets, is added to the summary. The regulators themselves can be annotated with `annotate_mra()`, which reports how much of each regulon lies in the death axes and in which direction. ```{r mra} sig <- death_signatures("ventilator") up <- sig$ensembl[sig$direction == "up"][1:30] regs <- list( TF_vent = list(tfmode = setNames(rep(1, 30), up)), TF_other = paste0("ENSG0000000", seq_len(40)) ) annotate_mra(c(TF_vent = 3.1, TF_other = 0.2), regs, axes = c("ventilator", "agony")) ``` `audit_report()` writes the whole thing as text for a supplement. ```{r report} audit_report(sc, selection = select_samples(sc, preset = "no_agony"), comparison = cc) ``` # Annotating an existing differential-expression table `annotate_de()` adds to each gene the axis and direction it falls in, the consensus log fold change and the change in the tumour-versus-control log fold change expected when the control subset moves from non-ventilated to ventilated donors (or from fast to slow deaths), which within GTEx equals the contrast between the two subsets of controls. ```{r annotate} sig <- death_signatures("ventilator") de <- data.frame( logFC = c(0.2, 2.5, -1), adj.P.Val = c(0.01, 0.001, 0.04), row.names = c(sig$ensembl[1], sig$ensembl[2], "ENSG00000000003") ) annotate_de(de, axes = c("ventilator", "agony")) ``` # References
# Session information ```{r session} sessionInfo() ```