​
Introduction

Forecasting time series is a ubiquitous task in finance, supporting decisions in trading, risk management, and strategic planning. Despite its prevalence, predicting the future prices of financial assets remains a formidable challenge, mainly due to the inherent volatility of financial markets. For those who believe in the feasibility of forecasting these assets, or for professionals whose roles require such predictions, TimeGPT is a powerful tool that simplifies the forecasting process. In this tutorial, we will demonstrate how to use TimeGPT for financial time series forecasting, focusing on Bitcoin price prediction. We will also showcase how to use TimeGPT for uncertainty quantification, which is essential for risk management and decision-making. Outline:
  1. Load Bitcoin Price Data
  2. Get Started with TimeGPT
  3. Visualize the Data
  4. Forecast with TimeGPT
  5. Extend Bitcon Price Analysis with TimeGPT
  6. Understand the Model’s Limitations
  7. References and Additional Material

​
1. Load Bitcoin Price Data

Bitcoin (₿) is the first decentralized digital currency and is one of the most popular cryptocurrencies. Transactions are managed and recorded on a public ledger known as the blockchain. Bitcoins are created as a reward for mining, a process that involves solving complex cryptographic tasks to verify transactions. This digital currency can be used as payment for goods and services, traded for other currencies, or held as a store of value. In this tutorial, we will first download the historical Bitcoin price data in USD as a pandas DataFrame. 
import pandas as pd 

df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/bitcoin_price_usd.csv', sep=',')  
df.head()
DateClose
02020-01-017200.174316
12020-01-026985.470215
22020-01-037344.884277
32020-01-047410.656738
42020-01-057411.317383
This dataset contains the closing price of Bitcoin in USD from 2020-01-01 to 2023-12-31. It’s important to note that unlike traditional financial assets, Bitcoin trades 24/7. Therefore, the closing price represents the price of Bitcoin at a specific time each day, rather than at the end of a trading day. For convenience, we will rename the Date and Close columns to ds and y, respectively. 
df.rename(columns={'Date': 'ds', 'Close': 'y'}, inplace=True)

​
2. Get Started with TimeGPT

To get started with TimeGPT, you need to instantiate the NixtlaClient class. For this, you will need a Nixtla API key. 
from nixtla import NixtlaClient

nixtla_client = NixtlaClient(
    # defaults to os.environ.get("NIXTLA_API_KEY")
    api_key = 'my_api_key_provided_by_nixtla'
)
👍 Use an Azure AI endpoint To use an Azure AI endpoint, remember to set also the base_url argument: nixtla_client = NixtlaClient(base_url="you azure ai endpoint", api_key="your api_key")
To learn more about how to set up your API key, please refer to the Setting Up Your Authentication API Key tutorial.

​
3. Visualize the Data

Before attempting any forecasting, it is good practice to visualize the data we want to predict. The NixtlaClient class includes a plot method for this purpose. The plot method has an engine argument that allows you to choose between different plotting libraries. Default is matplotlib, but you can also use plotly for interactive plots. 
nixtla_client.plot(df)
If you haven’t renamed the column names of your DataFrame to ds and y, you will need to specify the time_col and target_col arguments of the plotmethod: 
nixtla_client.plot(df, time_col='name of your time column', target_col='name of your target column')
This is necessary not only for the plot method but for all methods from the NixtlaClient class.

​
4. Forecast with TimeGPT

Now we are ready to generate predictions with TimeGPT. To do this, we will use the forecast method from the NixtlaClient class. The forecast method requires the following arguments:
  • df: The DataFrame containing the time series data
  • h: (int) The forecast horizon. In this case, we will forecast the next 7 days.
  • level: (list) The confidence level for the prediction intervals. Given the inherent volatility of Bitcoin, we will use multiple confidence levels. 
level = [50,80,90] # confidence levels 

