GitHub Open ScarfWeb

Ligand-Receptor Analysis

Infer ligand-receptor interactions between cell populations from your ScarfWeb analysis.

Ligand-receptor (LR) analysis

LR analysis in ScarfWeb identifies ligand-receptor 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.

Cluster annotation: Label your clusters before running LR analysis. You can do this with Auto Annotation, CyteType, manual labels, or any other annotation method. Cell type labels are especially useful because interactions such as T cells → B cells are much easier to interpret than Cluster 1 → Cluster 2.

Cluster annotations are not strictly required, but they make downstream interpretation much clearer.

Getting started

Steps

  1. Open your dataset on the Explore page after running a standard analysis (cell filtering, HVG selection, UMAP, clustering, and so on).
  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 to view the output.

Parameters

Primary grouping

The categorical used to define source and target populations for LR inference. This is usually a cell type or cluster annotation (for example, Leiden clusters labeled with CyteType).

Select cells

Optionally limit which cells are included in the analysis. Cells that do not match the filter are excluded.

  • All cells Uses all cells currently in the analysis. If some cells are hidden on the Explore page, the option appears as All visible cells, and hidden cells are excluded.
  • Categorical Include only cells in selected categories of another metadata column. For example, you might include only disease or control samples while still inferring interactions between the groups in your primary grouping (such as cell types).
  • Custom cell sets Use saved cell sets for more advanced filtering. Create cell sets from Cell Sets & DGE if you need a custom subset. See Cell Selections and Custom Categories for selecting and saving cells.

Minimum cells per group

Minimum number of cells required for a group to be included. Groups below this threshold are excluded.

Use lower values for small datasets or sparse clusters so rare populations are not dropped. Very low values 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 so they can be matched to ligand-receptor databases. Before starting the analysis, check Yes, feature names are gene symbols.

Confirm your features use official HGNC symbols (human, e.g. CD4, HAVCR2) or MGI symbols (mouse, e.g. Cd4, Havcr2).

Species

Select the species for 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 showing 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

The table includes these columns:

Column Description
Source Cell population expressing the ligand
Target Cell population expressing the receptor
Ligand complex Ligand gene symbol(s)
Receptor complex Receptor gene symbol(s). Multi-subunit receptors are joined with underscores, e.g. ITGA7_ITGB1
Magnitude rank Rank for expression strength. Lower values indicate stronger interactions. Treat both magnitude rank and specificity rank like p-values.
Specificity rank Rank for how specific the pair is to the source-target combination. Lower values indicate higher specificity

Results are sorted by Magnitude rank by default (ascending). Lower ranks are better for both magnitude and specificity.

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

Export: Download the filtered table as CSV.

LR dot plot

The dot plot visualizes 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 color settings and plot labels

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

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

Example workflow

Steps

  1. Upload a dataset and run a standard analysis (filtering, HVG selection, UMAP, clustering).
  2. Label clusters with cell types using Auto Annotation, CyteType, or manual annotation. (See the annotation and CyteType docs for details.)
  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 (for example, 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.

Related articles