Data sources

Root-level sources is a list describing where records come from and how to interpret their original times. With one source, omit its name and signals[].source. BLF/ASC are detected by extension. After choosing log paths and DBC, configure signal bindings. dataset defines analysis identity and the requested range.

For ASC/BLF sources, optional file_merge controls record ordering: concatenate (default) consumes files in declared order; time_order validates each file and stably merges a verified shared timeline. It rejects null and is unsupported for CSV/memory. Set execution.process_count independently. See continuous-file multiprocessing.

A reader opens the source and interprets its records. source_type selects the format: CSV physical-value text is parsed into values; CAN bytes are decoded through a DBC. Signals then name, optionally convert, and validate those values. “Original value” therefore depends on the stage: in a signal declaration it has already been parsed/decoded and is not necessarily the file's original text or bytes.

Basic single-source ASC/BLF configurations use execution.process_count: 4: workers read and decode different files, then feed one analysis session in the selected order. A single file uses at most one reading worker. CSV, memory, and multi-source analyses currently keep process_count: 1. For independent experiments, use batch execution to run whole tasks in parallel. The program default remains one; see continuous-file multiprocessing for supported combinations.

Choose an input format

AnalysisRunner supports the five explicit types can_blf, can_asc, raw_can_csv, signal_csv, and memory, plus default asc_or_blf, which reads ASC and BLF sequentially by extension. signal_csv reads decoded physical values; it cannot treat message bytes directly as voltage or current.

Run a complete task first

Start with the supplied ASC and DBC in the BLF/ASC quick start and check 38 J. Replace its path with your own BLF or log directory without an intermediate CSV conversion.

chronaxis run analysis.yaml --output can-result

Run from the examples directory with an output directory that can be reused. CSV and memory examples serve decoded tables and programmatic records; they are not prerequisites for CAN analysis.

The offset example demonstrates a known 2-second shift: original 0 becomes 2 seconds, while energy remains 38 J. Set common clock and offset values only from established synchronization evidence; defaults do not synchronize clocks.

The following tables adapt examples to your input. Do not substitute null for omission except where explicitly allowed. Unknown fields or wrong structures are rejected when loading; missing files, mismatched headers, and malformed cells are reported when read.

Fields common to source objects

Paths below are relative to sources[]. Thus sources[].paths means the paths child of each source list item; dots and [] describe nesting, not literal YAML keys. See configuration and the format-specific text input fields.

load_analysis_plan resolves paths from the declaring configuration file. AnalysisPlan.from_dict uses base_dir, or the current directory when omitted.

Directories and continuous files

This is an editing fragment. Starting with analysis.yaml, replace its root sources list with your log directory and DBC, and set process_count inside root execution. Keep the dataset, signal and calculation sections. The paths must exist and the DBC must contain the signals referenced by the configuration.

sources:                # Input sources used by this analysis
  - paths: data/can     # Directory, relative to this configuration
    dbc_by_channel:     # DBC files indexed by user-facing CAN channel
      '1': network.dbc  # DBC for public channel 1
execution:              # Sibling of sources; control how the analysis runs
  process_count: 4      # Up to four file-reading workers, capped by the number of files

Files part1.asc, part2.blf, and part10.asc use at most three reading workers. The main process still consumes them in order 1, 2, 10 and retains signal and event state between files. Use paths: data/can/*.asc for ASC only and explicit data/can/**/*.asc for subdirectories. Empty directories or unmatched patterns are errors, not silently skipped. Explicit [part10.asc, part2.asc] retains that order.

