Quickstart

👍

Prerequesites

This tutorial assumes you already have a an API Token and the SDK installed. Visit Quick Start to learn how to get your token to start using TimeGPT. Visit Installation (Python SDK) to learn how to install the Python SDK.

This tutorial shows a quick example of forecasting with the TimeGPT SDK. The primary function of our Python SDK is to provide a powerful and user-friendly interface for the TimeGPT API. TimeGPT can produce accurate forecasts for new time series without training, using only historical values as inputs.

The main method of the SDK is the forecast function. The two main required arguments are:

1. Dataframe with the historical values of the time series you want to forecast (df argument).
2. The number of datestamps to predict (h argument).

Input dataframe

The following table presents an example of an input dataframe.

📘

Important requirements of the data

1. Make sure the target variable column does not have missing or non-numeric values.
2. Do not include gaps/jumps in the datestamps (for the given frequency) between the first and late datestamps. The forecast function will not impute missing dates.
3. The format of the datestamp column should be readable by Pandas (see this link for more details).

Forecast horizon

Specify the number of observations to predict with the horizon (h) argument. The forecasts will be produced after the final date provided in the input dataframe.

🚧

TimeGPT-1 is currently optimized for short horizon forecasting (for instance, 7 for daily data, 24 for hourly data). While the forecast function will allow any positive and large horizon, the accuracy of the forecasts might degrade. We are currently working to improve the accuracy on longer forecasts.

Complete example

Here's the complete example with the classic AirPassengers data:

#!pip install nixtlats

import pandas as pd  
from nixtlats import TimeGPT  # Importing the TimeGPT class from nixtlats library.

# Initializing the `TimeGPT` class with a token from the environment variable.
timegpt = TimeGPT(token='YOUR_TIMEGPT_TOKEN') #https://dashboard.nixtla.io

# Check if the token provided is valid.
if timegpt.validate_token():
    print("Token validation successful!")  # Token is valid.
else:
    # Raise an exception if token validation fails.
    raise Exception("Token validation failed! Please check go to https://dashboard.nixtla.io/ to get your token.")

# Loading the air passengers dataset from a remote URL as an example
df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv')

# Forecasting the next 12 horizons using TimeGPT
timegpt_fcst_df = timegpt.forecast(df=df, h=12, time_col='timestamp', target_col='value', freq='MS')

📘

Frequency

We are improving the automatic frequency inference, so it might be unstable. We advise you to specify the correct frequency for now. We support all common definitions.

Check the following recipe for more details: