single2spatial-spatial-mapping

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Single2Spatial spatial mapping

Single2Spatial空间映射

Overview

概述

Apply this skill when converting single-cell references into spatially resolved profiles. It follows

t_single2spatial.ipynb

, demonstrating how Single2Spatial trains on PDAC scRNA-seq and Visium data, reconstructs spot-level proportions, and visualises marker expression.

当你需要将单细胞参考数据转换为空间解析图谱时，可以使用该技能。本内容遵循

t_single2spatial.ipynb

教程，演示了Single2Spatial如何在PDAC scRNA-seq和Visium数据上进行训练、重建斑点水平的细胞比例并可视化标记基因表达。

Instructions

操作步骤

Import dependencies and style

Load

omicverse as ov

scanpy as sc

anndata

pandas as pd

numpy as np

, and

matplotlib.pyplot as plt

Call
```
ov.utils.ov_plot_set()
```
(or
```
ov.plot_set()
```
in older versions) to align plots with omicverse styling.

Load single-cell and spatial datasets
- Read processed matrices with
```
pd.read_csv(...)
```
  then create AnnData objects (
```
anndata.AnnData(raw_df.T)
```
  ).
- Attach metadata:
```
single_data.obs = pd.read_csv(...)[['Cell_type']]
```
  and
```
spatial_data.obs = pd.read_csv(... )
```
  containing coordinates and slide metadata.

Initialise Single2Spatial

Instantiate

ov.bulk2single.Single2Spatial(single_data=single_data, spatial_data=spatial_data, celltype_key='Cell_type', spot_key=['xcoord','ycoord'], gpu=0)

Note that inputs should be normalised/log-scaled scRNA-seq matrices; ensure
```
spot_key
```
matches spatial coordinate columns.

Train the deep-forest model
- Execute
```
st_model.train(spot_num=500, cell_num=10, df_save_dir='...', df_save_name='pdac_df', k=10, num_epochs=1000, batch_size=1000, predicted_size=32)
```
  to fit the mapper and generate reconstructed spatial AnnData (
```
sp_adata
```
  ).
- Explain that
```
spot_num
```
  defines sampled pseudo-spots per iteration and
```
cell_num
```
  controls per-spot cell draws.

Load pretrained weights

Use

st_model.load(modelsize=14478, df_load_dir='.../pdac_df.pth', k=10, predicted_size=32)

when checkpoints already exist to skip training.

Assess spot-level outputs

Call
```
st_model.spot_assess()
```
to compute aggregated spot AnnData (
```
sp_adata_spot
```
) for QC.

Plot marker genes with

sc.pl.embedding(sp_adata, basis='X_spatial', color=['REG1A', 'CLDN1', ...], frameon=False, ncols=4)

Visualise proportions and cell-type maps

Use

sc.pl.embedding(sp_adata_spot, basis='X_spatial', color=['Acinar cells', ...], frameon=False)

to highlight per-spot cell fractions.

Plot
```
sp_adata
```
coloured by
```
Cell_type
```
with
```
palette=ov.utils.ov_palette()[11:]
```
to show reconstructed assignments.

Export results
- Encourage saving generated AnnData objects (
```
sp_adata.write_h5ad(...)
```
  ,
```
sp_adata_spot.write_h5ad(...)
```
  ) and derived CSV summaries for downstream reporting.
Troubleshooting tips
- If training diverges, reduce
```
learning_rate
```
  via keyword arguments or decrease
```
predicted_size
```
  to stabilise the forest.
- Ensure scRNA-seq inputs are log-normalised; raw counts can lead to scale mismatches and poor spatial predictions.
- Verify GPU availability when
```
gpu
```
  is non-zero; fallback to CPU by omitting the argument or setting
```
gpu=-1
```
  .

导入依赖项和样式
- 导入
```
omicverse as ov
```
  、
```
scanpy as sc
```
  、
```
anndata
```
  、
```
pandas as pd
```
  、
```
numpy as np
```
  和
```
matplotlib.pyplot as plt
```
  。
- 调用
```
ov.utils.ov_plot_set()
```
  （旧版本中为
