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/inspectdata/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:
- checks the time axis (ordering, gaps, regular step) and computes descriptive statistics
- runs a significance-tested periodicity check and autocorrelation (here a 25-sample, 0.5 s period)
- screens for regime changes
- writes a structured JSON summary with next steps across anomaly detection, segmentation, decomposition, spectral analysis, and forecasting, plus a findings ledger
- 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-re200Both 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/forecastCompares 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-longerKey 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/activityThis workflow:
- reads a labeled-stream CSV
- sets aside held-out data first: whole label segments, or whole subjects or sessions when
--group-colis given - sweeps candidate window sizes on the remaining data only
- scores the selected window on the held-out data and reports that score
- 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-industrialKey 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-subjectsWithout --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.csvThen 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-wisdmOutput artifacts are the same as the synthetic walkthrough: window_selection.json, window_scores.png, eval.json, confusion_matrix.png, and report.md.