Home

Awesome

<!-- README.md is generated from README.Rmd. Please edit that file --> <!-- github markdown built using rmarkdown::render("README.Rmd",output_format = "md_document") -->

multinichenetr

<!-- badges: start -->

R build
status Coverage
Status

<!-- badges: end -->

multinichenetr: the R package for differential cell-cell communication analysis from single-cell transcriptomics data with complex multi-sample, multi-condition designs. The goal of this toolbox is to study differences in intercellular communication between groups of samples of interest (eg patients of different disease states).

You can read all about MultiNicheNet in the following preprint: https://www.biorxiv.org/content/10.1101/2023.06.13.544751v1

Aims of MultiNicheNet

The main goal of the MultiNicheNet package is to find which ligand-receptor interactions are differentially expressed and differentially active between conditions of interest, such as patient groups. Compared to the normal NicheNet workflow, MultiNicheNet 1) considers more information to prioritize interactions (differential and cell-type specific expression in addition to ligand activity); 2) is more suited to tackle complex experimental designs such as those with multiple samples and conditions, and multiple receiver cell types of interest; and 3) enables incorporation of complementary data types for prioritization of cell-cell interactions (e.g., proteomics).

<br><br> <br><br>

In the MultiNicheNet approach, we allow the user to prioritize differential cell-cell communication events (ligand-receptor interactions and downstream signaling to target genes) based on the following criteria:

MultiNicheNet combines all these criteria in a single prioritization score, which is also comparable between all sender-receiver pairs. This way, MultiNicheNet extends on the prioritization done by NicheNet, which is only based on the ligand activity score. Importantly, this prioritization framework is flexible and extendable: it is possible to design an additional criterion based on complementary data such as serum proteomics.

To summarize the main functionalities of multinichenetr:

Note: at the basis of MultiNicheNet for defining differentially expressed ligands, receptors and target genes, is the the differential state analysis as discussed by muscat, which provides a framework for cell-level mixed models or methods based on aggregated “pseudobulk” data (https://doi.org/10.1038/s41467-020-19894-4, https://bioconductor.org/packages/release/bioc/html/muscat.html). We use this muscat framework to make inferences on the sample-level (as wanted in a multi-sample, multi-condition setting) and not the classic cell-level differential expression analysis of Seurat (Seurat::FindMarkers), because muscat allows us to overcome some of the limitations of cell-level analyses for differential state analyses. Some of these limitations include: a bias towards samples with more cells of cell type, a lack of flexibility to work with complex study designs, and a too optimistic estimation of the statistical power since the analysis is done at the cell-level and not at the sample level.

In the future, we might extend the differential expression analyses options to include other frameworks than muscat.

IMPORTANT UPDATE MAY 2024: multinichenetr 2.0.0.

Since May 13 2024, we have put out multinichenetr 2.0.0. on the main branch. Please install this latest version of multinichenetr, which has been improved at several levels compared to the first version:

Novelties

Here is a concise list of methodological novelties compared to the previous version. See the tutorials for more in-depth explanation on each of these aspects. These novelties will also be discussed in the revised version of the manuscript.

Software changes

Here is a concise list of software changes compared to the previous version. See the tutorials for more in-depth explanation on each of these aspects.

Notes

Call for feedback

multinichenetr is in ongoing development. We always appreciate it if you let us know how we can improve the software/documentation/algorithm/output visualizations further. The best way to do this is through the issues page: https://github.com/saeyslab/multinichenetr/issues

How to install multinichenetr?

Installation typically takes a few minutes, depending on the number of dependencies that has already been installed on your pc.

You can install multinichenetr (and required dependencies) from github with:

# install.packages("devtools")
devtools::install_github("saeyslab/nichenetr")
devtools::install_github("saeyslab/multinichenetr")

It is possible that during installation the following warning is thrown:

“glmmTMB was built with TMB version 1.9.4” “Current TMB version is 1.9.5

This warning can be safely ignored since this does not affect multinichenetr’s installation and functionalities.

multinichenetr is tested via Github Actions version control on Windows, Linux (Ubuntu) and Mac (most recently tested R version: R 4.3.1.).

How to use multinichenetr?

We provide several vignettes demonstrating the different types of analysis that can be performed with MultiNicheNet, and the several types of downstream visualizations that can be created.

Tutorials

We recommend users to start with the following vignette, which demonstrates the different steps in the analysis and exploration of the output. This is the recommended vignette to learn MultiNicheNet.

That vignette provides an example of a comparison between 3 groups. The following vignettes demonstrate how to analyze cell-cell communication differences in other settings. These vignettes are the best vignettes to learn how to apply MultiNicheNet to different datastes for addressing different questions. To reduce the length of these vignettes, the sections on downstream analysis has been reduced strongly and a wrapper function is sometimes used to perform the core analysis. So we strongly recommend to read these vignettes to learn how to perform the analysis in different settings, but still perform all additional analyses and checks as demonstrated in the comprehensive tutorial vignette.

In addition to these vignettes, we also provide 2 other vignettes showcasing the flexibility and extendibility of the MultiNicheNet framework: how to include additional complementary data modalities and assess condition-specific cell types:

When applying MultiNicheNet on datasets with many samples and cell types, it is often needed to run the analysis on HPC infrastructure. In those cases, we recommend to first set up your pipeline locally on a subset of the data (eg subset of 2/3 cell types). Then we recommend to run the core analysis on HPC infrastructure and save the output, and finally interpret this output locally. In the following scripts you can see an example of how we split up the analysis in two parts: 1) running MultiNicheNet (with qsub on gridengine cluster) and saving necessary output and plots; and 2) interpreting the results and generating visualizations. These scripts are illustrative and will not work directly when you would just run them.

Guidelines for parameter changes and interpretation of output figures

To help users in interpreting parameter values and output figures, we provide the following two files:

Frequently recurring questions and issues

References

Browaeys, R. et al. MultiNicheNet: a flexible framework for differential cell-cell communication analysis from multi-sample multi-condition single-cell transcriptomics data. (preprint). https://www.biorxiv.org/content/10.1101/2023.06.13.544751v1

Browaeys, R., Saelens, W. & Saeys, Y. NicheNet: modeling intercellular communication by linking ligands to target genes. Nat Methods (2019) <a href="https://doi:10.1038/s41592-019-0667-5" class="uri">https://doi:10.1038/s41592-019-0667-5</a>

Crowell, H.L., Soneson, C., Germain, PL. et al. muscat detects subpopulation-specific state transitions from multi-sample multi-condition single-cell transcriptomics data. Nat Commun 11, 6077 (2020). https://doi.org/10.1038/s41467-020-19894-4