快速开始

安装

Potentia 提供四种安装方式，按需选择：

# 基础安装（仅 CPU）
pip install potentia

# 安装开发依赖（测试、代码检查）
pip install "potentia[dev]"

# 安装 GPU 支持（faiss-gpu、torch）
pip install "potentia[gpu]"

# 安装全部依赖
pip install "potentia[all]"

依赖项：scanpy、numpy、scipy、scikit-learn、anndata。GPU 加速需要 faiss-gpu 和 torch。

5 分钟示例

使用 scanpy 内置的 PBMC 3k 数据集，无需下载外部文件。

1. 加载和预处理数据

import scanpy as sc
import potentia as pt

adata = sc.datasets.pbmc3k()
sc.pp.filter_cells(adata, min_genes=200)
sc.pp.filter_genes(adata, min_cells=3)
sc.pp.normalize_total(adata, target_sum=1e4)
sc.pp.log1p(adata)
sc.pp.highly_variable_genes(adata, n_top_genes=2000)
sc.pp.pca(adata, n_comps=50)

2. 运行 Potentia

pt.tl.potentia(
    adata,
    n_neighbors=30,
    n_slow_features=10,
    diffusion_time=10,
)

3. 可视化结果

sc.pl.embedding(adata, basis='potentia', color='cell_type')

输出为一张射线图：原点对应身份模糊的细胞，不同射线方向对应不同的细胞身份，径向距离反映状态强度。

结果存储位置

运行完成后，结果存储在 AnnData 对象的以下位置：

位置内容
adata.obsm['X_potentia']2D 嵌入坐标
adata.obsm['X_phi']右特征向量
adata.obsm['X_psi']左特征向量
adata.obsm['X_slow']慢特征（细胞身份）
adata.obsm['X_fast']快特征（细胞状态）
adata.obs['potential']势函数 U
adata.obsm['vector_field']向量场 b
adata.uns['potentia']谱结果和参数

主要参数

参数默认值说明
n_neighbors30kNN 图邻居数
n_slow_features10慢特征数量（细胞身份）
n_spectral_features21谱分解总特征数
diffusion_time10预测滤波的时间范围
n_landmarks5000大规模 MDS 的地标点数
embedding_methodproj_mds嵌入方法：original、proj_mds、proj_kernel

下一步