---
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)
```

## Differential mode 

`BulkSignalR` now allows the user to request different pairwise
comparisons from a large cohort of samples.  

In this mode, ligand-receptor interactions are inferred based on gene or protein
regulation-associated P-values when comparing two clusters of samples. 

The user must first perform a differential expression analysis 
(using the tool of his choice as DESeq2, EdgeR...) between a 
pair of sample clusters.


In the next chunk of code, we describe an application to 
Salivary Duct Carcinoma (SDC) samples where we compare two clusters 
of patients.  

We first create a **BSR-DataModel** object as follows : 

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

As an example here, 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)

# We then coerce the initial **BSRDataModel** object to 
# a **BSRDataModelComp** object. 

bsrdm.comp <- as(bsrdm, "BSRDataModelComp")


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

Three previously described S4 objects 
(BSR-DataModel, BSR-Inference, BSR-Signature) 
have been extented :  

\
    

* **BSR-DataModelComp**, denoted `bsrdm.comp` is an extension from 
**BSR-DataModel**, previously denoted `bsrdm`  
* **BSR-InferenceComp**, denoted `bsrinf.comp` is an extension from 
**BSR-Inference**, previously denoted `bsrinf` 
* **BSR-SignatureComp**, denoted `bsrsig.comp` is an extension from 
**BSR-Signature**, previously denoted `bsrsig` 

A new S4 object **BSR-ClusterComp** representing the comparison of two clusters
of samples to infer LR interactions based on the resulting P-values and
log-fold-changes (logFC) has been added.

This new desgin let us handle sample cluster comparisons.


`as.BSRDataModelComp` converts of **BSR-DataModel** into **BSR-DataModelComp** 
In case ligand-receptor inferences should be obtained
based on gene/protein regulation P-values comparing two clusters of
samples, it is necessary to first promote the **BSR-DataModel** object that
contains the count matrix into a **BSR-DataModelComp** object able to contain
a list of such cluster pairs comparisons. This function performs this
promotion, adding an empty list of comparisons.  

`BSRClusterComp` is used to define the comparison
between two clusters of samples
by using defined column indexes of the expression matrix
that belong to each cluster,
and storing the result of the cluster difference statistical analysis
obtained by an external tool such as edgeR, DESeq2, etc.

`addClusterComp` add a comparison between two clusters of samples 
to a **BSR-DataModelComp** object.

Several comparison can be defined and added sequentially.  

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

## Session Information

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