!pip install -Uqq nixtla

from nixtla.utils import in_colab

IN_COLAB = in_colab()

if not IN_COLAB:
    from nixtla.utils import colab_badge
    from dotenv import load_dotenv
TimeGPT is a production ready, generative pretrained transformer for time series. It’s capable of accurately predicting various domains such as retail, electricity, finance, and IoT with just a few lines of code 🚀.

​
Step 1: Create a TimeGPT account and generate your API key

  • Go to dashboard.nixtla.io to activate your free trial and set up an account.
  • Sign in with Google, GitHub or your email
  • Create your API key by going to ‘API Keys’ in the menu and clicking on ‘Create New API Key’
  • Your new key will appear. Copy the API key using the button on the right.
Dashboard for TimeGPT API keys. Keys is in the middle, with trash and copy buttons on the right.

​
Step 2: Install Nixtla

In your favorite Python development environment: Install nixtla with pip: 
pip install nixtla

​
Step 3: Import the Nixtla TimeGPT client

from nixtla import NixtlaClient
You can instantiate the NixtlaClient class providing your authentication API key. 
nixtla_client = NixtlaClient(
    api_key = 'my_api_key_provided_by_nixtla'
)

if not IN_COLAB:
    nixtla_client = NixtlaClient()
Check your API key status with the validate_api_key method. 
nixtla_client.validate_api_key()

INFO:nixtla.nixtla_client:Happy Forecasting! :), If you have questions or need support, please email support@nixtla.io

True
This will get you started, but for more secure usage, see Setting Up your API Key.

​
Step 4: Start making forecasts!

Now you can start making forecasts! Let’s import an example using the classic AirPassengers dataset. This dataset contains the monthly number of airline passengers in Australia between 1949 and 1960. First, load the dataset and plot it to illustrate the time series: 
import pandas as pd

df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv')
df.head()
timestampvalue
01949-01-01112
11949-02-01118
21949-03-01132
31949-04-01129
41949-05-01121
nixtla_client.plot(df, time_col='timestamp', target_col='value')
📘 Data Requirements
  • Make sure the target variable column does not have missing or non-numeric values.
  • 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.
  • The format of the datestamp column should be readable by Pandas (see this link for more details).
For further details go to Data Requirements.
👍 Save figures made with TimeGPT The plot method automatically displays figures when in a notebook environment. To save figures locally, you can do: fig = nixtla_client.plot(df, time_col='timestamp', target_col='value') fig.savefig('plot.png', bbox_inches='tight')

​
Forecast a longer horizon into the future

Next, forecast the next 12 months using the SDK forecast method. Set the following parameters:
  • df: A pandas DataFrame containing the time series data.
  • h: Horizons is the number of steps ahead to forecast.
  • freq: The frequency of the time series in Pandas format. See pandas’ available frequencies. (If you don’t provide any frequency, the SDK will try to infer it)
  • time_col: The column that identifies the datestamp.
  • target_col: The variable to forecast.
timegpt_fcst_df = nixtla_client.forecast(df=df, h=12, freq='MS', time_col='timestamp', target_col='value')
timegpt_fcst_df.head()

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
timestampTimeGPT
01961-01-01437.837921
11961-02-01426.062714
21961-03-01463.116547
31961-04-01478.244507
41961-05-01505.646484
nixtla_client.plot(df, timegpt_fcst_df, time_col='timestamp', target_col='value')
You can also produce longer forecasts by increasing the horizon parameter and selecting the timegpt-1-long-horizon model. Use this model if you want to predict more than one seasonal period of your data. For example, let’s forecast the next 36 months: 
timegpt_fcst_df = nixtla_client.forecast(df=df, h=36, time_col='timestamp', target_col='value', freq='MS', model='timegpt-1-long-horizon')
timegpt_fcst_df.head()

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
WARNING:nixtla.nixtla_client:The specified horizon "h" exceeds the model horizon. This may lead to less accurate forecasts. Please consider using a smaller horizon.
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
timestampTimeGPT
01961-01-01436.843414
11961-02-01419.351532
21961-03-01458.943146
31961-04-01477.876068
41961-05-01505.656921
nixtla_client.plot(df, timegpt_fcst_df, time_col='timestamp', target_col='value')

​
Produce a shorter forecast

You can also produce a shorter forecast. For this, we recommend using the default model, timegpt-1. 
timegpt_fcst_df = nixtla_client.forecast(df=df, h=6, time_col='timestamp', target_col='value', freq='MS')
nixtla_client.plot(df, timegpt_fcst_df, time_col='timestamp', target_col='value')

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...