Tutorial Nixtla TimeGPT: Foundation Model untuk Time Series Forecasting

Time series forecasting adalah salah satu task paling penting dalam data science, mulai dari prediksi penjualan, forecasting demand, monitoring infrastruktur, hingga analisis keuangan. Namun, membangun model forecasting yang akurat seringkali membutuhkan expertise mendalam dalam pemilihan model, feature engineering, dan hyperparameter tuning.

Nixtla hadir dengan TimeGPT — sebuah foundation model untuk time series yang mengubah cara kita melakukan forecasting. Mirip seperti GPT untuk teks, TimeGPT adalah model pre-trained yang bisa langsung digunakan untuk forecasting tanpa perlu training dari nol. Dalam tutorial ini, kita akan mempelajari cara menggunakan Nixtla TimeGPT secara praktis, mulai dari instalasi hingga advanced use cases.

Apa itu Nixtla TimeGPT?

TimeGPT adalah foundation model pertama untuk time series forecasting yang dikembangkan oleh Nixtla. Model ini di-training pada miliaran data point dari berbagai domain, sehingga mampu melakukan zero-shot forecasting — artinya model bisa langsung memberikan prediksi tanpa perlu di-training ulang pada data spesifik Anda.

Keunggulan utama TimeGPT:

• Zero-shot forecasting: Langsung prediksi tanpa training
• Multi-horizon: Bisa forecast untuk berbagai horizon waktu
• Anomaly detection: Deteksi anomali pada time series data
• Exogenous variables: Support variabel eksternal untuk meningkatkan akurasi
• Conformal prediction: Interval prediksi yang terkalibrasi
• Cross-validation: Built-in temporal cross-validation
• Fine-tuning: Bisa di-fine-tune pada data spesifik untuk performa lebih baik

Instalasi

Menggunakan pip

pip install nixtla

Menggunakan conda

conda install -c conda-forge nixtla

Dependensi tambahan untuk visualisasi

pip install nixtla matplotlib plotly pandas

Setup API Key

TimeGPT menggunakan API-based inference. Anda perlu mendaftar di dashboard Nixtla untuk mendapatkan API key.

from nixtla import NixtlaClient

Inisialisasi client
nixtlaclient = NixtlaClient(apikey='yourapikeyhere')


Atau set via environment variable
export NIXTLAAPIKEY=yourapikeyhere
nixtlaclient = NixtlaClient()

nixtlaclient.validateapikey()
Output: True jika valid

Basic Usage: Forecasting Sederhana

Menyiapkan Data

TimeGPT menerima data dalam format pandas DataFrame dengan minimal dua kolom: timestamp dan value.

import pandas as pd
from nixtla import NixtlaClient

nixtlaclient = NixtlaClient()


Membuat sample data
Misalnya data penjualan harian selama 2 tahun
dates = pd.daterange(start='2024-01-01', end='2025-12-31', freq='D')
import numpy as np

np.random.seed(42)
trend = np.linspace(100, 200, len(dates))
seasonal = 30  np.sin(2  np.pi  np.arange(len(dates)) / 365.25)

noise = np.random.normal(0, 10, len(dates))
values = trend + seasonal + noise

df = pd.DataFrame({
    'timestamp': dates,
    'value': values
})

print(df.head())
print(f"Shape: {df.shape}")

# Forecast 30 hari ke depan
forecastdf = nixtlaclient.forecast(
    df=df,
    h=30,  # horizon: 30 hari ke depan
    timecol='timestamp',

    targetcol='value'
)

print(forecastdf.head())

# Plot hasil forecasting
nixtlaclient.plot(
    df=df,
    forecastsdf=forecastdf,
    timecol='timestamp',

    targetcol='value',
    maxinsamplelength=90  # Tampilkan 90 hari data historis
)

# Menggunakan dataset AirPassengers
from nixtla import NixtlaClient
import pandas as pd

nixtlaclient = NixtlaClient()


