Forecast

async AsyncCogniteClient.ai.time_series.forecast(

time_series: ForecastInputTimeSeries | Sequence[ForecastInputTimeSeries],

) → ForecastResult | ForecastResultList

Forecast the next 512 points of each time series from its history.

No training or tuning on your data is needed. Each forecast point holds a set of quantiles, describing both the most likely value and the uncertainty around it. The points continue at the interval of the history, starting one interval after its last datapoint. Time series in the same cohort are forecast jointly, so the model can use the relationships between them. A time series without an underlying pattern, such as random noise, a flat line, or a setpoint changed by an operator, will not give a useful forecast.

Note

This endpoint is in beta, and is called with the beta cdf-version header.

Parameters:

time_series (ForecastInputTimeSeries | Sequence[ForecastInputTimeSeries]) – The time series to forecast. Each needs a unique label and between 2 and 8192 evenly spaced datapoints, at least one of which has a value and is not marked missing. Time series in a cohort must have identical timestamps.

Returns:

The result for a single time series, or one result per time series, in

input order. Use the 0.5 quantile, the median, as a single predicted value.

Return type:

ForecastResult | ForecastResultList

Raises:

ValueError – If a label is repeated, a cohort has more than 32 time series, or a time series or cohort is over 5 MiB on its own. These are the API’s limits for one request, and a cohort is always sent in one request.

Examples

Forecast a time series, and get the median forecast as a DataFrame:

>>> from cognite.client import CogniteClient, AsyncCogniteClient
>>> from cognite.client.data_classes.ai import (
...     ForecastInputDatapoint,
...     ForecastInputTimeSeries,
... )
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> series = ForecastInputTimeSeries(
...     "21-PT-1019",
...     [
...         ForecastInputDatapoint(1790812800000, 42.1),
...         ForecastInputDatapoint(1790812860000, 42.4),
...     ],
... )
>>> res = client.ai.time_series.forecast(series)
>>> median = res.to_pandas()["21-PT-1019"]

Forecast correlated time series jointly by giving them the same cohort, for example the compressors on one compression train:

>>> res = client.ai.time_series.forecast(
...     [
...         ForecastInputTimeSeries(
...             "23-PT-1101",
...             [ForecastInputDatapoint(0, 42.1), ForecastInputDatapoint(60_000, 42.4)],
...             cohort="compression-train-a",
...         ),
...         ForecastInputTimeSeries(
...             "23-PT-1201",
...             [ForecastInputDatapoint(0, 39.8), ForecastInputDatapoint(60_000, 40.1)],
...             cohort="compression-train-a",
...         ),
...     ]
... )