Learn R Programming
⚠️There's a newer version (1.0.0) of this package.Take me there.

nichenetr

nichenetr: the R implementation of the NicheNet method. The goal of NicheNet is to study intercellular communication from a computational perspective. NicheNet uses human or mouse gene expression data of interacting cells as input and combines this with a prior model that integrates existing knowledge on ligand-to-target signaling paths. This allows to predict ligand-receptor interactions that might drive gene expression changes in cells of interest.

We describe the NicheNet algorithm in the following paper: NicheNet: modeling intercellular communication by linking ligands to target genes.

Bonnardel, T’Jonck et al. already used NicheNet to predict upstream niche signals driving Kupffer cell differentiation Stellate Cells, Hepatocytes, and Endothelial Cells Imprint the Kupffer Cell Identity on Monocytes Colonizing the Liver Macrophage Niche.

Important update!

Check the recently added FAQ page at FAQ NicheNet: vignette("faq", package="nichenetr")

Introduction to NicheNet

The figure below shows a graphical representation of the NicheNet workflow. Interactions inferred from several complementary ligand-receptor, signaling and gene regulatory data sources were aggregated in respective integrated networks from which ligand-target regulatory potential scores were calculated. This model of prior information on potential ligand-target links can then be used to infer active ligand-target links between interacting cells. NicheNet prioritizes ligands according to their activity (i.e., how well they predict observed changes in gene expression in the receiver cell) and looks for affected targets with high potential to be regulated by these prioritized ligands.

We offer the option to use the prebuilt prior model (such that the network integration steps should not be repeated), or to create and use your own prior model (see reference to detailed vignette below).

NicheNet strongly differs from most current computational approaches to study intercellular communication. Current approaches study intercellular communication from (single-cell) expression data by linking ligands expressed by sender cells to their corresponding receptors expressed by receiver cells. However, functional understanding of a cellular communication process also requires knowing how these inferred ligand-receptor interactions result in changes in the expression of downstream target genes within the receiver cells. To address this need, we developed NicheNet. Contrary to existing approaches, NicheNet looks at gene regulatory effects of ligands because the used prior knowledge goes beyond ligand-receptor interactions and incorporates intracellular signaling and transcriptional regulation as well. As a result, NicheNet allows to predict which ligands influence the expression in another cell, which target genes are affected by each ligand and which signaling mediators may be involved. By generating these novel types of hypotheses, NicheNet can drive an improved functional understanding of a cell-cell communication process of interest. The figure below summarizes the conceptual differences between most current ligand-receptor network inference approaches (top panel) and NicheNet (bottom panel) and visualizes the power of NicheNet in prioritizing ligand-receptor interactions based on gene expression effects.

Main functionalities of nichenetr

Specific functionalities of this package include:

  • assessing how well ligands expressed by a sender cell can predict changes in gene expression in the receiver cell
  • prioritizing ligands based on their effect on gene expression
  • inferring putative ligand-target links active in the system under study
  • inferring potential signaling paths between ligands and target genes of interest: to generate causal hypotheses and check which data sources support the predictions
  • validation of the prior ligand-target model
  • construction of user-defined prior ligand-target models

Moreover, we provide instructions on how to make intuitive visualizations of the main predictions (e.g., via circos plots as shown here below).

Installation of nichenetr

Installation typically takes a few minutes, depending on the number of dependencies that has already been installed on your pc. You can install nichenetr (and required dependencies) from github with:

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

nichenetr was tested on both Windows and Linux (most recently tested R version: R 4.0.0)

Learning to use nichenetr

To learn using nichenetr, read one of the following vignettes explaining several types of analyses:

Following vignette contains the explanation on how to perform a basic NicheNet analysis. This includes prioritizing ligands and predicting target genes of prioritized ligands. This demo analysis takes only a few minutes to run:

Following vignettes contain explanation on how to do some follow-up analyses after performing the most basic analysis:

To facilitate the use of NicheNet on single-cell data, we demonstrate the use of NicheNet on a Seurat object in following vignettes. One demonstrates the use of a single wrapper function, the other demonstrates what’s behind the wrapper (recommended).

