Forecasting

NoriTSForecaster converts one or many time series into regression features and reconstructs point and quantile forecasts. The quickstart below runs Nori locally with an explicitly selected model.

Quickstart

Install the forecasting dependencies

Follow Installation and choose the hosted or local forecasting extra.

Create a history DataFrame

Provide timestamp and target columns, ordered from oldest to newest.

import numpy as np
import pandas as pd
from synthefy.nori_ts import NoriTSForecaster

periods = 500
history = pd.DataFrame({
    "timestamp": pd.date_range("2024-01-01", periods=periods, freq="h"),
    "target": 10 + np.sin(2 * np.pi * np.arange(periods) / 24),
})

Forecast the horizon

predict_df returns one row per future timestamp.

forecaster = NoriTSForecaster(
    mode="local",
    model="nori-30m",
    quantiles=[0.1, 0.5, 0.9],
)
forecast = forecaster.predict_df(history, prediction_length=48)

print(forecast.columns.tolist())
print(forecast.index.names)
print(forecast.shape)

['target', '0.1', '0.5', '0.9']
['item_id', 'timestamp']
(48, 4)

target is the median forecast. The other columns contain the requested quantiles.

Choose where it runs

The quickstart uses mode="local". To run the same feature preparation and forecast reconstruction against hosted Nori, change only the backend configuration:

import os
from synthefy import SynthefyNoriClient
from synthefy.nori_ts import NoriTSForecaster

client = SynthefyNoriClient(
    mode="remote",
    model="synthefy/nori-30m",
    api_key=os.environ["SYNTHEFY_NORI_API_KEY"],
)
forecaster = NoriTSForecaster(
    client=client,
    quantiles=[0.1, 0.5, 0.9],
)
forecast = forecaster.predict_df(history, prediction_length=48)

There is no separate forecasting endpoint. The workflow prepares numeric X_train, y_train, and X_test locally, then sends the unchanged regression contract through the selected client backend. Use mode="sagemaker" with endpoint_name= and region_name= for your AWS endpoint.

Multiple series

Add an item_id column to forecast several series in one call. Nori fits and forecasts each series independently.

import numpy as np
import pandas as pd
from synthefy.nori_ts import NoriTSForecaster

periods = 300
t = np.arange(periods)
timestamps = pd.date_range("2024-01-01", periods=periods, freq="h")
history = pd.concat(
    [
        pd.DataFrame({
            "item_id": "north",
            "timestamp": timestamps,
            "target": 10 + np.sin(2 * np.pi * t / 24),
        }),
        pd.DataFrame({
            "item_id": "south",
            "timestamp": timestamps,
            "target": 20 + np.sin(2 * np.pi * t / 24 + np.pi / 4),
        }),
    ],
    ignore_index=True,
)

forecast = NoriTSForecaster(
    mode="local",
    model="nori-30m",
    quantiles=[0.1, 0.5, 0.9],
).predict_df(history, prediction_length=24)

print(forecast.groupby(level="item_id").size().to_dict())

{'north': 24, 'south': 24}

Future-known covariates

Pass future_df= when a numeric feature is known across the forecast horizon. For example, you know a planned promotion before prediction and can supply it for both the history and future rows. Use target_column= to keep a domain name such as sales in both the input and forecast.

import numpy as np
import pandas as pd
from synthefy.nori_ts import NoriTSForecaster

periods = 300
horizon = 24
t = np.arange(periods)
timestamps = pd.date_range("2024-01-01", periods=periods, freq="h")
promotion = ((t % 72) >= 60).astype(float)

history = pd.DataFrame({
    "item_id": "store-a",
    "timestamp": timestamps,
    "sales": 10 + np.sin(2 * np.pi * t / 24) + 3 * promotion,
    "promotion": promotion,
})

future_timestamps = pd.date_range(
    timestamps[-1] + pd.Timedelta(hours=1), periods=horizon, freq="h"
)
future = pd.DataFrame({
    "item_id": "store-a",
    "timestamp": future_timestamps,
    "promotion": np.r_[np.zeros(12), np.ones(12)],
})

forecast = NoriTSForecaster(
    mode="local",
    model="nori-30m",
    quantiles=[0.1, 0.5, 0.9],
).predict_df(history, future_df=future, target_column="sales")

print(forecast.columns.tolist())
print(forecast.shape)

['sales', '0.1', '0.5', '0.9']
(24, 4)

The target remains univariate; promotion is an input feature. Every numeric history covariate must appear throughout future_df. Only provide values you know at prediction time, such as planned promotions, holidays, weather forecasts, or scheduled prices. A realized future target or any value observed only after the forecast timestamp would be target leakage.

target_column= accepts one column name per call. To forecast several target columns, call predict_df once for each target. Passing a sequence raises a clear error before Nori sends a local or hosted request.

How it works

Tabular conversion

For each series, the forecaster creates rows indexed by (item_id, timestamp). Historical rows contain the observed target, and future rows contain generated time features. Numeric columns supplied in both the history and horizon are also used as covariates. Nori fits on the historical rows and predicts the future rows.

The time features

The default features include a running index, calendar sine and cosine values, and seasonal periods detected from the history. You can replace them with custom feature generators through features=.

Quantile output

Set quantiles= to choose the returned quantile columns. The target column contains the median forecast.

Configuration

NoriTSForecaster parameters

Parameter	Default	Description
`mode`	required	`"local"`, `"remote"`, or `"sagemaker"`; there is no automatic selection.
`model`	required	Explicit model selector such as `"nori-6m"` or `"nori-30m"`.
`client`	`None`	Inject an already configured `SynthefyNoriClient`; do not also pass backend constructor arguments.
`api_key`	`None`	Hosted API key, used only with `mode="remote"`.
`endpoint_name`	`None`	Required with `mode="sagemaker"`.
`region_name`	AWS configuration	AWS region containing the SageMaker endpoint.
`context_length`	`4096`	Cap on history rows per series (last-N kept).
`quantiles`	`[0.1 … 0.9]`	Forecast quantile levels; the median is the point forecast.
`features`	`None`	Feature generators; defaults to the standard set.

predict_df DataFrame contract

context_df needs timestamp and one target column. Add item_id for multi-series frames. Pass exactly one of prediction_length= or future_df=. Use target_column= when the target is not named target. The result is indexed by (item_id, timestamp) and contains the median under the target’s original name plus one column per quantile level.

forecast = NoriTSForecaster(
    mode="local",
    model="nori-30m",
    quantiles=[0.1, 0.5, 0.9],
).predict_df(
    history,
    prediction_length=48,
)

With prediction_length=, the forecaster generates timestamps and drops history covariates because their future values are unknown. With future_df=, the explicit horizon supplies those future values. Its target must be absent or entirely missing.

Good to know

One predict_df call forecasts one target column across one or many item_id series.
future_df must contain the same item_id values as history, without duplicate or overlapping timestamps.
DataFrame preparation is local in every mode. Remote and SageMaker modes send only the resulting numeric regression request.

Next steps

Python Client

Configure explicit local, hosted, and SageMaker execution.

Text Features

Add free-text columns to the shared regression preparation path.

Examples

Browse more end-to-end Nori workflows.

Get Started

Guides

Integration

Quickstart

Choose where it runs

Multiple series

Future-known covariates

How it works

Configuration

Good to know

Next steps

Python Client

Text Features

Examples

​Quickstart

​Choose where it runs

​Multiple series

​Future-known covariates

​How it works

​Configuration

​Good to know

​Next steps

Python Client

Text Features

Examples

Quickstart

Choose where it runs

Multiple series

Future-known covariates

How it works

Configuration

Good to know

Next steps