nichenetr: predicting which ligands actually drive target genes

Ranking ligands by their downstream effect, not by receptor binding

Most computational approaches to cell-cell communication do one thing: they link ligands expressed by a sender cell to receptors expressed in a receiver cell. The project argues that this is only half the story, because understanding a communication process also requires knowing how such an interaction changes the expression of downstream target genes in the receiver. nichenetr, the R implementation of the NicheNet method, is built around that second question. Given expression data of interacting cells, it returns a ranking of ligands that best explain the communication event you are interested in, together with candidate target genes that could be regulated by those ligands. The audience is computational biologists who already have annotated expression data and want testable hypotheses rather than a catalogue of interactions. The method is described in a Nature Methods paper, and the project points to nichenetpy as the Python implementation of the same method.

The prior model is the part you can rebuild or replace

Everything NicheNet produces flows from a prior knowledge model. The project built that model by integrating three kinds of database: ligand-receptor interactions, signalling pathways, and transcription factor regulation. Merged together they form a communication network that spans from ligands all the way to downstream target genes, which is what lets the method reason about intracellular signalling and transcriptional regulation rather than stopping at the receptor. The consequence is that a single query can ask which ligands influence expression in another cell, which target genes each ligand affects, and which signalling mediators may sit in between. A pre-built prior model is provided, and the documentation also states that a user-defined model can be constructed, with validation of the prior ligand-target model listed among the main functionalities. The trade-off is that a pre-built model carries the assumptions of the databases it was assembled from, and rebuilding it is the documented path for anyone whose biology is not covered by them.

Three extracted features decide which ligands rank highest

Before the model runs, the workflow extracts three features from the input, and they are where most of the real decisions get made. The first is a list of potential ligands, drawn from the sender side of the communication event. The second is a gene set capturing the downstream effects of the event of interest, which encodes what changed in the receiver. The third is a background set of genes, which frames the comparison. The introductory vignette is where the documentation says the detail on each feature lives, and the workflow packages this step as an explicit extraction rather than hiding it inside a single call. That structure is deliberate. Because the ligand ranking is a ranking, the background and the gene set of interest effectively define what counts as an explanation, so two analysts with the same expression data and different background choices can get different ligand lists from the same model.

Installing the package from GitHub with devtools

The installation path is short. The project notes that installation typically takes a few minutes depending on how many dependencies are already on your machine, because nichenetr pulls in a chain of Bioconductor packages. The README first checks whether devtools is available and installs it if not, then installs nichenetr itself from GitHub:

devtools::install_github("saeyslab/nichenetr")

This is a source install rather than a binary one, so the wait is real and happens before any analysis. The documentation states that nichenetr was tested on both Windows and Linux, most recently tested with R 4.3.2. After the install, the vignettes are the intended entry point, and the project recommends starting with the step-by-step analysis. A full demo analysis is described as taking only a few minutes to run, which is a reasonable cost for a method that ranks ligands and predicts their targets.

Two vignettes cover the same Seurat workflow at two speeds

Learning the package happens through two vignettes. One is titled Perform NicheNet analysis starting from a Seurat object: step-by-step analysis, and the other is the shorter Perform NicheNet analysis starting from a Seurat object, which demonstrates the use of a single wrapper function. Both are ordinary R vignettes, opened from within R by naming the vignette and the package. The distinction matters in practice. The step-by-step path exposes the extraction of the ligand list, the gene set of interest and the background set, so a user can see and adjust them. The wrapper path hides those steps behind one call, which is faster to try and slower to debug. The project recommends the step-by-step route first and treats the wrapper as a shortcut, which is the right order for anyone planning to publish results.

The best practices workflow splits sender-agnostic from sender-focused

A separate protocol paper, published with a step-by-step workflow built over four years of use and user feedback, defines the approach the project now considers best practice. It describes two framings. The sender-agnostic approach considers ligands from the entire microenvironment, so any cell type in the data can act as a source. The sender-focused approach restricts the candidate ligands to cell populations of interest. The protocol also adds a downstream procedure for prioritising cell type-specific ligand-receptor pairs, which the core package does not claim to cover on its own. The code to reproduce the protocol and its figures is kept in a separate repository, nichenet_protocol. For a first analysis the simpler framing inside the vignettes is enough, but anyone aiming to defend a specific sender-receptor claim in a paper needs the protocol's stricter definitions, and that is where the two approaches can diverge in their conclusions.

Release tags stop in 2024 while the branch keeps moving

The version history needs care. The most recent tagged releases are v2.2.0 from 2024-09-05, v2.1.0 from 2024-05-03 and v2.0.5 from 2024-02-28, and the repository publishes a Zenodo DOI for the package. The last push to the default branch was on 2026-09-25, so the branch continues to receive work that the release tags do not reflect. The practical consequence for an R user is that devtools::install_github always takes the current branch, not the newest tag, so behaviour on your machine can differ from the published version number. The repository layout shows a standard Bioconductor-style package with DESCRIPTION, NAMESPACE, R/, man/, tests/, vignettes/ and inst/, plus a separate R-raw/ directory. Licensing is the other loose end: the repository has no licence identifier recorded, so teams that need redistribution terms should ask the maintainers directly rather than assume a default.

Editorial conclusion

nichenetr suits computational biologists who already work with annotated single-cell or bulk expression data and need ranked ligand hypotheses rather than bare interaction pairs. It is a poor fit if your cells are not annotated by type, since the method requires that annotation to define senders and receivers, and it is the wrong choice for a Python-only group unless you switch to the separate nichenetpy implementation. Before running it, check the three inputs it extracts, in particular the background gene set, because the documentation gives no default for it and the choice changes which ligands rank highest.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. saeyslab/nichenetr on GitHub