People interested in building own models or benchmark own models against NicheNet can read one of the following vignettes:

People working with mouse data can see in the following vignette how to convert NicheNet’s ligand-target model (given in human symbols) to mouse symbols:

FAQ

Check the recently added FAQ page at FAQ NicheNet: vignette("faq", package="nichenetr")

References

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

Bonnardel et al. Stellate Cells, Hepatocytes, and Endothelial Cells Imprint the Kupffer Cell Identity on Monocytes Colonizing the Liver Macrophage Niche. Immunity (2019) doi:10.1016/j.immuni.2019.08.017

Copy Link

Version

Version

0.1.0

License

GPL-3

Issues

19

Pull Requests

2

Stars

535

Forks

124

Maintainer

Robin Browaeys

Last Published

August 26th, 2021

Functions in nichenetr (0.1.0)

assess_rf_class_probabilities

Assess probability that a target gene belongs to the geneset based on a multi-ligand random forest model
annotation_data_sources

Annotation table of all data sources used in the NicheNet model
add_hyperparameters_parameter_settings

Add hyperparameters to existing parameter settings
apply_hub_corrections

Apply hub corrections to the weighted integrated ligand-signaling and gene regulatory network
add_ligand_popularity_measures_to_perfs

Merge target gene prediction performances with popularity measures of ligands
calculate_fraction_top_predicted_fisher

Perform a Fisher's exact test to determine whether genes belonging to the gene set of interest are more likely to be part of the top-predicted targets.
classification_evaluation_continuous_pred_wrapper

Assess how well classification predictions accord to the expected response
construct_ligand_target_matrix

Construct a ligand-target probability matrix for ligands of interest.
construct_model

Construct a ligand-target model given input parameters.
construct_ligand_tf_matrix

Construct a ligand-tf signaling probability matrix for ligands of interest.
construct_tf_target_matrix

Construct a tf-target matrix.
get_lfc_celltype

Get log fold change values of genes in cell type of interest
convert_expression_settings_evaluation

Convert expression settings to correct settings format for evaluation of target gene prediction.
convert_cluster_to_settings

Convert cluster assignment to settings format suitable for target gene prediction.
assess_influence_source

Assess the influence of an individual data source on ligand-target probability scores
get_ligand_signaling_path

Get ligand-target signaling paths between ligand(s) and target gene(s) of interest
evaluate_importances_ligand_prediction

Evaluation of ligand activity prediction based on ligand importance scores.
convert_expression_settings_evaluation_regression

Convert expression settings to correct settings format for evaluation of target gene log fold change prediction (regression).
convert_gene_list_settings_evaluation

Convert gene list to correct settings format for evaluation of target gene prediction.
estimate_source_weights_characterization

Estimate data source weights of data sources of interest based on leave-one-in and leave-one-out characterization performances.
evaluate_model_application

Construct and evaluate a ligand-target model given input parameters (for application purposes).
convert_settings_ligand_prediction

Convert settings to correct settings format for ligand prediction.
convert_settings_topn_ligand_prediction

Converts expression settings to format in which the total number of potential ligands is reduced up to n top-predicted active ligands.
construct_random_model

Construct a randomised ligand-target model given input parameters.
get_multi_ligand_rf_importances_regression

Get ligand importances from a multi-ligand trained random forest regression model.
evaluate_model_application_multi_ligand

Construct and evaluate a ligand-target model given input parameters (for application purposes + multi-ligand predictive model).
convert_single_cell_expression_to_settings

Prepare single-cell expression data to perform ligand activity analysis
model_evaluation_optimization

Construct and evaluate a ligand-target model given input parameters with the purpose of parameter optimization.
model_evaluation_optimization_application

Construct and evaluate a ligand-target model given input parameters with the purpose of parameter optimization for multi-ligand application.
get_ncitations_genes

Get the number of times of gene is mentioned in the pubmed literature
evaluate_target_prediction_interprete

