spatial-communication

Spatial communication

When to use

Infer ligand-receptor interactions between annotated populations. LIANA is the default; CellPhoneDB and FastCCC need a local CellPhoneDB database. CellChat runs in an R subprocess. These methods do not constrain interactions by spatial distance: coordinates support the CLI maps, not the inference.

API

Use load_skill("spatial-communication") in an analysis step. examples/example_step.py uses real PBMC expression with explicitly synthetic coordinates. The CLI demo uses synthetic expression and is not biological evidence.

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

communicate(adata, *, method='liana', cell_type_key='leiden', species='human', random_state=None, **parameters)

Infer ligand-receptor interactions and return the same AnnData.

LIANA uses raw when present, otherwise X. Other backends read normalized X. Coordinates support CLI maps; these methods do not impose distance filters.

:param adata: Log-normalized expression with cell-type labels; modified in place. :param method: CLI default liana; cellphonedb, fastccc or cellchat_r also supported. :param cell_type_key: CLI default leiden; obs column defining populations. :param species: CLI default human; mouse supported by LIANA and CellChat. :param random_state: None keeps LIANA seed 1337 and CellChat seed 1; CellPhoneDB uses 0. :param parameters: Native backend keywords in references/parameters.md. :returns: The same AnnData with canonical ccc_results and role summaries in uns. :raises ValueError: Method, labels, species or numeric controls are invalid. :raises ImportError: Optional backend is missing; use install_skill_deps. :raises FileNotFoundError: CellPhoneDB/FastCCC's local database is missing.

interactions(adata, *, significant_only=False)

Return ligand-receptor scores; unmeasured p values remain missing.

:param adata: AnnData returned by communicate. :param significant_only: Default False; True selects real p values below 0.05. :returns: A new DataFrame with ligand, receptor, source, target, score and pvalue. :raises ValueError: No run is recorded.

run_info(adata, *, keep=True)

Read the last run's diagnostics and optional backend tables.

:param adata: AnnData returned by communicate. :param keep: Default True; False removes transient diagnostics for CLI serialization. :returns: Summary dictionary including tested/significant counts and extra_tables. :raises ValueError: No communication run is recorded.

roles_figure(adata, *, n_top=20)

Plot population sender and receiver scores without file writes.

:param adata: AnnData returned by communicate. :param n_top: Default 20 populations; use fewer for a smaller figure. :returns: A matplotlib Figure, explicitly labelled when no scores exist. :raises ValueError: No run is recorded or n_top is not positive.

<!-- api:end -->

Key CLI

python skills/spatial/spatial-communication/spatial_communication.py \
  --input processed.h5ad --output results/communication \
  --cell-type-key cell_type --method liana --liana-n-perms 1000
python skills/spatial/spatial-communication/spatial_communication.py \
  --demo --output /tmp/communication_demo

Inputs & Outputs

Input is log-normalized AnnData with at least two populations in obs[cell_type_key] (default leiden). LIANA reads raw when present; other methods read X. Use gene symbols, not synthetic feature identifiers. LIANA and CellChat support human and mouse; the other wrappers support human.

The API mutates and returns the same object, preserving observation and feature order. It stores uns["ccc_results"], method-specific results, communication_summary, communication_signaling_roles, and diagnostics. interactions returns a new DataFrame; roles_figure returns a Figure. Library calls do not create report directories. Optional external tools use temporary files that are removed after execution.

The CLI writes processed.h5ad, report.md, result.json, reproducibility commands, figure-data CSVs, and conditional tables/figures. See output inventory for exact conditions.

Gotchas

• _api.py:communicate rejects absent labels and populations with fewer than two distinct labels; it does not substitute a different annotation.
• uns["ccc_results"] has missing p values when the backend supplies no statistical test. LIANA specificity ranks are not p values.
• tables/lr_interactions.csv is absent when no interactions are returned; an empty result does not establish absence of biological communication.
• _api.py:communicate raises an install hint for missing backends. CellPhoneDB/FastCCC also require a local database; no substitute is generated.
• rscripts/cellchat.R needs Rscript, Matrix and CellChat, not rpy2.
• _api.py:communicate defaults to LIANA seed 1337, CellPhoneDB 0 and CellChat 1; FastCCC has no seed argument.

References

• Parameters: CLI-to-library keyword mapping.
• Methodology: matrix and statistical semantics.
• Output contract: files and AnnData keys.

Dependencies

anndata, cellphonedb, fastccc, liana, matplotlib, numpy, pandas, scanpy, scipy, seaborn, CellChat, Matrix

The R backend requires an Rscript executable.