Load AirPassengers dataset
df = pd.readcsv(
    'https://raw.githubusercontent.com/jbrownlee/Datasets/master/airline-passengers.csv',
    parsedates=['Month'],

)
df.columns = ['timestamp', 'value']

Forecast 12 bulan ke depan
forecastdf = nixtlaclient.forecast(

    df=df,
    h=12,
    timecol='timestamp',
    targetcol='value',

    freq='MS'  # Monthly Start frequency
)

Visualisasi
nixtlaclient.plot(
    df=df,
    forecastsdf=forecastdf,
    timecol='timestamp',

    targetcol='value'
)

# Data dengan multiple series
data = []
for productid in ['SKU001', 'SKU002', 'SKU003']:

    dates = pd.daterange('2024-01-01', '2025-12-31', freq='D')
    np.random.seed(hash(productid) % 100)

    values = (
        np.random.uniform(50, 150) +
        20  np.sin(2  np.pi  np.arange(len(dates)) / 7) +  # weekly pattern
        np.random.normal(0, 5, len(dates))
    )
    for date, val in zip(dates, values):
        data.append({
            'uniqueid': productid,

            'timestamp': date,
            'value': max(0, val)
        })

dfpanel = pd.DataFrame(data)

Forecast semua series sekaligus
forecastpanel = nixtlaclient.forecast(
    df=dfpanel,

    h=14,  # 2 minggu ke depan
    timecol='timestamp',
    targetcol='value',

    idcol='uniqueid'

)

print(forecastpanel.groupby('uniqueid').size())

# Forecast dengan prediction intervals
forecastwithintervals = nixtlaclient.forecast(
    df=df,
    h=30,
    timecol='timestamp',

    targetcol='value',
    level=[80, 95]  # 80% dan 95% prediction intervals
)

print(forecastwithintervals.columns)
Output: ['timestamp', 'TimeGPT', 'TimeGPT-lo-95', 'TimeGPT-lo-80',
'TimeGPT-hi-80', 'TimeGPT-hi-95']

Visualisasi dengan intervals
nixtlaclient.plot(

    df=df,
    forecastsdf=forecastwithintervals,
    timecol='timestamp',

    targetcol='value',
    level=[80, 95],
    maxinsamplelength=60
)

Exogenous Variables

Tambahkan variabel eksternal untuk meningkatkan akurasi prediksi:

# Menambahkan exogenous variables
dfwithexog = df.copy()
dfwithexog['dayofweek'] = dfwithexog['timestamp'].dt.dayofweek
dfwithexog['month'] = dfwithexog['timestamp'].dt.month
dfwithexog['isweekend'] = (dfwithexog['dayofweek'] >= 5).astype(int)


Buat future exogenous variables
futuredates = pd.daterange(

    start=dfwithexog['timestamp'].max() + pd.Timedelta(days=1),

    periods=30,
    freq='D'
)
futureexog = pd.DataFrame({
    'timestamp': futuredates,

    'dayofweek': futuredates.dayofweek,
    'month': futuredates.month,

    'isweekend': (futuredates.dayofweek >= 5).astype(int)

})

Forecast dengan exogenous variables
forecastexog = nixtlaclient.forecast(

    df=dfwithexog,

    Xdf=futureexog,

    h=30,
    timecol='timestamp',
    targetcol='value'

)

# Deteksi anomali
anomaliesdf = nixtlaclient.detectanomalies(
    df=df,
    timecol='timestamp',

    targetcol='value',
    freq='D'
)

Visualisasi anomali
nixtlaclient.plot(

    df=df,
    anomaliesdf=anomaliesdf,

    timecol='timestamp',
    targetcol='value'

)

Filter hanya data point yang anomali
anomalouspoints = anomaliesdf[anomaliesdf['anomaly'] == True]
print(f"Jumlah anomali terdeteksi: {len(anomalouspoints)}")

# Cross-validation
cvresults = nixtlaclient.crossvalidation(
    df=df,
    h=30,            # forecast horizon
    nwindows=3,     # jumlah windows

    timecol='timestamp',
    targetcol='value',

    level=[90]
)