```
ov.plot_set()
```
  ）使绘图样式与omicverse保持一致。
加载单细胞和空间数据集
- 使用
```
pd.read_csv(...)
```
  读取处理后的矩阵，然后创建AnnData对象（
```
anndata.AnnData(raw_df.T)
```
  ）。
- 附加元数据：
```
single_data.obs = pd.read_csv(...)[['Cell_type']]
```
  ，
```
spatial_data.obs = pd.read_csv(... )
```
  需包含坐标和切片元数据。

初始化Single2Spatial

实例化

ov.bulk2single.Single2Spatial(single_data=single_data, spatial_data=spatial_data, celltype_key='Cell_type', spot_key=['xcoord','ycoord'], gpu=0)

。

注意：输入应为归一化/对数转换后的scRNA-seq矩阵；确保
```
spot_key
```
与空间坐标列匹配。

训练深度森林模型
- 执行
```
st_model.train(spot_num=500, cell_num=10, df_save_dir='...', df_save_name='pdac_df', k=10, num_epochs=1000, batch_size=1000, predicted_size=32)
```
  来拟合映射器并生成重建后的空间AnnData（
```
sp_adata
```
  ）。
- 说明：
```
spot_num
```
  定义每次迭代中采样的伪斑点数量，
```
cell_num
```
  控制每个斑点抽取的细胞数。

加载预训练权重

当检查点已存在时，使用

st_model.load(modelsize=14478, df_load_dir='.../pdac_df.pth', k=10, predicted_size=32)

跳过训练步骤。

评估斑点水平输出结果

调用
```
st_model.spot_assess()
```
计算聚合后的斑点AnnData（
```
sp_adata_spot
```
）以进行质量控制。

使用

sc.pl.embedding(sp_adata, basis='X_spatial', color=['REG1A', 'CLDN1', ...], frameon=False, ncols=4)

绘制标记基因。

可视化细胞比例和细胞类型图谱
- 使用
```
sc.pl.embedding(sp_adata_spot, basis='X_spatial', color=['Acinar cells', ...], frameon=False)
```
  突出显示每个斑点的细胞比例。
- 使用
```
palette=ov.utils.ov_palette()[11:]
```
  绘制按
```
Cell_type
```
  着色的
```
sp_adata
```
  ，展示重建后的细胞分配结果。
导出结果
- 建议保存生成的AnnData对象（
```
sp_adata.write_h5ad(...)
```
  、
```
sp_adata_spot.write_h5ad(...)
```
  ）和衍生的CSV汇总文件，用于后续分析报告。
故障排除提示
- 如果训练过程出现异常，可通过关键字参数降低
```
learning_rate
```
  ，或减小
```
predicted_size
```
  来稳定模型。
- 确保scRNA-seq输入数据经过对数归一化；原始计数会导致尺度不匹配，进而影响空间预测效果。
- 当
```
gpu
```
  参数非0时，需验证GPU是否可用；可通过省略该参数或设置
```
gpu=-1
```
  回退到CPU运行。

Examples

示例

"Train Single2Spatial on PDAC scRNA-seq and Visium slides, then visualise REG1A and CLDN1 spatial expression."
"Load a saved Single2Spatial checkpoint to regenerate spot-level cell-type proportions for reporting."
"Plot reconstructed cell-type maps with omicverse palettes to compare against histology."

"在PDAC scRNA-seq和Visium切片上训练Single2Spatial，然后可视化REG1A和CLDN1的空间表达。"
"加载已保存的Single2Spatial检查点，重新生成斑点水平的细胞类型比例用于报告。"
"使用omicverse调色板绘制重建后的细胞类型图谱，与组织学图像进行对比。"

References

参考资料

Tutorial notebook:
```
t_single2spatial.ipynb
```

Example datasets and models:

omicverse_guide/docs/Tutorials-bulk2single/data/pdac/

Quick copy/paste commands:
```
reference.md
```

教程笔记本：
```
t_single2spatial.ipynb
```

示例数据集和模型：

omicverse_guide/docs/Tutorials-bulk2single/data/pdac/

快速复制命令：
```
reference.md
```