> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synthefy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Forecasting

> Forecast a univariate time series with Nori and return point and quantile predictions.

`NoriTSForecaster` converts a time series into tabular features and predicts a
requested number of future steps. It returns a pandas DataFrame containing the
median forecast and any requested quantiles. Forecasting runs locally and
requires the `timeseries` extra.

## Quickstart

<Steps>
  <Step title="Install the forecasting dependencies">
    Follow [Installation](/setup/installation#forecasting) to install the
    `timeseries` extra for `synthefy-nori`.
  </Step>

  <Step title="Create a history DataFrame">
    Provide `timestamp` and `target` columns, ordered from oldest to newest.

    ```python theme={null}
    import numpy as np
    import pandas as pd
    from synthefy_nori.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),
    })
    ```
  </Step>

  <Step title="Forecast the horizon">
    `predict_df` returns one row per future timestamp.

    ```python theme={null}
    forecaster = NoriTSForecaster(
        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)
    ```

    ```text theme={null}
    ['target', '0.1', '0.5', '0.9']
    ['item_id', 'timestamp']
    (48, 4)
    ```

    `target` is the median forecast. The other columns contain the requested
    quantiles.
  </Step>
</Steps>

## How it works

<AccordionGroup>
  <Accordion title="Tabular conversion" icon="table-cells">
    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. Nori fits on the historical
    rows and predicts the future rows.
  </Accordion>

  <Accordion title="The time features" icon="wave-square">
    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=`.
  </Accordion>

  <Accordion title="Quantile output" icon="chart-area">
    Set `quantiles=` to choose the returned quantile columns. The `target`
    column contains the median forecast.
  </Accordion>
</AccordionGroup>

## Configuration

<AccordionGroup>
  <Accordion title="NoriTSForecaster parameters" icon="sliders">
    | Parameter        | Default       | Description                                                                                     |
    | ---------------- | ------------- | ----------------------------------------------------------------------------------------------- |
    | `quantiles`      | `[0.1 … 0.9]` | Forecast quantile levels; the median is the point forecast.                                     |
    | `context_length` | `4096`        | Cap on history rows per series (last-N kept).                                                   |
    | `device`         | `None`        | Torch device (e.g. `"cuda:0"`); `None` auto-selects.                                            |
    | `features`       | `None`        | Feature generators; defaults to the standard set.                                               |
    | `model`          | `"nori-6m"`   | Nori checkpoint variant; use `"nori-6m"` or `"nori-30m"`.                                       |
    | `model_path`     | `None`        | Explicit checkpoint path; overrides `model`. `None` resolves the named model from Hugging Face. |
  </Accordion>

  <Accordion title="predict_df(context_df, prediction_length)" icon="code">
    `context_df` needs a `timestamp` and a `target` column (an optional
    `item_id` for multi-series frames). Returns a DataFrame indexed by
    `(item_id, timestamp)` over the horizon, with a `target` (median) column and
    one column per quantile level (`"0.1"`, `"0.5"`, …).

    ```python theme={null}
    forecast = NoriTSForecaster(
        model="nori-30m",
        quantiles=[0.1, 0.5, 0.9],
    ).predict_df(
        history,
        prediction_length=48,
    )
    ```

    For frames already in `(item_id, timestamp)` form, `predict(train_tsdf,
            test_tsdf)` is the lower-level entry point.
  </Accordion>
</AccordionGroup>

## Next steps

Continue with [Text Features](/nori/text-features), or browse more local Nori
workflows in [Examples](/nori/examples).