Trace formats

Trace::from_path reads a trace from disk and chooses the reader from the file extension. Delimited text and classic MATLAB files load on the default build; the columnar, database, and log formats each sit behind a Cargo feature, so a build carries only the parsers it needs. Whatever the format, the time column is found by name and every other numeric column becomes a signal.

Formats and extensions

A .mat file is sniffed from its header banner: a v7.3 file is HDF5 underneath and routes to the HDF5 reader, so it needs the hdf5 feature, while the classic v5/v6/v7 container reads on the default build through a pure-Rust parser. When an extension's feature is off, from_path returns an Ingest error naming the feature to enable rather than failing to compile. An extension the table does not list is rejected the same way, with an Ingest error naming the unrecognized extension; from_path never guesses a parser from content.

Reading a trace

use sentil::Trace;

let trace = Trace::from_path("flight.parquet")?;

For data already in memory, two readers take a string directly and need no feature beyond ingest:

use sentil::Trace;

let trace = Trace::from_csv_str("time,x,y\n0,10,1\n1,5,2\n2,1,3")?;
assert_eq!(trace.variables(), vec!["x", "y"]);

Trace::from_tsv_str is the same reader split on tabs.

How the time column is found

The reader scans the header for a known time name, in priority order: time, timestamp, t, time_s, time_sec, time_ms, time_ns, elapsed, elapsed_time, epoch. If none matches, the first column is taken as the time axis. Every remaining numeric column becomes a signal under its header name. The time values are read in whatever units the source carries, and a formula's interval bounds are read in those same units, so the axis and the windows stay consistent without the reader guessing a scale. A null cell in a numeric column, or a non-numeric time column, is rejected with the offending column named.

The command line

The CLI carries its own text readers, so csv, tsv, txt, json, and ndjson load in every build, from a file or from standard input. It is also more forgiving than from_path about extensions: an unknown extension over UTF-8 content is sniffed as text, so a .dat or .log file holding CSV still loads. A binary file falls through to Trace::from_path, which reads classic .mat in the stock binary. The stock binary carries none of the feature-gated readers; cargo install sentil-cli --features formats enables Parquet, Arrow, and SQLite, and the hdf5 and mcap readers are not reachable from the CLI at all.

sentil check -f 'G (speed > 5)' -t speeds.csv

For the trace model itself, its shape and its invariants, see signals and traces. The full engine feature set is on the Cargo features page.