数据来源

sources位于配置根级，是来源对象的列表。每项说明从哪里读取数据、怎样解释原时间；只有一个来源时，不必填写来源名或signals[].source。BLF/ASC由文件扩展名识别；填日志路径和DBC后，再配置信号绑定。分析对象和请求范围由dataset控制。

程序中负责打开来源、读取记录并解释内容的组件称为读取器。source_type选择它要处理的格式：CSV物理量列先由文本解析成值，CAN报文字节先按DBC解码成物理量。后续signals把得到的值命名、按需换算并检查有效性。因此“原始值”须结合阶段理解：信号字段中的原始值已经完成CSV解析或DBC解码，不一定是文件里最初的文字或字节。

选择输入格式

AnalysisRunner支持表中的BLF、ASC、原始CAN CSV、信号CSV和内存来源，也支持默认的asc_or_blf来源：按扩展名识别ASC/BLF，同一来源可依次读取两种格式。signal_csv专门读取已解码的物理量列；它不能直接把报文字节当成电压或电流。

单一ASC/BLF来源的入门配置采用execution.process_count: 4，让不同文件并行读取和解码，再按选定顺序送入同一个分析会话。只有一个文件时实际最多用1个读取工作进程。CSV、内存和多个来源联合分析当前保持process_count: 1；若有多次独立试验，可在批量任务中并行运行完整任务。进程数的默认值仍为1，完整使用条件见连续记录多进程。

先运行一个完整任务

优先从BLF／ASC快速开始运行随附的ASC日志和DBC，核对38J的能量。相同配置可将路径替换为自己的BLF，或者整个日志目录，无须中间转换成CSV。

chronaxis run analysis.yaml --output can-result

从随册examples目录执行，结果目录可以重复使用，文件名自动增加时间后缀。CSV最小配置和内存最小配置分别用于已经解码的信号表和程序内记录，不是CAN分析的前置步骤。

时间平移示例专门演示已知2秒偏移：原0秒变成2秒，能量仍为38J。多来源只有在确知同步关系时才设置共同clock与offset，默认值不自动校时。

下面的字段表用于把示例换成自己的输入。除明确标注可为null的字段外，不把null当作省略；未知字段或错误结构在加载计划时拒绝，文件不存在、表头不符和无法解析的单元格在读取时报告。

来源对象的共同字段

表中字段均相对于sources[]，例如paths的完整路径为sources[].paths，表示sources列表中每个来源的paths。点号和[]用于说明层级，不是要照写的键名。每项放在sources数组中。YAML结构见配置说明。ASC和原始CSV的专用读取字段另见文本输入。

用load_analysis_plan加载时，相对路径以配置文件所在目录为起点；用AnalysisPlan.from_dict构建时，以传入的base_dir为起点，未传则用当前工作目录。

目录与连续文件

下面是修改片段：以analysis.yaml为基础，用自己的日志目录和DBC替换根级sources列表，并在根级execution中设置process_count。其他数据集、信号和计算段保留；目录与DBC须实际存在，DBC中须有配置引用的信号。

sources:                # 列出输入来源；每项规定数据位置、格式和时间解释方式
  - paths: data/can     # 选择输入文件、连续分卷列表或目录；相对路径基于本配置，目录按自然序读取
    dbc_by_channel:     # 为每个CAN通道指定解码用DBC文件；键是通道编号的字符串
      '1': network.dbc  # 为这个通道指定DBC文件；路径相对当前配置文件，通道键须为字符串
execution:              # 与sources并列，控制本次分析的执行方式
  process_count: 4      # 最多4个文件读取工作进程；实际不超过文件数

目录内 part1.asc、part2.blf、part10.asc最多由3个工作进程读取，主进程仍按1、2、10接续处理，保留跨文件信号和事件状态。只取ASC可写paths: data/can/*.asc；需要子目录时明确写data/can/**/*.asc。空目录或无匹配文件报错，不静默跳过。显式列表[part10.asc, part2.asc]保持原顺序。

