Configuration structure

Use YAML for hand-written configurations and JSON for exchange between tools. Both use the same fields. Analysis configurations require the integer config_version: 4. A missing or unsupported version is rejected. JSON Schema describes the accepted structure; it is not another configuration format.

The root sections below are siblings. For example, signals is not nested inside sources, and calculations is not nested inside dataset.

Root fields

Field	What it controls and what omission means
`config_version`	Required integer: `4`. Other analysis configuration versions are rejected.
`dataset`	Required analysis identity, normally just `name`. `entity` and `session` inherit that name. Omit `domain` to use the actual observed range.
`sources`	Input definitions. At least one must exist after shared definitions are expanded. ASC/BLF can be detected automatically; CSV and memory sources need their appropriate source type and reader settings.
`signals`	Signal definitions, which may come from shared definitions. CAN data can obtain `dtype` and `unit` from the DBC; decoded CSV and memory inputs need explicit definitions. See the signal chapter for `valid_for` defaults.
`imports`	Optional ordered list of local shared files. They can supply `sources`, `signals`, and `derived`, one level deep. Duplicate definitions are rejected; intentional changes use `overrides`.
`overrides`	Optional changes to allowed fields of existing named definitions. It cannot create new definitions.
`lookups`	Optional. Map an input to a value from calibration points; see the lookup and interpolation field reference and voltage example.
`derived`	Optional named expressions; defaults to empty. Units are inferred, and an explicitly supplied unit is checked.
`transforms`	Optional. Produce a new time series such as a rolling mean or rate; see time-series transforms.
`aggregations`	Optional. Summarize scalar calculation results for sessions, events or segments and request/response delays, or count events and final window segments within this analysis; for example, P95 across load means. See Result aggregation.
`rules`	Event rules, each selected by `rule_type`.
`presets`	Optional ready-made combinations selected by `preset_type`, including charging, fault pairing, and threshold alarms.
`windows`	Time ranges around events.
`sequences`	Request/response pairing and latency analysis.
`calculations`	Ordinary calculations selected by `operation`, with an expression or condition and an optional scope.
`message_calculations`	Calculations performed for individual matching messages. They have different interval semantics from ordinary time integration.
`intervals`	Shared calculation-interval choice; defaults to actual intervals. A local `interval` overrides the shared choice.
`outputs`	Defaults to readable Chinese CSV tables and a manifest. CSV/JSONL can be selected explicitly. Contribution details, signal exports, and raw CAN exports are off unless requested.
`execution`	File-reading worker count, calculation implementation, resource limits, and handling of incomplete data. Single-source ASC/BLF examples explicitly select `process_count: 4`; omission still defaults to one and the default backend setting is auto, selecting reference or numpy from the whole plan. See Execution settings.
`diagnostics`	Optional diagnostics; all switches default to false.
`metadata`	Optional notes, default `{}`. `device_label` accepts any nonblank string and defaults to `pending` for both analysis and exports; other notes do not affect computation.

Field names are case-sensitive. Unknown fields are errors. A diagnostic may suggest a spelling correction, but the program does not silently accept it. Duplicate YAML keys and conflicting object names are also rejected. Preserve DBC names exactly; use a signal's user-facing name as your convenient alias.

Keeping ordinary configurations short

Omit a field when its documented default, inheritance, or reliable detection already gives the behavior you want. User-assigned names use name; references identify their target with fields such as source, rule, or window. A CAN message number is frame_id, and the signal's DBC name is field.signal. Expressions refer to configured signal names.

Basic examples retain an explicit execution choice: up to four file-reading workers for a single ASC/BLF source. Add this root-level fragment to a complete configuration. If execution already exists, set only its process_count child and keep its other settings; do not add a second parent key.

yaml

execution:          # Control how this analysis runs
  process_count: 4  # Up to four file-reading workers, capped by the number of files

This is an explicit recommendation used by the manual; the program default remains one. A single file is not split among workers, and multiple files still form one continuous analysis. CSV, memory, and multi-source analyses use one. For independent tasks, set process_count at the batch configuration root and keep each child analysis at one. See Execution settings for supported combinations and overrides.

Starting with analysis.yaml, replace its entire calculations list with the following to integrate the power signal already defined in that file:

yaml

calculations:            # Requested statistics or selected rows
  - name: energy         # Name used to identify and reference this object
    operation: integral  # Calculation to apply to the expression
    expr: power          # Formula using the declared signal or derived names

Keep every other section, including sources, signals, and execution settings. Do not append a second calculations key. Specify a calculation scope or an interval only when this task needs a choice other than the defaults.

Reader settings are grouped under reader; value conversions are grouped under conversion. time.clock identifies a shared time origin, whereas resampling.start identifies the start of a sampling grid. These names describe different choices.

A dotted path such as dataset.domain.start identifies where a field belongs. It is not a literal YAML key; see Configuration syntax. Omission uses the documented default. Whether explicit null is accepted depends on the field: for example, execution.spool_quota_bytes: null sets no additional spool disk quota. Invalid types and values are rejected.

Ordinary execution checks, calculates, and retains what the requested results require. Additional diagnostics are enabled explicitly.

Configuration language

The loader accepts a single JSON or restricted YAML document with string-keyed mappings, lists, and JSON-compatible scalar values. Numbers must be finite, and nesting is limited to 64 levels. YAML comments and multiline strings are supported; duplicate keys, non-string keys, multiple documents, custom tags, anchors, aliases, and merge keys are rejected. There is no environment substitution or template expansion. Dates and durations remain text. A YAML version directive, if present, must specify 1.2.

Read Configuration file syntax before editing nested structures or list items.

Time and statistics terms

A signal's valid_for limits how long its most recent value can be used after an update. Once that time has passed, the value becomes unknown. A timeout limits how long a rule waits. A minimum_duration determines how long a condition must hold before it qualifies. These settings serve different purposes.

An arithmetic sample average and a time-weighted average can also differ. In the teaching input, sample_mean gives 6 W, while the time-weighted result is 38 / 6 W. See Calculations for the values and intervals used.

Finding a feature or field

Start with the relevant task chapter, such as Event windows or Calculations. Use the configuration field index to find every root section and its detailed field reference.

Locating a configuration error

When available, a diagnostic identifies the file, line, column, original field path, object, error code, offending value, and a correction hint. If a field is missing, the location points to the nearest existing parent rather than inventing a line for the missing field.

Use validate for a text diagnostic or machine-readable JSON diagnostic. Schema and editor setup explains editor validation without adding an unsupported $schema field.