术语表
假设你有一组BLF或ASC日志，DBC中定义了功率和设备是否工作的信号。你想知道设备工作了几次、每次多久、用了多少能量。下面的词都围绕这个任务说明。
数据在各步骤中是什么样
CSV文件里的5000最初是文本。程序按照列和信号配置把它读成数值；这一步叫解析。CAN日志保存的是报文字节，程序按DBC规定的位位置、比例和偏移取出物理量；这一步叫DBC解码。执行这些读取、解析或解码工作的程序组件称为读取器，BLF和ASC按扩展名自动选择；CSV或内存输入才需要指定sources[].source_type，用户不需要自己创建读取器。
信号配置中的“转换前”指CSV解析或DBC解码已经完成、但还没有执行signals[].conversion.scale和conversion.offset的阶段。“转换后”指额外乘加完成后的数值。例如DBC解码或CSV解析得到5000mA，再乘0.001得到5A：invalid_values填写5000一侧的无效代码，valid_range填写5A一侧允许的范围。CAN已按DBC得到5A时，不再重复DBC的比例换算。
输入代码是设备用来表示状态的值，例如0表示待机、7表示运行；代码和含义应查设备协议或数据列说明。枚举标签就是分析中给状态取的非空文本名称，例如"idle"和"running"。choices: [[0, "idle"], [7, "running"]]规定左侧输入代码转换为右侧名称，之后用mode == "running"比较状态。整数1、文本"1"、布尔值true是不同类型；这里的输入代码是解析之后的类型，不能仅凭CSV显示的字符判断。
预设是一组可复用的规则和计算，例如充电过程分析。角色表示它需要哪种输入，例如电流角色current；role_bindings由用户明确指定哪条信号担任角色。自动查找是在未明确绑定时，根据semantic_id等业务声明寻找恰好一条满足角色要求的原始信号。角色要求（语义契约）是预设对输入类型、单位、正负方向、测点、有效期等条件的规定，不是根据名字猜测输入。字符串版本"1"取自预设角色要求表。
业务声明只记录含义。例如sign_convention: positive_is_charge声明正电流代表充电；它不会把负数取反。填写前应先查设备规范和实际测量约定。
数据和计算
| 词语 | 在这里是什么意思 | 具体例子 |
|---|---|---|
| 来源（source） | 一组输入数据，例如连续的BLF或ASC文件，也可以是一张CSV表 | 一项来源读取logs/目录中的ASC和BLF |
| 信号（signal） | 随时间变化的一项量或状态 | 功率是一个信号，工作状态是另一个 |
| 样本（sample） | 某个信号在某个时间的一次记录 | “2秒，功率4000W”是一条样本 |
| 合成测试数据 | 为了检查计算是否正确，手工准备几条能算出答案的数据 | 只写几条ASC报文，就可以检查两次工作能否被找出 |
| 别名（name） | 你在表达式里使用的信号名称，可以与DBC信号名或文件列名不同 | 把DBC信号Current_mA命名为current，表达式就写current > 5 |
| 派生信号（derived） | 根据已有信号算出的新信号 | power = voltage * current，由电压和电流算功率 |
| 表达式 | 配置中的一段计算式或条件 | power / 1000算数值，active > 0判断条件 |
| 单位（unit） | 说明一个数表示多少伏、安、瓦或秒 | 4000和unit="W"一起表示4000瓦 |
| 数据类型（dtype） | 规定信号可以存哪一种值 | float64存小数，int64存整数，bool存真/假，enum存声明过的状态标签 |
| 绑定（binding） | 指定“哪个文件中的哪个字段”作为“哪个表达式名称”的数据 | name: power绑定frame_id: 0x100下的signal: Power；唯一来源不必重复引用 |
int64范围是−2⁶³到2⁶³−1，uint64是0到2⁶⁴−1；float64能表示小数，但并非每个十进制数和大整数都能精确保存。bool的True/False不会自动当成1/0参与算术。具体限制见表达式完整说明。
时间和结果
| 词语 | 在这里是什么意思 | 具体例子 |
|---|---|---|
| 会话（session） | 本次分析的一组输入及其时间范围，不是登录会话 | 把同一次连续试验的多个ASC和BLF一起分析 |
| 请求范围（dataset.domain） | 你想计算的开始时间和结束时间 | 请求0—12秒，不代表文件真的记录了12秒 |
| 实际观测范围 | 文件或输入实际提供的时间范围 | 文件最后一条记录在8秒，就不能据此计算到12秒 |
| 信号有效期（valid_for） | 允许一条旧记录继续被使用的最长时间 | 0秒测得10A、有效期2秒；没有更新时，到2秒后不能继续使用10A |
| 未知（UNKNOWN） | 数据不足，无法判断条件是真还是假 | 电流已经过期，便无法判断current > 5 |
| 事件（Event） | 找到的一次活动或一次瞬间变化 | 设备从0秒工作到1秒是一段活动；报警由假变真的时刻是一次点事件 |
| 片段（Segment） | 按窗口定义从事件生成的分析或导出时间范围，可向前后扩展（包括零扩展）或合并，并可按片段计算 | 报警前5秒、后10秒；相邻范围可合并，片段也可与原活动同范围；见窗口与片段 |
| 计算项（calculation） | 针对某段时间算出的数值或选择结果 | 工作时长、最大电流、能量，以及符合条件的数据行 |
| 统计范围（scope） | 决定对整个会话、每次事件还是每个片段分别计算 | 同一功率数据，算工作事件的能量与算含停机时间的片段能量，答案不同 |
| 覆盖率（coverage） | “有数据、可以计算的部分”占“需要检查的范围”的比例 | 请求12秒、只观测到8秒，请求覆盖率为8÷12 |
| 部分结果处理（partial_policy） | 数据不全时，要不要返回已知部分算出的数值 | report返回已知部分并标记；strict在所需范围不完整时返回空值 |
| 质量标记（quality） | 说明数据为什么可能不能使用的标记 | 信号过期、输入为空、除数为0；它不是给数据打的百分制分数 |
覆盖率不只有一个：日志是否覆盖请求时间、信号在日志内是否有效、条件在日志内是否可判断，是不同的问题。完整计算例子见运行参数，字段解释见结果说明。
运行程序
| 词语 | 在这里是什么意思 | 具体例子 |
|---|---|---|
| 分析计划（AnalysisPlan） | 检查过的配置，说明读什么、怎么算、输出什么；此时还没读日志 | load_analysis_plan("analysis.yaml")生成计划 |
| 后端（backend） | 执行同一套计算规则的实现方式；这里不是网站服务器 | numpy按计算路径采用逐点或数组计算；reference使用另一套实现作结果对照 |
| 批次（batch） | 把大量数据拆成若干份，依次交给程序处理 | 一次处理1000条，再处理接下来的1000条；到一批末尾不代表一次工作事件结束 |
| 缓冲（buffer） | 为了减少频繁读写，暂时放在内存中的数据 | 先积累一批结果行，再一起写到磁盘 |
| 预算（budget） | 允许程序使用的资源上限，单位是字节或行数；与金额无关 | memory_budget_bytes=268435456表示新分析部分按256MiB的额度管理内存 |
| 暂存（spool） | 先写到工作目录的中间数据或结果，供后续继续计算、排序和导出 | 还没发布最终CSV时，结果可能已写在工作目录里 |
| 发布（write） | 把本次完整结果以带时间后缀的文件写进本地输出目录；这里不表示上传互联网 | 从本轮清单读取实际的时间后缀结果文件名 |
| 运行清单（manifest） | 记录这次用了什么输入、配置和计算方式，以及输出了哪些文件的JSON | 用来确认两次结果是否基于同一输入和设置 |
| 游标/迭代器（cursor/iterator） | 每次取下一行结果的读取对象，不一次加载整张表 | for row in result.iter_calculations()逐行读取计算结果 |
| 资源关闭（close） | 释放文件句柄和迭代器等运行资源 | 关闭后不能再用同一对象读取；默认清理程序为本次运行创建的临时数据，已发布结果和原始输入保留 |
第一次使用可保留默认运行参数。什么时候需要改批次、内存额度或处理不完整数据，见运行参数怎么选。
阅读内部API时还会遇到的词
| 词语 | 具体含义 |
|---|---|
| 有限数值/非有限数值 | 1、−2.5都是有限数值；NaN表示非数，inf/-inf表示正/负无穷。它们不能作为正常统计值交给用户 |
| 溢出/下溢 | 结果超出类型能表示的范围；浮点下溢还可能使本应非零的极小结果变成0 |
| 只读/冻结（frozen） | 对象创建后不允许直接改字段；例如不能把已经使用过的计划修改为另一套配置 |
| 数组形状(N,) | 一维数组里有N项，例如3个时间就是形状(3,)；“同长”表示时间、值和标记的项数一致 |
| 掩码（mask） | 与数据等长的一组布尔标记，指出哪些位置有效 |
| 归约（reduction） | 把多项输入汇总为较少的输出，例如把100条功率记录算成一个最大值 |
| 时间对齐（alignment） | 算某个时刻的电压×电流时，分别找该时刻仍有效的电压值和电流值 |
| 归一化（normalization） | 按配置转换单位和数据类型，例如把1000mA变成1A；不是自动把所有数缩到0—1 |
| 不变量/一致性检查 | 检查几个字段是否互相矛盾，例如总共只有8秒，却声称有效数据有9秒，就应报错 |
| 标识（identity） | 用来区分一次输入、配置或信号绑定。例如同一个current名称改为取另一个文件的列，绑定标识也应改变。这里不是指人员身份。 |
| 哈希（hash） | 根据文件或配置内容计算的一串字符，用于比较内容是否改变。哈希相同不表示两次试验的业务含义相同。 |
| 封口（seal） | 该份暂存已写完，后续只能读取，不能再往里面追加记录 |
| owner | 负责关闭一组文件、游标或释放资源额度的内部对象；一般用户用AnalysisRunner和with语句即可 |
| 配置结构（schema） | 列明配置允许哪些字段、字段类型和必填项的规则；结构合法不代表文件存在或数据可用 |
| 表达式语言（DSL） | 本项目提供的计算写法，例如current > 5；它只支持文档列出的运算符和函数，不是完整Python。 |
| 语法树（AST） | 程序把公式拆成操作及操作数后得到的结构。例如current > 5拆成“大于比较”、current和5；用于检查公式及安排计算。用户无需手写这棵树。 |
| NumPy | Python的数值计算库，可以对一整列数字做运算；本项目的numpy计算实现使用它 |
| ZOH/backward_hold | 两次更新之间使用前一次仍有效的值。例如0秒2W、3秒8W，0—3秒按2W计算；不画斜线插值 |
| 边沿（edge） | 条件从假变真叫上升沿，从真变假叫下降沿；它表示变化的瞬间 |
| 依赖（dependency） | 为了算某个结果必须使用的输入。power=voltage×current依赖电压和电流 |
| 归并（merge） | 按共同时间顺序处理多路输入；不是把不同来源的同名字段当作同一个信号 |
| 状态机/状态推进 | 程序记住当前处于什么状态，读到新数据再更新。例如记住“已工作2秒”，下一批继续累计 |
| watermark | 读取器承诺后续不会再补来更早数据的时间标记，用来判断何时可以完成某个时刻的处理 |
| EOF | 输入结束标记，表示已读到文件或来源末尾；文件结束不一定意味着设备已经停机 |
| FD（文件描述符）/文件句柄 | 程序打开文件后，操作系统分配的资源。未及时关闭可能让文件无法移动或删除。此处FD与下面的CAN FD含义不同。 |
| CAN FD | 支持更长数据内容等能力的一种CAN帧格式。配置中的is_fd用于区分它与经典CAN；它不是文件描述符。 |
| RSS | 操作系统观察到的进程常驻物理内存；不等于memory_budget_bytes中受程序管理的额度 |
| 惰性/按需读取 | 调用者要下一条数据时才继续读取或计算，避免一次把全部结果装进列表 |
| 原子发布 | 先准备本次结果，再以不覆盖已有文件的方式发布；最后发布 manifest 作为本次完成标志。输出目录可复用，不能仅凭目录存在判断完成，见结果发布 |
| 原生Python数值 | 这里指内置int/float/bool等类型；某些底层对象要求它们，不接受未经转换的数组标量 |
| 快照（snapshot） | 某个确定时点保存下来的内容，例如固定到某个Git提交的源码；后续代码修改不改变这个版本 |
事件、窗口与批量任务
| 词语 | 是什么意思 | 例子 |
|---|---|---|
| 请求/响应配对 | 把一个请求点与允许时间内的响应点关联 | 1秒请求、3秒响应，延迟2秒 |
| FIFO | 把响应先交给最早且仍合格的等待请求 | 1秒、2秒两次请求，3秒响应优先配1秒 |
| 迟滞 | 进入和退出使用不同条件，中间保留此前状态 | 80进入、75退出，77时看此前是否报警 |
| 防抖 | 条件连续保持一段时间才改变活动状态 | 真满2秒才进入，短脉冲不进入 |
| 完整窗口 | 窗口整个时段都有可判断的数据 | 4秒变化量只有中间两条样本不能证明整个4秒均有有效数据 |
| 独立批量任务 | 一次调度多个互不共享分析状态的计划 | 三辆车分别运行；不是把一个文件切成三段 |
| 重采样 | 把原来间隔不一的记录整理到指定时间点；缺实际记录时，按配置决定能否估算 | 每100ms输出一行电压。 |
| 时间网格 | 一组等间隔输出时间点。导出使用resampling.start和resampling.period；时序变换使用origin和step | resampling.start为50ms、resampling.period为100ms，时间点为50、150、250ms等。 |
| 线性插值 | 沿两个已知点之间的直线估计中间值 | 0秒0V、2秒10V，1秒估计5V |
| 连续量/状态量 | 前者允许有物理意义的中间值；后者代表类别或状态 | 电压可估计；挡位不能在1和2间造1.5挡 |
| 最近邻 | 挑距离目标时间最近的一条实际记录 | 0和2秒等距时取较早的0秒帧 |
| DBC | 描述CAN报文里每个信号占哪些位、怎样换算的文件 | 把两个字节按声明比例换成电压。 |
| DLC | CAN报文的数据长度编码，未必等于实际字节数 | CAN FD的DLC 10代表16字节。 |
| 原帧 | 输入日志里实际记录的一条CAN报文 | 时间、ID和数据字节都来自原文件。 |
| 基础帧 | 生成等间隔报文时，选来作为底本的一条原帧 | 重新估算电压后，只替换电压占用的位；其他位保留这条原帧的内容。 |
| 超时/未知 | 超时是等满约定时间；未知是资料不足以判断 | 日志提前结束不能证明设备未响应 |