Code

    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 :

Code

    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.

Code

    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.

Code

    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.

Code

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

    ##           L     R         pw.id                        pw.name       pval
    ## 1    ADAM12  SDC4 R-HSA-3000170 REACTOME_SYNDECAN_INTERACTIONS 0.13442392
    ## 43     CCL5  SDC4 R-HSA-3000170 REACTOME_SYNDECAN_INTERACTIONS 0.38232159
    ## 57     CHAD ITGA2 R-HSA-3000170 REACTOME_SYNDECAN_INTERACTIONS 0.02113754
    ## 571    CHAD ITGA2 R-HSA-3000178     REACTOME_ECM_PROTEOGLYCANS 0.01808526
    ## 59  COL11A1 ITGA2 R-HSA-3000170 REACTOME_SYNDECAN_INTERACTIONS 0.14117500
    ## 591 COL11A1 ITGA2 R-HSA-3000178     REACTOME_ECM_PROTEOGLYCANS 0.12078918
    ##          qval  L.logFC  R.logFC    LR.pval LR.corr rank len rank.pval rank.corr
    ## 1   0.2063691 2.960116 1.034627 0.20004618       1    4   9 0.6755402         1
    ## 43  0.3907810 3.392849 1.034627 0.56896105       1    4   9 0.6755402         1
    ## 57  0.1355289 1.477644 1.385011 0.04512763       1    3   7 0.6219091         1
    ## 571 0.1314195 1.477644 1.385011 0.04512763       1    8  16 0.4996652         1
    ## 59  0.2107955 3.187252 1.385011 0.30140176       1    3   7 0.6219091         1
    ## 591 0.1965078 3.187252 1.385011 0.30140176       1    8  16 0.4996652         1
    ##      LR.score   L.expr   R.expr
    ## 1   0.1011691 1.967641 1.154262
    ## 43  0.1047028 2.235875 1.154262
    ## 57  0.1698102 6.317184 2.995667
    ## 571 0.1698102 6.317184 2.995667
    ## 59  0.1788653 8.555470 2.995667
    ## 591 0.1788653 8.555470 2.995667

## 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

Code

    sessionInfo()

    ## R version 4.5.0 RC (2025-04-04 r88126)
    ## Platform: x86_64-apple-darwin20
    ## Running under: macOS Monterey 12.7.6
    ##
    ## Matrix products: default
    ## BLAS:   /Library/Frameworks/R.framework/Versions/4.5-x86_64/Resources/lib/libRblas.0.dylib
    ## LAPACK: /Library/Frameworks/R.framework/Versions/4.5-x86_64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.1
    ##
    ## locale:
    ## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    ##
    ## time zone: America/New_York
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## other attached packages:
    ## [1] BulkSignalR_1.0.2
    ##
    ## loaded via a namespace (and not attached):
    ##   [1] RColorBrewer_1.1-3          jsonlite_2.0.0
    ##   [3] shape_1.4.6.1               magrittr_2.0.3
    ##   [5] magick_2.8.6                farver_2.1.2
    ##   [7] rmarkdown_2.29              GlobalOptions_0.1.2
    ##   [9] fs_1.6.6                    vctrs_0.6.5
    ##  [11] multtest_2.64.0             memoise_2.0.1
    ##  [13] RCurl_1.98-1.17             ggtree_3.16.0
    ##  [15] rstatix_0.7.2               htmltools_0.5.8.1
    ##  [17] S4Arrays_1.8.0              curl_6.2.2
    ##  [19] broom_1.0.8                 SparseArray_1.8.0
    ##  [21] Formula_1.2-5               gridGraphics_0.5-1
    ##  [23] sass_0.4.10                 bslib_0.9.0
    ##  [25] htmlwidgets_1.6.4           plotly_4.10.4
    ##  [27] cachem_1.1.0                igraph_2.1.4
    ##  [29] lifecycle_1.0.4             iterators_1.0.14
    ##  [31] pkgconfig_2.0.3             Matrix_1.7-3
    ##  [33] R6_2.6.1                    fastmap_1.2.0
    ##  [35] GenomeInfoDbData_1.2.14     MatrixGenerics_1.20.0
    ##  [37] clue_0.3-66                 digest_0.6.37
    ##  [39] aplot_0.2.5                 colorspace_2.1-1
    ##  [41] patchwork_1.3.0             S4Vectors_0.46.0
    ##  [43] grr_0.9.5                   GenomicRanges_1.60.0
    ##  [45] RSQLite_2.3.11              ggpubr_0.6.0
    ##  [47] filelock_1.0.3              httr_1.4.7
    ##  [49] abind_1.4-8                 compiler_4.5.0
    ##  [51] withr_3.0.2                 bit64_4.6.0-1
    ##  [53] doParallel_1.0.17           backports_1.5.0
    ##  [55] orthogene_1.14.0            carData_3.0-5
    ##  [57] DBI_1.2.3                   homologene_1.4.68.19.3.27
    ##  [59] ggsignif_0.6.4              MASS_7.3-65
    ##  [61] DelayedArray_0.34.1         rjson_0.2.23
    ##  [63] tools_4.5.0                 ape_5.8-1
    ##  [65] glue_1.8.0                  stabledist_0.7-2
    ##  [67] nlme_3.1-168                grid_4.5.0
    ##  [69] Rtsne_0.17                  cluster_2.1.8.1
    ##  [71] generics_0.1.4              gtable_0.3.6
    ##  [73] tidyr_1.3.1                 data.table_1.17.2
    ##  [75] car_3.1-3                   XVector_0.48.0
    ##  [77] BiocGenerics_0.54.0         ggrepel_0.9.6
    ##  [79] RANN_2.6.2                  foreach_1.5.2
    ##  [81] pillar_1.10.2               yulab.utils_0.2.0
    ##  [83] babelgene_22.9              circlize_0.4.16
    ##  [85] splines_4.5.0               dplyr_1.1.4
    ##  [87] BiocFileCache_2.16.0        treeio_1.32.0
    ##  [89] lattice_0.22-7              survival_3.8-3
    ##  [91] bit_4.6.0                   tidyselect_1.2.1
    ##  [93] ComplexHeatmap_2.24.0       SingleCellExperiment_1.30.1
    ##  [95] knitr_1.50                  gridExtra_2.3
    ##  [97] IRanges_2.42.0              SummarizedExperiment_1.38.1
    ##  [99] stats4_4.5.0                xfun_0.52
    ## [101] Biobase_2.68.0              matrixStats_1.5.0
    ## [103] UCSC.utils_1.4.0            lazyeval_0.2.2
    ## [105] ggfun_0.1.8                 yaml_2.3.10
    ## [107] evaluate_1.0.3              codetools_0.2-20
    ## [109] tibble_3.2.1                ggplotify_0.1.2
    ## [111] cli_3.6.5                   jquerylib_0.1.4
    ## [113] dichromat_2.0-0.1           Rcpp_1.0.14
    ## [115] GenomeInfoDb_1.44.0         dbplyr_2.5.0
    ## [117] gprofiler2_0.2.3            png_0.1-8
    ## [119] parallel_4.5.0              ggplot2_3.5.2
    ## [121] blob_1.2.4                  ggalluvial_0.12.5
    ## [123] bitops_1.0-9                glmnet_4.1-8
    ## [125] SpatialExperiment_1.18.1    viridisLite_0.4.2
    ## [127] tidytree_0.4.6              scales_1.4.0
    ## [129] purrr_1.0.4                 crayon_1.5.3
    ## [131] GetoptLong_1.0.5            rlang_1.1.6