print(cvresults.head())

Hitung metrik evaluasi
from sklearn.metrics import meanabsoluteerror, meansquarederror

mae = meanabsoluteerror(cvresults['value'], cvresults['TimeGPT'])
rmse = meansquarederror(cvresults['value'], cvresults['TimeGPT'], squared=False)
mape = np.mean(np.abs(
    (cvresults['value'] - cvresults['TimeGPT']) / cvresults['value']

))  100


print(f"MAE:  {mae:.2f}")
print(f"RMSE: {rmse:.2f}")
print(f"MAPE: {mape:.2f}%")

# Fine-tuning TimeGPT pada data Anda
forecastfinetuned = nixtlaclient.forecast(

    df=df,
    h=30,
    timecol='timestamp',
    targetcol='value',

    finetunesteps=50,       # jumlah langkah fine-tuning
    finetuneloss='mse'      # loss function: 'mse', 'mae', 'rmse', 'mape'

)

Bandingkan dengan tanpa fine-tuning
forecastdefault = nixtlaclient.forecast(

    df=df,
    h=30,
    timecol='timestamp',
    targetcol='value'

)

Visualisasi perbandingan
import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(12, 6))
ax.plot(df['timestamp'].tail(60), df['value'].tail(60), label='Historical', color='black')
ax.plot(forecastdefault['timestamp'], forecastdefault['TimeGPT'],

        label='TimeGPT (default)', linestyle='--')
ax.plot(forecastfinetuned['timestamp'], forecastfinetuned['TimeGPT'],

        label='TimeGPT (fine-tuned)', linestyle='-.')
ax.legend()
ax.settitle('Perbandingan Default vs Fine-tuned')
plt.tightlayout()

plt.savefig('comparison.png', dpi=150)
plt.show()

# Long-horizon forecasting
longforecast = nixtlaclient.forecast(

    df=df,
    h=365,  # Forecast 1 tahun ke depan
    timecol='timestamp',
    targetcol='value',

    model='timegpt-1-long-horizon',  # Model khusus long-horizon
    level=[90]
)

nixtlaclient.plot(
    df=df,
    forecastsdf=longforecast,
    timecol='timestamp',

    targetcol='value',
    level=[90],
    maxinsamplelength=180
)

import mlflow
from nixtla import NixtlaClient

nixtlaclient = NixtlaClient()


with mlflow.startrun(runname="timegptforecast"):
    # Forecast
    forecastdf = nixtlaclient.forecast(
        df=df, h=30,
        timecol='timestamp', targetcol='value',
        level=[90]
    )

    # Cross-validation untuk metrik
    cvresults = nixtlaclient.crossvalidation(

        df=df, h=30, nwindows=3,
        timecol='timestamp', targetcol='value'
    )

    # Log metrik
    mae = meanabsoluteerror(cvresults['value'], cvresults['TimeGPT'])
    rmse = meansquarederror(
        cvresults['value'], cvresults['TimeGPT'], squared=False
    )

    mlflow.logmetric("mae", mae)

    mlflow.logmetric("rmse", rmse)
    mlflow.logparam("horizon", 30)

    mlflow.logparam("model", "timegpt-1")

    # Simpan forecast sebagai artifact
    forecastdf.tocsv("forecastresults.csv", index=False)

    mlflow.logartifact("forecastresults.csv")


    print(f"MAE: {mae:.2f}, RMSE: {rmse:.2f}")

import plotly.graphobjects as go

Forecast dengan intervals
forecastdf = nixtlaclient.forecast(
    df=df, h=30,
    timecol='timestamp', targetcol='value',
    level=[80, 95]
)

fig = go.Figure()

Data historis
fig.addtrace(go.Scatter(

    x=df['timestamp'].tail(90),
    y=df['value'].tail(90),
    mode='lines',
    name='Historical',
    line=dict(color='black')
))

