spatial-transcriptomics-analysis-squidpy
Squidpy spatial statistics on annotated spatial transcriptomics: build the spatial graph (Visium grid, kNN, radius, Delaunay), neighbourhood enrichment z-scores, distance-resolved co-occurrence, interaction matrix and centrality scores, Ripley's L/F/G point patterns, spatially variable genes by Moran's I / Geary's C, and permutation ligand-receptor tests (ligrec, OmniPath). Works on Visium spots and single-cell-resolution data (Xenium, MERFISH, CosMx, Slide-seq). Needs cluster or cell type labels for all but the spatially variable gene step. For an end-to-end ligand-receptor workflow use spatial-transcriptomics-cell-cell-communication.
- License 许可
- CC-BY-4.0
- 最近更新
- 2026-11-15
- Stars
- ★ 6
- Forks
- 0
01 前言 Front Matter
- name
- spatial-transcriptomics-analysis-squidpy
- license
- CC-BY-4.0
- description
- Squidpy spatial statistics on annotated spatial transcriptomics: build the spatial graph (Visium grid, kNN, radius, Delaunay), neighbourhood enrichment z-scores, distance-resolved co-occurrence, interaction matrix and centrality scores, Ripley's L/F/G point patterns, spatially variable genes by Moran's I / Geary's C, and permutation ligand-receptor tests (ligrec, OmniPath). Works on Visium spots and single-cell-resolution data (Xenium, MERFISH, CosMx, Slide-seq). Needs cluster or cell type labels for all but the spatially variable gene step. For an end-to-end ligand-receptor workflow use spatial-transcriptomics-cell-cell-communication.
03 SKILL.md 正文
Squidpy Spatial Analysis
Overview
Graph and point-pattern statistics that describe how cell types (or spot clusters) are arranged in tissue and which genes follow a spatial pattern. Each Core API module answers one question and exports a CSV:
| Question | Module |
|---|---|
| Which cell types sit next to each other more than chance? | 2 Neighbourhood enrichment |
| At what distance do two types co-occur? | 3 Co-occurrence |
| How many contacts between types; which types are central? | 4 Interaction matrix + centrality |
| Is a type clustered, random or dispersed? | 5 Ripley's statistics |
| Which genes are spatially patterned? | 6 Spatial autocorrelation |
| Which LR pairs are specific to a cluster pair? | 7 Ligand-receptor test |
When to Use
- Testing which cell types are neighbours more or less often than chance
- Measuring the distance range over which two cell types stay together
- Deciding whether a cell type is clustered, random or evenly dispersed in tissue
- Finding spatially variable genes by Moran's I or Geary's C
- Running a quick permutation ligand-receptor test between labels
- Use
spatial-transcriptomics-cell-cell-communicationinstead for a multi-method LIANA ligand-receptor ranking with a spatial adjacency filter - For tissue regions without labels, use
spatial-domain-detectionfirst; for cell labels usespatial-transcriptomics-cell-type-annotation
Prerequisites
- Input: AnnData with
obsm["spatial"]and log-normalisedX - Labels: a categorical column in
obs(cell types for single-cell data; spot clusters or domains for Visium - spots are mixtures, so read results as region-level) - Network: Module 7 downloads OmniPath interactions
- Versions: squidpy >= 1.6.
sq.gr.spatial_neighborsis deprecated from 1.7 in favour ofspatial_neighbors_knn/_radius/_delaunay/_grid; it still works through 1.8
# Install only what `import` reports missing. `--pypi` keeps the env's scanpy/numba
# stack; a conda add can swap it and bare pip can shadow it.
pixi add --pypi squidpy omnipath scanpy
pixi add --pypi liana # only for the local-LR-list recipe
Quick Start
import scanpy as sc
import squidpy as sq
adata = sc.read_h5ad("celltype_annotated.h5ad")
adata.obs["cell_type"] = adata.obs["cell_type"].astype("category")
sq.gr.spatial_neighbors(adata, coord_type="generic", n_neighs=10) # Visium: coord_type="grid", n_rings=1
sq.gr.nhood_enrichment(adata, cluster_key="cell_type", n_perms=1000, seed=0)
sq.pl.nhood_enrichment(adata, cluster_key="cell_type", save="nhood_quick.png")
Core API
Module 1: Build the Spatial Graph
All graph-based modules (2, 4, 6) read obsp["spatial_connectivities"].
import numpy as np
import pandas as pd
import scanpy as sc
import squidpy as sq
import matplotlib.pyplot as plt
adata = sc.read_h5ad("celltype_annotated.h5ad")
CLUSTER_KEY = "cell_type"
adata.obs[CLUSTER_KEY] = adata.obs[CLUSTER_KEY].astype("category")
cats = adata.obs[CLUSTER_KEY].cat.categories
PLATFORM = "single_cell" # "visium" for Visium spots
if PLATFORM == "visium":
sq.gr.spatial_neighbors(adata, coord_type="grid", n_neighs=6, n_rings=1) # hexagonal ring
else:
sq.gr.spatial_neighbors(adata, coord_type="generic", n_neighs=10)
# alternatives: delaunay=True (natural neighbours) or radius=30 (same units as coordinates)
deg = np.asarray(adata.obsp["spatial_connectivities"].sum(1)).ravel()
print(f"{adata.n_obs} nodes, median degree {np.median(deg):.0f}, isolated {(deg == 0).sum()}")
Module 2: Neighbourhood Enrichment
Permutation test of how often two labels are neighbours versus shuffled labels:
sq.gr.nhood_enrichment(adata, cluster_key=CLUSTER_KEY, n_perms=1000, seed=0)
z = pd.DataFrame(adata.uns[f"{CLUSTER_KEY}_nhood_enrichment"]["zscore"], index=cats, columns=cats)
z.to_csv("nhood_enrichment_z.csv")
sq.pl.nhood_enrichment(adata, cluster_key=CLUSTER_KEY, method="average", figsize=(8, 8),
save="nhood_enrichment.png")
pairs = z.where(np.triu(np.ones(z.shape, bool), k=1)).stack().sort_values()
print("most co-located:\n", pairs.tail(8).round(1))
print("most avoiding:\n", pairs.head(8).round(1))
z > 2: neighbours more often than chance; z < -2: avoid each other. The diagonal measures self-clustering.
Module 3: Co-occurrence Across Distances
Ratio of P(type B | within distance d of type A) to P(type B). Memory grows with cell count squared, so subsample large data:
MAX_CELLS = 20000
sub = adata if adata.n_obs <= MAX_CELLS else sc.pp.subsample(adata, n_obs=MAX_CELLS, random_state=0, copy=True)
occ, interval = sq.gr.co_occurrence(sub, cluster_key=CLUSTER_KEY, interval=50, copy=True)
# occ: n_clusters x n_clusters x n_distances; distance bins = interval[1:]
dist = interval[1:] if len(interval) == occ.shape[2] + 1 else interval
sub_cats = sub.obs[CLUSTER_KEY].cat.categories
rows = [(a, b, d, occ[i, j, k]) for i, a in enumerate(sub_cats) for j, b in enumerate(sub_cats)
for k, d in enumerate(dist)]
co = pd.DataFrame(rows, columns=["anchor", "other", "distance", "ratio"])
co.to_csv("co_occurrence.csv", index=False)
ANCHOR = sub_cats[0] # set to the cell type of interest
sq.pl.co_occurrence(sub, cluster_key=CLUSTER_KEY, clusters=[ANCHOR], figsize=(8, 4),
save="co_occurrence.png")
Ratio > 1 at short distance = attraction; the distance where it returns to 1
is the spatial range of the association. Older squidpy versions also take
n_splits to reduce memory.
Module 4: Interaction Matrix and Centrality
im = sq.gr.interaction_matrix(adata, cluster_key=CLUSTER_KEY, normalized=True, copy=True)
im = pd.DataFrame(im, index=cats, columns=cats) # row-normalised share of each type's edges
im.to_csv("interaction_matrix.csv")
sq.pl.interaction_matrix(adata, cluster_key=CLUSTER_KEY, save="interaction_matrix.png") # recomputes uns if needed
cent = sq.gr.centrality_scores(adata, cluster_key=CLUSTER_KEY, copy=True)
cent.to_csv("centrality_scores.csv")
print(cent.sort_values("closeness_centrality", ascending=False).round(3))
The interaction matrix counts raw contacts (dominated by abundant types);
use Module 2 for enrichment over chance. Centrality: degree_centrality = share
of graph connections, closeness_centrality = how central a type is in the
tissue graph, average_clustering = how tightly its cells group.
Module 5: Ripley's Statistics
MODE = "L" # "L" clustering scale, "G" nearest-neighbour, "F" empty space
rip = sq.gr.ripley(adata, cluster_key=CLUSTER_KEY, mode=MODE, n_simulations=100, seed=0, copy=True)
stat = rip[f"{MODE}_stat"] # columns: bins, <cluster_key>, stats
stat.to_csv(f"ripley_{MODE}.csv", index=False)
fig, ax = plt.subplots(figsize=(8, 5))
for ct, d in stat.groupby(CLUSTER_KEY, observed=True):
ax.plot(d["bins"], d["stats"], label=ct)
band = rip["sims_stat"].groupby("bins")["stats"] # columns: bins, simulations, stats
lo, hi = band.min(), band.max()
ax.fill_between(lo.index, lo, hi, color="grey", alpha=0.3, label="random (simulated)")
ax.set_xlabel("distance"); ax.set_ylabel(f"Ripley's {MODE}"); ax.legend(fontsize=7)
plt.tight_layout(); plt.savefig(f"ripley_{MODE}.png", dpi=150); plt.close()
For L, a curve above the simulated band = clustered at that distance, below =
dispersed (regular). rip["pvalues"] (cluster x bin) tests each curve
against the simulations.
Module 6: Spatially Variable Genes
GENES = None # None -> highly variable genes; or a list of genes
if GENES is None:
if "highly_variable" not in adata.var:
sc.pp.highly_variable_genes(adata, n_top_genes=min(2000, adata.n_vars))
GENES = adata.var_names[adata.var["highly_variable"]].tolist()
sq.gr.spatial_autocorr(adata, mode="moran", genes=GENES, n_perms=100, n_jobs=4, seed=0)
moran = adata.uns["moranI"].sort_values("I", ascending=False)
moran.to_csv("moran_i.csv")
sig = moran[moran["pval_norm_fdr_bh"] < 0.05]
print(f"{len(sig)} of {len(moran)} genes spatially autocorrelated (FDR < 0.05)")
print(sig.head(15)[["I", "pval_norm_fdr_bh"]])
sq.pl.spatial_scatter(adata, color=sig.index[:4].tolist(), shape=None, size=2, save="top_svg.png")
Moran's I near 1 = smooth spatial pattern, near 0 = random. For a targeted
panel (< ~1,000 genes) test all genes with GENES = adata.var_names.tolist().
mode="geary" writes uns["gearyC"] (C near 0 = clustered, 1 = random).
On Visium use sq.pl.spatial_scatter with the default shape to draw spots
over the image.
Module 7: Ligand-Receptor Permutation Test
CellPhoneDB-style test with OmniPath LR pairs, between labels:
res = sq.gr.ligrec(adata, cluster_key=CLUSTER_KEY, n_perms=1000, threshold=0.1, use_raw=False,
corr_method="fdr_bh", seed=0, copy=True,
transmitter_params={"categories": "ligand"}, receiver_params={"categories": "receptor"})
def to_long(df, name):
d = df.copy()
d.columns = [f"{a}|{b}" for a, b in d.columns]
d.index = [f"{a}|{b}" for a, b in d.index]
return d.stack().rename(name).rename_axis(["lr", "pair"]).reset_index()
lr = to_long(res["means"], "mean").merge(to_long(res["pvalues"], "pval"), on=["lr", "pair"])
lr[["ligand", "receptor"]] = lr["lr"].str.split("|", n=1, expand=True)
lr[["sender", "receiver"]] = lr["pair"].str.split("|", n=1, expand=True)
hits = lr[(lr["pval"] < 0.05) & (lr["mean"] > 0)].sort_values("mean", ascending=False)
hits.to_csv("ligrec_significant.csv", index=False)
print(f"{len(hits)} significant LR x cluster pair combinations")
print(hits.head(15)[["sender", "receiver", "ligand", "receptor", "mean", "pval"]])
Means index = (ligand, receptor), columns = (sender, receiver). For a
consensus across several LR methods and spatial filtering use
spatial-transcriptomics-cell-cell-communication.
Common Workflows
Workflow: Cell Type Arrangement Report
Graph, enrichment, contact counts and the distance range of the strongest pair, in one pass:
sq.gr.spatial_neighbors(adata, coord_type="generic", n_neighs=10)
sq.gr.nhood_enrichment(adata, cluster_key=CLUSTER_KEY, n_perms=1000, seed=0)
z = pd.DataFrame(adata.uns[f"{CLUSTER_KEY}_nhood_enrichment"]["zscore"], index=cats, columns=cats)
im = pd.DataFrame(sq.gr.interaction_matrix(adata, cluster_key=CLUSTER_KEY, normalized=True, copy=True),
index=cats, columns=cats)
pairs = z.where(np.triu(np.ones(z.shape, bool), k=1)).stack()
a, b = pairs.idxmax()
report = pd.DataFrame({"z": pairs, "contact_share": [im.loc[x, y] for x, y in pairs.index]})
report.sort_values("z", ascending=False).to_csv("arrangement_report.csv")
sub = adata if adata.n_obs <= 20000 else sc.pp.subsample(adata, n_obs=20000, random_state=0, copy=True)
occ, interval = sq.gr.co_occurrence(sub, cluster_key=CLUSTER_KEY, interval=50, copy=True)
sc_ = list(sub.obs[CLUSTER_KEY].cat.categories)
dist = interval[1:] if len(interval) == occ.shape[2] + 1 else interval
print(f"strongest pair: {a} - {b} (z = {pairs.max():.1f})")
print(pd.Series(occ[sc_.index(a), sc_.index(b)], index=np.round(dist, 1)).head(10).round(2))
Workflow: Compare Arrangement Between Samples
Neighbourhood z-scores are computed per sample (graphs must not connect cells across sections), then compared:
SAMPLE_KEY = "sample"
zs = {}
for s in adata.obs[SAMPLE_KEY].unique():
a_s = adata[adata.obs[SAMPLE_KEY] == s].copy()
a_s.obs[CLUSTER_KEY] = a_s.obs[CLUSTER_KEY].cat.remove_unused_categories()
sq.gr.spatial_neighbors(a_s, coord_type="generic", n_neighs=10)
sq.gr.nhood_enrichment(a_s, cluster_key=CLUSTER_KEY, n_perms=1000, seed=0)
c = a_s.obs[CLUSTER_KEY].cat.categories
zs[s] = pd.DataFrame(a_s.uns[f"{CLUSTER_KEY}_nhood_enrichment"]["zscore"], index=c, columns=c).stack()
zdf = pd.DataFrame(zs)
zdf.to_csv("nhood_z_by_sample.csv")
print(zdf.assign(spread=zdf.max(axis=1) - zdf.min(axis=1)).sort_values("spread", ascending=False).head(15).round(1))
With one section per condition the difference is descriptive; replicate sections are needed to call a change.
Key Parameters
| Parameter | Module | Default | Effect |
|---|---|---|---|
n_neighs / radius / delaunay |
1 | 10 / - / False | Defines "neighbour"; drives Steps 2, 4, 6 |
n_rings |
1 | 1 | Visium hex rings (1 = 6 neighbours) |
n_perms |
2, 6, 7 | 1000 / 100 / 1000 | Permutation precision |
interval |
3 | 50 | Number of distance bins |
MODE |
5 | "L" | Ripley's function |
threshold |
7 | 0.1 | Min fraction of a cluster expressing each gene |
Common Recipes
Recipe: Visium - Use Expression Clusters as Labels
Spots have no cell type; cluster them on expression (or use domains from
spatial-domain-detection) and run the modules on those labels:
sc.pp.pca(adata, n_comps=30)
sc.pp.neighbors(adata)
sc.tl.leiden(adata, resolution=0.5, key_added="spot_cluster", flavor="igraph", n_iterations=2)
sq.gr.spatial_neighbors(adata, coord_type="grid", n_rings=1)
sq.gr.nhood_enrichment(adata, cluster_key="spot_cluster", n_perms=1000, seed=0)
sq.pl.spatial_scatter(adata, color="spot_cluster", save="spot_clusters.png") # spots over the H&E image
Recipe: Ligrec with a Local LR List (no OmniPath download)
Pass interactions as a DataFrame with source (ligand) and target
(receptor) columns, for example from LIANA's consensus resource:
import liana as li
pairs_df = li.rs.select_resource("consensus").rename(columns={"ligand": "source", "receptor": "target"})
pairs_df = pairs_df[~pairs_df["source"].str.contains("_") & ~pairs_df["target"].str.contains("_")] # simple genes only
res = sq.gr.ligrec(adata, cluster_key=CLUSTER_KEY, interactions=pairs_df[["source", "target"]],
n_perms=1000, threshold=0.1, use_raw=False, corr_method="fdr_bh", seed=0, copy=True)
print(res["pvalues"].shape)
Complex (multi-subunit) pairs are dropped here; Module 7 with OmniPath or the
CellPhoneDB route of spatial-transcriptomics-cell-cell-communication handles complexes.
Expected Outputs
nhood_enrichment_z.csv,figures/nhood_enrichment.pngco_occurrence.csv,figures/co_occurrence.pnginteraction_matrix.csv,centrality_scores.csvripley_L.csv,ripley_L.pngmoran_i.csv,figures/top_svg.pngligrec_significant.csv
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
KeyError: spatial_connectivities |
Module 1 not run on this object | Run sq.gr.spatial_neighbors first |
ValueError on coord_type="visium" |
Not a valid value | Use coord_type="grid" for Visium |
| Co-occurrence out of memory | Too many cells | Lower MAX_CELLS |
| Many isolated nodes | radius too small for the coordinate units |
Check units (pixels vs microns); use kNN |
| Ligrec fails to download | No internet / omnipath missing | pixi add --pypi omnipath; or pass interactions= a DataFrame with source/target columns |
| Neighbourhood z-scores extreme for rare types | Few cells | Merge rare types or interpret with counts |
Deprecation warning for spatial_neighbors |
squidpy >= 1.7 | Switch to sq.gr.spatial_neighbors_knn etc. |
Related Skills
spatial-transcriptomics-cell-cell-communication- LIANA/CellPhoneDB ranking filtered by neighbourhood enrichment, local LR scores, MISTyspatial-transcriptomics-cell-type-annotation- labels and niches for single-cell dataspatial-domain-detection- spatial domains to use asCLUSTER_KEY
References
- Palla et al. (2022) Squidpy, Nature Methods: https://doi.org/10.1038/s41592-021-01358-2
- squidpy documentation: https://squidpy.readthedocs.io/en/stable/
- squidpy ligand-receptor test: https://squidpy.readthedocs.io/en/stable/api/squidpy.gr.ligrec.html
- squidpy Ripley's statistics: https://squidpy.readthedocs.io/en/stable/api/squidpy.gr.ripley.html
- OmniPath: https://omnipathdb.org/
04 同仓库更多 Skills
serpmaven
Scrape Google search results (SERP) to JSON with SERP Maven (serpmaven) - a real Chrome browser on a residential proxy with sticky sessions. Run it as a CLI, a Python library, a local HTTP search API (`serve`), an MCP server or a Docker image; set the proxy login, workers, pages and cost tracking. Use when the user wants Google results, rank tracking, a self-hosted SERP API, or live Google search for an AI agent.
revnu-landing-page-audit
Find out why a landing page isn't turning visitors into signups, demos or sales. Audits one page against what the ad, post or search that sends people there promised, then checks the first screen, proof, call to action, friction and mobile. Returns at most 7 prioritized fixes, plus what is fine and what could not be checked; rewrites specific lines and fixes the page in the repo when asked. Never promises a conversion lift. Works without a Revnu account. Use when the user says or asks: "audit my landing page", "why isn't this page converting", "review my homepage", "my ads get clicks but no signups", "people bounce from the pricing page", "CRO review", "improve conversion rate", "is my hero section clear", "roast my landing page", "rewrite my headline", "what's wrong with this page", "landing page feedback", "make the signup page convert better". Not for SEO or AI-search audits, page speed engineering on its own, or building a new page from scratch.
revnu-growth-context
Write down once who buys, what they're stuck on, what it costs, what proof you have and what you've already tried, so every growth task starts from facts instead of a questionnaire. Creates or updates .agents/revnu-growth.md from the repo, the live site and the user, and imports an existing product-marketing.md. Use when the user says "set up our marketing context", "who is our ideal customer", "write our ICP", "describe the product for marketing", "positioning doc", "what's our brand voice", "remember this about our customers", "log what we tried", "what have we learned from marketing", "we changed pricing, update the context", "update our growth notes", "summarize the business for the agent", "import my product-marketing.md", "start a growth doc", or before a first marketing, SEO, outreach or launch task when no context file exists. Works without a Revnu account.
revnu-get-listed
Get onto the third-party pages AI answers and search cite when buyers ask for the best tool in your category: "best X" roundups, directories, review sites, GitHub awesome lists, community threads and comparison pages. Finds which ones are cited, ranks them by fit and effort, and drafts each submission, PR or pitch by the target's own rules. Use when the user says "get us listed", "which directories should we submit to", "how do we get into best-of lists", "why does ChatGPT recommend competitors and not us", "get mentioned in AI answers", "submit to awesome lists", "get on G2", "where are our competitors listed", "pitch listicle authors", "find backlink opportunities", "launch directories", "get into roundups", "Product Hunt alternatives", "where should we be listed", "get cited by Perplexity". Never submits, pays or posts without a yes. Works without a Revnu account.
revnu-ai-readiness-audit
Audit whether your website gives ChatGPT, Perplexity, Claude, Gemini and Google's AI Overviews something worth quoting, and fix the pages that don't. Use when the user says or asks "is my site ready for AI search", "audit my site for AI answers", "AEO audit", "GEO audit", "why doesn't ChatGPT quote our pricing", "make our pages citable by AI", "do I need llms.txt", "does schema help with ChatGPT", "check our structured data", "is our content visible without JavaScript", "AI SEO audit", "optimize our homepage for AI answers", "LLM SEO check", "why does AI get our product wrong", "fix our site for AI Overviews". Checks fetchability and indexability, answers in the raw HTML, entity facts, schema (including JS-injected markup), headings, dates and llms.txt, then gives at most 10 prioritised fixes and edits the repo when asked. Works without a Revnu account.
proxy-troubleshooting
Diagnose residential proxy failures, with NodeMaven's gateway as the reference - 407 with correct credentials, 406, 410, 500, a connection that hangs, ERR_TUNNEL_CONNECTION_FAILED in a browser, Playwright or Puppeteer ignoring proxy credentials, a sticky session that changes IP, geo-targeting that is silently ignored, passwords with special characters, and unexpected traffic from headless Chrome. Use when a proxy connection fails, returns the wrong location, or costs more traffic than expected.