Ligand-Receptor Analysis

Overview

Ligand-receptor (LR) analysis in ScarfWeb identifies interactions between populations or clusters of cells. The platform uses liana-py with the rank_aggregate method. See the liana-py documentation for method details.

For help interpreting ranked interactions, see The biology in your ligand-receptor analysis, and how to read it.

Before You Start

Annotate your clusters first. Use Auto Annotation, CyteType, or manual labels. Interactions labelled T cells → B cells are far easier to interpret than Cluster 1 → Cluster 2. Not strictly required, but it makes downstream interpretation substantially clearer.

Getting Started

1. Open your dataset on the Explore page after running a standard analysis (cell filtering, HVG selection, UMAP, clustering).
2. Click LR analysis in the top bar to open the slideover panel.
3. Configure parameters on the LR analysis tab, then click Start analysis.
4. When the run finishes, open the Results tab.

Parameters

Primary Grouping

The categorical used to define source and target populations for LR inference. Typically a cell type or cluster annotation (e.g. Leiden clusters labelled with CyteType).

Select Cells

Optionally limit which cells are included. Cells outside the filter are excluded.

• All cells: uses all cells in the analysis. If some cells are hidden on the Explore page, this appears as All visible cells.
• Categorical: include only cells in selected categories of another metadata column (e.g. disease or control samples).
• Custom cell sets: use saved cell sets for more advanced filtering. Create these from Cell Sets & DGE. Learn more on selecting and saving cells: Cell Selections and Custom Categories.

Minimum Cells per Group

Minimum number of cells required for a group to be included. Groups below this threshold are excluded. Lower values retain sparse or rare populations but can increase noise.

Default: 5**

Expression Proportion

Minimum proportion of cells in a group that must express a ligand or receptor for it to count as expressed. Value from 0 to 1.

Default: 0.1 (10%)

Gene Symbols

Feature names must be gene symbols for matching against ligand-receptor databases. Confirm your features use official HGNC symbols (human: CD4, HAVCR2) or MGI symbols (mouse: Cd4, Havcr2), then check Yes, feature names are gene symbols.

Species

Select the species matching your gene symbols. Currently supported: Human and Mouse.

Results

When a run completes, open the Results tab. Each completed run appears as a separate entry with its parameters and timestamp.

From each result you can open:

• Results table: full interaction list with filtering and sorting
• Dot plot: visual summary of selected interactions

Results Table

💡 Treat magnitude rank and specificity rank like p-values. Lower is better for both.

Results are sorted by Magnitude rank ascending by default.

For additional columns and method details, see the liana rank_aggregate documentation.

Export: Download the filtered table as CSV.

LR Dot Plot

Visualises selected ligand-receptor pairs across chosen source and target groups. Use the sidebar to:

• Select up to 3 source clusters and 3 target clusters
• Choose top-ranked pairs or add specific pairs manually
• Adjust colour settings and plot labels

Dot size and colour reflect rank values for each source-target combination.

Export: Download the plot as PNG, SVG, or CSV.

Example Workflow

1. Upload a dataset and run a standard analysis (filtering, HVG selection, UMAP, clustering).
2. Label clusters using Auto Annotation, CyteType, or manual annotation.
3. Open Explore, then click LR analysis in the top bar.
4. Set Primary grouping to your cell type annotation.
5. Optionally use Select cells to restrict the analysis (e.g. disease samples only).
6. Adjust Minimum cells per group and Expression proportion if needed.
7. Confirm gene symbols and species, then click Start analysis.
8. When the run completes, open the Results tab to explore the table or dot plot.