FineST教程(中):从安装环境到快速跑通NPC Visium数据

写在前面

上一篇我们解读了 FineST 的功能框架：它把 H&E 图像特征和空间转录组融合起来，用于 sub-spot 或 nuclei-resolved 的表达插补和 ligand-receptor 分析。

这一篇进入实操。目标不是一口气复现论文所有图，而是先把官方 HIPT demo 跑通，理解 FineST 的输入、输出和关键参数。HIPT 路线的好处是不用申请 Hugging Face token，比 Virchow2 更适合作为第一次上手。

适合这篇教程的应用场景

这篇教程适合三类读者。

第一，你手里有 10x Visium 数据和 H&E 图像，想评估 FineST 是否能接入自己的项目。

第二，你关注肿瘤微环境中的 ligand-receptor 分析，但觉得 spot-level 通信结果太粗，希望提高空间分辨率。

第三，你暂时没有 Virchow2 权限或 GPU 资源有限，希望先用 HIPT 跑一个官方示例，熟悉流程和文件结构。

这篇不会强行把所有参数都讲完。我们先跑通最小工作流：安装环境、下载教程数据、提取图像特征、训练 FineST。

一、准备环境

FineST 官方推荐使用 Python 3.8 的 conda 环境。

git clone https://github.com/StatBiomed/FineST.gitcd FineSTconda create --name FineST python=3.8 -yconda activate FineSTpip install -r requirements.txtpython -m pip install ipykernelpython -m ipykernel install --user --name=FineST

安装完成后，先检查 PyTorch 是否可用。

import torchprint(torch.__version__)print(torch.cuda.is_available())

如果返回 True，说明当前环境可以调用 GPU。没有 GPU 也可以先做流程检查，但真实数据训练和大图像特征提取会慢很多。

环境提醒

• FineST 依赖 scanpy、anndata、SpatialDM、SparseAEH、stardist、tensorflow、torch 等包。
• stardist
   和 tensorflow 主要用于后续 nuclei segmentation。
• 如果服务器磁盘配额较紧，官方 requirements 中也提示可以先安装 CPU 版本的 torch/tensorflow，再装其余依赖。
• 建议把 FineST 放在独立 conda 环境，不要混装到长期使用的单细胞环境里。

二、下载教程数据

官方 README 提供了 Google Drive 教程数据下载方式。

python -m pip install gdowngdown --folder https://drive.google.com/drive/folders/1rZ235pexAMVvRzbVZt1ONOu7Dcuqz5BD?usp=drive_link

下载后需要确认目录中至少包含这些关键文件。

空间坐标文件

FineST_tutorial_data/spatial/tissue_positions_list.csv

这是 Visium spot 位置文件，后续图像 patch 对齐和 spot 插值都会用到。

组织图像文件

FineST_tutorial_data/20210809-C-AH4199551.tif

这是 H&E 图像，FineST 会从中提取 patch-level 图像特征。

表达矩阵和排序文件

FineST_tutorial_data/OrderData/position_order.csv

FineST_tutorial_data/OrderData/matrix_order.npy

训练阶段会把这些空间位置和表达矩阵输入模型。

三、Step0：提取 H&E 图像特征

官方 quick start 推荐 HIPT，不需要 Hugging Face token。

python ./demo/Image_feature_extraction.py \  --dataset NPC \  --position_path FineST_tutorial_data/spatial/tissue_positions_list.csv \  --rawimage_path FineST_tutorial_data/20210809-C-AH4199551.tif \  --scale_image False \  --method HIPT \  --patch_size 64 \  --output_img FineST_tutorial_data/ImgEmbeddings/pth_64_16_image \  --output_pth FineST_tutorial_data/ImgEmbeddings/pth_64_16 \  --logging FineST_tutorial_data/ImgEmbeddings/Logging/ \  --scale 0.5

这一步可以理解为把每个 spot 周围的 H&E patch 转成深度特征向量。后续 FineST 不直接读取原始图像像素，而是读取这些图像 embedding。

关键参数解释

--dataset NPC

给当前数据集起一个名字。官方 demo 使用 nasopharyngeal carcinoma 数据。

--position_path

spot 坐标文件。Visium 示例使用 CSV；Visium HD 示例通常使用 parquet。

--rawimage_path

原始 H&E 图像路径。图像越大，对内存和读取速度要求越高。

--method HIPT

指定图像特征提取模型。HIPT 适合快速入门；Virchow2 更强但可能需要模型权限。

--patch_size 64

控制从图像中截取多大 patch。Visium HIPT 示例使用 64。

--output_pth

保存提取后的图像 embedding，Step1 训练时会读取这个目录。

【配图建议】这里适合放一张 H&E 原图和 patch 提取示意图。如果用论文图，优先选择 Figure 1 中展示图像特征提取的面板。

四、Step1：训练 FineST 模型

图像特征准备好后，运行 Step1 训练模型。

