Score-based approaches
Score-based methods facilitate direct comparisons of gene set
activity between phenotypic groups (e.g., being senescent) and
can be used in downstream analyses, including for example correlation
with other metadata variables of interest (e.g., day of
sequencing) . We first compute log2-median scores. In this dataset, the
HernandezSegura and LiteratureMarkers gene sets yield large effect sizes
(|Cohen’s d|), whereas REACTOME_CELLULAR_SENESCENCE shows more modest
separation between senescent and proliferative fibroblasts.
# Quantification approach: scores
# Method: log2-median
PlotScores(data = counts_example,
metadata = metadata_example,
gene_sets = genesets_example,
Variable="Condition",
method ="logmedian",
nrow = 1,
pointSize=4,
title="Marthandan et al. 2016",
widthTitle = 24,
labsize=12,
titlesize = 12)

Next, scores are calculated using multiple methods (log2-median,
ranking, ssGSEA) to assess consistency across strategies. Outputs
include heatmaps and volcano plots of effect sizes (|Cohen’s d|).
HernandezSegura and LiteratureMarkers consistently discriminate
Senescent from Proliferative samples, while REACTOME_CELLULAR_SENESCENCE
shows weaker and less consistent separation.
Overall_Scores <- PlotScores(data = counts_example,
metadata = metadata_example,
gene_sets=genesets_example,
Variable="Condition",
method ="all",
ncol = NULL,
nrow = 1,
widthTitle=30,
limits = c(0,3.5),
title="Marthandan et al. 2016",
titlesize = 10,
ColorValues = list(heatmap=c("#F9F4AE", "#B44141"),
volcano=signature_colors <- c(
HernandezSegura = "#A07395",
REACTOME_CELLULAR_SENESCENCE = "#6B8E9E",
LiteratureMarkers = "#CA7E45"
)
),
mode="simple",
widthlegend=30,
sig_threshold=0.05,
cohen_threshold=0.6,
pointSize=6,
colorPalette="Paired")


The discriminatory capacity of gene set scores can also be assessed
using ROC curves and corresponding AUC values. HernandezSegura and
LiteratureMarkers exhibit consistently high AUCs across scoring methods,
while REACTOME_CELLULAR_SENESCENCE shows more heterogeneous
performance.
ROC_Scores(data = counts_example,
metadata = metadata_example,
gene_sets=genesets_example,
method = "all",
variable ="Condition",
colors = c(logmedian = "#3E5587", ssGSEA = "#B65285", ranking = "#B68C52"),
grid = TRUE,
spacing_annotation=0.3,
ncol=NULL,
nrow=1,
mode = "simple",
widthTitle = 28,
titlesize = 10,
title="Marthandan et al. 2016")

Finally, false positive rates for effect sizes are estimated by
simulating random gene sets of equal size. This step provides a null
distribution against which observed scores can be compared. In this
example, the LiteratureMarkers signature demonstrates the strongest
performance. Increasing the number of simulations would yield finer
resolution at the cost of additional computational time.
set.seed("123456")
FPR_Simulation(data = counts_example,
metadata = metadata_example,
original_signatures = genesets_example,
gene_list = row.names(counts_example),
number_of_sims = 100,
title = "Marthandan et al. 2016",
widthTitle = 30,
Variable = "Condition",
titlesize = 12,
pointSize = 5,
labsize = 10,
mode = "simple",
ColorValues=NULL,
ncol=NULL,
nrow=1 )