Evaluation of target gene prediction.
get_ligand_slope_ligand_prediction_popularity

Regression analysis between popularity of left-out ligands for ligand activity prediction performance
evaluate_target_prediction_per_bin

Evaluate target gene predictions for different bins/groups of targets genes
evaluate_ligand_prediction_per_bin

Evaluate ligand activity predictions for different bins/groups of targets genes
construct_weighted_networks

Construct weighted layer-specific networks
convert_human_to_mouse_symbols

Convert human gene symbols to their mouse one-to-one orthologs.
convert_mouse_to_human_symbols

Convert mouse gene symbols to their human one-to-one orthologs.
evaluate_single_importances_ligand_prediction

Evaluation of ligand activity prediction performance of single ligand importance scores: aggregate all datasets.
diagrammer_format_signaling_graph

Prepare extracted ligand-target signaling network for visualization with DiagrammeR.
correct_topology_ppr

Adapt a ligand-target probability matrix construced via PPR by correcting for network topolgoy.
optimized_source_weights_df

Optimized data source weights
evaluate_multi_ligand_target_prediction_regression

Evaluation of target gene value prediction for multiple ligands (regression).
convert_settings_tf_prediction

Convert settings to correct settings format for TF prediction.
evaluate_random_model

Construct and evaluate a randomised ligand-target model given input parameters.
evaluate_model

Construct and evaluate a ligand-target model given input parameters.
extract_ligands_from_settings

Extract ligands of interest from settings
expression_settings_validation

Expression datasets for validation
evaluate_target_prediction_regression

Evaluation of target gene value prediction (regression).
get_active_ligand_target_matrix

Get active ligand-target matrix.
extract_top_fraction_ligands

Get the predicted top n percentage ligands of a target of interest
get_active_regulatory_network

Get active gene regulatory network in a receiver cell.
evaluate_target_prediction

Evaluation of target gene prediction.
evaluate_multi_ligand_target_prediction

Evaluation of target gene prediction for multiple ligands.
get_multi_ligand_importances

Get ligand importances from a multi-ligand classfication model.
evaluate_model_cv

Construct and evaluate a ligand-target model given input parameters with the purpose of evaluating cross-validation models.
get_multi_ligand_importances_regression

Get ligand importances from a multi-ligand regression model.
get_multi_ligand_rf_importances

Get ligand importances from a multi-ligand trained random forest model.
predict_ligand_activities

Predict activities of ligands in regulating expression of a gene set of interest
gr_network

Gene regulatory network
get_single_ligand_importances

Get ligand importances based on target gene prediction performance of single ligands.
get_single_ligand_importances_regression

Get ligand importances based on target gene value prediction performance of single ligands (regression).
scaling_modified_zscore

Normalize values in a vector by the modified z-score method.
make_discrete_ligand_target_matrix

Convert probabilistic ligand-target matrix to a discrete one.
mlrmbo_optimization

Optimization of objective functions via model-based optimization.
scaling_zscore

Normalize values in a vector by the z-score method
hyperparameter_list

Optimized hyperparameter values
make_threecolor_heatmap_ggplot

Make a ggplot heatmap object from an input matrix (3-color).
predict_single_cell_ligand_activities

Single-cell ligand activity prediction
extract_top_fraction_targets

Get the predicted top n percentage target genes of a ligand of interest
lr_network

Ligand-receptor network
prepare_ligand_target_visualization

Prepare heatmap visualization of the ligand-target links starting from a ligand-target tibble.
ncitations

Number of citations for genes
process_mlrmbo_nichenet_optimization

Process the output of mlrmbo multi-objective optimization to extract optimal parameter values.
process_characterization_target_prediction_average

Process the output of model evaluation for data source characterization purposes on the target prediction performance (average)
geneinfo_human

Gene annotation information
extract_top_n_targets

Get the predicted top n target genes of a ligand of interest
get_active_signaling_network

Get active signaling network in a receiver cell.
get_active_ligand_receptor_network

Get active ligand-receptor network for cellular interaction between a sender and receiver cell.
get_expressed_genes

