alterlab-squidpy-spatial

Squidpy：空間トランスクリプトミクス

Squidpyは、AnnDataとSpatialDataを基盤に構築された、空間解像度のオミクス解析向けscverseツールキットです。空間解析を含まないscRNA-seqパイプラインでは答えられない疑問に対応します。どの細胞種がどの細胞種の隣にあるか（近傍エンリッチメント）、細胞種のペアが距離に応じてどのように共起するか（共起解析）、組織空間の中でどの遺伝子に変動があるか（Moran's I／空間可変遺伝子）、どのリガンド・受容体シグナル伝達が起こり得るか（ligrec）を調べられます。このスキルは空間解析を行い、空間解析を含まないQC／クラスタリングはalterlab-scanpyに、スポットのデコンボリューションはalterlab-scvi-toolsに引き継ぎます。

このスキルを使う場面

次のようなリクエストで使用します。

• Visium、Visium HD、Xenium、MERFISH/MERSCOPE、CosMxのデータを使った空間トランスクリプトミクス／空間解像度のオミクス解析。
• 空間近傍グラフの構築と、近傍エンリッチメント、共起解析、相互作用行列、Ripley統計量、中心性スコアの計算。
• Moran's I（spatial_autocorr）またはSepalによる空間可変遺伝子の特定。
• 空間コンテキストでのリガンド・受容体解析（ligrec）。
• 空間ニッチ／組織ドメイン（近傍プロファイル、UTAG、CellCharter、SpatialLeiden）の特定（calculate_niche_*）。
• プラットフォームの出力をAnnData/SpatialDataに読み込み、プラットフォームに適したcoord_typeを選択する作業。

対象外

リクエスト	振り分け先
空間解析を含まないscRNA-seqのQC、正規化、PCA/UMAP、Leidenクラスタリング、マーカー遺伝子解析	alterlab-scanpy
スポットのデコンボリューション／細胞種のVisiumスポットへのマッピング（destVI、Tangram）、確率的なバッチ補正／統合	alterlab-scvi-tools（references/models-spatial.mdを参照）
.h5ad AnnDataオブジェクトの構築／スライス／連結、レイヤーとobsmの操作（空間解析なし）	alterlab-anndata
RNA velocity／軌跡ダイナミクス	alterlab-scvelo
カウント行列を使ったバルクRNA-seqの差次的発現解析	alterlab-pydeseq2
生のFASTQから発現行列への変換（リードアラインメント／定量）	alterlab-rnaseq-quant
フィーチャーテーブルの多様性／生態学的統計解析	alterlab-scikit-bio

ユーザーがパイプライン全体（「Xeniumデータをクラスタリングしてから、どの細胞種同士が隣接しているか調べて」など）を求めている場合は、まずalterlab-scanpyでScanpyのクラスタリング工程を実行し、その後ここに戻って空間グラフとエンリッチメントを計算します。

重要な判断は1つだけ：プラットフォーム → coord_type

Squidpyの空間グラフは測定ジオメトリに依存します。coord_typeを誤ると、意味のないグラフが気づかれないまま生成されます。（以下のパラメーターの動作はすべて、squidpy 1.8のsq.gr.spatial_neighbors APIに基づいています。）

プラットフォーム	解像度	グラフ構築方法	組み合わせるもの
Visium	スポット（複数細胞、六角形グリッド）	coord_type="grid"、n_neighs=6、n_rings=1..2	デコンボリューション → alterlab-scvi-tools
Visium HD	2/8/16 µmビン（正方形グリッド）	coord_type="grid"（正方格子）	事前にビニング方法を選択
Xenium / MERFISH / CosMx	単一細胞	coord_type="generic"、delaunay=True（またはn_neighs=k）	直接的な細胞種解析

• coord_type=Noneの場合、spatialがadata.unsにあり、かつn_neighs=6のときに限り、自動的に"grid"が選ばれます（Visiumの特徴）。それ以外の場合は"generic"にフォールバックします。自動検出に頼らず、coord_typeを明示的に設定してください。
• delaunay=Trueが使用されるのはcoord_type="generic"の場合のみです。これはk近傍スポットの代わりに、ドロネー三角形分割からグラフを構築します。n_ringsが使用されるのはcoord_type="grid"の場合のみです。
• Squidpy 1.8では、sq.gr.spatial_neighbors_grid、_knn、_radius、_delaunayといったグラフ構築関数も直接利用できます。それぞれに、適用可能なパラメーターのみが用意されています。ジオメトリがわかっている場合は、これらを優先してください。sq.gr.spatial_neighbors(..., delaunay=True)ではn_neighsが黙って無視されます。これは「kを指定したのに何も変わらない」というよくある原因です。

データの読み込み（プラットフォームに応じたリーダーを選択）

import squidpy as sq
import scanpy as sc

# Visium (legacy spot data) — squidpy's own reader, returns AnnData
adata = sq.read.visium("path/to/visium_outs/")

# Vizgen MERSCOPE / Nanostring CosMx via squidpy readers
adata = sq.read.vizgen("path/to/merscope/", counts_file="cell_by_gene.csv",
                       meta_file="cell_metadata.csv")
adata = sq.read.nanostring("path/to/cosmx/", counts_file="exprMat_file.csv",
                           meta_file="metadata_file.csv", fov_file="fov_positions.csv")

Xenium と Visium HDでは、**spatialdata-io**のリーダーを使用し、SpatialDataオブジェクトを操作してください（squidpyにはsq.read.xeniumがありません）。

