附录B 接口速查表

文档摘要

附录 B 接口速查表

Ripser.py 公开 API 高频参数与返回值。细节见第 4 章。

ripser()


result = ripser(
    X,
    maxdim=1,
    thresh=np.inf,
    coeff=2,
    distance_matrix=False,
    do_cocycles=False,
    metric='euclidean',
    n_perm=None,
)

参数

参数	默认	说明
`X`	—	(n,d) 点云或 (n,n) 距离矩阵或 sparse
`maxdim`	1	计算 H_0 … H_maxdim
`thresh`	inf	最大过滤尺度
`coeff`	2	素数，Z/pZ
`distance_matrix`	False	X 是否为距离矩阵
`do_cocycles`	False	是否算代表上循环
`metric`	euclidean	点云距离；可 callable
`n_perm`	None	贪心子采样点数

返回 dict

键	类型	说明
`dgms`	list[ndarray(n,2)]	各维持久图
`cocycles`	list[list[ndarray]]	与 dgms 平行
`num_edges`	int	边数
`dperm2all`	ndarray	距离矩阵
`idx_perm`	ndarray	子采样索引
`r_cover`	float	覆盖半径

Rips 类


rips = Rips(
    maxdim=1,
    thresh=np.inf,
    coeff=2,
    do_cocycles=False,
    n_perm=None,
    verbose=True,
)

diagrams = rips.fit_transform(X, distance_matrix=False, metric='euclidean')
rips.plot(diagrams)

方法

方法	说明
`fit_transform(X, ...)`	计算并返回 dgms
`transform(X, ...)`	需先 fit 或直接用 fit_transform
`plot(diagrams)`	persim 绑图

属性（transform 后）

属性	对应
`dgm_`	dgms
`cocycles_`	cocycles
`dperm2all_`	dperm2all
`idx_perm`	idx_perm
`num_edges`	num_edges
`metric_`	使用的 metric
`r_cover`	r_cover

lower_star_img()


from ripser import lower_star_img

dgm_h0 = lower_star_img(image)       # 下水平集 H0
dgm_super = lower_star_img(-image)   # 上水平集（局部极大）

项	说明
输入	2D 灰度 ndarray (H, W)
输出	H0 持久图 ndarray (n_pairs, 2)
内部	8 邻域稀疏 Lower-Star + ripser(maxdim=0)

persim 常用

函数	用途
`plot_diagrams(dgms, show=True)`	持久图
`plot_bars(dgm, show=True)`	条形码
`bottleneck(dgm_a, dgm_b)`	瓶颈距离与匹配
`PersistenceImager(...)`	持久图像向量化

典型一行命令


# 点云 H0+H1
ripser(X, maxdim=1)['dgms']

# 距离矩阵 + 截断
ripser(D, distance_matrix=True, maxdim=1, thresh=2.0)

# 子采样加速
ripser(X, maxdim=1, n_perm=500)

# 上循环 + Z/17Z
ripser(X, maxdim=1, coeff=17, do_cocycles=True)

# sklearn 风格
Rips(maxdim=1, thresh=1.5).fit_transform(X)

约束组合

组合	是否允许
稀疏 D + distance_matrix=True	✅
n_perm + 稀疏 D	❌ ValueError
n_perm > n	❌ ValueError
coeff 非素数	❌ 未定义行为/错误

内置 metric 字符串（点云模式）

值	含义
`euclidean`	欧氏距离
`manhattan`	L1
`cosine`	余弦距离

更多 sklearn pairwise_distances 支持的名称可用；或预计算 D。