When a wildcard pattern ends in the literal extension .asc, .blf, .csv, or .txt, extension letters are matched without regard to case. For example, data/can/*.asc also finds part10.ASC, and *.bLf also finds .BLF files; the source type still filters the accepted formats. Filename stems, directory names, and other wildcard patterns retain the operating system's matching rules. This does not make the whole path case-insensitive. Subdirectory recursion still requires explicit **.

For known per-file offsets, write paths: [{path: part1.asc, offset: 0s}, {path: part2.asc, offset: 100s}]. They add to source time.offset. These offsets apply to default ASC/BLF, explicit can_asc, and raw_can_csv; signal_csv and explicit can_blf support only source-wide time.offset. Applicable sources also accept an offsets array, but not together with embedded file offsets. Use batch tasks for independent experiments.

All time fields

These fields are inside sources[].time. Time unit is not signals[].unit.

The field is always sources[].time.timezone, though accepted values depend on format. ASC/raw CSV reject explicit null. For signal_csv/memory, null means no timezone supplement. A date already containing a timezone uses its own offset. Integer minute-offset notation is not accepted.

CAN sources and signal location

Place the first excerpt in root sources, the second in root signals. These are partial configurations, requiring your actual trial.blf, network.dbc, and remaining task declarations. Replace existing lists rather than nesting a second parent key inside an item.

sources:                # Input sources used by this analysis
  - path: trial.blf     # Replace with your actual input
    dbc_by_channel:     # DBC files indexed by user-facing CAN channel
      '1': network.dbc  # DBC for channel 1; channel keys are strings

signals:                   # Signals available to expressions
  - name: voltage          # Name used to identify and reference this object
    field:                 # Locate the original input field
      frame_id: 0x100      # CAN message identifier; decimal or prefixed hexadecimal/binary
      signal: PackVoltage  # Actual case-sensitive DBC name

This assumes the DBC supplies a unit and message period. Numeric type, unit, and frame type are inferred; validity defaults to three periods. Add period or valid_for when the needed period is unavailable. Add location fields only when multiple channels/frame candidates cannot be distinguished.

Common CAN fields

Fields are in sources[] and apply to BLF, ASC, and raw-message CSV. signal_csv and memory do not use DBC.

Additional options for the BLF reader entry point

Only the can_blf entry point accepts these options: explicit source_type: can_blf, or a default source containing only BLF with no per-file offsets. Mixed ASC/BLF, can_asc, and raw_can_csv do not accept them explicitly.

reader.decode_policy: CAN decoding policy

This child of each CAN source's reader controls DBC decoding in asc_or_blf, can_blf, can_asc, and raw_can_csv. It is neither interval selection nor signal conversion. The excerpt belongs inside a source item, replacing its reader mapping where appropriate:

reader:                  # Input-format parsing options
  decode_policy: strict  # Length checks and decoding-failure behavior

Default asc_or_blf allows mixed formats; explicit can_asc/can_blf restrict them. Lists preserve order, while directories/wildcards use natural order. Text/column parsing happens first: decoding policy cannot turn malformed text into a valid frame. See CAN fields for the supported classic-CAN/DBC-FD compatibility.

Decoding failures by reader path

These policies apply to selected data frames. Use strict for full-length records, partial for explicitly accepted short records, and legacy only to retain a particular historical path.

The decoding-failure rows specifically mean cantools DecodeError. In serial pure-BLF decoding with a unique DBC definition for the ID, other ordinary Exceptions from the decoding function also produce invalid values for that message. Duplicate-ID definitions and file-parallel decoding only handle DecodeError this way; other exceptions propagate. Length checks, malformed text, invalid input time, and I/O errors are not bypassed. Partial does not ignore every error or fill missing short-frame fields with zero.

reader.decode_scope: all broadens attempted decoding; it does not mean every frame passes DBC checks. This option is available in the serial pure-BLF entry point. File multiprocessing and time_order require requested. Under all, frame categories are handled as follows:

This table describes decoding scope. Input structure, required timestamps and I/O errors retain their own rules. input_check: full checks whole-source time order; it does not add whole-log DBC certification.

Normalized source_type determines the path. can_asc, raw_can_csv, and retained mixed asc_or_blf use the text CAN adapter. can_blf uses the pure-BLF length and DecodeError policies in the table; other exceptions differ between serial and parallel execution as described above. Omitted/asc_or_blf normalizes pure ASC to can_asc, including with offsets; pure BLF without offsets becomes can_blf. Mixed formats, or pure BLF with offsets, retain asc_or_blf. A single filename extension therefore does not establish legacy behavior.

signals[].field: select a CAN signal

BLF, ASC, and raw CAN CSV share the same binding structure. frame_id and signal are required; a unique DBC channel allows omitted channel. message is not accepted. Channel, ID, and signal name locate the value.

JSON needs "frame_id": "0x100" or "frame_id": 256, because prefixed numeric literals are invalid JSON. YAML can use frame_id: 0x100. Prefixes are case-insensitive; negatives, floats, Booleans, and octal prefixes are rejected. Omission means automatic frame-type recognition; explicit null does not.

JSON Schema checks ID text syntax; plan loading also converts it to an integer and validates the range. For example, is_extended: false with frame_id: "0x800" is rejected because 2048 exceeds 2047. Editor schema success does not replace chronaxis validate analysis.yaml.

Suppose standard and extended message 0x100 both contain PackVoltage. A log containing only the extended frame can resolve the definition using actual flags. If a matching standard frame later appears for the same binding, the program asks for is_extended rather than merging both into one signal. Missing IDs or misspelled signal names produce a specific missing-definition error; type flags cannot conceal that problem.

The supported case where the DBC says FD but the actual log is classic CAN remains compatible and records a notice. Explicit type selection does not modify input frames. Each source uses one channel and DBC, continuous files retain order, and DBC factor/offset must not be applied again.

Decoding scope versus timestamp-check scope

sources[].reader.decode_scope applies only to the pure-BLF entry point: default requested decodes required messages; all broadens attempted decoding. The table above describes skips and failures; it does not establish that every frame passed DBC checks.

sources[].reader.input_check applies to all CAN sources: default auto follows task requirements; full checks whole-source ordering. It does not enable all signal decoding or diagnostic output.

A whole-file fixed-period message-energy sum may not need message times. Activities and time-range selections do. Inspect input_requirements in explain for required signals and time checks. Unchecked records cannot be called verified.

For ordinary ASC and mixed ASC/BLF, auto requires only selected channels/IDs to advance in original order. Microsecond regressions in unrelated Tx frames do not block analysis. Earliest/latest source times are collected during the same read separately from ordering checks; original timestamps are unchanged. Full checks/raw export reject whole-source regressions. Target regressions, including across continuous files, always fail; no automatic sorting, clamping, or cleaning occurs. ASC relative increments still accumulate across all relevant time rows: skipping unrelated decoding does not discard increments. Raw CSV retains its own column parsing/time rules; ASC behavior does not imply arbitrary malformed CSV rows are ignored.

Rules, windows, calculations, and exports can omit dataset.domain and use actual observation. Multiple sources use the union of observed ranges. Empty observation produces no events and null session statistics. A whole-file message sum that needs no time can avoid constructing a time domain, but time filters, events, and other temporal features still require time checks. Omitting domain does not disable them. See analysis range and message calculations.

CSV: every row is an explicit update

Signal CSV batches depend on the data actually read and the remaining budget; execution.batch_rows is an upper limit, and the default is usually suitable. Insufficient capacity for even the smallest required record and handoff state still causes failure. See Execution settings for batch behavior and memory limits.

This partial root sources section requires actual part1.csv and part2.csv files containing time_ms and the referenced signal columns. Replace the existing root list; do not nest another sources key inside an item.

sources:                           # Input sources used by this analysis
  - paths: [part1.csv, part2.csv]  # File, continuous file list or directory; relative to this configuration
    source_type: signal_csv        # Input adapter; CSV or memory must be declared explicitly
    time_column: time_ms           # Exact header
    time:                          # Input timestamp interpretation
      unit: ms                     # Unit of the input timestamp values
    reader:                        # Input-format parsing options
      missing_values: ['', NA]     # Invalid updates, not zero

Choose exactly one of path and paths. Explicit lists retain order; discovered files use natural order. If part 1 ends at 10 seconds and part 2 restarts at zero, joining them directly fails due to backwards time.

With the example missing tokens, current 5 A followed by NA becomes unknown at the latter row, not held at 5 A. Enable diagnostics.trace and read input_trace only when you need input locations; default summaries do not retain per-cell original positions.

The default encoding removes only a file-leading BOM; U+FEFF inside a column name or cell is preserved. Empty names at the end of a header are allowed: time,power, accepts rows 0,100, and 0,100. The corresponding unnamed cells must be empty; whitespace or other content is an error and requires a column name. Empty names in the middle, duplicate names, missing named cells, and rows wider than the original header still fail. CSV quoting, multiline cells, and physical error-line reporting remain in effect.

Bind original Current_mA as current with this root signals excerpt:

signals:               # Signals available to expressions
  - name: current      # Name used to identify and reference this object
    field: Current_mA  # Locate the original input field
    dtype: float64     # Analysis value type
    unit: A            # Unit in which this value is interpreted or the result is displayed
    valid_for: 200ms   # Example; establish for actual acquisition
    conversion:        # Optional unit conversion after decoding
      input_unit: mA   # Unit of the parsed or decoded input value
      scale: 0.001     # Explicit mA-to-A conversion

This explicitly converts milliamperes to amperes. valid_for is illustrative and needs an acquisition-based choice in a real task. Expressions use current even though the column has another name.

Memory: put records directly in configuration

This complete minimal memory configuration defines only power and needs no external files. Its signal type, unit and validity are shown in the same example. Power is 2 W from 0 to 1 s and 4 W from 1 to 2 s, so the integral is 2×1+4×1=6 J.

config_version: 4          # Current analysis configuration format
dataset:                   # Name and requested analysis interval
  domain:                  # Integrate the half-open interval [0, 2) seconds
    end: 2s                # Right endpoint is not an extra interval
    start: 0s              # Include the start
  name: memory_power       # Name of this synthetic analysis
sources:                   # Explicit records; no external data files
  - rows:                  # Each record updates the stated field
      - time: 0s           # First observation
        values:            # Fields updated at this timestamp
          power: 2         # 2 W, interpreted by the signal below
      - time: 1s           # Replace the previous power value
        values:            # Fields updated at this timestamp
          power: 4         # 4 W for the second interval
      - time: 2s           # Marks the observed endpoint
        values:            # Fields updated at this timestamp
          power: 4         # No duration remains inside the requested interval
    source_type: memory    # Read records from this configuration
signals:                   # Type, unit and validity of the input field
  - dtype: float64         # Numeric values used in the calculation
    field: power           # Original key in rows[].values
    name: power            # Name used by the expression
    unit: W                # Watts
    valid_for: 3s          # Each value remains valid across these one-second intervals
calculations:              # Requested output
  - name: energy           # Result name
    operation: integral    # Value multiplied by its valid duration
    expr: power            # Integrate the declared power signal
execution:                 # Memory input reads in the current process
  process_count: 1         # Memory plans require this limit

From the configuration directory run python -m chronaxis run input-memory-minimal.yaml --output memory-result. Use the completion manifest to find the session results: energy（J） is 6 and energy：状态 is 完整 (complete). To add a Boolean signal later, use native true/false values; integer 0/1 inputs instead require dtype: bool and choices: [[0, false], [1, true]] on that signal before referring to it in a condition.

Memory timestamps require units, or an explicit absolute date/time/timezone. The three records above are synthetic, allowing an expected answer before checking the implementation. For large actual inputs, use CSV/BLF streaming instead of placing the whole dataset in configuration. SourceSpec/MemoryRow and MemorySourceAdapter are Chinese implementation references for typed interfaces.

Synchronize multiple sources

“3 seconds” in two files need not be the same instant. If CAN starts at the experiment button and a CSV instrument started 2 seconds earlier, 3 seconds after the button is CAN 3 seconds and CSV 5 seconds.

Subtract 2 seconds from CSV time to combine them. Conversion first changes units, then adds offset, so use offset: -2s. If the instrument started 2 seconds later, add 2 seconds instead.

Put this block inside the CAN source item, beside paths, replacing its existing time:

time:                 # Time settings for the CAN source
  clock: test_button  # Established common origin

Put this separate block inside the CSV source item, beside time_column, replacing its existing time:

time:                 # Time settings for the CSV source
  unit: ms            # Input time column uses milliseconds
  clock: test_button  # Same established origin as CAN
  offset: -2s         # Instrument started 2 seconds earlier

Each block belongs to one source; neither is a complete sources list. CSV 5000 ms first becomes 5 seconds, then shifts to common time 3 seconds. See the CAN/CSV example for a complete configuration.

clock declares a known common origin. Assigning the same name to unrelated origins does not synchronize them. Derive offsets from known acquisition starts, synchronization records, or an identifiable simultaneous event. If the offset is unknown, analyze separately rather than combine arbitrarily to calculate power.

If both files contain dated, zoned absolute timestamps, use absolute time normalized to UTC. This version supports known fixed offsets; it does not automatically match waveforms or correct clock drift.

After alignment, signal validity still matters: an expired voltage cannot be multiplied by a new current. See the runnable joint CAN/CSV example.

ASC and raw CAN CSV

can_asc and raw_can_csv both read undecoded CAN messages and require a DBC. The former reads the selected ASC dialect; the latter decodes mapped raw-message columns. This differs from signal_csv, which already contains voltage/current columns. See text CAN inputs for all fields, dates/time-of-day, channel origins, and per-file offsets.