简介
在标准的 STOmics 分析流程中，SAW 会生成包含基因表达矩阵和空间坐标的 Cellbin GEF 文件。虽然 SAW 提供了初步的聚类结果，但研究人员通常会使用第三方工具，如 Scanpy、Seurat，或专用算法，如 cell2location、RCTD（Robust Cell Type Decomposition），进行高级下游分析，以准确鉴别细胞类型或功能状态。
然而，这些精细的注释信息通常仅存在矩阵文件或静态图像中，与原始的空间数据是脱节的。这就导致用户无法利用 StereoMap 交互式可视化功能来查看重新定义的细胞类型。
本指南旨在填补这一空白，提供了一套分步工作流程，指导您将下游分析生成的自定义细胞注释重新导入到原始的 Cellbin GEF 文件中。
前置准备
在开始之前，请确保已准备好以下内容：
运行环境：建议在 Jupyter Notebook 中执行此工作流；
Stereopy：确保已安装 Stereopy (>=1.0.0) (
pip install stereopy)；
SAW：需要访问 SAW 软件包（特别是
cellShape工具）；
数据集：
包含细胞坐标和注释标签的注释文件（
.h5ad或.csv）。输入 Cellbin GEF 文件 (
.gef)；
分布指南
Step 1: 加载 Cellbin GEF
首先，加载 GEF 文件并提取细胞的空间坐标。
import stereo as st
import pandas as pd
import numpy as np
# 1. 读取 cellbin GEF 文件
# 将 'input.cellbin.gef' 替换为您的实际文件路径
gef_path = "/path/to/input.cellbin.gef"
data = st.io.read_gef(gef_path, bin_type="cell_bins")
# 2. 将空间坐标 (x, y) 提取到 metadata DataFrame
# 这对于在文件之间匹配细胞至关重要
data.cells.to_df()['x'] = data.cells_matrix['spatial'][:, 0]
data.cells.to_df()['y'] = data.cells_matrix['spatial'][:, 1]
print(f"已加载 {data.cells.to_df().shape[0]} 个细胞。")
注意: 强烈建议在继续操作之前备份您的原始 Cellbin GEF 文件。
Step 2: 合并注释信息
加载注释文件，可以从 H5AD 文件或 CSV 文件导入数据。
Option A: 从 AnnData (.h5ad) 导入
# 加载注释信息
anno_path = "/path/to/annotation.h5ad"
anno = st.io.read_h5ad(anno_path, bin_type="cell_bins")
# 基于 x, y 坐标合并
# 确保 h5ad 文件中存在注释列（例如 'anno_rctd'）
merged = data.cells.to_df()[['x', 'y']].merge(
anno.cells.to_df()[['x', 'y', 'anno_rctd']],
on=['x', 'y'],
how='left'
)
# 将合并后的注释赋值给主数据对象
# 用 'others' 填充缺失值
data.cells.to_df()['anno_rctd'] = merged['anno_rctd'].fillna('others').values
Option B: 从 CSV (.csv) 导入
# 加载注释信息
csv_path = "/path/to/annotation.csv"
anno_df = pd.read_csv(csv_path)
# 检查您的 CSV 列名
# 在此示例中，我们假设列名为：'X coordinate', 'Y coordinate', 'Label name'
merged = data.cells.to_df()[['x', 'y']].merge(
anno_df[['X coordinate', 'Y coordinate', 'Label name']],
left_on=['x', 'y'],
right_on=['X coordinate', 'Y coordinate'],
how='left'
)
# 赋值注释
data.cells.to_df()['anno_rctd'] = merged['Label name'].fillna('others').values
Step 3: 更新 GEF 文件
将新的注释列写回 Cellbin GEF 文件。
# 使用新的聚类键更新原始 GEF 文件
st.io.update_gef(
data=data,
gef_file=gef_path,
cluster_res_key="anno_rctd" # 您在第 2 步中添加的列名
)
print("GEF 文件更新成功。")
Step 4: 生成预渲染可视化数据（关键步骤）
为了优化 StereoMap 的性能，此步骤将预先计算好的细胞边界（多边形）信息写入 GEF 文件。这能显著提升软件加载速度，因为 StereoMap 无需实时计算形状。此步骤使用 SAW 软件包中的 cellShape 脚本。
您可以直接在 Notebook 中运行此步骤，也可以通过标准终端运行。
Option 1: 在 Jupyter Notebook 中运行 使用 ! 魔法命令在 notebook 单元格中执行 shell 命令。
# 定义 SAW 和文件路径
# 请根据您的环境更新路径
saw_path = "/path/to/SAW/package/saw-8.1.3"
gef_file = "/path/to/input.cellbin.gef"
# 设置环境变量并运行脚本
!export HDF5_USE_FILE_LOCKING=FALSE
!export LD_LIBRARY_PATH={saw_path}/anaconda/lib:$LD_LIBRARY_PATH
!{saw_path}/anaconda/bin/python {saw_path}/lib/cellshape/cellShape.pyc -i {gef_file} -o {gef_file}
Option 2: 在 Shell / 终端中运行 如果您更喜欢使用命令行，请打开终端并运行以下命令：
# 1. 设置环境变量
export saw_path=/path/to/SAW/package/saw-8.1.3
export LD_LIBRARY_PATH=${saw_path}/anaconda/lib:$LD_LIBRARY_PATH
export HDF5_USE_FILE_LOCKING=FALSE
# 2. 运行 cellShape 脚本
${saw_path}/anaconda/bin/python ${saw_path}/lib/cellshape/cellShape.pyc \
-i /path/to/input.cellbin.gef \
-o /path/to/input.cellbin.gef
Step 5: 在 StereoMap 中可视化
启动 StereoMap 并加载更新后的 .gef 文件。在右侧控制面板中，找到 Clustering（聚类） 或 Annotation（注释）下拉菜单，即可查看新添加的注释。