Forecast
fig.addtrace(go.Scatter(
    x=forecastdf['timestamp'],

    y=forecastdf['TimeGPT'],
    mode='lines',
    name='Forecast',
    line=dict(color='blue')
))

95% interval
fig.addtrace(go.Scatter(

    x=pd.concat([forecastdf['timestamp'], forecastdf['timestamp'][::-1]]),

    y=pd.concat([forecastdf['TimeGPT-hi-95'], forecastdf['TimeGPT-lo-95'][::-1]]),

    fill='toself',
    fillcolor='rgba(0,0,255,0.1)',
    line=dict(color='rgba(255,255,255,0)'),
    name='95% CI'
))

fig.updatelayout(
    title='TimeGPT Forecast dengan Prediction Intervals',
    xaxistitle='Tanggal',

    yaxistitle='Value',
    template='plotlywhite'

)

fig.show()

# Pastikan data lengkap tanpa missing values
def preparetimeseries(df, timecol, valuecol, freq='D'):
    df = df.copy()
    df[timecol] = pd.todatetime(df[timecol])

    df = df.sortvalues(timecol)


    # Buat complete date range
    fullrange = pd.daterange(

        start=df[timecol].min(),
        end=df[timecol].max(),

        freq=freq
    )

    df = df.setindex(timecol).reindex(fullrange)
    df.index.name = timecol

    df = df.resetindex()

    # Interpolasi missing values
    df[valuecol] = df[valuecol].interpolate(method='linear')

    # Hapus remaining NaN
    df = df.dropna(subset=[valuecol])


    return df

dfclean = preparetimeseries(df, 'timestamp', 'value')

# Rule of thumb: gunakan timegpt-1-long-horizon untuk h > 1 seasonality period
datafreq = 'D'  # daily data
seasonalityperiod = 7  # weekly seasonality


horizon = 30  # 30 hari

if horizon > seasonalityperiod:
    model = 'timegpt-1-long-horizon'
else:
    model = 'timegpt-1'

forecast = nixtlaclient.forecast(

    df=df, h=horizon,
    timecol='timestamp', targetcol='value',

    model=model
)

# Comprehensive evaluation
def evaluatetimegpt(df, horizons=[7, 14, 30], nwindows=5):

    results = {}
    for h in horizons:
        cv = nixtlaclient.crossvalidation(

            df=df, h=h, nwindows=nwindows,

            timecol='timestamp', targetcol='value'

        )
        mae = meanabsoluteerror(cv['value'], cv['TimeGPT'])

        rmse = meansquarederror(cv['value'], cv['TimeGPT'], squared=False)

        results[h] = {'MAE': mae, 'RMSE': rmse}

    return pd.DataFrame(results).T

evalresults = evaluatetimegpt(df)

print(evalresults)

# Fine-tuning dengan evaluasi
cvdefault = nixtlaclient.crossvalidation(

    df=df, h=30, nwindows=3,
    timecol='timestamp', targetcol='value'
)

cvfinetuned = nixtlaclient.crossvalidation(

    df=df, h=30, nwindows=3,
    timecol='timestamp', targetcol='value',
    finetunesteps=50

)

maedefault = meanabsoluteerror(cvdefault['value'], cvdefault['TimeGPT'])
maefinetuned = meanabsoluteerror(cvfinetuned['value'], cvfinetuned['TimeGPT'])


print(f"MAE Default:    {maedefault:.2f}")
print(f"MAE Fine-tuned: {maefinetuned:.2f}")

print(f"Improvement:    {((maedefault - maefinetuned) / maedefault)  100:.1f}%")

5. Monitoring dan Alerting