通配符末尾明确写成 .asc、.blf、.csv 或 .txt 时，扩展名匹配忽略字母大小写。例如 data/can/*.asc 也能找到 part10.ASC，*.bLf 也能找到 .BLF 文件；仍按来源类型筛选格式。文件名主体、目录名和其他通配符继续按操作系统的匹配规则处理，不能据此把整个路径视为大小写无关。需要递归查找时仍须显式写 **。

文件之间有已知时间偏移时，把它与文件写在一起，例如paths: [{path: part1.asc, offset: 0s}, {path: part2.asc, offset: 100s}]；偏移叠加来源的time.offset。逐文件偏移适用于默认ASC/BLF、显式can_asc和raw_can_csv；signal_csv与显式can_blf只支持来源统一的time.offset。适用来源也可写offsets数组，但不能与文件对象中的offset同时声明。独立试验要分别运行，见批量任务。

time的全部字段

下表位于sources[].time内，例如unit完整写作sources[].time.unit。这不是信号的signals[].unit。

字段位置统一为sources[].time.timezone，但允许值依输入格式而异。ASC/原始CSV显式null无效；signal_csv/memory的null表示不补时区。已有时区的日期按其中偏移解释，不再使用分钟整数形式。

CAN：来源与信号定位

第一段放入sources列表，第二段放入signals列表。需要实际的trial.blf和network.dbc；字段定位必须与DBC相符。

应用位置：以自己新建的分析文件为基础，在文件根级加入或替换sources，代码已包含父键。存在同名列表时按本例替换该列表，不把父键再嵌入列表项。 示例文件名是待替换的输入路径，须准备相应CSV/DBC/CAN数据；本块本身不是完整任务。

sources:                # 列出输入来源；每项规定数据位置、格式和时间解释方式
  - path: trial.blf     # 指定单个输入文件；相对路径从本配置文件所在目录计算
    dbc_by_channel:     # 为每个CAN通道指定解码用DBC文件；键是通道编号的字符串
      '1': network.dbc  # 为这个通道指定DBC文件；路径相对当前配置文件，通道键须为字符串

应用位置：以自己新建的分析文件为基础，在文件根级加入或替换signals，代码已包含父键。存在同名列表时按本例替换该列表，不把父键再嵌入列表项。 示例文件名是待替换的输入路径，须准备相应CSV/DBC/CAN数据；本块本身不是完整任务。

signals:                   # 把输入字段定义为有名称、类型、单位和有效期的分析信号
  - name: voltage          # 给分析信号取名称；后续表达式和计算通过此名称引用它
    field:                 # 指定来源中的原始字段；CSV填表头，CAN填写通道/报文ID/DBC信号名
      frame_id: 0x100      # 选择包含信号的报文ID；从对应DBC取得，可写整数或支持的进制文本
      signal: PackVoltage  # 填写DBC中的信号名称，大小写须一致

本例假定DBC包含信号单位和该报文周期。程序从DBC推导数值类型、单位与帧类型；有效期默认是周期3倍。只有DBC没有周期且本任务需要有效期时，再填写period或valid_for。多通道/多帧候选不能唯一确定时才补充对应定位字段。

CAN共同字段

下表字段位于sources[]，适用于BLF、ASC和原始报文CSV；signal_csv和memory不使用DBC。

BLF读取入口的额外选项

以下字段只由can_blf入口接受：显式source_type: can_blf，或默认来源全部为BLF且未设置逐文件偏移时使用该入口。默认混合ASC/BLF、can_asc及raw_can_csv不能显式填写这些字段。

reader.decode_policy：CAN解码策略

此字段位于每个CAN来源的reader映射内，控制如何处理DBC解码，适用于asc_or_blf、can_blf、can_asc、raw_can_csv；不是计算间隔或信号转换字段。替换已有来源bus的reader时，可写下面的子映射；只包含reader父键，不是完整sources列表：

reader:                  # 设置来源的读取选项；本片段放在对应sources列表项内
  decode_policy: strict  # 选择已选CAN帧长度检查和解码失败处理；按输入章节的路径对照表选择

默认asc_or_blf允许ASC/BLF混合；显式can_asc/can_blf限定对应格式。显式文件列表保持顺序，目录与通配符自然排序。ASC/CSV的文字和列结构首先由reader检查，decode_policy不能让无法解析的文本成为有效帧。经典CAN与DBC FD标记的支持范围见信号定位。

解码失败时各读取路径的处理

reader.decode_policy决定已选数据帧的长度检查与解码失败处理。strict用于要求长度完整的输入；partial允许短帧只提供可解出的字段；legacy仅用于需要保留指定旧路径行为的迁移。

上表的解码失败专指cantools的DecodeError。纯BLF串行读取且DBC中该ID只有一个定义时，解码函数的其他普通Exception也会使本条值无效；同ID存在多个定义或采用文件并行时，只将DecodeError按表处理，其他异常继续抛出。长度检查、文本结构、输入时间及I/O错误不因此被忽略。不能把partial理解成忽略所有错误；缺少的短帧字段不补零。

reader.decode_scope: all扩大尝试解码的范围，不表示全部报文都通过DBC检查。此选项用于纯BLF串行入口；文件并行与time_order要求requested。下表说明选择all时各类帧的处理：

表中只描述解码范围。输入结构、实际需要的时间及I/O错误仍按各自规则处理；input_check: full检查完整来源的时间顺序，不补充一份全帧DBC认证。

路径由规范化后的source_type决定：can_asc、raw_can_csv和保留为asc_or_blf的混合路径使用文本CAN适配层；can_blf采用表中的纯BLF长度与DecodeError政策，其他异常的串行/并行区别见上文。省略source_type或填写asc_or_blf时，纯ASC归一为can_asc，包括设置了逐文件offsets的情况；纯BLF且未填offsets时归一为can_blf；混合ASC/BLF，或纯BLF且设置offsets时保留asc_or_blf。不能只看某一个文件后缀判断legacy行为。

signals[].field：选择CAN报文中的信号

BLF、ASC和原始报文CSV使用相同的绑定结构。必填frame_id和signal；唯一DBC通道可省略channel，field不接受message字段，报文由通道、ID和信号名定位。

JSON不允许直接写带进制前缀的数值，因此写"frame_id": "0x100"或"frame_id": 256；YAML可写frame_id: 0x100。前缀大小写均可；不接受负数、浮点数、布尔值或八进制前缀。两个类型选项省略表示自动识别，显式null不合法。

当前JSON Schema对ID字符串先检查数字格式；加载计划时，Python还会把它转换为整数并检查范围。例如is_extended: false配frame_id: "0x800"会被计划加载器拒绝，因为2048超过标准帧上限2047。编辑器只显示Schema检查通过，不能替代chronaxis validate analysis.yaml的完整检查。

例如标准帧和扩展帧都使用ID 0x100，且都含PackVoltage。日志只有扩展帧时可根据实际标志选中扩展定义；同一绑定后续又遇到也符合条件的标准帧时，程序会提示补充is_extended，不会把两类数据混在一个信号中。ID不存在或信号名写错时会直接说明缺项，不要求用类型参数掩盖错误。

DBC标为FD但日志实际为经典CAN的已支持兼容继续保留，并记录提示；显式设置类型只用于选择报文，不修改输入帧。每个来源仍使用一个通道和对应DBC，连续文件按原序处理。DBC已经应用的factor/offset不能重复执行。

解码范围与时间检查范围

以下两个选项回答不同的问题，完整路径分别为sources[].reader.decode_scope和sources[].reader.input_check：

• decode_scope只用于纯BLF入口，决定尝试解码哪些报文。默认 "requested" 处理当前任务需要的报文；"all" 扩大尝试范围，具体跳过和失败情况见上表，不证明全部报文已通过DBC检查。
• input_check用于所有CAN来源，决定时间检查范围。默认 "auto" 根据任务决定；"full" 检查完整来源的时间顺序，不是开启所有信号解码或所有诊断输出。

例如只按固定周期累计整份文件的消息能量，可能不需要报文时间；但找活动或筛选某段时间，就需要检查时间。运行explain后，可在 input_requirements 查看本次需要的信号和时间检查范围。未检查的记录不能据此认定为正确。

普通ASC及混合ASC/BLF的auto模式只要求所需通道和报文ID按原顺序推进；无关Tx帧的微秒回退不会阻断分析。来源范围与记录顺序分开处理：最早/最晚观测时间在同次读取中统计，原始时间不改写。显式full或原帧导出仍拒绝全来源回退；目标报文及跨连续文件的目标时间回退始终报错，不自动排序、钳平或清洗。ASC的relative增量仍按全部相关时间行依次累加，不能把跳过无关解码理解为丢弃这些增量。原始CSV沿用其列解析及时间策略，不能由ASC的说明推定它会忽略任意坏行。

普通规则、窗口、计算和导出也可以省略dataset.domain，程序采用输入实际观测范围；多来源取观测范围的并集，没有观测数据不生成事件，会话统计返回空值。仅整文件逐消息累计且不需要时间时，可以不额外建立时间范围；存在时间筛选、事件或其他时间相关功能时仍检查所需时间。省略domain不会关闭时间相关功能所需的检查。详见分析范围和当前消息累计。

CSV：每行是一次明确更新

信号CSV按实际内容和剩余预算分批交付，execution.batch_rows是上限；通常可使用默认设置。所需最小记录和交接状态也放不下时才因这项容量不足而失败，具体处理与内存边界见执行批次说明。

下面是sources列表中的一项，文件part1.csv和part2.csv须包含时间列time_ms及所引用的信号列。

应用位置：以自己新建的分析文件为基础，在文件根级加入或替换sources，代码已包含父键。存在同名列表时按本例替换该列表，不把父键再嵌入列表项。 示例文件名是待替换的输入路径，须准备相应CSV/DBC/CAN数据；本块本身不是完整任务。

sources:                           # 列出输入来源；每项规定数据位置、格式和时间解释方式
  - paths: [part1.csv, part2.csv]  # 选择输入文件、连续分卷列表或目录；相对路径基于本配置，目录按自然序读取
    source_type: signal_csv        # 选择数据格式；memory内存记录、signal_csv物理量表、can_blf/can_asc/raw_can_csv原始CAN
    time_column: time_ms           # 填写CSV时间列的实际表头，大小写和文件一致
    time:                          # 说明输入时间数值的类型、单位、共同起点和校准偏移
      unit: ms                     # 声明输入时间数值的单位；根据文件说明填写s/ms/us/ns等受支持单位
    reader:                        # 设置当前来源的文本解析、列映射或解码行为；可用子字段取决于来源格式
      missing_values: ['', NA]     # 列出CSV中表示缺失的文本；遇到它们产生无效更新，不按零计算

下表位于sources[]；例如编码写在sources[].reader.encoding，不是来源顶层。

path和paths二选一。显式列表按给定顺序读取；目录和通配符自然排序。比如part1结束于第10秒，part2却从第0秒重新计时，直接连接读取会因时间回退而报错。

上例把空单元格和NA都声明为无效值。如果上一行电流为5A，下一行写NA，程序就从下一行时刻起认为电流未知，不再沿用5A。需要查输入位置时显式开启diagnostics.trace并读取input_trace；默认摘要结果不保存逐单元格原始位置。

默认编码只去掉文件开头的BOM，不删除列名或单元格中间的U+FEFF字符。表头末尾多出的空列名可以省略，例如time,power,可读取数据行0,100,或0,100；对应匿名尾列只允许空单元格，空格和其他非空内容都会报错，需要为其补列名。中间空列名、重复列名、有名列缺失及超出表头宽度的行仍然报错。引号、引号内换行及错误的物理行号按CSV规则处理。

例如原列Current_mA转成别名current：

应用位置：以自己新建的分析文件为基础，在文件根级加入或替换signals，代码已包含父键。存在同名列表时按本例替换该列表，不把父键再嵌入列表项。 示例文件名是待替换的输入路径，须准备相应CSV/DBC/CAN数据；本块本身不是完整任务。

signals:               # 把输入字段定义为有名称、类型、单位和有效期的分析信号
  - name: current      # 给分析信号取名称；后续表达式和计算通过此名称引用它
    field: Current_mA  # 指定来源中的原始字段；CSV填表头，CAN填写通道/报文ID/DBC信号名
    dtype: float64     # 选择分析值类型；float64小数、int64有符号整数、uint64非负整数、bool真假、enum状态名称
    unit: A            # 声明分析值的单位；按物理含义填写，无量纲用字符串"1"；按已知单位关系推导换算
    valid_for: 200ms   # 设置一次有效更新最多沿用多久；依据采样周期和允许数据陈旧程度填写
    conversion:        # 设置读取后额外的单位换算；不重复DBC已执行的缩放和偏移
      input_unit: mA   # 声明CSV解析或DBC解码后、额外换算前的单位；查列说明或DBC物理单位
      scale: 0.001     # 设置额外数值乘数；按输入与目标单位的合法换算倍率填写，避免重复DBC换算

上例0.001明确把毫安换为安培。valid_for=200ms仅是示意，真实项目应按采集方式确认。字段名与别名可以不同，表达式统一写current。

内存：把记录直接写进配置

下面是可独立运行的内存最小配置。它只定义功率，不需要外部文件；字段的类型、单位和有效期均在同一个例子中给出。0至1秒为2W，1至2秒为4W，因此积分为2×1+4×1=6J。

# 合成教学配置；请连同配套输入使用，数值仅用于复现本例。
config_version: 4          # 声明分析文件采用的字段结构版本；当前填写整数4
dataset:                   # 设置本次分析名称及可选的对象、会话和时间范围
  domain:                  # 限定本次分析请求的起止时间；应与来源采用相同时间基准
    end: 2s                # 设置分析终点；连续时长不包含该端点，按希望分析的范围填写
    start: 0s              # 设置分析起点，包含该时刻；按希望分析的范围填写
  name: memory_power       # 命名本次分析数据集；名称写入结果身份字段
sources:                   # 列出输入来源；每项规定数据位置、格式和时间解释方式
  - rows:                  # 提供内存来源的记录列表；每条记录含时间及该时刻的字段值
      - time: 0s           # 填写本条合成记录的发生时间，按本来源的time声明解释
        values:            # 列出本条记录实际更新的原字段及值；字段名供signals.field选择
          power: 2         # 本时刻原字段power的合成输入值；其类型和单位由下方信号定义说明
      - time: 1s           # 填写本条合成记录的发生时间，按本来源的time声明解释
        values:            # 列出本条记录实际更新的原字段及值；字段名供signals.field选择
          power: 4         # 本时刻原字段power的合成输入值；其类型和单位由下方信号定义说明
      - time: 2s           # 填写本条合成记录的发生时间，按本来源的time声明解释
        values:            # 列出本条记录实际更新的原字段及值；字段名供signals.field选择
          power: 4         # 本时刻原字段power的合成输入值；其类型和单位由下方信号定义说明
    source_type: memory    # 选择数据格式；memory内存记录、signal_csv物理量表、can_blf/can_asc/raw_can_csv原始CAN
signals:                   # 把输入字段定义为有名称、类型、单位和有效期的分析信号
  - dtype: float64         # 选择分析值类型；float64小数、int64有符号整数、uint64非负整数、bool真假、enum状态名称
    field: power           # 指定来源中的原始字段；CSV填表头，CAN填写通道/报文ID/DBC信号名
    name: power            # 给分析信号取名称；后续表达式和计算通过此名称引用它
    unit: W                # 声明分析值的单位；按物理含义填写，无量纲用字符串"1"；按已登记的兼容单位换算数值
    valid_for: 3s          # 设置一次有效更新最多沿用多久；依据采样周期和允许数据陈旧程度填写
calculations:              # 列出希望获得的统计或积分结果，每项独立选择范围和算法
  - name: energy           # 为这项计算结果取唯一名称；结果表用它区分计算项
    operation: integral    # 选择计算方法；本例将有效数值乘持续时间后累计，例如功率乘秒得到能量
    expr: power            # 指定参与计算的数值或信号表达式；引用前面已定义的信号
execution:                 # 设置本次分析的并行处理方式
  process_count: 1         # 本例为CSV、内存或多来源会话，当前仅支持单进程

在保存配置的目录运行python -m chronaxis run input-memory-minimal.yaml --output memory-result。从完成摘要中的清单定位会话结果表，检查energy（J）列为6、energy：状态为“完整”。若以后加入真假信号，原值可直接写true/false；使用整数0/1时须在该信号声明dtype: bool及choices: [[0, false], [1, true]]，再在条件中引用它。

下表位于sources[]；记录时间的完整路径为sources[].rows[].time。

内存行的time必须带单位（绝对时间则明确日期/时区），不是按source.time.unit猜裸数字。上面的3条记录是手工准备的测试数据，方便先算出预期答案再检查规则；真实数据很多时改用CSV或BLF文件，程序可以分批读取，不必把整份记录写进配置。SourceSpec/MemoryRow和MemorySourceAdapter给出底层类型化接口。

多来源时间同步

两份文件都写“3秒”，不一定表示同一时刻。例如CAN采集从按下试验按钮开始计时，CSV仪表提前2秒就已开始计时。按钮后的第3秒，在CAN里是3秒，在CSV里是5秒。

此时要把CSV的时间减去2秒，才能与CAN一起计算。时间转换使用“原时间换成规定单位后，加offset”；因此CSV填写offset="-2s"。如果仪表晚开始2秒，则应加2秒。

两个来源的time字段可写成：

将下面第一段放在CAN来源的列表项内，与paths同级，替换该来源原有的time：

time:                 # 该CAN来源的时间设置
  clock: test_button  # 已确认的共同起点

将下面第二段放在CSV来源的列表项内，与time_column同级，替换该来源原有的time：

time:                 # 该CSV来源的时间设置
  unit: ms            # 输入时间列以毫秒计
  clock: test_button  # 与CAN使用同一个已确认起点
  offset: -2s         # 仪器比共同起点早启动2秒

这两段分别是一个来源内的字段，不是完整sources数组。CSV原值5000ms先变为5秒，再减2秒，得到共同时间3秒。完整多来源配置见CAN与CSV联合分析。

clock是对共同起点的声明。把两个不同起点强行写成相同名字不会真的同步数据。偏移量必须来自已知采集起点、同步记录或能确认发生在同一时刻的事件；如果不知道偏了多少，先分别分析，不能任意拼在一起算功率。

若两份文件都已有带日期和时区的绝对时间，可使用absolute方式统一到UTC时间。本版只支持已知的固定偏移，不会自动识别相似波形，也不会校正两个时钟越来越不同步的漂移。

时间对齐后，仍要检查信号是否有效。例如该时刻电压已经过期，就不能继续拿旧电压乘新的电流。可运行例子见CAN与CSV联合分析。

ASC和原始CAN CSV

can_asc和raw_can_csv都读取未解码的CAN报文。前者按指定ASC版本读报文，后者从原始报文列直接解码，两者都需要DBC；这和已经有电压/电流列的signal_csv不同。全部字段、日期/日内时间、通道和跨文件偏移见文本CAN输入。