Skip to main content

Workflow Walkthroughs

Step-by-step guides for the first-class workflows. The commands assume a source checkout (repo-root data/ files and uv run).

Profile note: - Base install supports inspect-series plus a light seasonal_naive forecast baseline. - Use ts-agents[recommended] for the full forecasting and activity-recognition walkthroughs below. - From a source checkout, plain uv sync matches the base CLI-first profile; use uv sync --extra recommended for the same recommended workflow stack.

Inspect a series

1. Run the workflow

uv run ts-agents workflow run inspect-series \
  --input data/synthetic_signals.csv \
  --time-col t \
  --value-col periodic \
  --output-dir outputs/inspect

data/synthetic_signals.csv is a 50 Hz known-answer table (see data/README.md); the periodic column is a 2 Hz sine plus noise. This single command:

  1. checks the time axis (ordering, gaps, regular step) and computes descriptive statistics
  2. runs a significance-tested periodicity check and autocorrelation (here a 25-sample, 0.5 s period)
  3. screens for regime changes
  4. writes a structured JSON summary with next steps across anomaly detection, segmentation, decomposition, spectral analysis, and forecasting, plus a findings ledger
  5. writes a Markdown report and an autocorrelation plot

2. Interpret the outputs

All artifacts land in outputs/inspect/ by default.

Artifact What it tells you
summary.json Time axis, stats, periodicity test, autocorrelation, regime screen, recommended next steps, and a forecast recommendation section
ledger.json Structured findings ledger for downstream agent/model-selection steps
autocorrelation.png Visual lag structure for the inspected series
report.md Markdown summary of the diagnostic run

3. Customize the run

# Inline JSON instead of a file, with a longer autocorrelation horizon
uv run ts-agents workflow run inspect-series \
  --input-json '{"series":[1,2,3,4,5,6,7,8,9,10]}' \
  --max-lag 12 \
  --output-dir outputs/inspect-inline

# Bundled smoke fixture (5 points per run)
uv run ts-agents workflow run inspect-series \
  --run-id Re200Rm200 \
  --variable bx001_real \
  --output-dir outputs/inspect-re200

Both of these series are too short for the periodicity test, so the runs report quality_status: degraded with the periodicity_not_assessed quality flag.

Key flags:

Flag Default Options
--input / --value-col / --time-col off CSV, parquet, or JSON file and its columns
--input-json off inline JSON or JSON file path
--run-id / --variable off bundled short_real.csv smoke fixture (5 points per run)
--max-lag auto any positive integer
--output-dir workflow-specific temp path any path

Forecasting comparison

1. Run the workflow

uv run ts-agents workflow run forecast-series \
  --input-json '{"series":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]}' \
  --horizon 5 \
  --methods seasonal_naive,arima,theta \
  --output-dir outputs/forecast

Compares forecasting methods on a deterministic inline series and writes comparison artifacts.

2. Interpret the outputs

Artifacts land in outputs/forecast/ by default.

Artifact What it tells you
forecast_comparison.json Per-method RMSE, MAE, MAPE and the best method
forecast_comparison.png Overlay plot of each method’s forecast vs actuals
forecast.json The selected best-model forecast in JSON form
forecast.csv The selected best-model forecast as CSV
report.md Markdown table with metrics and a recommendation

Example report snippet:

Compared Methods: arima, theta | Best Method (RMSE): arima
arima: RMSE=0.0000, MAE=0.0000, MAPE=0.00%
theta: RMSE=0.0148, MAE=0.0134, MAPE=0.07%
Recommendation: ARIMA (RMSE: 0.0000)

3. Customize the run

# More methods and a longer horizon
uv run ts-agents workflow run forecast-series \
  --input-json '{"series":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20]}' \
  --methods seasonal_naive,arima,ets,theta \
  --horizon 8 \
  --output-dir outputs/forecast-longer

Key flags:

Flag Default Options
--methods seasonal_naive,arima,theta seasonal_naive, arima, ets, theta (comma-separated)
--horizon 1 Any positive integer
--input / --value-col / --time-col off CSV, parquet, or JSON file and its columns
--run-id / --variable off bundled short_real.csv smoke fixture (5 points per run)
--output-dir workflow-specific temp path Any path

