v1.7.0 by dbdimitrov · Pull Request #225 · saezlab/liana-py

dbdimitrov · 2026-01-07T18:32:05Z

This pull request adds spatial proximity support to single-cell (typically dissociated) cell-cell communication inference methods, improving spatial analysis documentation, and updating dependencies.

The most significant changes include:

Inflow implementation and tutorial Feature/inflow score #221 by @AtheerAS
Global specificity calculation Feature/inflow score #221 by @AtheerAS
The integration of spatial proximity weighting ligand-receptor methods, new user-facing parameters for spatial analysis, and enhancements to the documentation to reflect these features. Spatial weighting for sc liana methods #222. The main cell-cell communication pipeline (liana_pipe) and scoring methods now support spatial proximity weighting. This includes new arguments (spatial_key, spatial_kwargs) and logic to compute and merge spatial proximity scores into LR (ligand-receptor) results, and to adjust permutation-based p-value calculations accordingly. (src/liana/method/sc/_liana_pipe.py)

Documentation and Usability Improvements:

Expanded docstrings and parameter documentation to cover new spatial analysis arguments, including detailed descriptions of spatial proximity options and kernel/bandwidth settings.
Updated the notebook index and documentation to reference new spatial analysis notebooks, such as inflow_score.ipynb.
Properly check if a passed (cell type) labels in plotting are a string Fix: Incorrect type check for labelsvariable in plotting module #220
Fixed an issue where MetalinksDB download would fail due to User-Agent restrictions.

Dependency and Version Updates:

Bumped the package version to 1.7.0 across configuration files, and updated version for decoupler.
Added Python 3.13 support in classifiers. change for python 3.13 needed? #216

…tmap plot function

Copilot

Pull request overview

This pull request introduces version 1.7.0 of LIANA, adding spatial proximity support to cell-cell communication inference methods, implementing new spatial analysis features (inflow and global specificity), and improving documentation.

Key changes:

Integration of spatial proximity weighting into existing ligand-receptor scoring methods with new spatial_key and spatial_kwargs parameters
Implementation of two new spatial methods: inflow for trivariate (source cell type, ligand, receptor) spatial metrics and compute_global_specificity for group-specific interaction analysis
Updated dependencies (decoupler>=1.7.0, cvxpy-base>=1.7.0) and added Python 3.13 support

Reviewed changes

Copilot reviewed 32 out of 34 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
src/liana/init.py	Version bump to 1.7.0
pyproject.toml	Version update, dependency updates (decoupler, cvxpy-base), Python 3.13 classifier
src/liana/utils/spatial_neighbors.py	Added `spatial_pair_proximity()` function and refactored kernel function logic
src/liana/utils/init.py	Export new `spatial_pair_proximity` function
src/liana/plotting/_feature_by_group.py	New plotting function for visualizing features by spatial groups
src/liana/plotting/_common.py	Fixed string type check from `labels is str` to `isinstance(labels, str)`
src/liana/plotting/init.py	Export new `feature_by_group` function
src/liana/method/sp/_utils.py	Added utility functions for MuData/AnnData processing and connectivity handling
src/liana/method/sp/_inflow.py	New inflow method implementation for trivariate spatial metrics
src/liana/method/sp/_compute_global_specificity.py	New method for computing group-specific LR means with permutation testing
src/liana/method/sp/_bivariate/_spatial_bivariate.py	Refactored to use shared utility functions from _utils.py
src/liana/method/sp/init.py	Export new `compute_global_specificity` and `inflow` methods
src/liana/method/sc/_rank_aggregate.py	Added `spatial_key` and `spatial_kwargs` parameters
src/liana/method/sc/_liana_pipe.py	Integrated spatial proximity calculation and weighting into main pipeline
src/liana/method/sc/_geometric_mean.py	Added proximity weighting support to geometric mean scoring
src/liana/method/sc/_cellphonedb.py	Added proximity weighting support to CellPhoneDB scoring
src/liana/method/sc/_cellchat.py	Added proximity weighting support to CellChat scoring
src/liana/method/sc/_Method.py	Added `spatial_key` and `spatial_kwargs` parameters to Method class
src/liana/method/_pipe_utils/_get_mean_perms.py	Added proximity weighting functions for permutation-based methods
src/liana/method/init.py	Export new spatial methods
src/liana/_docs.py	Added documentation strings for new spatial parameters
tests/test_transform_kwargs.py	Tests for transform kwargs with AnnData and MuData
tests/test_spatial_proximity.py	Tests for spatial proximity calculations and pipeline integration
tests/test_plotting.py	Test for new `feature_by_group` plotting function
tests/test_inflow.py	Comprehensive tests for inflow method
tests/test_compute_global_specificity.py	Tests for global specificity computation
tests/test_bivar.py	Comment formatting fix
docs/notebooks/index.md	Added reference to inflow_score.ipynb
docs/notebooks/basic_usage.ipynb	Added cell ID for markdown cell
docs/installation.md	New installation documentation
docs/index.md	Added installation.md to table of contents
CHANGELOG.md	Version 1.7.0 changelog entries
.bumpversion.cfg	Version update to 1.7.0

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-07T18:37:37Z

