tutorials.md

Tutorials

These examples follow the same rhythm I use while working: create or run something, record it, inspect the evidence, and only then write the report.

Motor response

Suppose I want to see how a simulated motor approaches its target speed. I start with deterministic data so I can repeat the exact run later:

datary generate motor-speed --seed 4 --duration 10 |
  datary record motor --format jsonl --time-field timestamp \
    --target-field target_rpm --response-field speed_rpm --unit speed_rpm=rpm
datary inspect motor --quality --plot speed_rpm,current_a --plot-kind line
datary inspect motor --plot speed_rpm --plot-max-points 500
datary report motor

The pipe sends one JSON object at a time into datary record. Datary preserves those lines in raw.log, writes accepted objects to records.jsonl, calculates metrics and quality findings, and then finalizes the session. inspect reads that evidence back; report turns it into a local Markdown narrative. Large plots downsample for display only and leave a .meta.json sidecar that records the algorithm and point counts.

Network comparison

Oh! Comparison is the point where I want intent to be explicit. Generate and record two network-latency sessions with different --noise, then compare latency_ms using:

datary compare baseline improved --field latency_ms --goal lower:latency_ms

The lower: goal is what gives Datary permission to calculate improvement or regression. Without it, Datary shows the measurements but does not invent a winner.

For network metrics, record the field roles explicitly:

datary record network-run --format jsonl \
  --time-field timestamp \
  --sequence-field sequence \
  --latency-field latency_ms \
  --bytes-field bytes

That gives the report enough meaning to calculate loss, duplicate rate, out-of-order packets, latency summaries, jitter, and throughput without guessing which column means what.

Counter and monotonicity expectations

Some fields only make sense when I tell Datary how they should behave:

datary inspect packet-run \
  --counter-field sequence \
  --monotonic-field bytes_received \
  --quality

This does not change the records. It asks for two additional checks and produces explainable findings if the selected fields decrease.