Activity recognition (synthetic data)

1. Generate data and run the workflow

uv run python data/make_synthetic_labeled_stream.py \
  --scenario gait --seconds 40 --seed 1337 \
  --out data/demo_labeled_stream.csv
uv run ts-agents workflow run activity-recognition \
  --input data/demo_labeled_stream.csv \
  --label-col label \
  --value-cols x,y,z \
  --output-dir outputs/activity

This workflow:

  1. reads a labeled-stream CSV
  2. sets aside held-out data first: whole label segments, or whole subjects or sessions when --group-col is given
  3. sweeps candidate window sizes on the remaining data only
  4. scores the selected window on the held-out data and reports that score
  5. writes plots, JSON metrics, and a Markdown report

eval.json includes details.chance_balanced_accuracy. With the balanced_accuracy metric, a held-out score that does not beat chance is flagged score_at_or_below_chance. If the --time-col values decrease (across the stream, or within a group when --group-col is given), the run is flagged non_monotonic_time and rows are used in input order.

2. Interpret the outputs

All artifacts land in outputs/activity/ by default.

Artifact What it tells you
window_selection.json Per-window scores and the chosen best_window_size
window_scores.png Visual score vs window size
eval.json Final metrics, confusion matrix, class counts
confusion_matrix.png Heatmap of predicted vs true labels
report.md Markdown summary of the workflow run

The synthetic classes are easy to separate, so these runs report quality_status: degraded: the 40-second stream above is flagged too_few_windows among others, and longer streams are flagged perfect_metrics. Read quality_flags before quoting the score.

3. Customize the run

# Different synthetic scenario
uv run python data/make_synthetic_labeled_stream.py \
  --scenario industrial --seconds 40 --seed 1337 \
  --out data/demo_labeled_stream_industrial.csv

# Narrower sweep with an explicit classifier and metric
uv run ts-agents workflow run activity-recognition \
  --input data/demo_labeled_stream_industrial.csv \
  --label-col label \
  --value-cols x,y,z \
  --window-sizes 32,64,128 \
  --classifier minirocket \
  --metric balanced_accuracy \
  --output-dir outputs/activity-industrial

Key flags:

Flag Default Options
--window-sizes 32,64,96,128,160 Comma-separated integers
--classifier auto auto, minirocket, rocket, knn
--metric balanced_accuracy accuracy, balanced_accuracy, f1_macro
--group-col off Subject/session column; windows never span groups and whole groups are held out
--output-dir workflow-specific temp path Any path

Activity recognition (WISDM data)

This WISDM walkthrough is a source-checkout workflow. It uses the repo-root dataset data/wisdm_subset.csv, which is not bundled into the published wheel.

Multi-subject data: hold out whole subjects

data/wisdm_subset.csv holds two subjects. Pass --group-col so windows never span subjects and the reported score comes from a subject the window selection never saw (leave-subject-out):

uv run ts-agents workflow run activity-recognition \
  --input data/wisdm_subset.csv \
  --label-col label \
  --value-cols x,y,z \
  --group-col subject_id \
  --output-dir outputs/activity-wisdm-subjects

Without --group-col, held-out segments come from the same subjects as the training data, so the score can overstate performance on a new person.

Build a custom WISDM stream

To download the full WISDM dataset and build your own labeled stream:

python data/make_demo_labeled_stream_wisdm.py \
  --subject 1600 --device watch --sensor accel \
  --activities walking,jogging,sitting,standing \
  --trim-policy per_class_seconds \
  --per-class-seconds walking=180,jogging=60,sitting=180,standing=180 \
  --out data/demo_labeled_stream.csv

Then run the workflow on that CSV:

uv run ts-agents workflow run activity-recognition \
  --input data/demo_labeled_stream.csv \
  --label-col label \
  --value-cols x,y,z \
  --output-dir outputs/activity-wisdm

Output artifacts are the same as the synthetic walkthrough: window_selection.json, window_scores.png, eval.json, confusion_matrix.png, and report.md.