Enrichment-based approaches
The first step is the quantification of differential expression.
Here, a design matrix (as defined by the limma package) is
automatically constructed from the Condition variable in
the metadata, defining the contrast
Senescent - Proliferative. Internally, this fits a linear
model without an intercept, enabling quick comparison between levels of
a categorical variable.
# Build design matrix from variables (Condition) and apply a contrast.
# The design matrix is constructed automatically using the variable "Condition".
DEGs <- calculateDE(data = counts_example,
metadata = metadata_example,
variables = "Condition",
contrasts = c("Senescent - Proliferative"))
DEGs$`Senescent-Proliferative`[1:5,]
## logFC AveExpr t P.Value adj.P.Val B
## CCND2 3.816674 4.406721 12.379571 2.944841e-15 2.349757e-12 24.64395
## MKI67 -3.581174 6.605339 -9.187514 2.110510e-11 4.769568e-10 15.91258
## PTCHD4 3.398914 3.556007 10.729126 2.461327e-13 2.868691e-11 20.30116
## KIF20A -3.365481 5.934893 -9.718104 4.406643e-12 1.771710e-10 17.45858
## CDC20 -3.304602 6.104079 -9.791031 3.562991e-12 1.592176e-10 17.66821
Differential expression results can be visualised with volcano plots.
These highlight the magnitude of expression changes (log2 fold change)
against statistical significance (adjusted p-value for the moderated
t-statistic), with genes from predefined sets emphasised (up- in green
and downregulated in red). In this example:
- Genes in the HernandezSegura set annotated as upregulated (green)
display positive log2 fold changes, whereas those annotated as
downregulated (red) show negative log2 fold changes. This pattern is
consistent with the annotation of the set, although these genes are not
necessarily those exhibiting the largest absolute fold changes.
- In the LiteratureMarkers set, LMNB1 and MKI67
exhibit strongly negative log2 fold change, consistent with their roles
as proliferation markers absent in senescent cells.
- Genes from the REACTOME_CELLULAR_SENESCENCE set are undirected and
appear across the full range of log2 fold change values, diluting
discriminatory power.
# Change order: gene sets in columns, contrast in rows
plotVolcano(DEGs, genes = genesets_example,
N = NULL,
x = "logFC", y = "-log10(adj.P.Val)", pointSize = 2,
color = "#6489B4", highlightcolor = "#05254A", highlightcolor_upreg = "#038C65", highlightcolor_downreg = "#8C0303",nointerestcolor = "#B7B7B7",
threshold_y = NULL, threshold_x = NULL,
xlab = NULL, ylab = NULL, ncol = NULL, nrow = NULL, title = "Marthandan et al. 2016",
labsize = 10, widthlabs = 24, invert = TRUE)

We next apply GSEA to the differential expression results. This
evaluates whether genes from each set are non-randomly concentrated at
the top or bottom of the ranked list. Results are reported as NES with
multiple-testing adjusted p-values. Gene ranking can be based on
alternative statistics (e.g., moderated t or B-statistic),
which influence whether results are interpreted as enrichment/depletion
or as altered directionality. For a full example and explanation, see
the online tutorial here.
GSEAresults <- runGSEA(DEGList = DEGs,
gene_sets = genesets_example,
stat = NULL,
ContrastCorrection = FALSE)
GSEAresults
## $`Senescent-Proliferative`
## pathway pval padj log2err ES
## <char> <num> <num> <num> <num>
## 1: HernandezSegura 7.942215e-10 2.382665e-09 0.8012156 0.6263553
## 2: REACTOME_CELLULAR_SENESCENCE 1.575684e-02 2.363525e-02 0.1151671 0.3687292
## 3: LiteratureMarkers 2.571070e-02 2.571070e-02 0.1295475 0.6948634
## NES size leadingEdge stat_used
## <num> <int> <list> <char>
## 1: 2.639526 52 CNTLN,DYNLT3,SLC10A3,CCND1,TOLLIP,DDA1,...[37] t
## 2: 1.450470 128 H1-2,H2BC4,H2BC5,H4C15,IGFBP7,H2BC12,...[31] B
## 3: 1.648484 7 LMNB1,MKI67,GLB1,CDKN1A,CDKN2A,CCL2 t
Enrichment curves from fgsea show the running enrichment
score across the ranked list, indicating the distribution of set members
therein.
plotGSEAenrichment(GSEA_results=GSEAresults,
DEGList=DEGs,
gene_sets=genesets_example,
widthTitle=40, grid = TRUE, titlesize = 10, nrow=1, ncol=3)

Enrichment results can also be summarised with a lollipop plot, which
compactly shows the NES and highlights statistically significant gene
sets. Here, we can see that the HernandezSegura gene set clearly
exhibits the strongest enrichment signal. When many gene sets and
contrasts are evaluated (which is not the case in this vignette), NES
and adjusted p-values can be summarized in a scatter (volcano-style)
plot for a simpler visualisation, using
plotCombinedGSEA.
plotNESlollipop(GSEA_results=GSEAresults,
saturation_value=NULL,
nonsignif_color = "#F4F4F4",
signif_color = "red",
sig_threshold = 0.05,
grid = FALSE,
nrow = NULL, ncol = NULL,
widthlabels=13,
title=NULL, titlesize=12)
## $`Senescent-Proliferative`

From this exercise in Benchmarking Mode, we can see that two gene
sets clearly perform best at discriminating between Senescent and
Proliferative conditions: HernandezSegura and LiteratureMarkers. The
REACTOME_CELLULAR_SENESCENCE gene set does not show a strong signal; the
absense of information on putative gene up- or downregulation upon
phenotype potentially dilutes the signal, highlighting the importance of
providing directionality when available.
Scoring and enrichment approaches provide complementary insights.
Score-based methods offer sample-level resolution, capturing strong
contributions from individual genes, while enrichment-based methods
evaluate coordinated behaviour across the set.