diff --git a/DESCRIPTION b/DESCRIPTION index 3813984..c639091 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -5,7 +5,7 @@ Version: 2.0.0 Author: person("Robin", "Browaeys", email = "robin.browaeys@ugent.be", role = c("aut", "cre")) Maintainer: Robin Browaeys -Description: This package allows you the investigate differences in intercellular communication between multiple conditions of interest. It is a flexible framework that builds upon the NicheNet framework (https://github.com/saeyslab/nichenetr) to better suit scRNAseq datasets with complex designs. +Description: This package allows you the investigate differences in intercellular communication between multiple conditions of interest. It is a flexible framework that enables multi-criteria prioritization of cell-cell communication patterns from scRNAseq datasets with complex experimental designs. These datasets can contain multiple samples (e.g. patients) over different groups of interest (e.g. disease subtypes). With MultiNicheNet, you can now better analyze the differences in cell-cell signaling between the different groups of interest. License: GPL-3 + file LICENSE Encoding: UTF-8 diff --git a/README.Rmd b/README.Rmd index 005afda..ee46fe1 100644 --- a/README.Rmd +++ b/README.Rmd @@ -13,15 +13,17 @@ rmarkdown::render("README.Rmd",output_format = "md_document") # multinichenetr -[![R build status](https://github.com/browaeysrobin/multinichenetr/workflows/R-CMD-check-bioc/badge.svg)](https://github.com/browaeysrobin/multinichenetr/actions) -[![Coverage Status](https://codecov.io/gh/browaeysrobin/multinichenetr/branch/master/graph/badge.svg?token=0X627I4TM7)](https://codecov.io/gh/browaeysrobin/multinichenetr) +[![R build status](https://github.com/saeyslab/multinichenetr/workflows/R-CMD-check-bioc/badge.svg)](https://github.com/saeyslab/multinichenetr/actions) +[![Coverage Status](https://codecov.io/gh/saeyslab/multinichenetr/branch/master/graph/badge.svg?token=0X627I4TM7)](https://codecov.io/gh/saeyslab/multinichenetr) **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 -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 is more suited to tackle complex experimental designs such as those with multiple samples and conditions, and multiple receiver cell types of interest. +## Aim 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; 3) enables incorporation of complementary data types for prioritization of cell-cell interactions (e.g., proteomics).

![](vignettes/overview_figure.png) @@ -32,25 +34,47 @@ In the MultiNicheNet approach, we allow the user to prioritize differential cell * Upregulation of the ligand in a sender cell type and/or upregulation of the receptor in a receiver cell type - in the condition of interest. * Sufficiently high expression levels of ligand and receptor in many samples of the same group (to mitigate the influence of outlier samples). * Cell-type and condition specific expression of the ligand in the sender cell type and receptor in the receiver cell type (to mitigate the influence of upregulated but still relatively weakly expressed ligands/receptors) -* High NicheNet ligand activity, to further prioritize ligand-receptor pairs based on their predicted effect of the ligand-receptor interaction on the gene expression in the receiver cell type +* High NicheNet ligand activity, to further prioritize ligand-receptor pairs based on the enrichment of their predicted target genes in the receiver cell type -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. +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. -Users can customize the weights of these different factors to prioritize some of these criteria stronger, or neglect them altogether. +To summarize the main functionalities of multinichenetr: +* Prioritizing the most differential ligand-receptor interactions from different sender-receiver pairs between different sample groups, according to criteria such as condition specificity, cell-type specificity, ligand activity (= downstream signaling activity / target gene enrichement), and more. +* Predicting the specific downstream affected target genes of prioritized differential ligand-receptor links of interest. +* Predicting intercellular gene regulatory networks, connecting ligands to ligand- or receptor-encoding target genes in other cell types, enabling predictions concerning intercellular cascade and feedback mechanisms. -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. +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. -## Main functionalities of multinichenetr +# 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. + +* It is now possible to add new prioritization criteria based on additional data modalities. This option can helps users prioritize interactions better if they have additional complementary data, such as proteomics data. This option can help overcome major limitations of cell-cell communication inference from transcriptomics data. +* An additional alternative workflow has been added to prioritize interactions involving condition-specific cell types. This option was added to not ignore biological signal from potentially relevant condition-specifc cell types. +* More emphasis on the usability of the "Intercellular regulatory network" to prune prioritized interactions. +* Integration with the Omnipath L-R database to check database source, quality and curation effort behind prioritized ligand-receptor interactions. + +### Software changes -* Prioritizing the most important ligand-receptor interactions from different sender-receiver pairs between different sample groups, according to criteria such as condition specificity, cell-type specificity, ligand activity (= downstream signaling activity), and more. -* Finding differential expressed ligand-receptor interactions from different sender-receiver pairs between different sample groups (Differential Ligand-Receptor network inference). -* Predicting the most active ligand-receptor interactions in different sample groups based on predicted signaling effects (NicheNet ligand activity analysis). -* Predicting specific downstream affected target genes of ligand-receptor links of interest (NicheNet ligand-target inference). -* Predicting intercellular signaling networks, connecting ligands to ligand- or receptor-encoding target genes in other cell types, enabling predictions concerning intercellular cascade and feedback mechanisms. +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. -## Installation of multinichenetr +* Gene filtering has been modified slightly, resulting in fewer and easier to interpret parameters and more consistency with the rest of the MultiNicheNet methodology +* Prioritization can now be done by only using the up-regulatory ligand activities instead of both up- and downregulatory activities. This option was added because of the difficulty of interpreting downregulatory activities. +* The option to flexibly change prioritization weights has been replaced by the option to select biological scenario’s. This reduces the number of parameters for the end users and limits unwanted tunability of end results. +* The standard interpretable bubble plot visualization has been extended and provides now information about cell-type specificity, fraction of expression, and curation effort of the ligand-receptor pairs according to Omnipath. As a result of this, this plot now summarizes all the criteria used for prioritization and gives an indication about the curation effort of the ligand-receptor prior knowledge. This can help users now to get better insights in their results and define better candidate interactions for follow-up validation. + +### 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. + +# How to install multinichenetr? Installation typically takes a few minutes, depending on the number of dependencies that has already been installed on your pc. @@ -71,56 +95,48 @@ This warning can be safely ignored since this does not affect multinichenetr's i multinichenetr is tested via Github Actions version control on Windows, Linux (Ubuntu) and Mac (most recently tested R version: R 4.3.1.). -## Learning to use multinichenetr +# 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. We recommend users to start with the following vignette, which demonstrates the different steps in the analysis without too many details yet. This is the recommended vignette to learn the basics of MultiNicheNet. -TEST -TEST -TEST -TEST +* [MultiNicheNet - comprehensive tutorial - Condition A vs Condition B vs Condition C](vignettes/basic_analysis_steps_MISC.knit.md) | [__R Markdown version__](vignettes/basic_analysis_steps_MISC.Rmd) | [__HTML version__](vignettes/basic_analysis_steps_MISC.html) -* [MultiNicheNet analysis: MIS-C threewise comparison - step-by-step](vignettes/basic_analysis_steps_MISC.html): `vignette("basic_analysis_steps_MISC", package="multinichenetr")` -* [MultiNicheNet analysis: MIS-C threewise comparison - step-by-step](vignettes/basic_analysis_steps_MISC.knit.md): `vignette("basic_analysis_steps_MISC", package="multinichenetr")` +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. So we strongly recommend to read these vignettes to learn how to perform the analysis in other settings, but still perform all additional analyses and checks as demonstrated in the comprehensive vignette . -TEST -TEST -TEST -TEST +* [Condition A vs Condition B - without repeated subjects](vignettes/pairwise_analysis_MISC.knit.md) | [__R Markdown version__](vignettes/pairwise_analysis_MISC.Rmd) | [__HTML version__](vignettes/pairwise_analysis_MISC.html) +* [Condition A vs Condition B - with **repeated subjects**: paired analysis with subject_id as covariate](vignettes/paired_analysis_SCC.knit.md) | [__R Markdown version__](vignettes/paired_analysis_SCC.Rmd) | [__HTML version__](vignettes/paired_analysis_SCC.html) +* [Condition A vs Condition B - from integrated atlas data: correcting for **batch effects**](vignettes/batch_correction_analysis_LungAtlas.knit.md) | [__R Markdown version__](vignettes/batch_correction_analysis_LungAtlas.Rmd) | [__HTML version__](vignettes/batch_correction_analysis_LungAtlas.html) +* [**Multifactorial analysis**: condition-differences in cell-cell communication dynamics: (Time2_ConditionA - Time1_ConditionA) vs (Time2_ConditionB - Time1_ConditionB)](vignettes/multifactorial_analysis_BreastCancer.knit.md) | [__R Markdown version__](vignettes/multifactorial_analysis_BreastCancer.Rmd) | [__HTML version__](vignettes/multifactorial_analysis_BreastCancer.html) -This vignette provides an example of a comparison between 3 groups. The following vignettes demonstrate how to analyze cell-cell communication differences in other settings. For sake of simplicity, these vignettes also use a MultiNicheNet wrapper function, which encompasses the different steps demonstrated in the previous vignette. These vignettes are the best vignettes to learn how to apply MultiNicheNet to different datastes for addressing different questions. +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: -* [MultiNicheNet analysis: MIS-C pairwise comparison - wrapper function](vignettes/pairwise_analysis_MISC.md): `vignette("pairwise_analysis_MISC.Rmd", package="multinichenetr")` -* [MultiNicheNet analysis: MIS-C threewise comparison - wrapper function](vignettes/threewise_analysis_MISC.md): `vignette("threewise_analysis_MISC", package="multinichenetr")` -* [MultiNicheNet analysis: SCC paired analysis - wrapper function](vignettes/paired_analysis_SCC.md): `vignette("paired_analysis_SCC", package="multinichenetr")` -* [MultiNicheNet analysis: anti-PD1 Breast cancer multifactorial comparison - wrapper function](vignettes/multifactorial_analysis_BreastCancer.md): `vignette("multifactorial_analysis_BreastCancer", package="multinichenetr")` -* [MultiNicheNet analysis: Integrated lung atlas analysis - correct for batch effects to infer differences between IPF and healthy subjects - wrapper function](vignettes/batch_correction_analysis_LungAtlas.md): `vignette("batch_correction_analysis_LungAtlas", package="multinichenetr")` +* [Incorporating **additional prioritization criteria** based on **complementary data** types: serum **proteomics**](vignettes/add_proteomics_MISC.knit.md) | [__R Markdown version__](vignettes/add_proteomics_MISC.Rmd) | [__HTML version__](vignettes/add_proteomics_MISC.html) +* [Altnernative workflow to assess interactions involving **condition-specific cell types**](vignettes/condition_specific_celltype_MISC.knit.md) | [__R Markdown version__](vignettes/condition_specific_celltype_MISC.Rmd) | [__HTML version__](vignettes/condition_specific_celltype_MISC.html) -The next vignette will cover the different steps in more detail, showcasing some additional recommended quality checks and visualizations +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 run the core analysis on HPC infrastructure and save the output, and then 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. -* [MultiNicheNet analysis: MIS-C threewise comparison - step-by-step with all details](vignettes/detailed_analysis_steps_MISC.md): `vignette("detailed_analysis_steps_MISC", package="multinichenetr")` +* [MultiNicheNet core analysis on gridengine cluster via HPC](vignettes/multinichenet_qsub.Rmd) +* [Interpreting MultiNicheNet results locally](vignettes/multinichenet_intepretation.Rmd) -That vignettes checks as well for the DE analysis p-value distributions. In case these are suboptimal, pointing to violations to some model assumptions, we recommend to use empirical p-values as discussed in the Methods section of the paper and demonstrated in the following vignette: +## Guidelines for parameter changes and interpretation of output figures -* [MultiNicheNet analysis: anti-PD1 Breast cancer multifactorial comparison - step-by-step with all details](vignettes/detailed_analysis_steps_empirical_pvalues.md): `vignette("detailed_analysis_steps_empirical_pvalues", package="multinichenetr")` +To help users in interpreting parameter values and output figures, we provide the following two files: -When applying MultiNicheNet on datasets with many samples and cell types, it is recommended to run the analysis on HPC infrastructure.You can have a look at following scripts to see how we split up the analysis in two parts: 1) running MultiNicheNet and saving necessary output and plots; and 2) interpreting the results and generating visualizations. - -* [Running MultiNicheNet with qsub](vignettes/2-multinichenet_prism_final_MSA.Rmd) -* [Interpreting MultiNicheNet results locally](vignettes/3-multinichenet_interpretation_MSA_final.Rmd) +* [Parameter interpretation](parameter_interpretation.pdf): provides an explanation of different parameter choices - can help users in deciding when the default parameter values would not be optimal for their own dataset +* [Output figure interpretation](output_interpretation.pdf): provides an explanation of different output figures - can help users in drawing hypotheses based on the output figures ## Frequently recurring questions and issues -* Even though it is stated in the vignettes, many reported issues arise because names of celltypes, groups/conditions, and/or samples are not syntactically valid. Before reporting your issue, make sure you satisfy this condition and other conditions described in the vignettes. In the latest version of MultiNicheNet, input checks are run to check this and give an understandable error message. -* It is required that each sample is uniquely assigned to only one condition/group of interest. See the vignettes about paired and multifactorial analysis to see how to define your analysis input when you have multiple samples and conditions per patient. In the latest version of MultiNicheNet, input checks are run to check this and give an understandable error message. -* We strongly recommend having at least 4 samples in each of the groups/conditions you want to compare. With less samples, the benefits of performing a pseudobulk-based DE analysis are less clear and non-multi-sample tools for differential cell-cell communication might be better alternatives. +* The input data needed for MultiNicheNet should be raw counts, and metadata of cells giving information about the sample, condition and cell type. In all vignettes, we assume that the data has been preprocessed adequately (proper cell filtering, doublet removal, ambient RNA correction,...). +* We strongly recommend having at least 4 samples in each of the groups/conditions you want to compare. With less samples, the benefits of performing a pseudobulk-based DE analysis are less clear and non-multi-sample tools for differential cell-cell communication might be better alternatives. If you want to perform differential cell-cell communication with a MultiNicheNet-like prioritization framework, you can have a look at this vignette:[Differential cell-cell Communication for datasets with limited samples: "sample-agnostic/cell-level" MultiNicheNet](vignettes/basic_analysis_steps_MISC_SACL.knit.md). Just realize that the analysis is based on a limited number of samples, and it will be hard to draw strong conclusions. This may often be the best you can get out of your data, but it is not a practice we would recommend. + +# References -## 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. et al. MultiNicheNet: a flexible framework for differential cell-cell communication analysis from multi-sample multi-condition single-cell transcriptomics data. (preprint) +Browaeys, R., Saelens, W. & Saeys, Y. NicheNet: modeling intercellular communication by linking ligands to target genes. Nat Methods (2019) https://doi:10.1038/s41592-019-0667-5 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 -Browaeys, R., Saelens, W. & Saeys, Y. NicheNet: modeling intercellular communication by linking ligands to target genes. Nat Methods (2019) doi:10.1038/s41592-019-0667-5 diff --git a/README.md b/README.md index 27ae5aa..9cda936 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,9 @@ rmarkdown::render("README.Rmd",output_format = "md_document") [![R build -status](https://github.com/browaeysrobin/multinichenetr/workflows/R-CMD-check-bioc/badge.svg)](https://github.com/browaeysrobin/multinichenetr/actions) +status](https://github.com/saeyslab/multinichenetr/workflows/R-CMD-check-bioc/badge.svg)](https://github.com/saeyslab/multinichenetr/actions) [![Coverage -Status](https://codecov.io/gh/browaeysrobin/multinichenetr/branch/master/graph/badge.svg?token=0X627I4TM7)](https://codecov.io/gh/browaeysrobin/multinichenetr) +Status](https://codecov.io/gh/saeyslab/multinichenetr/branch/master/graph/badge.svg?token=0X627I4TM7)](https://codecov.io/gh/saeyslab/multinichenetr) **multinichenetr: the R package for differential cell-cell communication @@ -22,13 +22,18 @@ samples of interest (eg patients of different disease states). You can read all about MultiNicheNet in the following preprint: +## Aim 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 is more -suited to tackle complex experimental designs such as those with +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. +interest; 3) enables incorporation of complementary data types for +prioritization of cell-cell interactions (e.g., proteomics).

![](vignettes/overview_figure.png)

@@ -48,22 +53,33 @@ following criteria: the influence of upregulated but still relatively weakly expressed ligands/receptors) - High NicheNet ligand activity, to further prioritize ligand-receptor - pairs based on their predicted effect of the ligand-receptor - interaction on the gene expression in the receiver cell type + pairs based on the enrichment of their predicted target genes in the + receiver cell type 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. - -Users can customize the weights of these different factors to prioritize -some of these criteria stronger, or neglect them altogether. - -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 -(, +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: \* Prioritizing +the most differential ligand-receptor interactions from different +sender-receiver pairs between different sample groups, according to +criteria such as condition specificity, cell-type specificity, ligand +activity (= downstream signaling activity / target gene enrichement), +and more. \* Predicting the specific downstream affected target genes of +prioritized differential ligand-receptor links of interest. \* +Predicting intercellular gene regulatory networks, connecting ligands to +ligand- or receptor-encoding target genes in other cell types, enabling +predictions concerning intercellular cascade and feedback mechanisms. + +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 (, ). 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 @@ -78,28 +94,68 @@ 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. -## Main functionalities of multinichenetr - -- Prioritizing the most important ligand-receptor interactions from - different sender-receiver pairs between different sample groups, - according to criteria such as condition specificity, cell-type - specificity, ligand activity (= downstream signaling activity), and - more. -- Finding differential expressed ligand-receptor interactions from - different sender-receiver pairs between different sample groups - (Differential Ligand-Receptor network inference). -- Predicting the most active ligand-receptor interactions in different - sample groups based on predicted signaling effects (NicheNet ligand - activity analysis). -- Predicting specific downstream affected target genes of - ligand-receptor links of interest (NicheNet ligand-target - inference). -- Predicting intercellular signaling networks, connecting ligands to - ligand- or receptor-encoding target genes in other cell types, - enabling predictions concerning intercellular cascade and feedback - mechanisms. - -## Installation of multinichenetr +# 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. + +- It is now possible to add new prioritization criteria based on + additional data modalities. This option can helps users prioritize + interactions better if they have additional complementary data, such + as proteomics data. This option can help overcome major limitations + of cell-cell communication inference from transcriptomics data. +- An additional alternative workflow has been added to prioritize + interactions involving condition-specific cell types. This option + was added to not ignore biological signal from potentially relevant + condition-specifc cell types. +- More emphasis on the usability of the “Intercellular regulatory + network” to prune prioritized interactions. +- Integration with the Omnipath L-R database to check database source, + quality and curation effort behind prioritized ligand-receptor + interactions. + +### 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. + +- Gene filtering has been modified slightly, resulting in fewer and + easier to interpret parameters and more consistency with the rest of + the MultiNicheNet methodology +- Prioritization can now be done by only using the up-regulatory + ligand activities instead of both up- and downregulatory activities. + This option was added because of the difficulty of interpreting + downregulatory activities. +- The option to flexibly change prioritization weights has been + replaced by the option to select biological scenario’s. This reduces + the number of parameters for the end users and limits unwanted + tunability of end results. +- The standard interpretable bubble plot visualization has been + extended and provides now information about cell-type specificity, + fraction of expression, and curation effort of the ligand-receptor + pairs according to Omnipath. As a result of this, this plot now + summarizes all the criteria used for prioritization and gives an + indication about the curation effort of the ligand-receptor prior + knowledge. This can help users now to get better insights in their + results and define better candidate interactions for follow-up + validation. + +### 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. + +# How to install multinichenetr? Installation typically takes a few minutes, depending on the number of dependencies that has already been installed on your pc. @@ -121,7 +177,7 @@ 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.). -## Learning to use multinichenetr +# How to use multinichenetr? We provide several vignettes demonstrating the different types of analysis that can be performed with MultiNicheNet, and the several types @@ -132,103 +188,127 @@ demonstrates the different steps in the analysis without too many details yet. This is the recommended vignette to learn the basics of MultiNicheNet. -TEST TEST TEST TEST - -- [MultiNicheNet analysis: MIS-C threewise comparison - - step-by-step](vignettes/basic_analysis_steps_MISC.html): - `vignette("basic_analysis_steps_MISC", package="multinichenetr")` -- [MultiNicheNet analysis: MIS-C threewise comparison - - step-by-step](vignettes/basic_analysis_steps_MISC.knit.md): - `vignette("basic_analysis_steps_MISC", package="multinichenetr")` - -TEST TEST TEST TEST +- [MultiNicheNet - comprehensive tutorial - Condition A vs Condition B + vs Condition C](vignettes/basic_analysis_steps_MISC.knit.md) | [**R + Markdown version**](vignettes/basic_analysis_steps_MISC.Rmd) | + [**HTML version**](vignettes/basic_analysis_steps_MISC.html) -This vignette provides an example of a comparison between 3 groups. The +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. For sake of simplicity, these vignettes -also use a MultiNicheNet wrapper function, which encompasses the -different steps demonstrated in the previous vignette. These vignettes -are the best vignettes to learn how to apply MultiNicheNet to different -datastes for addressing different questions. - -- [MultiNicheNet analysis: MIS-C pairwise comparison - wrapper - function](vignettes/pairwise_analysis_MISC.md): - `vignette("pairwise_analysis_MISC.Rmd", package="multinichenetr")` -- [MultiNicheNet analysis: MIS-C threewise comparison - wrapper - function](vignettes/threewise_analysis_MISC.md): - `vignette("threewise_analysis_MISC", package="multinichenetr")` -- [MultiNicheNet analysis: SCC paired analysis - wrapper - function](vignettes/paired_analysis_SCC.md): - `vignette("paired_analysis_SCC", package="multinichenetr")` -- [MultiNicheNet analysis: anti-PD1 Breast cancer multifactorial - comparison - wrapper - function](vignettes/multifactorial_analysis_BreastCancer.md): - `vignette("multifactorial_analysis_BreastCancer", package="multinichenetr")` -- [MultiNicheNet analysis: Integrated lung atlas analysis - correct - for batch effects to infer differences between IPF and healthy - subjects - wrapper - function](vignettes/batch_correction_analysis_LungAtlas.md): - `vignette("batch_correction_analysis_LungAtlas", package="multinichenetr")` - -The next vignette will cover the different steps in more detail, -showcasing some additional recommended quality checks and visualizations - -- [MultiNicheNet analysis: MIS-C threewise comparison - step-by-step - with all details](vignettes/detailed_analysis_steps_MISC.md): - `vignette("detailed_analysis_steps_MISC", package="multinichenetr")` - -That vignettes checks as well for the DE analysis p-value distributions. -In case these are suboptimal, pointing to violations to some model -assumptions, we recommend to use empirical p-values as discussed in the -Methods section of the paper and demonstrated in the following vignette: - -- [MultiNicheNet analysis: anti-PD1 Breast cancer multifactorial - comparison - step-by-step with all - details](vignettes/detailed_analysis_steps_empirical_pvalues.md): - `vignette("detailed_analysis_steps_empirical_pvalues", package="multinichenetr")` +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. So we +strongly recommend to read these vignettes to learn how to perform the +analysis in other settings, but still perform all additional analyses +and checks as demonstrated in the comprehensive vignette . + +- [Condition A vs Condition B - without repeated + subjects](vignettes/pairwise_analysis_MISC.knit.md) | [**R Markdown + version**](vignettes/pairwise_analysis_MISC.Rmd) | [**HTML + version**](vignettes/pairwise_analysis_MISC.html) +- [Condition A vs Condition B - with **repeated subjects**: paired + analysis with subject\_id as + covariate](vignettes/paired_analysis_SCC.knit.md) | [**R Markdown + version**](vignettes/paired_analysis_SCC.Rmd) | [**HTML + version**](vignettes/paired_analysis_SCC.html) +- [Condition A vs Condition B - from integrated atlas data: correcting + for **batch + effects**](vignettes/batch_correction_analysis_LungAtlas.knit.md) | + [**R Markdown + version**](vignettes/batch_correction_analysis_LungAtlas.Rmd) | + [**HTML + version**](vignettes/batch_correction_analysis_LungAtlas.html) +- [**Multifactorial analysis**: condition-differences in cell-cell + communication dynamics: (Time2\_ConditionA - Time1\_ConditionA) vs + (Time2\_ConditionB - + Time1\_ConditionB)](vignettes/multifactorial_analysis_BreastCancer.knit.md) + | [**R Markdown + version**](vignettes/multifactorial_analysis_BreastCancer.Rmd) | + [**HTML + version**](vignettes/multifactorial_analysis_BreastCancer.html) + +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: + +- [Incorporating **additional prioritization criteria** based on + **complementary data** types: serum + **proteomics**](vignettes/add_proteomics_MISC.knit.md) | [**R + Markdown version**](vignettes/add_proteomics_MISC.Rmd) | [**HTML + version**](vignettes/add_proteomics_MISC.html) +- [Altnernative workflow to assess interactions involving + **condition-specific cell + types**](vignettes/condition_specific_celltype_MISC.knit.md) | [**R + Markdown version**](vignettes/condition_specific_celltype_MISC.Rmd) + | [**HTML + version**](vignettes/condition_specific_celltype_MISC.html) When applying MultiNicheNet on datasets with many samples and cell -types, it is recommended to run the analysis on HPC infrastructure.You -can have a look at following scripts to see how we split up the analysis -in two parts: 1) running MultiNicheNet and saving necessary output and -plots; and 2) interpreting the results and generating visualizations. - -- [Running MultiNicheNet with - qsub](vignettes/2-multinichenet_prism_final_MSA.Rmd) +types, it is often needed to run the analysis on HPC infrastructure. In +those cases, we recommend to first run the core analysis on HPC +infrastructure and save the output, and then 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. + +- [MultiNicheNet core analysis on gridengine cluster via + HPC](vignettes/multinichenet_qsub.Rmd) - [Interpreting MultiNicheNet results - locally](vignettes/3-multinichenet_interpretation_MSA_final.Rmd) + locally](vignettes/multinichenet_intepretation.Rmd) + +## 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: + +- [Parameter interpretation](parameter_interpretation.pdf): provides + an explanation of different parameter choices - can help users in + deciding when the default parameter values would not be optimal for + their own dataset +- [Output figure interpretation](output_interpretation.pdf): provides + an explanation of different output figures - can help users in + drawing hypotheses based on the output figures ## Frequently recurring questions and issues -- Even though it is stated in the vignettes, many reported issues - arise because names of celltypes, groups/conditions, and/or samples - are not syntactically valid. Before reporting your issue, make sure - you satisfy this condition and other conditions described in the - vignettes. In the latest version of MultiNicheNet, input checks are - run to check this and give an understandable error message. -- It is required that each sample is uniquely assigned to only one - condition/group of interest. See the vignettes about paired and - multifactorial analysis to see how to define your analysis input - when you have multiple samples and conditions per patient. In the - latest version of MultiNicheNet, input checks are run to check this - and give an understandable error message. +- The input data needed for MultiNicheNet should be raw counts, and + metadata of cells giving information about the sample, condition and + cell type. In all vignettes, we assume that the data has been + preprocessed adequately (proper cell filtering, doublet removal, + ambient RNA correction,…). - We strongly recommend having at least 4 samples in each of the groups/conditions you want to compare. With less samples, the benefits of performing a pseudobulk-based DE analysis are less clear and non-multi-sample tools for differential cell-cell communication - might be better alternatives. - -## References + might be better alternatives. If you want to perform differential + cell-cell communication with a MultiNicheNet-like prioritization + framework, you can have a look at this vignette:[Differential + cell-cell Communication for datasets with limited samples: + “sample-agnostic/cell-level” + MultiNicheNet](vignettes/basic_analysis_steps_MISC_SACL.knit.md). + Just realize that the analysis is based on a limited number of + samples, and it will be hard to draw strong conclusions. This may + often be the best you can get out of your data, but it is not a + practice we would recommend. + +# 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) +single-cell transcriptomics data. (preprint). + + +Browaeys, R., Saelens, W. & Saeys, Y. NicheNet: modeling intercellular +communication by linking ligands to target genes. Nat Methods (2019) +https://doi:10.1038/s41592-019-0667-5 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). - -Browaeys, R., Saelens, W. & Saeys, Y. NicheNet: modeling intercellular -communication by linking ligands to target genes. Nat Methods (2019) -