# 处理自己的数据与遇错恢复

## 输入检查

从任务选择入口：普通数值表用 csv-preview/csv-points；单列均匀序列用 csv-series；有时间戳、缺失或不规则采样的序列用 signal-csv；顶点拓扑用 volume，物理孔隙分割用 pores。二者的体素含义和尺寸上限不同，见 [能力边界](capabilities.md)。使用 `COMMAND --help` 查看该命令的参数。

CSV 使用 UTF-8、唯一非空表头，逗号分隔；显式 --columns 选择并排列数值特征。普通 CSV 数值路径拒绝缺失值；signal-csv 的空 value 单元格保留为缺失，不能填成数值零。重复点默认保留，不自动去重。先确认每一列的单位和采样意义，再归一化。

CLI 按文件字节检查 1000000 上限；库字符串接口按字符检查。点数满足上限并不保证复形细胞数或工作预算足够。输入检查只发现结构与部分数值问题，不证明测量正确或样本独立。

直接使用库时，分析对象就是传入的过滤复形。若要计算 Rips 的 H2，应先构建 `max_dimension=3` 的骨架；`analyze_json` 的 `homology_dimension=2` 会处理这一点。提高 analyze 的同调维度不会自动给任意输入复形补细胞。

## 参数选择与停止解释的条件

| 参数 | 会改变什么 | 操作建议与停止条件 |
| --- | --- | --- |
| --columns | 距离所在的特征空间 | 只选择有意义且可比较的数值特征；无关编号不能当测量坐标 |
| none/zscore/minmax | 距离尺度及各列权重 | 先保留原值作为参照；跨样本使用共同方案，避免分别归一化后误解距离 |
| threshold | 可观察过滤范围、细胞量和截断情况 | 结合数据单位、小范围尝试并检查截止存活；若超预算应缩小截止、数据或显式采样，不能把一次截断当无限寿命 |
| dimension/lag/stride | 嵌入几何、点数和时间跨度 | 结合采样间隔和任务时间尺度；比较参数变化，不能把长环路直接视作已确认周期 |
| window/hop | 时间分辨率、窗口相关性和计算量 | 窗口应容纳关心的结构；hop 小会增加重叠，重叠窗口不能充当独立研究样本 |
| baseline_windows | 归一化拟合及变化阈值 | 使用明确的参考时段并核对异常、缺失和漂移；基准不合理时停止解释报警 |
| grid_step/max_gap | 重采样分辨率及允许补齐的缺口 | 只有依据支持线性插值时才启用；不外推，未补齐的窗口另行列出 |
| spacing/origin/unit | 孔隙体积、面积和物理位置 | 从数据标定中提供；单位未知时只报告声明单位，不解释为真实 mm 或 um |

参数没有普遍最优默认值。对关键结论至少保留原值/变换或相邻参数的一组对照；若结论随合理参数剧烈变化，应报告敏感性而非只保留满意的图。

## 失败后怎么做

| 错误码或情况 | 含义 | 恢复方法 |
| --- | --- | --- |
| ENOENT | 输入或输出父路径不存在 | 检查工作目录、文件名与父目录；不要把文件路径当目录 |
| EMPTY_INPUT / INVALID_UTF8 | 空文件或错误编码 | 检查导出方式，使用含有效数据的 UTF-8 文件 |
| INPUT_TOO_LARGE | CLI 超过文件字节上限 | 有依据地选取子集，保留来源索引；不能只改文件扩展名 |
| INVALID_GZIP | gzip 损坏、截断或解压超限 | 检查原始数据与解压大小，必要时先在外部裁剪 |
| EACCES / EPERM | 系统拒绝读写或文件被占用 | 选择可写目录，关闭占用；原有报告不覆盖 |
| EEXIST | 输出目录已经存在 | 选择新目录，不直接覆盖旧结果 |
| ENOSPC | 磁盘空间不足 | 清理空间后重新运行；不要使用临时目录里的半成品 |
| cell/work budget | 精确计算超出预算 | 调整输入规模或截止，或主动选用有近似标记的入口 |
| 指标为 null / unavailable | 指标不可得 | 查字段含义与相邻状态，不能替换为零 |

命令出错返回非零退出码；常见输入/输出错误返回 2。读取错误与计算错误保留各自含义。结果写出采用同父目录暂存后重命名交付；外部并发修改、不可捕获终止或系统故障不在完整事务保证内。