fcst = nixtla_client.forecast(df, h=7, level=level)
fcst.head()

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Inferred freq: D
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
dsTimeGPTTimeGPT-lo-90TimeGPT-lo-80TimeGPT-lo-50TimeGPT-hi-50TimeGPT-hi-80TimeGPT-hi-90
02024-01-0142269.46093839567.20902040429.95363641380.65464643158.26722944108.96823944971.712855
12024-01-0242469.91796939697.94166940578.19704941466.51136143473.32457644361.63888845241.894268
22024-01-0342864.07812540538.87124341586.25250742284.31667443443.83957644141.90374345189.285007
32024-01-0442881.62109440603.11744841216.10649342058.53939243704.70279544547.13569445160.124739
42024-01-0542773.45703140213.69976040665.38478041489.81243144057.10163244881.52928245333.214302
📘 Available models in Azure AI If you are using an Azure AI endpoint, please be sure to set model="azureai": nixtla_client.forecast(..., model="azureai") For the public API, we support two models: timegpt-1 and timegpt-1-long-horizon. By default, timegpt-1 is used. Please see this tutorial on how and when to use timegpt-1-long-horizon.
We can pass the forecasts we just generated to the plot method to visualize the predictions with the historical data. 
nixtla_client.plot(df, fcst, level=level)
To get a closer look at the predictions, we can zoom in on the plot or specify the maximum number of in-sample observations to be plotted using the max_insample_length argument. Note that setting max_insample_length=60, for instance, will display the last 60 historical values along with the complete forecast. 
nixtla_client.plot(df, fcst, level=level, max_insample_length=60)
Additionally, if you set the add_history argument of the forecast method to True, TimeGPT will generate predictions for the historical observations too. This can be useful for assessing the model’s performance on the training data. 
forecast = nixtla_client.forecast(df, h=7, level=level, add_history=True)
forecast.head()

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Inferred freq: D
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
INFO:nixtla.nixtla_client:Calling Historical Forecast Endpoint...
dsTimeGPTTimeGPT-lo-50TimeGPT-lo-80TimeGPT-lo-90TimeGPT-hi-50TimeGPT-hi-80TimeGPT-hi-90
02020-02-039425.7021487622.2871945999.1574795027.77967711229.11710312852.24681813823.624619
12020-02-049568.4824227765.0674676141.9377525170.55995111371.89737612995.02709213966.404893
22020-02-059557.0820317753.6670776130.5373625159.15956011360.49698612983.62670113955.004502
32020-02-069486.1230477682.7080926059.5783775088.20057611289.53800112912.66771713884.045518
42020-02-079475.2421887671.8272336048.6975185077.31971611278.65714212901.78685713873.164659
📘 Available models in Azure AI If you are using an Azure AI endpoint, please be sure to set model="azureai": nixtla_client.forecast(..., model="azureai") For the public API, we support two models: timegpt-1 and timegpt-1-long-horizon. By default, timegpt-1 is used. Please see this tutorial on how and when to use timegpt-1-long-horizon. 
nixtla_client.plot(df, forecast, level=level)

​
5. Extend Bitcoin Price Analysis with TimeGPT

​
Anomaly Detection

Given the volatility of the price of Bitcoin, it can be useful to try to identify anomalies in the data. TimeGPT can be used for this by calling the detect_anomalies method from the NixtlaClient class. This method evaluates each observation against its context within the series, using statistical measures to determine its likelihood of being an anomaly. By default, it identifies anomalies based on a 99 percent prediction interval. To change this, you can specify the level argument. 
anomalies_df = nixtla_client.detect_anomalies(df)

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Inferred freq: D
INFO:nixtla.nixtla_client:Calling Anomaly Detector Endpoint...
📘 Available models in Azure AI If you are using an Azure AI endpoint, please be sure to set model="azureai": nixtla_client.detect_anomalies(..., model="azureai") For the public API, we support two models: timegpt-1 and timegpt-1-long-horizon. By default, timegpt-1 is used. Please see this tutorial on how and when to use timegpt-1-long-horizon. 
nixtla_client.plot(df, anomalies_df, plot_anomalies=True)
To learn more about how to detect anomalies with TimeGPT, take a look at our Anomaly Detection tutorial.

​
Add Exogenous Variables

If you have additional information that you believe could help improve the forecast, consider including it as an exogenous variable. For instance, you might add data such as the price of other cryptocurrencies, proprietary information, stock market indices, or the number of transactions in the Bitcoin network. TimeGPT supports the incorporation of exogenous variables in the forecast method. However, keep in mind that you’ll need to know the future values of these variables. To learn how to incorporate exogenous variables to TimeGPT, refer to the Exogenous Variables tutorial.

​
6. Understand the Model’s Limitations

As stated in the introduction, predicting the future prices of financial assets is a challenging task, especially for assets like Bitcoin. The predictions in this tutorial may appear accurate, mainly because they align with recent historical data and the model updates with new values at short intervals, avoiding significant deviations. However, the true challenge lies in forecasting Bitcoin’s price for the upcoming days, not just its historical performance. For those who need or want to try to forecast these assets, TimeGPT can be an option that simplifies the forecasting process. With just a couple of lines of code, TimeGPT can help you:
  • Produce point forecasts
  • Quantify the uncertainty of your predictions
  • Produce in-sample forecasts
  • Detect anomalies
  • Incorporate exogenous variables
To learn more about TimeGPT capabilities, please refer to the TimeGPT Documentation.

​
7. References and Additional Material

References Furthermore, for many financial time series, the best estimate for the price is often a random walk model, meaning that the best forecast for tomorrow’s price is today’s price. Nixtla’s StatsForecast library allows you to easily implement this model and variations.