from spatialdata_io import xenium, visium_hd, merscope
sdata = xenium("path/to/xenium_outs/")        # 10x Xenium
sdata = visium_hd("path/to/visium_hd_outs/")  # 10x Visium HD
sdata = merscope("path/to/merscope/")         # Vizgen MERSCOPE

spatialdata-ioのリーダー名は、spatialdata-ioの安定版APIに照らして確認済みです。 Squidpy 1.8はSpatialDataオブジェクトを直接受け付けます。SpatialDataからAnnData（table）への流れについては、references/spatialdata_io.mdを参照してください。

標準的な空間ワークフロー

QC、正規化、HVG、PCA、近傍、Leiden、sc.tl.umapはscanpyのステップです。alterlab-scanpyを介して実行してください。クラスター／細胞種ラベルが得られたら、ここで空間解析を行います。

import squidpy as sq

# 1. Build the spatial neighbor graph (choose coord_type per the table above)
sq.gr.spatial_neighbors(adata, coord_type="generic", delaunay=True)   # Xenium/MERFISH
# sq.gr.spatial_neighbors(adata, coord_type="grid", n_neighs=6)       # Visium

# 2. Neighborhood enrichment: which cluster pairs are spatially adjacent?
sq.gr.nhood_enrichment(adata, cluster_key="leiden")
sq.pl.nhood_enrichment(adata, cluster_key="leiden")

# 3. Co-occurrence across distance
sq.gr.co_occurrence(adata, cluster_key="leiden")
sq.pl.co_occurrence(adata, cluster_key="leiden", clusters="0")

# 4. Spatially variable genes via Moran's I
sq.gr.spatial_autocorr(adata, mode="moran")
svgs = adata.uns["moranI"].head(20)   # ranked by Moran's I

# 5. Ligand-receptor interaction (Omnipath-backed)
sq.gr.ligrec(adata, cluster_key="leiden")

# 6. Spatial niches / tissue domains — cluster cells by their neighborhood, not
#    just their own expression. Requires a spatial graph (step 1) already built.
sq.gr.calculate_niche_neighborhood(adata, groups="leiden", resolutions=[0.5, 1.0])
# other flavors: calculate_niche_utag, calculate_niche_cellcharter,
#                calculate_niche_spatialleiden

汎用のsq.gr.calculate_niche(..., flavor=...)ディスパッチャーも引き続き機能しますが、squidpy 1.9で削除予定のため非推奨です。各flavorが実際に使用するパラメーターのみを含むシグネチャを持つ、flavor固有の関数を呼び出してください。ニッチ解析が答える問いはnhood_enrichmentとは異なります。エンリッチメントでは「平均して、どのラベル付き細胞種が互いに隣接しているか」を問い、ニッチ解析では「各細胞を、繰り返し現れる組織内の微小環境に割り当てます」。

その他のグラフ統計には、sq.gr.interaction_matrix、sq.gr.centrality_scores、sq.gr.ripley（CSRとの比較によるクラスター化／分散）、sq.gr.sepal（空間的可変遺伝子を検出する別の検定）があります。組織の可視化には、sq.pl.spatial_scatter（スポット／点）またはsq.pl.spatial_segment（セグメント化された細胞）を使用してください。ほかに知っておく価値のあるプロットは、sq.pl.nhood_enrichment_dotplotとsq.pl.var_by_distance（アンカーからの距離に応じた発現）です。H&E／IF画像の特徴量には、ImageContainerを操作するsq.imモジュール（process、segment、calculate_image_features）を使用します。

ヘルパースクリプト — 1回の呼び出しでグラフを構築し、主要な統計を実行します。

uv run python skills/bioinformatics/alterlab-squidpy-spatial/scripts/spatial_neighborhood.py \
    clustered.h5ad --platform xenium --cluster-key leiden --out spatial_report.json

scripts/spatial_neighborhood.py --helpを参照してください。--platformからcoord_typeを選択し、spatial_neighbors、nhood_enrichment、co_occurrence、spatial_autocorrを実行します。そのうえで、JSONサマリー（空間的可変性が上位の遺伝子とエンリッチメントのzスコア行列）と、更新済みの.h5adを書き出します。

詳細なリファレンス

• references/platform_routing.md — プラットフォームからcoord_typeを決定するための完全な表、n_neighs／n_rings／delaunayパラメーターの意味、プラットフォームごとの注意点。
• references/analysis_recipes.md — 各sq.gr／sq.pl関数のコピペ可能なレシピ。重要なパラメーターと出力の読み取り方も記載しています。
• references/spatialdata_io.md — Xenium／Visium HD／MERSCOPEをSpatialDataに読み込み、squidpyが操作するAnnDataのtableを取得する方法。

報告前のセルフチェック

• プラットフォームに合ったcoord_typeを設定しましたか（Visiumにはgrid、シングルセルにはgeneric）？誤ったグラフを使用すると、それ以降のすべての統計が無効になります。
• クラスタリング／QCはalterlab-scanpyで実行しましたか（このスキルではラベルが存在することを前提とします）？
• Visiumスポットデータの場合、細胞種レベルの主張を行う前にデコンボリューション（alterlab-scvi-tools）が必要であることを明記しましたか？スポットには複数の細胞が含まれます。
• nhood_enrichmentのzスコアは、生カウントとしてではなく、置換検定の条件を添えて報告していますか？

AlterLab Academic Skillsスイートの一部です。