Time-series forecasting

Predict future values from past ones. The dataset is a single CSV where every row is one time step: a timestamp column, numeric feature columns and a numeric target. Rows must be in chronological order.

Folder layout

/data/shared/energy-demand/
└── demand.csv

Data CSV

timestamp,day_of_week,month,day_of_month,week_of_year,is_weekend,lag_1,moving_avg_7,value
2023-10-01,7,10,1,40,1,,,125.50
2023-10-02,1,10,2,40,0,125.50,,132.30
2023-10-03,2,10,3,40,0,132.30,,128.75
2023-10-07,6,10,7,40,1,152.40,132.75,148.60

Column	Meaning
`timestamp`	Fixed name. One value per row in ISO 8601 (`YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`). Rows must be sorted ascending; every value must parse; every value must be before today. Dates that read differently day-first and month-first (such as `03.04.2026`) are rejected — use ISO 8601.
feature columns	Numeric, declared in `schema`. Empty cells are allowed (stored as NULL) — lag and rolling-window features are typically blank at the start of the series.
target column (`value` here)	Numeric; named by `label.column`, not declared in `schema`.

Categorical features (region, segment, …) must be encoded as integers before ingest: every non-timestamp column in schema must be numeric.

Ingest with the CLI

Pass the CSV file, or a folder that holds only that CSV. Ingest the training and the test split separately:

tracebloc data ingest ./demand_train.csv --task time_series_forecasting --name energy_demand_train --intent train \
  --label-column value --label-policy bucket \
  --schema 'timestamp:TIMESTAMP,day_of_week:INT,month:INT,day_of_month:INT,week_of_year:INT,is_weekend:INT,lag_1:FLOAT,moving_avg_7:FLOAT,value:FLOAT'
tracebloc data ingest ./demand_test.csv --task time_series_forecasting --name energy_demand_test --intent test \
  --label-column value --label-policy bucket \
  --schema 'timestamp:TIMESTAMP,day_of_week:INT,month:INT,day_of_month:INT,week_of_year:INT,is_weekend:INT,lag_1:FLOAT,moving_avg_7:FLOAT,value:FLOAT'

--label-policy bucket is the default. Without --schema, the CLI infers a type for every column and types timestamp as DATETIME or DATE, which the ingestor also accepts; pass --schema (quoted) to pin the types, as above. --schema replaces the inferred schema, so list every column you want stored. Including the label column in --schema is fine: the ingestor drops it from the stored schema.

ingest.yaml

apiVersion: tracebloc.io/v1
kind: IngestConfig
category: time_series_forecasting
table: energy_demand_train
intent: train
csv: /data/shared/energy-demand/demand.csv
schema:
  timestamp: TIMESTAMP     # required; TIMESTAMP, DATETIME or DATE
  day_of_week: INT
  month: INT
  day_of_month: INT
  week_of_year: INT
  is_weekend: INT
  lag_1: FLOAT             # blank on the first row
  moving_avg_7: FLOAT      # blank until 7 rows of history exist
label:
  column: value
  policy: bucket

Field	Required	Meaning
`csv`	yes	Path to the data CSV.
`schema`	yes (with the CLI, inferred for you)	Must contain `timestamp` with a calendar type (`TIMESTAMP`, `DATETIME` or `DATE`) plus the numeric feature columns.
`label`	yes, object form	`column` names the target; `policy: bucket` keeps raw targets in your secure environment (the platform receives 64 hash buckets; stored rows keep the raw value).
`time_column`	leave out	The time column is always `timestamp`. Any other value is rejected at preflight.
`columns`	no	Per-column `unit` and `ordinal` facts.
`data_id`, `spec.csv_options`	no	See the contract.

What the ingestor checks

Check	Rejects
Time format	A `schema` without `timestamp`, or with `timestamp` typed as text or a number; a CSV without a `timestamp` column; unparseable values; day-first/month-first ambiguous dates.
Time ordered	Any pair of consecutive rows whose timestamps decrease.
Time before today	Any timestamp on or after today’s date.
Numeric columns	A non-numeric value in any schema column other than `timestamp`. Empty cells are allowed.
Data types	Duplicate headers, schema columns missing from the CSV, values that do not match their type (checked for every schema column except `timestamp`).

Plus the checks every ingest runs. There is no label-diversity check.

Sample dataset

The template ships 31 daily rows starting 2023-10-01 with calendar features (day_of_week, month, day_of_month, week_of_year, is_weekend as INT), lag and moving-average features (lag_1, moving_avg_7 as FLOAT, blank until enough history exists) and the target value — the rows shown above are from it. The ingest.yaml above ingests it as is; only csv: changes to wherever you staged the file.

Model settings for this dataset

When you link a model, the platform checks num_feature_points against the dataset (see model parameters by task). It must equal the number of stored columns minus the target and timestamp. For the sample, that is 7. The model-zoo templates default to 9 (1 for TimesFM), so edit it. Feature columns reach the model sorted by column name, whatever order the CSV or schema uses. The test split must hold at least sequence_length + forecast_horizon rows, or evaluation fails with Not enough data to create sequences. Training shortens sequence_length with a warning when the training split is too short, but evaluation does not. The model-zoo templates default to a sequence_length of 60 or 96 (512 for TimesFM), so lower it for a short series: with the 31-row sample as the test split, sequence_length + forecast_horizon must be 31 or less. By default, when the data has feature columns besides timestamp and the target, the target is scaled to the 0–1 range (MinMaxScaler) before training, so error metrics such as MAE, RMSE and MAPE are in scaled units, not in your data’s units. The accuracy value that a forecasting run reports has no meaning for this task.

Next steps

Ingest the data: Prepare Data
Shared rules for every template: Dataset templates

Overview

Create a Use Case

Join a Use Case

Environment Setup

Tools & Help

Releases

Time-series forecasting

Folder layout

Data CSV

Ingest with the CLI

ingest.yaml

What the ingestor checks

Sample dataset

Model settings for this dataset

Next steps

​Folder layout

​Data CSV

​Ingest with the CLI

​ingest.yaml

​What the ingestor checks

​Sample dataset

​Model settings for this dataset

​Next steps

Folder layout

Data CSV

Ingest with the CLI

ingest.yaml

What the ingestor checks

Sample dataset

Model settings for this dataset

Next steps