Time series data often follows regular intervals. However, in certain cases—like trading days in stock markets—timestamps can be irregular. This page shows you how to work with both regular and irregular timestamps in TimeGPT.

1

1. Import Packages

First, import the required libraries and initialize the Nixtla client.

Import Packages and Initialize NixtlaClient
import pandas as pd
import pandas_market_calendars as mcal
from nixtla import NixtlaClient

Initialize NixtlaClient with your API key:

Initialize NixtlaClient with API key
nixtla_client = NixtlaClient(
    api_key='my_api_key_provided_by_nixtla'
)
2

2. Handling Regular Frequencies

TimeGPT automatically detects appropriate frequency for most regular intervals (e.g. daily, monthly). No manual frequency specification is needed for regular Pandas DataFrames—unless you want to override the inferred frequency.

For Polars DataFrames, specifying the frequency is mandatory. Here’s an example using Polars:

Polars DataFrame Forecast Example
import polars as pl 

url = 'https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv'
polars_df = pl.read_csv(url, try_parse_dates=True)

fcst_df = nixtla_client.forecast(
    df=polars_df,
    h=12,
    freq='1mo',
    time_col='timestamp',
    target_col='value',
    level=[80, 95]
)

When you run the code, you’ll see logs indicating each step of the process in the console:

Plot the forecast results:

Plotting Forecast Results
nixtla_client.plot(
    polars_df,
    fcst_df,
    time_col='timestamp',
    target_col='value',
    level=[80, 95]
)

Air Passengers Forecast

3

3. Handling Irregular Frequencies

Irregular frequencies mean timestamps are not equally spaced, such as stock market trading days. TimeGPT handles irregular frequencies but requires an explicit frequency specification. Make sure you have no missing data. If data is missing, see the missing dates tutorial.

4

4. Summary

Key Takeaways

  • TimeGPT infers regular frequencies automatically.
  • Polars DataFrames require manual frequency specification.
  • Custom frequencies allow forecasts only on valid (or desired) dates.
  • Ensure no missing data for irregular timestamps.

You can now forecast time series that do not align to standard daily, monthly, or hourly intervals. By explicitly specifying your own custom frequencies, TimeGPT maintains accuracy even in irregular data scenarios.

For more details on handling missing data, visit the Missing Dates Tutorial.