Determine expressed genes of a cell type from a Seurat object single-cell RNA seq dataset or Seurat spatial transcriptomics dataset
extract_top_n_ligands

Get the predicted top n ligands of a target gene of interest
infer_supporting_datasources

Get the data sources that support the specific interactions in the extracted ligand-target signaling subnetwork
get_slope_target_gene_popularity_ligand_prediction

Regression analysis between target gene popularity and ligand activity predictive performance
ligand_activity_performance_top_i_removed

Calculate ligand activity performance without considering evaluation datasets belonging to the top i most frequently cited ligands
get_top_predicted_genes

Find which genes were among the top-predicted targets genes in a specific cross-validation round and see whether these genes belong to the gene set of interest as well.
get_slope_ligand_popularity

Regression analysis between ligand popularity and target gene predictive performance
get_slope_target_gene_popularity

Regression analysis between target gene popularity and target gene predictive performance
get_weighted_ligand_target_links

Infer weighted active ligand-target links between a possible ligand and target genes of interest
get_active_ligand_target_df

Get active ligand-target network in data frame format.
nichenet_seuratobj_aggregate_cluster_de

Perform NicheNet analysis on Seurat object: explain DE between two cell clusters from separate conditions
get_target_genes_ligand_oi

Get a set of predicted target genes of a ligand of interest
make_heatmap_bidir_lt_ggplot

Make a ggplot heatmap object from an input ligand-target matrix.
nichenet_seuratobj_cluster_de

Perform NicheNet analysis on Seurat object: explain DE between two cell clusters
prepare_settings_leave_one_in_characterization

Prepare settings for leave-one-in characterization
prepare_settings_leave_one_out_characterization

Prepare settings for leave-one-out characterization
model_based_ligand_activity_prediction

Prediction of ligand activity prediction by a model trained on ligand importance scores.
make_heatmap_ggplot

Make a ggplot heatmap object from an input matrix (2-color).
nichenet_seuratobj_aggregate

Perform NicheNet analysis on Seurat object: explain DE between conditions
process_characterization_ligand_prediction

Process the output of model evaluation for data source characterization purposes on the ligand prediction performance
scale_quantile

Cut off outer quantiles and rescale to a [0, 1] range
prepare_settings_one_vs_one_characterization

Prepare settings for one-vs-one characterization
randomize_network

Randomize a network
nichenetr

nichenetr: Linking Extracellular Protein Signals to Target Genes by data-integration.
model_evaluation_hyperparameter_optimization

Construct and evaluate a ligand-target model given input parameters with the purpose of hyperparameter optimization.
randomize_complete_network_source_specific

Randomize an integrated network by shuffling its source networks
process_characterization_target_prediction

Process the output of model evaluation for data source characterization purposes on the target prediction performance
process_characterization_popularity_slopes_target_prediction

Process the output of model evaluation for data source characterization purposes on the popularity bias assessment of target prediction performance
single_ligand_activity_score_regression

Perform a correlation and regression analysis between cells' ligand activities and property scores of interest
randomize_datasource_network

Randomize a network of a particular data source.
source_weights_df

Data source weights
wrapper_evaluate_single_importances_ligand_prediction

Evaluation of ligand activity prediction performance of single ligand importance scores: each dataset individually.
wrapper_average_performances

Calculate average performance of datasets of a specific ligand.
process_characterization_popularity_slopes_ligand_prediction

Process the output of model evaluation for data source characterization purposes on the popularity bias assessment of ligand activity performance
single_ligand_activity_score_classification

Assess how well cells' ligand activities predict a binary property of interest of cells.
normalize_single_cell_ligand_activities

Normalize single-cell ligand activities
process_characterization_ligand_prediction_single_measures

Process the output of model evaluation for data source characterization purposes on the ligand prediction performance (for every importance score individually)
sig_network

Signaling network
add_new_datasource

Add a new data source to the model
calculate_fraction_top_predicted

Determine the fraction of genes belonging to the geneset or background and to the top-predicted genes.