示例02 返回字典逐字段解读

"""ex02_return_dict.py — 第 1、4 章 解读 ripser() 返回字典

对应教程：tutorials/01-environment.md 1.5 节、tutorials/04-ripser-api.md。

逐字段拆解 ripser() 返回值，让你看懂每个键的含义：
dgms / cocycles / num_edges / dperm2all / idx_perm / r_cover

运行：
python ex02_return_dict.py
"""

import numpy as np
from ripser import ripser

from common import sample_circle

def main():
data = sample_circle(n=80, noise=0.05, seed=1)

# 开启 cocycles 才能在返回里看到代表上循环
result = ripser(data, maxdim=1, do_cocycles=True)

print("=== ripser() 返回字典的键 ===")
for k in result.keys():
    v = result[k]
    if isinstance(v, list):
        print(f"  {k:12s}: list, len={len(v)}")
    elif isinstance(v, np.ndarray):
        print(f"  {k:12s}: ndarray, shape={v.shape}")
    else:
        print(f"  {k:12s}: {type(v).__name__} = {v}")

# ── dgms ──
dgms = result['dgms']
print("\n=== dgms（持久图列表）===")
for d, dgm in enumerate(dgms):
    print(f"  H{d}: shape={dgm.shape}, 前 3 行:")
    for row in dgm[:3]:
        print(f"       birth={row[0]:.3f}  death={row[1]}")

# ── cocycles ──
print("\n=== cocycles（代表上循环，与 dgms 一一对应）===")
for d, cycs in enumerate(result['cocycles']):
    print(f"  H{d}: {len(cycs)} 个 cocycle")
    if cycs:
        print(f"       第一个 shape={cycs[0].shape}, 前 3 行:")
        for row in cycs[0][:3]:
            print(f"       {row}")

# ── num_edges：过滤复杂度指标 ──
print(f"\nnum_edges（过滤中加入的边数）= {result['num_edges']}")

# ── dperm2all：实际使用的距离矩阵 ──
D = result['dperm2all']
if D is not None:
    print(f"dperm2all shape = {D.shape}, "
          f"对角线全 0: {np.allclose(np.diag(D), 0)}")
    # 自定义距离时这块是关键（第 6 章）

# ── 用 n_perm 时才有的 idx_perm / r_cover ──
print("\n=== 子采样相关字段（n_perm 未设时为 None）===")
print(f"  idx_perm = {result.get('idx_perm')}")
print(f"  r_cover  = {result.get('r_cover')}")
​

if name == "main":
main()