satuRn
is an R package for performing differential
transcript usage analyses in bulk and single-cell transcriptomics
datasets. The package has three main functions.
The first function, fitDTU
, is used to model
transcript usage profiles by means of a quasi-binomial generalized
linear model.
Second, the testDTU
function tests for differential
usage of transcripts between certain groups of interest (e.g. different
treatment groups or cell types).
Finally, the plotDTU
can be used to visualize the
usage profiles of selected transcripts in different groups of
interest.
All details about the satuRn
model and statistical tests
are described in our preprint (Gilis Jeroen
2021).
In this vignette, we analyze a small subset of the data from (Tasic Bosiljka 2018). More specifically, an
expression matrix and the corresponding metadata of the subset data has
been provided with the satuRn
package. We will adopt this
dataset to showcase the different functionalities of
satuRn
.
satuRn
(version 1.4.0) can be installed from
Bioconductor with:
if(!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("satuRn")
Alternatively, the development version of satuRn
can be
downloaded with:
devtools::install_github("statOmics/satuRn")
! for this vignette, we use the development version of satuRn. The vignette for the officially released satuRn version 1.4.0 can be viewed from Bioconductor
library(satuRn)
library(AnnotationHub)
library(ensembldb)
library(edgeR)
library(SummarizedExperiment)
library(ggplot2)
library(DEXSeq)
library(stageR)
The following data corresponds to a small subset of the dataset from
(Tasic Bosiljka 2018) and is readily
available from the satuRn
package. To check how the subset
was generate, please check ?Tasic_counts_vignette
.
data(Tasic_counts_vignette) # transcript expression matrix
data(Tasic_metadata_vignette) # metadata
We start the analysis from scratch, in order to additionally showcase some of the prerequisite steps for performing a DTU analysis.
First, we need an object that links transcripts to their
corresponding genes. We suggest using the BioConductor R packages
AnnotationHub
and ensembldb
for this
purpose.
ah <- AnnotationHub() # load the annotation resource.
all <- query(ah, "EnsDb") # query for all available EnsDb databases
ahEdb <- all[["AH75036"]] # for Mus musculus (choose correct release date)
txs <- transcripts(ahEdb)
Next, we perform some data wrangling steps to get the data in a
format that is suited for satuRn. First, we create a
DataFrame
or Matrix
linking transcripts to
their corresponding genes.
! Important: satuRn
is implemented such that the columns
with transcript identifiers is names isoform_id
, while the
column containing gene identifiers should be named gene_id
.
In addition, following chunk removes transcripts that are the only
isoform expressed of a certain gene, as they cannot be used in a DTU
analysis.
# Get the transcript information in correct format
txInfo <- as.data.frame(matrix(data = NA, nrow = length(txs), ncol = 2))
colnames(txInfo) <- c("isoform_id", "gene_id")
txInfo$isoform_id <- txs$tx_id
txInfo$gene_id <- txs$gene_id
rownames(txInfo) <- txInfo$isoform_id
# Remove transcripts that are the only isoform expressed of a certain gene
rownames(Tasic_counts_vignette) <- sub("\\..*", "",
rownames(Tasic_counts_vignette))
# remove transcript version identifiers
txInfo <- txInfo[txInfo$isoform_id %in% rownames(Tasic_counts_vignette), ]
txInfo <- subset(txInfo,
duplicated(gene_id) | duplicated(gene_id, fromLast = TRUE))
Tasic_counts_vignette <- Tasic_counts_vignette[which(
rownames(Tasic_counts_vignette) %in% txInfo$isoform_id), ]
Here we perform some feature-level filtering. For this task, we adopt
the filtering criterion that is implemented in the R package
edgeR
. Alternatively, one could adopt the
dmFilter
criterion from the DRIMSeq
R package,
which provides a more stringent filtering when both methods are run in
default settings. After filtering, we again remove transcripts that are
the only isoform expressed of a certain gene.
filter_edgeR <- filterByExpr(Tasic_counts_vignette,
design = NULL,
group = Tasic_metadata_vignette$brain_region,
lib.size = NULL,
min.count = 10,
min.total.count = 30,
large.n = 20,
min.prop = 0.7
) # more stringent than default to reduce run time of the vignette
table(filter_edgeR)
## filter_edgeR
## FALSE TRUE
## 5996 10982
Tasic_counts_vignette <- Tasic_counts_vignette[filter_edgeR, ]
# Update txInfo according to the filtering procedure
txInfo <- txInfo[which(
txInfo$isoform_id %in% rownames(Tasic_counts_vignette)), ]
# remove txs that are the only isoform expressed within a gene (after filtering)
txInfo <- subset(txInfo,
duplicated(gene_id) | duplicated(gene_id, fromLast = TRUE))
Tasic_counts_vignette <- Tasic_counts_vignette[which(rownames(
Tasic_counts_vignette) %in% txInfo$isoform_id), ]
# satuRn requires the transcripts in the rowData and
# the transcripts in the count matrix to be in the same order.
txInfo <- txInfo[match(rownames(Tasic_counts_vignette), txInfo$isoform_id), ]
Here we set up the design matrix of the experiment. The subset of the
dataset from (Tasic Bosiljka 2018)
contains cells of several different cell types (variable
cluster
) in two different areas of the mouse neocortex
(variable brain_region
). As such, we can model the data
with a factorial design, i.e. by generating a new variable
group
that encompasses all different cell type - brain
region combinations.
Tasic_metadata_vignette$group <- paste(Tasic_metadata_vignette$brain_region,
Tasic_metadata_vignette$cluster,
sep = ".")
All three main functions of satuRn
require a
SummarizedExperiment
object as an input class. See the
SummarizedExperiment vignette (Morgan Martin,
n.d.) for more information on this object class.
For the sake of completeness, it is advised to include the design matrix formula in the SummarizedExperiment as indicated below.
sumExp <- SummarizedExperiment::SummarizedExperiment(
assays = list(counts = Tasic_counts_vignette),
colData = Tasic_metadata_vignette,
rowData = txInfo
)
# for sake of completeness: specify design formula from colData
metadata(sumExp)$formula <- ~ 0 + as.factor(colData(sumExp)$group)
sumExp
## class: SummarizedExperiment
## dim: 9151 60
## metadata(1): formula
## assays(1): counts
## rownames(9151): ENSMUST00000037739 ENSMUST00000228774 ...
## ENSMUST00000127554 ENSMUST00000132683
## rowData names(2): isoform_id gene_id
## colnames(60): F2S4_160622_013_D01 F2S4_160624_023_C01 ...
## F2S4_160919_010_B01 F2S4_160915_002_D01
## colData names(4): sample_name brain_region cluster group
The fitDTU
function of satuRn
is used to
model transcript usage in different groups of samples or cells. Here we
adopt the default settings of the function. Without parallelized
execution, this code runs for approximately 15 seconds on a 2018 macbook
pro laptop.
system.time({
sumExp <- satuRn::fitDTU(
object = sumExp,
formula = ~ 0 + group,
parallel = FALSE,
BPPARAM = BiocParallel::bpparam(),
verbose = TRUE
)
})
## user system elapsed
## 18.403 0.615 19.021
The resulting model fits are now saved into the rowData
of our SummarizedExperiment object under the name
fitDTUModels
. These models can be accessed as follows:
rowData(sumExp)[["fitDTUModels"]]$"ENSMUST00000037739"
## An object of class "StatModel"
## Slot "type":
## [1] "glm"
##
## Slot "params":
## $coefficients
## designgroupALM.L5_IT_ALM_Tmem163_Dmrtb1
## 1.612656
## designgroupALM.L5_IT_ALM_Tnc
## 1.773648
## designgroupVISp.L5_IT_VISp_Hsd11b1_Endou
## 1.232522
##
## $df.residual
## [1] 55
##
## $dispersion
## [1] 28.14375
##
## $vcovUnsc
## designgroupALM.L5_IT_ALM_Tmem163_Dmrtb1
## designgroupALM.L5_IT_ALM_Tmem163_Dmrtb1 0.004760564
## designgroupALM.L5_IT_ALM_Tnc 0.000000000
## designgroupVISp.L5_IT_VISp_Hsd11b1_Endou 0.000000000
## designgroupALM.L5_IT_ALM_Tnc
## designgroupALM.L5_IT_ALM_Tmem163_Dmrtb1 0.000000000
## designgroupALM.L5_IT_ALM_Tnc 0.004363295
## designgroupVISp.L5_IT_VISp_Hsd11b1_Endou 0.000000000
## designgroupVISp.L5_IT_VISp_Hsd11b1_Endou
## designgroupALM.L5_IT_ALM_Tmem163_Dmrtb1 0.000000000
## designgroupALM.L5_IT_ALM_Tnc 0.000000000
## designgroupVISp.L5_IT_VISp_Hsd11b1_Endou 0.004042164
##
##
## Slot "varPosterior":
## [1] 27.73451
##
## Slot "dfPosterior":
## [1] 58.87993
The models are instances of the StatModel
class as
defined in the satuRn
package. These contain all relevant
information for the downstream analysis. For more details, read the
StatModel documentation with ?satuRn::StatModel-class
.
Here we test for differential transcript usage between select groups of interest. In this example, the groups of interest are the three different cell types that are present in the dataset associated with this vignette.
First, we set up a contrast matrix. This allows us to test for
differential transcript usage between groups of interest. The
group
factor in this toy example contains three levels; (1)
ALM.L5_IT_ALM_Tmem163_Dmrtb1, (2) ALM.L5_IT_ALM_Tnc, (3)
VISp.L5_IT_VISp_Hsd11b1_Endou. Here we show to assess DTU between cells
of the groups 1 and 3 and between cells of groups 2 and 3.
The contrast matrix can be constructed manually;
group <- as.factor(Tasic_metadata_vignette$group)
design <- model.matrix(~ 0 + group) # construct design matrix
colnames(design) <- levels(group)
L <- matrix(0, ncol = 2, nrow = ncol(design)) # initialize contrast matrix
rownames(L) <- colnames(design)
colnames(L) <- c("Contrast1", "Contrast2")
L[c("VISp.L5_IT_VISp_Hsd11b1_Endou","ALM.L5_IT_ALM_Tnc"),1] <-c(1,-1)
L[c("VISp.L5_IT_VISp_Hsd11b1_Endou","ALM.L5_IT_ALM_Tmem163_Dmrtb1"),2] <-c(1,-1)
L # contrast matrix
## Contrast1 Contrast2
## ALM.L5_IT_ALM_Tmem163_Dmrtb1 0 -1
## ALM.L5_IT_ALM_Tnc -1 0
## VISp.L5_IT_VISp_Hsd11b1_Endou 1 1
This can also be done automatically with the
makeContrasts
function of the limma
R
package.
group <- as.factor(Tasic_metadata_vignette$group)
design <- model.matrix(~ 0 + group) # construct design matrix
colnames(design) <- levels(group)
L <- limma::makeContrasts(
Contrast1 = VISp.L5_IT_VISp_Hsd11b1_Endou - ALM.L5_IT_ALM_Tnc,
Contrast2 = VISp.L5_IT_VISp_Hsd11b1_Endou - ALM.L5_IT_ALM_Tmem163_Dmrtb1,
levels = design
)
L # contrast matrix
## Contrasts
## Levels Contrast1 Contrast2
## ALM.L5_IT_ALM_Tmem163_Dmrtb1 0 -1
## ALM.L5_IT_ALM_Tnc -1 0
## VISp.L5_IT_VISp_Hsd11b1_Endou 1 1
Next we can perform differential usage testing using
testDTU
. We again adopt default settings. For more
information on the parameter settings, please consult the help file of
the testDTU
function. Note that the arguments
diagplot1
and diagplot2
were not yet
implemented in satuRn
v1.1.1.
sumExp <- satuRn::testDTU(
object = sumExp,
contrasts = L,
diagplot1 = TRUE,
diagplot2 = TRUE,
sort = FALSE
)