def forecastwithmonitoring(df, h, thresholdmape=10):
    # Cross-validation check
    cv = nixtlaclient.crossvalidation(

        df=df, h=h, nwindows=3,
        timecol='timestamp', targetcol='value'
    )

    mape = np.mean(np.abs(
        (cv['value'] - cv['TimeGPT']) / cv['value']
    ))  100


    if mape > thresholdmape:

        print(f"WARNING: MAPE {mape:.1f}% melebihi threshold {thresholdmape}%")
        print("Pertimbangkan fine-tuning atau tambahkan exogenous variables")

    # Actual forecast
    forecast = nixtlaclient.forecast(

        df=df, h=h,
        timecol='timestamp', targetcol='value',

        level=[90]
    )

    # Anomaly check pada data terbaru
    anomalies = nixtlaclient.detectanomalies(

        df=df.tail(90),
        timecol='timestamp', targetcol='value'

    )

    nanomalies = anomalies['anomaly'].sum()
    if nanomalies > 0:

        print(f"INFO: {nanomalies} anomali terdeteksi dalam 90 data point terakhir")

    return forecast, mape

forecast, mape = forecastwithmonitoring(df, h=30)

import pandas as pd
import numpy as np
from nixtla import NixtlaClient

nixtlaclient = NixtlaClient()


Simulasi data e-commerce
np.random.seed(42)
dates = pd.daterange('2024-01-01', '2026-09-28', freq='D')
products = ['ProductA', 'ProductB', 'ProductC']


data = []
for product in products:
    base = np.random.uniform(100, 500)
    trend = np.linspace(0, base  0.3, len(dates))
    weekly = base  0.2  np.sin(2  np.pi  np.arange(len(dates)) / 7)
    yearly = base  0.15  np.sin(2  np.pi  np.arange(len(dates)) / 365.25)
    noise = np.random.normal(0, base * 0.05, len(dates))

    sales = np.maximum(0, base + trend + weekly + yearly + noise)

    for date, val in zip(dates, sales):
        data.append({
            'uniqueid': product,
            'timestamp': date,
            'sales': round(val, 2)
        })

dfecommerce = pd.DataFrame(data)


Forecast 14 hari ke depan untuk semua produk
forecast = nixtlaclient.forecast(
    df=dfecommerce,

    h=14,
    timecol='timestamp',
    targetcol='sales',

    idcol='uniqueid',

    level=[80, 95]
)

Summary per produk
for product in products:
    productforecast = forecast[forecast['uniqueid'] == product]

    avgforecast = productforecast['TimeGPT'].mean()

    lo95 = productforecast['TimeGPT-lo-95'].mean()

    hi95 = productforecast['TimeGPT-hi-95'].mean()

    print(f"{product}: Avg forecast = {avgforecast:.0f} "
          f"(95% CI: {lo95:.0f} - {hi95:.0f})")

Perbandingan dengan Pendekatan Tradisional

| Aspek | TimeGPT | ARIMA/Prophet | Custom Deep Learning |

|-------|---------|---------------|---------------------|

| Setup time | Menit | Jam | Hari-Minggu |

| Training data diperlukan | Tidak (zero-shot) | Ya | Ya (banyak) |

| Expertise diperlukan | Minimal | Moderate | Tinggi |

| Multi-series | Native support | Per-series | Perlu arsitektur khusus |

| Anomaly detection | Built-in | Terpisah | Perlu implementasi |

| Scalability | API-based, auto-scale | Tergantung infra | Tergantung infra |

| Cost | Per API call | Compute sendiri | Compute sendiri |

| Customization | Fine-tuning | Full control | Full control |

Kesimpulan

Nixtla TimeGPT membawa paradigma baru dalam time series forecasting. Dengan pendekatan foundation model, TimeGPT menghilangkan kebutuhan untuk training model dari nol, memungkinkan data scientist dan engineer untuk langsung mendapatkan forecast berkualitas tinggi.

Poin-poin penting yang perlu diingat:

TimeGPT sangat cocok untuk rapid prototyping, baseline forecasting, dan use case di mana kecepatan delivery lebih penting daripada kontrol penuh atas model. Untuk production system yang membutuhkan volume tinggi, pertimbangkan untuk mengkombinasikan TimeGPT dengan solusi on-premise.