python ./demo/Step1_FineST_train_infer.py \  --system_path '/your/path/FineST/FineST/' \  --parame_path 'parameter/parameters_NPC_HIPT.json' \  --dataset_class 'Visium16' \  --image_class 'HIPT' \  --gene_selected 'CD70' \  --LRgene_path 'FineST/datasets/LR_gene/LRgene_CellChatDB_baseline_human.csv' \  --visium_path 'FineST_tutorial_data/spatial/tissue_positions_list.csv' \  --image_embed_path 'FineST_tutorial_data/ImgEmbeddings/pth_64_16' \  --spatial_pos_path 'FineST_tutorial_data/OrderData/position_order.csv' \  --reduced_mtx_path 'FineST_tutorial_data/OrderData/matrix_order.npy' \  --figure_save_path 'FineST_tutorial_data/Figures/' \  --save_data_path 'FineST_tutorial_data/SaveData/' \  --patch_size 64 \  --weight_w 0.5

注意把 --system_path 改成自己服务器上的 FineST 包路径，不要照抄作者机器路径。

几个需要重点看的参数

--dataset_class Visium16

官方 HIPT demo 使用 Visium16。如果后面做 single-cell/nuclei 级别或 Visium HD，要换成对应 dataset class。

--gene_selected CD70

示例里选择 CD70 作为展示基因。实际项目中可以换成自己关注的 ligand、receptor、marker 或功能基因。

--LRgene_path

配体受体基因列表，官方仓库提供 CellChatDB baseline human 版本。

--image_embed_path

Step0 输出的图像 embedding 目录，路径必须和前一步保持一致。

--weight_w 0.5

控制模型中相关权重。第一次跑 demo 可以先使用官方默认值，不建议一上来大幅改参数。

五、直接运行官方 demo

如果只是想快速确认环境是否能跑，官方仓库提供了 test_demo.sh。

bash test_demo.sh

官方脚本会依次运行 HIPT 图像特征提取和 Step1 训练。需要注意的是，脚本里的 Python 路径和 --system_path 是作者本地路径，实际运行前要改成自己的 conda 环境和 FineST 路径。

建议先打开 test_demo.sh，把下面两类路径替换掉。

Python 解释器路径

把 /ssd2/users/lingyu/conda_envs/FineST/bin/python 改成自己环境中的 Python，例如：

which python

FineST 系统路径

把 /ssd2/users/lingyu/Python/FineST/FineST/ 改成自己克隆仓库中的 FineST/ 子目录绝对路径。

六、结果文件怎么看

跑完 Step1 后，重点看两个目录。

FineST_tutorial_data/Figures/

这里会保存训练相关图、权重目录和可视化结果。后续 Step2 插补时需要用到 Step1 生成的 weights... 路径。

FineST_tutorial_data/SaveData/

这里保存中间对象和后续分析用数据。跑通后建议记录每一步输出文件名，不要随手覆盖。

如果你准备把 FineST 接到自己的项目，我建议建立类似下面的项目结构。

project/  raw/    spatial/    image/  finest/    image_embeddings/    figures/    savedata/    logs/  scripts/  results/

这样可以避免官方 demo 路径和真实项目路径混在一起。

七、常见问题

问题一：Virchow2 跑不起来

Virchow2 通常需要 Hugging Face token 和模型访问权限。第一次上手建议先用 HIPT。等流程跑通后，再切换到 Virchow2。

问题二：提示找不到路径

优先检查 --system_path、--position_path、--rawimage_path 和 --image_embed_path。FineST demo 中路径较多，绝大多数报错都和路径不一致有关。

问题三：GPU 不可用

先在 Python 中运行：

import torchprint(torch.cuda.is_available())

如果是 False，检查 CUDA、驱动和 torch 版本是否匹配。没有 GPU 可以先小规模测试，但正式项目建议使用 GPU。

问题四：图像太大导致内存压力

可以先缩小 ROI 或使用教程中的 ROI selection 流程，选取感兴趣组织区域后再跑 FineST。

小结

这篇教程的目标是把 FineST 的最小流程跑起来。核心顺序是：准备 conda 环境，下载教程数据，用 HIPT 提取 H&E 图像特征，再用 Step1 训练图像-表达映射模型。

跑通这一步后，我们就拿到了 FineST 后续高分辨率插补需要的模型权重。下一篇会继续讲 Step2：如何做 spot interpolation、sub-spot imputation、nuclei segmentation，以及如何把结果用于肿瘤微环境的 ligand-receptor 应用分析。

参考资料

1. Li L, Wang T, Liang Z, Yu H, Ma S, Yu L, Huang Y. FineST: contrastive learning integrates histology and spatial transcriptomics for nuclei-resolved ligand-receptor analysis. Nature Communications. 2026. PMID: 41839892. DOI: 10.1038/s41467-026-70528-7.

2. FineST GitHub repository: https://github.com/StatBiomed/FineST

3. FineST README: https://github.com/StatBiomed/FineST/blob/main/README.rst

4. FineST HIPT tutorial notebook: https://github.com/StatBiomed/FineST/blob/main/tutorial/NPC_Train_Impute_demo_HIPT.ipynb