---
title: "SPAROscore: Getting Started"
package: "SPAROscore"
author: "Venkatesh Kamaraj"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{SPAROscore: Getting Started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r global-options, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 10,
  fig.height = 8, 
  out.width = "100%" 
)
```

```{r setup, warning=FALSE, message=FALSE}
# load the necessary libraries
library(SPAROscore)
library(airway)
library(ggplot2)
```

# What is SPAROscore?
SPAROscore is a gene signature scoring method designed to be 
robust across diverse gene expression datasets.
SPAROscore adapts to varying levels of sparsity, allowing signature scores to be 
efficiently computed across bulk, single-cell, 
and spatial transcriptomic datasets.

The resulting scores quantify the relative expression of a gene signature 
compared with the background expression of each sample/cell/domain, 
making the scores straightforward to interpret biologically.

Internally, SPAROscore ranks genes within each column and 
computes the Spearman footrule distance between the observed ranks of the 
signature genes and a background gene expression rank estimated from the 
geometric mean expression of the sample, cell, or spatial domain.


# How to use SPAROscore?
To use SPAROscore, at minimum, a gene expression dataset and
one or more gene signatures are required. 

To demonstrate this, we will use the gene expression matrix 
from the `airway` package, containing RNA-seq read counts from eight 
human airway smooth muscle (ASM) cell line samples: 
four treated with dexamethasone and four untreated controls.

As an example gene signature, we use the top differentially expressed genes 
reported in the [original study](https://doi.org/10.1371/journal.pone.0099625).

## Load the dataset

The expression matrix contains genes in rows and samples in columns. 
The accompanying metadata indicates whether each sample received dexamethasone 
treatment (trt) or served as an untreated control (untrt).
```{r load-dataset}
# load the airway dataset
data(airway)

# extract the gene expression matrix
counts_data <- assay(airway)

# extract the metadata
metadata <- as.data.frame(colData(airway))

# view sample level dexamethasone treatment status
metadata[, c("Run", "dex")]

# set the glucocorticoid response markers as the gene signature 
signature_genes <- c("ENSG00000112936", "ENSG00000170606", "ENSG00000120129", 
                     "ENSG00000152795", "ENSG00000211445", "ENSG00000163884",
                     "ENSG00000189221", "ENSG00000101347", "ENSG00000196136", 
                     "ENSG00000152583", "ENSG00000120658", "ENSG00000157514",
                     "ENSG00000103196", "ENSG00000179094", "ENSG00000152763",
                     "ENSG00000103310", "ENSG00000127954")

# check if the gene ids in the signature match with that of the counts_data
head(signature_genes %in% rownames(counts_data))
```

## Compute signature scores using SPAROscore
```{r compute-scores}
scores <- sparoscore(data = counts_data, signatures = signature_genes)

# view the scores
scores
```


## Visualise the results
Since dexamethasone activates glucocorticoid signalling, treated samples are 
expected to exhibit higher glucocorticoid response scores than untreated 
controls.
```{r visualise-results}
# add the signature scores to the metadata
metadata$SPAROscore <- scores[, 1]

# plot results
ggplot(metadata, aes(x = dex, y = SPAROscore, fill = dex)) +
    geom_boxplot(width = 0.6, outlier.shape = NA) +
    geom_jitter(width = 0.12, size = 3) +
    xlab("Treatment") +
    ylab("SPAROscore")+
    ggtitle("Glucocorticoid response signature activity")+
    theme_classic()
```


# What transcriptomics technologies can SPAROscore handle?
SPAROscore is a rank-based gene signature scoring method designed to provide 
robust signature scores across a wide range of transcriptomics technologies, 
adapting automatically to the differences in platform-specific
sequencing depth, expression sparsity, and technical variation.

As a result, the same scoring framework of SPAROscore can be applied 
consistently to bulk RNA sequencing, single-cell RNA sequencing, and spatial 
transcriptomics data without requiring platform-specific adjustments.

More information on how SPAROscore can be integrated into the analysis workflows
of different transcriptomics technologies can be found here: 
[Transcriptomics technologies](sparoscore_transcriptomics_technologies.html)

# What data structures can SPAROscore handle?
SPAROscore accepts a wide variety of commonly used data structures, including
dense matrices, sparse matrices, DelayedArray, SummarizedExperiment, 
SingleCellExperiment, SpatialExperiment, and Seurat objects.

When dealing with transcriptomics-specific data structures like Seurat objects
and SummarizedExperiment-derived objects, SPAROscore appends the scores to the 
existing metadata, to enhance further analyses.

SPAROscore can also handle multiple data structures for the gene signatures,
including character vector, list of character vectors, GeneSet objects and
GeneSetCollection objects, enabling single and multiple signature scoring.

More information on data structures and example codes can be found here:
[Data structures](sparoscore_data_structures.html)

# What are some advanced capabilities of SPAROscore?
By default, background gene expression is approximated using geometric mean 
expression values. This approximation can be overridden to accommodate 
biological contexts in which signature genes are expected to have lower 
expression. Users may provide custom background expression values to better 
reflect these conditions and tailor the scoring accordingly. 

Because gene ranking is the most computationally intensive step, SPAROscore 
supports storing gene rankings for reuse in future scoring analyses. 
This avoids redundant computations and substantially improves performance.

For examples of additional options and more advanced usage, see:
[Advanced options](sparoscore_advanced_options.html)


```{r session-info}
sessionInfo()
```