Post-mortem tissue from GTEx (GTEx Consortium
2020) 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 (Hardy et al.
1985): 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 (Ferreira et al. 2018; Pozhitkov et al. 2017), and GTEx samples
also carry technical contamination from neighbouring tissues (Nieuwenhuis et al.
2020). 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:
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 (Leek et al. 2012) and RUVSeq (Risso et al. 2014) 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 Ferreira et al.
(2018) estimate ischemic time; here ischemic time is one
component of a wider description of the donor’s death.
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.
suppressPackageStartupMessages({
library(thanatome)
library(SummarizedExperiment)
})
data(thanatome_example)
thanatome_example
#> class: SummarizedExperiment
#> dim: 1663 114
#> metadata(2): tissue source
#> assays(1): counts
#> rownames(1663): ENSG00000237973 ENSG00000187608 ... ENSG00000228986
#> ENSG00000235649
#> rowData names(1): symbol
#> colnames(114): GTEX-145LS-2326-SM-5TDCY GTEX-1PIEJ-1626-SM-E6CP9 ...
#> TCGA-25-1313-01A-01R-1565-13 TCGA-29-1785-01A-01R-1567-13
#> colData names(6): group lib_size ... ischemic_time rin
ctl <- thanatome_example[, thanatome_example$group == "control"]
table(hardy = ctl$hardy)
#> hardy
#> 0 1 2 3 4
#> 45 6 10 6 7A 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
(Wilks et al.
2021); 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.
sc <- thanatome_score(ctl, reference = "ovary")
cols <- c("ventilator", "ischemia", "agony",
"position_ventilator", "position_agony", "state")
sc[1:5, cols]
#> DataFrame with 5 rows and 6 columns
#> ventilator ischemia agony position_ventilator
#> <numeric> <numeric> <numeric> <numeric>
#> GTEX-145LS-2326-SM-5TDCY -0.359062 0.194642 -0.536718 1.070872
#> GTEX-1PIEJ-1626-SM-E6CP9 -0.136852 0.392311 -0.123320 0.631058
#> GTEX-11ZVC-1426-SM-5EGGA -0.252840 0.113958 -0.437914 0.860630
#> GTEX-13X6H-1026-SM-5SIBE 0.260266 0.198291 0.515456 -0.154949
#> GTEX-WYBS-2426-SM-4ONDI -0.281514 0.921718 -0.289596 0.917383
#> position_agony state
#> <numeric> <character>
#> GTEX-145LS-2326-SM-5TDCY -0.1003801 postmortem_rapid
#> GTEX-1PIEJ-1626-SM-E6CP9 0.6331653 postmortem_agony
#> GTEX-11ZVC-1426-SM-5EGGA 0.0749413 postmortem_rapid
#> GTEX-13X6H-1026-SM-5SIBE 1.7666274 perfused
#> GTEX-WYBS-2426-SM-4ONDI 0.3381198 postmortem_rapidBecause 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.
metadata(sc)$auc
#> ventilator agony
#> 0.9425287 0.8125000
metadata(sc)$state_agreement
#> [1] 0.7297297The 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.
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.
sel <- select_samples(sc, agony = c(-Inf, 0.5))
sel$summary
#> n kept ventilator agony ischemia state flags
#> 74 60 0 13 0 0 2
head(sel$excluded)
#> DataFrame with 6 rows and 2 columns
#> sample reason
#> <character> <character>
#> 1 GTEX-1PIEJ-1626-SM-E.. agony
#> 2 GTEX-11ZVC-1426-SM-5.. flags
#> 3 GTEX-1RDX4-0826-SM-E.. agony
#> 4 GTEX-X4EO-2426-SM-4Q.. agony
#> 5 GTEX-13OVJ-2426-SM-5.. agony
#> 6 GTEX-146FH-2526-SM-5.. agony
keep <- ctl[, sel$keep]
keep
#> class: SummarizedExperiment
#> dim: 1663 60
#> metadata(2): tissue source
#> assays(1): counts
#> rownames(1663): ENSG00000237973 ENSG00000187608 ... ENSG00000228986
#> ENSG00000235649
#> rowData names(1): symbol
#> colnames(60): GTEX-145LS-2326-SM-5TDCY GTEX-13X6H-1026-SM-5SIBE ...
#> GTEX-1OJC4-2026-SM-E6CQW GTEX-1H1CY-1926-SM-9WG7X
#> colData names(6): group lib_size ... ischemic_time rinTo 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.
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.
cv <- death_covariates(sc)
#> death_covariates: adjust within post-mortem controls or keep the group term in the design; the adjustment centres controls at their mean, not at the living pole
head(cv)
#> ventilator agony
#> GTEX-145LS-2326-SM-5TDCY -0.3262836 -0.474967737
#> GTEX-1PIEJ-1626-SM-E6CP9 -0.1040744 -0.061569710
#> GTEX-11ZVC-1426-SM-5EGGA -0.2200621 -0.376163321
#> GTEX-13X6H-1026-SM-5SIBE 0.2930436 0.577205933
#> GTEX-WYBS-2426-SM-4ONDI -0.2487358 -0.227846062
#> GTEX-12WSK-1926-SM-5LZVK 0.3432129 -0.001652532logcpm <- 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)
#> [1] 1663 74The 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:
design <- model.matrix(~ ventilator + agony, data = colData(ctl_ann))
head(design)
#> (Intercept) ventilator agony
#> GTEX-145LS-2326-SM-5TDCY 1 -0.3590617 -0.53671796
#> GTEX-1PIEJ-1626-SM-E6CP9 1 -0.1368525 -0.12331993
#> GTEX-11ZVC-1426-SM-5EGGA 1 -0.2528402 -0.43791354
#> GTEX-13X6H-1026-SM-5SIBE 1 0.2602655 0.51545571
#> GTEX-WYBS-2426-SM-4ONDI 1 -0.2815139 -0.28959629
#> GTEX-12WSK-1926-SM-5LZVK 1 0.3104348 -0.06340276dds <- DESeq2::DESeqDataSet(ctl_ann, design = ~ ventilator + agony)
#> converting counts to integer mode
dds
#> class: DESeqDataSet
#> dim: 1663 74
#> metadata(4): tissue source thanatome version
#> assays(1): counts
#> rownames(1663): ENSG00000237973 ENSG00000187608 ... ENSG00000228986
#> ENSG00000235649
#> rowData names(1): symbol
#> colnames(74): GTEX-145LS-2326-SM-5TDCY GTEX-1PIEJ-1626-SM-E6CP9 ...
#> GTEX-1H1CY-1926-SM-9WG7X GTEX-1JN1M-2126-SM-D4P2X
#> colData names(15): group lib_size ... flag_surfactant n_genesWith 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.
rg <- thanatome_score(ctl, reference = "ovary", method = "regression")
summary(rg$r2_signature)
#> Min. 1st Qu. Median Mean 3rd Qu. Max.
#> 0.01142 0.05399 0.10140 0.11991 0.17327 0.34640
tapply(rg$r2_signature, ctl$hardy, median)
#> 0 1 2 3 4
#> 0.07251323 0.25437280 0.20831607 0.10832928 0.13268921The 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.
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)
#> criterion n_controls n_deg lost gained lost_random gained_random jaccard
#> 1 all 72 851 0 0 NA NA 1.0000000
#> 2 perfused 39 746 137 32 101 18 0.8086070
#> 3 no_agony 60 808 57 14 34 9 0.9179191
#> jaccard_random sd_delta_lfc sd_delta_lfc_random frac_deg_in_axes sign_flips
#> 1 NA 0.0000000 NA 0.9917744 0
#> 2 0.8640553 0.4033215 0.19127997 0.9946381 0
#> 3 0.9500000 0.1715700 0.08210375 0.9913366 0The 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.
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"))
#> DataFrame with 2 rows and 10 columns
#> regulator nes n_targets frac_ventilator direction_ventilator
#> <character> <numeric> <integer> <numeric> <numeric>
#> 1 TF_vent 3.1 30 1 1
#> 2 TF_other 0.2 40 0 NA
#> fisher_padj_ventilator frac_agony direction_agony fisher_padj_agony
#> <numeric> <numeric> <numeric> <numeric>
#> 1 3.61352e-20 0.333333 1 0.000151473
#> 2 1.00000e+00 0.000000 NA 1.000000000
#> flag_control_state
#> <logical>
#> 1 TRUE
#> 2 FALSEaudit_report() writes the whole thing as text for a
supplement.
audit_report(sc,
selection = select_samples(sc, preset = "no_agony"), comparison = cc)
#> thanatome audit report
#> ======================
#> Reference: GTEx ovary; method: signature; 74 samples.
#> States (threshold 0.50): perfused = 39, postmortem_rapid = 22, postmortem_agony = 13.
#> Median position on the ventilator axis 0.37 (IQR -0.03 to 0.92); on the agony axis 0.78 (IQR 0.34 to 1.14).
#> Technical flags: pancreas 1, surfactant 1.
#> Internal check against the Hardy label: AUC ventilator 0.94, agony 0.81; state agreement 0.73.
#>
#> Selection
#> ---------
#> 60 of 74 samples kept. Excluded by criterion: ventilator = 0, agony = 0, ischemia = 0, state = 13, flags = 2.
#>
#> Sensitivity of the differential expression to the control subset
#> ----------------------------------------------------------------
#> DEG defined by padj <= 0.05 and |log2FC| >= 1; random subsets of the same size are the yardstick.
#> criterion n_controls n_deg lost lost_random gained gained_random jaccard
#> all 72 851 0 NA 0 NA 1.000
#> perfused 39 746 137 101 32 18 0.809
#> no_agony 60 808 57 34 14 9 0.918
#> jaccard_random sd_delta_lfc sd_delta_lfc_random frac_deg_in_axes sign_flips
#> NA 0.000 NA 0.992 0
#> 0.864 0.403 0.1913 0.995 0
#> 0.950 0.172 0.0821 0.991 0
#> A criterion whose losses and gains do not exceed those of the random subsets acts through sample size, not through the death axes.
#>
#> In GTEx v8, no subset of post-mortem controls was closer to surgical or living tissue than the full set except, slightly, the ventilated donors; the package annotates and quantifies, it does not correct death.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.
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"))
#> annotate_de: 2 genes matched the death signatures
#> DataFrame with 3 rows and 12 columns
#> logFC adj.P.Val gene log2FoldChange padj
#> <numeric> <numeric> <character> <numeric> <numeric>
#> ENSG00000166189 0.2 0.010 ENSG00000166189 0.2 0.010
#> ENSG00000172409 2.5 0.001 ENSG00000172409 2.5 0.001
#> ENSG00000000003 -1.0 0.040 ENSG00000000003 -1.0 0.040
#> axis_ventilator lfc_consensus_ventilator delta_lfc_ventilator
#> <character> <numeric> <numeric>
#> ENSG00000166189 up 0.657379 -0.657379
#> ENSG00000172409 up 0.641746 -0.641746
#> ENSG00000000003 NA NA NA
#> axis_agony lfc_consensus_agony delta_lfc_agony
#> <character> <numeric> <numeric>
#> ENSG00000166189 NA NA NA
#> ENSG00000172409 NA NA NA
#> ENSG00000000003 NA NA NA
#> sign_depends_on_control
#> <logical>
#> ENSG00000166189 TRUE
#> ENSG00000172409 FALSE
#> ENSG00000000003 FALSEsessionInfo()
#> R version 4.6.2 (2026-10-29)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 LTS
#>
#> Matrix products: default
#> BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so; LAPACK version 3.12.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8
#> [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
#> [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
#> [9] LC_ADDRESS=C LC_TELEPHONE=C
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
#>
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats4 stats graphics grDevices utils datasets methods
#> [8] base
#>
#> other attached packages:
#> [1] thanatome_0.99.0 SummarizedExperiment_1.43.0
#> [3] Biobase_2.73.2 GenomicRanges_1.65.4
#> [5] Seqinfo_1.3.2 IRanges_2.47.5
#> [7] S4Vectors_0.51.10 BiocGenerics_0.59.12
#> [9] generics_0.1.4 MatrixGenerics_1.25.0
#> [11] matrixStats_1.5.0 BiocStyle_2.41.0
#>
#> loaded via a namespace (and not attached):
#> [1] sass_0.4.10 SparseArray_1.13.4 DESeq2_1.53.7
#> [4] lattice_0.23-1 digest_0.6.39 evaluate_1.0.5
#> [7] grid_4.6.2 RColorBrewer_1.1-3 fastmap_1.2.0
#> [10] jsonlite_2.0.0 Matrix_1.7-6 limma_3.99.4
#> [13] BiocManager_1.30.27 scales_1.4.0 codetools_0.2-20
#> [16] jquerylib_0.1.4 abind_1.4-8 cli_3.6.6
#> [19] rlang_1.3.0 XVector_0.53.0 withr_3.0.3
#> [22] cachem_1.1.0 DelayedArray_0.39.8 yaml_2.3.12
#> [25] otel_0.3.0 S4Arrays_1.13.2 parallel_4.6.2
#> [28] tools_4.6.2 BiocParallel_1.47.0 ggplot2_4.0.3
#> [31] locfit_1.5-9.12 buildtools_1.0.0 vctrs_0.7.3
#> [34] R6_2.6.1 lifecycle_1.0.5 edgeR_4.99.12
#> [37] bslib_0.12.0 gtable_0.3.6 Rcpp_1.1.2
#> [40] glue_1.8.1 statmod_1.5.2 xfun_0.62
#> [43] sys_3.4.3 knitr_1.52 farver_2.1.2
#> [46] htmltools_0.5.9 labeling_0.4.3 rmarkdown_2.32
#> [49] maketools_1.3.2 compiler_4.6.2 S7_0.2.2