src/liana/method/sp/_inflow.py

+
+        xy_stats.rename(columns={xy_stats.columns[0]: 'gene'}, inplace=True)
+
+        # Merge these stats into the resource; TODO: add to .var?


The comment formatting is inconsistent. The comment should be '# NOTE: add to .var?' with a space after '#' and before 'NOTE'.

Suggested change

# Merge these stats into the resource; TODO: add to .var?

# Merge these stats into the resource

# NOTE: add to .var?

Copilot · 2026-01-07T18:37:37Z

src/liana/method/sp/_utils.py

+        Sparse connectivity matrix in CSR format with float32 dtype.
+    """
+    if connectivity_key not in adata.obsp.keys():
+        raise ValueError(f'No connectivity matrix found in adata.obsp[{connectivity_key}]')


The typo 'founds' should be 'found' in the error message.

Copilot · 2026-01-07T18:37:37Z

src/liana/method/sp/_inflow.py

+        An AnnData object of size (s* l * r *, n), where s correspodns to the cell types passed via the groupby parameter,
+        l and r are respectively the ligand and receptors expressed in the data and covered in the resource, and n is the
+        number of observations.


The docstring states the return value includes 's* l * r *, n' but uses inconsistent spacing and unclear notation. It should be written more clearly, such as '(n_cell_types * n_ligand_receptor_pairs, n_observations)' to match standard matrix dimension notation.

Suggested change

An AnnData object of size (s* l * r *, n), where s correspodns to the cell types passed via the groupby parameter,

l and r are respectively the ligand and receptors expressed in the data and covered in the resource, and n is the

number of observations.

An AnnData object of shape (n_cell_type_ligand_receptor_combinations, n_observations), where

n_cell_type_ligand_receptor_combinations corresponds to the combinations of cell types (as defined by the

``groupby`` parameter) with ligands and receptors expressed in the data and covered by the resource, and

n_observations is the number of observations.

Copilot · 2026-01-07T18:37:38Z

src/liana/method/sp/_compute_global_specificity.py

+
+    final_df = final_df.sort_values('pval', ascending=True)
+
+    #Save result


Missing space after comment marker. The comment should be '# Save result' with a space after '#'.

Suggested change

#Save result

# Save result

Copilot · 2026-01-07T18:37:38Z

tests/test_compute_global_specificity.py

@@ -0,0 +1,33 @@
+import pytest
+import scanpy


Unused import. The 'scanpy' module is imported at line 2 but never used in the test file. The tests use 'from scanpy.datasets import pbmc68k_reduced' directly within the test functions.

Suggested change

import scanpy

Copilot · 2026-01-07T18:37:39Z

src/liana/method/sp/_inflow.py

+                **kwargs
+            )
+
+        # NOTE There are some repetitiions with bivariate scores


The comment has a typo: 'repetitiions' should be 'repetitions'.

Suggested change

# NOTE There are some repetitiions with bivariate scores

# NOTE There are some repetitions with bivariate scores

Copilot · 2026-01-07T18:37:40Z

src/liana/method/sp/_compute_global_specificity.py

+    original_groupby_labels = adata.obs[groupby].astype('category')
+    groups_order = list(original_groupby_labels.cat.categories)
+
+    #Compute observed statistic


Missing space after comment marker. The comment should be '# Compute observed statistic' with a space after '#'.

Copilot · 2026-01-07T18:37:40Z

src/liana/method/sp/_compute_global_specificity.py

+        delayed(_get_group_mean)(X, rng_main.permutation(original_groupby_labels.values), var_names, groups_order=groups_order)
+        for _ in tqdm(range(n_perms), desc="Running permutations", disable=not verbose))
+
+    #Convert results to array


Missing space after comment marker. The comment should be '# Convert results to array' with a space after '#'.

Copilot · 2026-01-07T18:37:40Z

src/liana/plotting/_feature_by_group.py

@@ -0,0 +1,136 @@
+import anndata
+import matplotlib.pyplot as plt
+from matplotlib.gridspec import GridSpec


Import of 'GridSpec' is not used.

Suggested change

from matplotlib.gridspec import GridSpec

Copilot · 2026-01-07T18:37:40Z

src/liana/plotting/_feature_by_group.py

+from matplotlib.gridspec import GridSpec
+import numpy 
+import itertools
+from liana._constants import DefaultValues as V


Import of 'V' is not used.

Suggested change

from liana._constants import DefaultValues as V

Copilot

Pull request overview

Copilot reviewed 32 out of 34 changed files in this pull request and generated 15 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-07T18:46:26Z

src/liana/method/sp/_inflow.py

+
+        Returns
+        -------
+        An AnnData object of size (s* l * r *, n), where s correspodns to the cell types passed via the groupby parameter,


There's a typo in the docstring: 'correspodns' should be 'corresponds'.

Suggested change

An AnnData object of size (s* l * r *, n), where s correspodns to the cell types passed via the groupby parameter,

An AnnData object of size (s* l * r *, n), where s corresponds to the cell types passed via the groupby parameter,

Copilot · 2026-01-07T18:46:26Z

pyproject.toml

@@ -22,14 +22,14 @@ authors = [
  { name = "Jovan Tanevski"},
  { name = "Ricardo Omar Ramirez Flores"},
  { name = "Julio Saez-Rodriguez"},


An empty line was removed from the authors list. While this doesn't affect functionality, it changes the formatting. Ensure this is intentional and consistent with the project's style guide.

Suggested change

{ name = "Julio Saez-Rodriguez"},

{ name = "Julio Saez-Rodriguez"},

Copilot · 2026-01-07T18:46:27Z

src/liana/method/sc/_liana_pipe.py

+
+        proximity_df = spatial_pair_proximity(
+            adata=adata,
+            groupby='@label',


The spatial proximity is calculated using '@Label' as the groupby parameter, but this appears to be a placeholder or internal label. The function should use the actual 'groupby' parameter passed to liana_pipe. This could cause the proximity calculation to fail or use incorrect grouping.

Suggested change

groupby='@label',

groupby=groupby,

This is incorrect, I purposely set it to adata.obs['@label'] = adata.obs[groupby] -> you would have to also override it there..., the idea was that then I don't have to pass it multiple times through all functions...

Copilot · 2026-01-07T18:46:27Z

src/liana/method/_pipe_utils/_get_mean_perms.py

+        # Apply proximity weights to both observed and permuted if provided
+        if proximity_weights is not None:
+            # Weight permuted: (n_perms, n_interactions) * (n_interactions,)
+            # Broadcasting automatically handles dimension alignment
+            lr_perm_means = lr_perm_means * proximity_weights


In the permutation-based p-value calculation, proximity weights are applied to both observed and permuted scores. However, permuted scores represent null distributions where cell labels are shuffled. Applying the same spatial proximity weights to permuted data may not be statistically appropriate since the spatial relationships between cell types change after permutation. Consider whether proximity weights should only be applied to observed scores, or if the permutation scheme needs to account for spatial structure.

Suggested change

# Apply proximity weights to both observed and permuted if provided

if proximity_weights is not None:

# Weight permuted: (n_perms, n_interactions) * (n_interactions,)

# Broadcasting automatically handles dimension alignment

lr_perm_means = lr_perm_means * proximity_weights

# Note: proximity weights, if any, are expected to have been applied

# to the observed scores (lr_truth) upstream. We do not re-apply them

# to the permuted statistics here to avoid distorting the null

# distribution when spatial structure is part of the signal.

Copilot · 2026-01-07T18:46:28Z

src/liana/plotting/_feature_by_group.py

+import anndata
+import matplotlib.pyplot as plt
+from matplotlib.gridspec import GridSpec
+import numpy 


The import statement 'import numpy' should follow Python naming conventions and be imported as 'import numpy as np' for consistency with the rest of the codebase.

Suggested change

import numpy

import numpy as np

Copilot · 2026-01-07T18:46:30Z

tests/test_bivar.py


 ### Test on AnnData and LRs
- # NOTE: these should be the same regardless of the local function
+# NOTE: these should be the same regardless of the local function


The comment line is missing a space after the comment marker. Should be '# NOTE: these should be the same regardless of the local function' for consistency with Python style guidelines.

Copilot · 2026-01-07T18:46:30Z

src/liana/method/sc/_liana_pipe.py

+            verbose=verbose,
+            **spatial_kwargs
+        )
+        # Set interacting to 0 where not interacting


The spatial proximity is set to 0 for non-interacting pairs by multiplying with the 'interacting' flag. However, this happens before the merge, which means the raw proximity values (which could be very small but non-zero) are zeroed out based on the count threshold. This is correct behavior but should be documented in the spatial_pair_proximity function to clarify that proximity weights represent both distance-based proximity AND count-based significance.

Suggested change

# Set interacting to 0 where not interacting

# Mask distance-based proximity by the interaction flag.

# Note: this sets proximity to 0 for non-interacting pairs (according to the count/interaction

# threshold used inside spatial_pair_proximity), so the resulting "proximity" column reflects

# both spatial closeness AND interaction/count-based significance rather than pure distance.

Copilot · 2026-01-07T18:46:30Z

src/liana/plotting/_feature_by_group.py

+    adata: anndata.AnnData = None,
+    groupby: str = None,
+    spatial_key = K.spatial_key,
+    labels: list[str] = None, 


The docstring specifies 'labels: list[str]' but the parameter type hint uses the older syntax. For consistency with Python 3.10+ type hints used elsewhere in the file, consider using 'list[str] | None' in the type hint as well.

Suggested change

labels: list[str] = None,

labels: list[str] | None = None,

Copilot · 2026-01-07T18:46:31Z

src/liana/plotting/_feature_by_group.py

+
+        cell_type_data.append({
+            'label': label,
+            'coords': coords[mask.values],


Using 'mask.values' assumes mask is a pandas Series. However, if groupby column is not a pandas Series or if the boolean indexing returns a numpy array directly, this could fail. Consider using 'coords[mask]' directly or add a check for the mask type.

Suggested change

'coords': coords[mask.values],

'coords': coords[mask],

Copilot · 2026-01-07T18:46:31Z

tests/test_compute_global_specificity.py

@@ -0,0 +1,33 @@
+import pytest
+import scanpy


Import of 'scanpy' is not used.

Suggested change

import scanpy

dbdimitrov · 2026-01-07T18:47:54Z

@copilot open a new pull request to apply changes based on the comments in this thread

Copilot · 2026-01-07T18:48:03Z

@dbdimitrov I've opened a new pull request, #226, to work on those changes. Once the pull request is ready, I'll request review from you.

Co-authored-by: dbdimitrov <50865230+dbdimitrov@users.noreply.github.com>

…tion Co-authored-by: dbdimitrov <50865230+dbdimitrov@users.noreply.github.com>

Atheer Alsayah and others added 30 commits November 12, 2025 11:41

Add inflow script and related tutorial

09047ca

Update inflow dirs

546a47d

Update inflow score plots functions

e8e34ac

Update inflow plot functions

ef344cb

Update pplot function

08efd6b

fix ruff issues

b3d3819

add tests for inflow

fd81d1c

rename tut; pass obsm_key

35fb772

prelim mudata application

30d0231

update minor comments

3e788e5

add spatial weights

22b0456

move to correct folder..

93d6824

random tests

c8e0cef

Update global specificity function & inflow tutorial

918bda9

Update inflow-related functions

1347885

Update inflow-related plots functions

b3b7abf

Update functions

352dbbf

Add unittest for heatmap, update global specificity function, and hea…

2ddcee8

…tmap plot function

Update spatial_inflow plot function

7c04f89

Add inflow_spatial unittest

6d64019

unittest for global_specificity

d997f26

Inflow updates

9740b18

Update inflow-related functions

b2882f8

merge

ad98024

merge spatial weights

f31e55b

mask acc to filter

47a4ed3

add comment

2ba87d9

Update inflow.var operations: gini

da11dd9

drop gini metrics

1aa0d40

Update global specificity function - omit loops

21257b8

Atheer Alsayah and others added 15 commits December 5, 2025 13:51

add unittest for global spec

998a5e8

update compute specificity

dce5cb5

Update inflow score notebook

dfcc59b

Update inflow notebook

45a8fb7

add adata to mudata function

070683d

Update inflow score

fe80ec9

update tests

5221683

fix import issue

dab259f

Bump version: 1.6.1 → 1.7.0

50bea1c

add 3.13 to toml #216

a18b1f6

remove wrong imports

1066c1c

update tutorial

cdbcbbc

add some plots

e546f35

add installation

0b44e13

resolve #220

d98539f

dbdimitrov requested a review from Copilot January 7, 2026 18:32

Copilot started reviewing on behalf of dbdimitrov January 7, 2026 18:32 View session

Copilot AI reviewed Jan 7, 2026

View reviewed changes

update dependencies

7fe04a6

dbdimitrov requested a review from Copilot January 7, 2026 18:39

Copilot started reviewing on behalf of dbdimitrov January 7, 2026 18:39 View session

Copilot AI reviewed Jan 7, 2026

View reviewed changes

Initial plan

f897876

Copilot AI mentioned this pull request Jan 7, 2026

Address code review feedback: fix formatting, typos, and imports #226

Merged

Copilot AI and others added 3 commits January 7, 2026 18:56

Address code review comments: fix formatting, typos, and unused imports

5ab0b43

Co-authored-by: dbdimitrov <50865230+dbdimitrov@users.noreply.github.com>

Revert groupby parameter change - '@Label' is correct internal conven…

01381ba

…tion Co-authored-by: dbdimitrov <50865230+dbdimitrov@users.noreply.github.com>

ensure metalinksdb gets properly downloaded

59a3546

dbdimitrov merged commit 180c6d2 into main Jan 7, 2026
4 checks passed


		xy_stats.rename(columns={xy_stats.columns[0]: 'gene'}, inplace=True)

		# Merge these stats into the resource; TODO: add to .var?

	# Merge these stats into the resource; TODO: add to .var?
	# Merge these stats into the resource
	# NOTE: add to .var?

-        An AnnData object of size (s* l * r *, n), where s correspodns to the cell types passed via the groupby parameter,
-        l and r are respectively the ligand and receptors expressed in the data and covered in the resource, and n is the
-        number of observations.
+        An AnnData object of shape (n_cell_type_ligand_receptor_combinations, n_observations), where
+        n_cell_type_ligand_receptor_combinations corresponds to the combinations of cell types (as defined by the
+        ``groupby`` parameter) with ligands and receptors expressed in the data and covered by the resource, and
+        n_observations is the number of observations.


		final_df = final_df.sort_values('pval', ascending=True)

		#Save result

	# NOTE There are some repetitiions with bivariate scores
	# NOTE There are some repetitions with bivariate scores

	An AnnData object of size (s* l * r *, n), where s correspodns to the cell types passed via the groupby parameter,
	An AnnData object of size (s* l * r *, n), where s corresponds to the cell types passed via the groupby parameter,

	{ name = "Julio Saez-Rodriguez"},
	{ name = "Julio Saez-Rodriguez"},

-        # Set interacting to 0 where not interacting
+        # Mask distance-based proximity by the interaction flag.
+        # Note: this sets proximity to 0 for non-interacting pairs (according to the count/interaction
+        # threshold used inside spatial_pair_proximity), so the resulting "proximity" column reflects
+        # both spatial closeness AND interaction/count-based significance rather than pure distance.

Conversation

dbdimitrov commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

dbdimitrov Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

dbdimitrov commented Jan 7, 2026

Uh oh!

Copilot AI commented Jan 7, 2026

Uh oh!

dbdimitrov commented Jan 7, 2026 •

edited

Loading