---
title: "BulkSignalR : </br> Inference of ligand-receptor interactions 
from bulk data or spatial transcriptomics"
author:
  - name: Jean-Philippe Villemin
    affiliation:
    - Institut de Recherche en Cancérologie de Montpellier,
     Inserm, Montpellier, France 
    email: jean-philippe.villemin@inserm.fr
  - name: Jacques Colinge
    affiliation:
    - Institut de Recherche en Cancérologie de Montpellier,
     Inserm, Montpellier, France 
    email: jacques.colinge@inserm.fr
date: "`r format(Sys.Date(), '%m/%d/%Y')`"
output: 
  rmarkdown::html_vignette:
      self_contained: true
      toc: true
      toc_depth: 4
      highlight: pygments
      fig_height: 3
      fig_width: 3
      fig_caption: no
      code_folding: show
package: BulkSignalR
vignette: >
  %\VignetteIndexEntry{BulkSignalR-Differential}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::knit_hooks$set(optipng = knitr::hook_optipng)
options(rmarkdown.html_vignette.check_title = FALSE)
```
```{r load-libs, message = FALSE,  warning = FALSE, results = FALSE}
library(BulkSignalR)
```

## Cluster-based differential analysis

By default, `BulkSignalR` inference of L-R interactions relies on correlation
analysis across all the samples. That is, a putative L-R interaction is assessed
for coherent expression of the ligand, the receptor, and target genes in a
pathway below receptor across all the samples.

Alternatively, it is possible to define sample clusters based on an independent
analysis (outside of `BulkSignalR`) to group similar samples. Based on cluster
definitions, it is for instance possible to assess whether L-R interactions are
significantly stronger in a cluster compared to all the samples, to all the
samples but the chosen cluster, or in comparison with another cluster.
In practice, the user must simply provide a table of differential gene or
protein expression analysis that is relevant for the selected comparison.

In this mode, L-R interactions are inferred based on gene or protein
regulation-associated P-values instead of P-values resulting from the
correlation analysis in the default mode. As already stated, differential
P-value estimations are left to the user to compute. With bulk data, commonly
used libraries such as `DESeq2`, `EdgeR`, or `limma` constitute obvious options.

In the next chunk of code, we illustrate the differential mode using 
Salivary Duct Carcinoma (SDC) samples where we compare two clusters 
of patients.  

We first create a **BSRDataModelComp** object as follows:

```{r diffmode1,eval=TRUE}
data(sdc, package = "BulkSignalR")
normal <- grep("^N", names(sdc))
bsrdm.comp <- BSRDataModelComp(sdc[, -normal])
```

To make a very small example we generate random values,
but user should provide his own logFC and
associated pvalues from DGE ouputs.  

```{r diffmode2,eval=TRUE}
colA <- as.integer(1:3)
colB <- as.integer(12:15)

n <- nrow(ncounts(bsrdm.comp))
stats <- data.frame(pval = runif(n),
logFC = rnorm(n, 0, 2),
expr = runif(n, 0, 10))
rownames(stats) <- rownames(ncounts(bsrdm.comp))
```    

We define the cluster comparison and add it.  

```{r diffmode3,eval=TRUE}

bsrcc <- BSRClusterComp(bsrdm.comp, colA, colB, stats)
bsrdm.comp <- addClusterComp(bsrdm.comp, bsrcc, "random.example")

```

Finally we infer ligand-receptor interactions from the comparison. 
We use a subset of the reference to speed up inference 
in the context of the vignette.

```{r diffmode4,eval=TRUE}

subset <- c("REACTOME_BASIGIN_INTERACTIONS",
"REACTOME_SYNDECAN_INTERACTIONS",
"REACTOME_ECM_PROTEOGLYCANS",
"REACTOME_CELL_JUNCTION_ORGANIZATION")

reactSubset <- BulkSignalR:::.SignalR$BulkSignalR_Reactome[
BulkSignalR:::.SignalR$BulkSignalR_Reactome$`Reactome name` %in% subset,]

resetPathways(dataframe = reactSubset,
resourceName = "Reactome")

bsrinf.comp <- BSRInferenceComp(bsrdm.comp,
reference="REACTOME",
max.pval = 1, 
"random.example")

head(LRinter(bsrinf.comp))

```  

\

##  Technical notes

The three basic `BulkSignalR` S4 classes 
BSRDataModel, BSRInference, and BSRSignature 
were derived into new classes to add the functionalities required by the
differential mode:  

* **BSRDataModelComp**, denoted here as `bsrdm.comp` is a daughter class of 
**BSRDataModel**, previously denoted `bsrdm`  
* **BSRInferenceComp**, denoted here as `bsrinf.comp` is a daughter class of
**BSRInference**, previously denoted `bsrinf` 
* **BSRSignatureComp**, denoted here as `bsrsig.comp` is a daughter class of 
**BSRSignature**, previously denoted `bsrsig` 

The new S4 class **BSRClusterComp** is meant to represent the comparison
between two clusters of samples. It primarily contains the results of the
user-provided differential analysis in a table containing gene/protein names,
P-values, and log-fold-changes (logFC).

Usually, we recommend instantiating a `BSRDataModel` object to contain the
expression matrix underlying the differential analysis. Then, it is
promoted into a `BSRDataModelComp` object such that cluster definitions
and comparisons can be added to it. This can be for instance done with
``as(bsrdm, "BSRDataModelComp")``. The `addClusterComp` method
of a `BSRDataModelComp` object allows adding one or several comparisons between
clusters, each added comparison being defined in a `BSRClusterComp` object.

\
    
Thank you for reading this guide and for using `BulkSignalR`.  

\

## Session Information

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