TimeGPT

 TimeGPT (token:Optional[str]=None, environment:Optional[str]=None,
          max_retries:int=6, retry_interval:int=10, max_wait_time:int=360)

Constructs all the necessary attributes for the TimeGPT object.

TypeDefaultDetails
tokenOptionalNoneThe authorization token interacts with the TimeGPT API.
If not provided, it will be inferred by the TIMEGPT_TOKEN environment variable.
environmentOptionalNoneCustom environment. Pass only if provided.
max_retriesint6The maximum number of attempts to make when calling the API before giving up.
It defines how many times the client will retry the API call if it fails.
Default value is 6, indicating the client will attempt the API call up to 6 times in total
retry_intervalint10The interval in seconds between consecutive retry attempts.
This is the waiting period before the client tries to call the API again after a failed attempt.
Default value is 10 seconds, meaning the client waits for 10 seconds between retries.
max_wait_timeint360The maximum total time in seconds that the client will spend on all retry attempts before giving up.
This sets an upper limit on the cumulative waiting time for all retry attempts.
If this time is exceeded, the client will stop retrying and raise an exception.
Default value is 360 seconds, meaning the client will cease retrying if the total time
spent on retries exceeds 360 seconds.
The client throws a ReadTimeout error after 60 seconds of inactivity. If you want to
catch these errors, use max_wait_time >> 60.

TimeGPT.validate_token

 TimeGPT.validate_token (log:bool=True)

Returns True if your token is valid.

Now you can start to make forecasts! Let’s import an example:


TimeGPT.plot

 TimeGPT.plot (df:pandas.core.frame.DataFrame,
               forecasts_df:Optional[pandas.core.frame.DataFrame]=None,
               id_col:str='unique_id', time_col:str='ds',
               target_col:str='y',
               unique_ids:Union[List[str],NoneType,numpy.ndarray]=None,
               plot_random:bool=True, models:Optional[List[str]]=None,
               level:Optional[List[float]]=None,
               max_insample_length:Optional[int]=None,
               plot_anomalies:bool=False, engine:str='matplotlib',
               resampler_kwargs:Optional[Dict]=None)

Plot forecasts and insample values.

TypeDefaultDetails
dfDataFrameThe DataFrame on which the function will operate. Expected to contain at least the following columns:
- time_col:
Column name in df that contains the time indices of the time series. This is typically a datetime
column with regular intervals, e.g., hourly, daily, monthly data points.
- target_col:
Column name in df that contains the target variable of the time series, i.e., the variable we
wish to predict or analyze.
Additionally, you can pass multiple time series (stacked in the dataframe) considering an additional column:
- id_col:
Column name in df that identifies unique time series. Each unique value in this column
corresponds to a unique time series.
forecasts_dfOptionalNoneDataFrame with columns [unique_id, ds] and models.
id_colstrunique_idColumn that identifies each serie.
time_colstrdsColumn that identifies each timestep, its values can be timestamps or integers.
target_colstryColumn that contains the target.
unique_idsUnionNoneTime Series to plot.
If None, time series are selected randomly.
plot_randomboolTrueSelect time series to plot randomly.
modelsOptionalNoneList of models to plot.
levelOptionalNoneList of prediction intervals to plot if paseed.
max_insample_lengthOptionalNoneMax number of train/insample observations to be plotted.
plot_anomaliesboolFalsePlot anomalies for each prediction interval.
enginestrmatplotlibLibrary used to plot. ‘plotly’, ‘plotly-resampler’ or ‘matplotlib’.
resampler_kwargsOptionalNoneKwargs to be passed to plotly-resampler constructor.
For further custumization (“show_dash”) call the method,
store the plotting object and add the extra arguments to
its show_dash method.

TimeGPT.forecast

 TimeGPT.forecast (df:pandas.core.frame.DataFrame, h:int,
                   freq:Optional[str]=None, id_col:str='unique_id',
                   time_col:str='ds', target_col:str='y',
                   X_df:Optional[pandas.core.frame.DataFrame]=None,
                   level:Optional[List[Union[int,float]]]=None,
                   finetune_steps:int=0, finetune_loss:str='default',
                   clean_ex_first:bool=True, validate_token:bool=False,
                   add_history:bool=False,
                   date_features:Union[bool,List[str]]=False,
                   date_features_to_one_hot:Union[bool,List[str]]=True,
                   model:str='timegpt-1',
                   num_partitions:Optional[int]=None)

Forecast your time series using TimeGPT.

TypeDefaultDetails
dfDataFrameThe DataFrame on which the function will operate. Expected to contain at least the following columns:
- time_col:
Column name in df that contains the time indices of the time series. This is typically a datetime
column with regular intervals, e.g., hourly, daily, monthly data points.
- target_col:
Column name in df that contains the target variable of the time series, i.e., the variable we
wish to predict or analyze.
Additionally, you can pass multiple time series (stacked in the dataframe) considering an additional column:
- id_col:
Column name in df that identifies unique time series. Each unique value in this column
corresponds to a unique time series.
hintForecast horizon.
freqOptionalNoneFrequency of the data. By default, the freq will be inferred automatically.
See pandas’ available frequencies.
id_colstrunique_idColumn that identifies each serie.
time_colstrdsColumn that identifies each timestep, its values can be timestamps or integers.
target_colstryColumn that contains the target.
X_dfOptionalNoneDataFrame with [unique_id, ds] columns and df’s future exogenous.
levelOptionalNoneConfidence levels between 0 and 100 for prediction intervals.
finetune_stepsint0Number of steps used to finetune TimeGPT in the
new data.
finetune_lossstrdefaultLoss function to use for finetuning. Options are: default, mae, mse, rmse, mape, and smape.
clean_ex_firstboolTrueClean exogenous signal before making forecasts
using TimeGPT.
validate_tokenboolFalseIf True, validates token before
sending requests.
add_historyboolFalseReturn fitted values of the model.
date_featuresUnionFalseFeatures computed from the dates.
Can be pandas date attributes or functions that will take the dates as input.
If True automatically adds most used date features for the
frequency of df.
date_features_to_one_hotUnionTrueApply one-hot encoding to these date features.
If date_features=True, then all date features are
one-hot encoded by default.
modelstrtimegpt-1Model to use as a string. Options are: timegpt-1, and timegpt-1-long-horizon.
We recommend using timegpt-1-long-horizon for forecasting
if you want to predict more than one seasonal
period given the frequency of your data.
num_partitionsOptionalNoneNumber of partitions to use.
If None, the number of partitions will be equal
to the available parallel resources in distributed environments.
Returnspandas.DataFrameDataFrame with TimeGPT forecasts for point predictions and probabilistic
predictions (if level is not None).

TimeGPT.cross_validation

 TimeGPT.cross_validation (df:pandas.core.frame.DataFrame, h:int,
                           freq:Optional[str]=None,
                           id_col:str='unique_id', time_col:str='ds',
                           target_col:str='y',
                           level:Optional[List[Union[int,float]]]=None,
                           validate_token:bool=False, n_windows:int=1,
                           step_size:Optional[int]=None,
                           finetune_steps:int=0,
                           finetune_loss:str='default',
                           clean_ex_first:bool=True,
                           date_features:Union[bool,List[str]]=False, date
                           _features_to_one_hot:Union[bool,List[str]]=True
                           , model:str='timegpt-1',
                           num_partitions:Optional[int]=None)

Perform cross validation in your time series using TimeGPT.

TypeDefaultDetails
dfDataFrameThe DataFrame on which the function will operate. Expected to contain at least the following columns:
- time_col:
Column name in df that contains the time indices of the time series. This is typically a datetime
column with regular intervals, e.g., hourly, daily, monthly data points.
- target_col:
Column name in df that contains the target variable of the time series, i.e., the variable we
wish to predict or analyze.
Additionally, you can pass multiple time series (stacked in the dataframe) considering an additional column:
- id_col:
Column name in df that identifies unique time series. Each unique value in this column
corresponds to a unique time series.
hintForecast horizon.
freqOptionalNoneFrequency of the data. By default, the freq will be inferred automatically.
See pandas’ available frequencies.
id_colstrunique_idColumn that identifies each serie.
time_colstrdsColumn that identifies each timestep, its values can be timestamps or integers.
target_colstryColumn that contains the target.
levelOptionalNoneConfidence level between 0 and 100 for detecting the anomalies.
validate_tokenboolFalseIf True, validates token before
sending requests.
n_windowsint1Number of windows to evaluate.
step_sizeOptionalNoneStep size between each cross validation window. If None it will be equal to h.
finetune_stepsint0Number of steps used to finetune TimeGPT in the
new data.
finetune_lossstrdefaultLoss function to use for finetuning. Options are: default, mae, mse, rmse, mape, and smape.
clean_ex_firstboolTrueClean exogenous signal before making forecasts
using TimeGPT.
date_featuresUnionFalseFeatures computed from the dates.
Can be pandas date attributes or functions that will take the dates as input.
If True automatically adds most used date features for the
frequency of df.
date_features_to_one_hotUnionTrueApply one-hot encoding to these date features.
If date_features=True, then all date features are
one-hot encoded by default.
modelstrtimegpt-1Model to use as a string. Options are: timegpt-1, and timegpt-1-long-horizon.
We recommend using timegpt-1-long-horizon for forecasting
if you want to predict more than one seasonal
period given the frequency of your data.
num_partitionsOptionalNoneNumber of partitions to use.
If None, the number of partitions will be equal
to the available parallel resources in distributed environments.
Returnspandas.DataFrameDataFrame with cross validation forecasts.
# test pass dataframe with index
df_ds_index = df_.set_index('ds')[['unique_id', 'y']]
df_ds_index.index = pd.DatetimeIndex(df_ds_index.index)
fcst_inferred_df_index = timegpt.forecast(df_ds_index, h=10)
anom_inferred_df_index = timegpt.detect_anomalies(df_ds_index)
fcst_inferred_df = timegpt.forecast(df_[['ds', 'unique_id', 'y']], h=10)
anom_inferred_df = timegpt.detect_anomalies(df_[['ds', 'unique_id', 'y']])
pd.testing.assert_frame_equal(fcst_inferred_df_index, fcst_inferred_df, atol=1e-3)
pd.testing.assert_frame_equal(anom_inferred_df_index, anom_inferred_df, atol=1e-3)
df_ds_index = df_ds_index.groupby('unique_id').tail(80)
for freq in ['Y', 'W-MON', 'Q-DEC', 'H']:
    df_ds_index.index = np.concatenate(
        df_ds_index['unique_id'].nunique() * [pd.date_range(end='2023-01-01', periods=80, freq=freq)]
    )
    df_ds_index.index.name = 'ds'
    fcst_inferred_df_index = timegpt.forecast(df_ds_index, h=10)
    df_test = df_ds_index.reset_index()
    fcst_inferred_df = timegpt.forecast(df_test, h=10)
    pd.testing.assert_frame_equal(fcst_inferred_df_index, fcst_inferred_df, atol=1e-3)

TimeGPT.detect_anomalies

 TimeGPT.detect_anomalies (df:pandas.core.frame.DataFrame,
                           freq:Optional[str]=None,
                           id_col:str='unique_id', time_col:str='ds',
                           target_col:str='y', level:Union[int,float]=99,
                           clean_ex_first:bool=True,
                           validate_token:bool=False,
                           date_features:Union[bool,List[str]]=False, date
                           _features_to_one_hot:Union[bool,List[str]]=True
                           , model:str='timegpt-1',
                           num_partitions:Optional[int]=None)

Detect anomalies in your time series using TimeGPT.

TypeDefaultDetails
dfDataFrameThe DataFrame on which the function will operate. Expected to contain at least the following columns:
- time_col:
Column name in df that contains the time indices of the time series. This is typically a datetime
column with regular intervals, e.g., hourly, daily, monthly data points.
- target_col:
Column name in df that contains the target variable of the time series, i.e., the variable we
wish to predict or analyze.
Additionally, you can pass multiple time series (stacked in the dataframe) considering an additional column:
- id_col:
Column name in df that identifies unique time series. Each unique value in this column
corresponds to a unique time series.
freqOptionalNoneFrequency of the data. By default, the freq will be inferred automatically.
See pandas’ available frequencies.
id_colstrunique_idColumn that identifies each serie.
time_colstrdsColumn that identifies each timestep, its values can be timestamps or integers.
target_colstryColumn that contains the target.
levelUnion99Confidence level between 0 and 100 for detecting the anomalies.
clean_ex_firstboolTrueClean exogenous signal before making forecasts
using TimeGPT.
validate_tokenboolFalseIf True, validates token before
sending requests.
date_featuresUnionFalseFeatures computed from the dates.
Can be pandas date attributes or functions that will take the dates as input.
If True automatically adds most used date features for the
frequency of df.
date_features_to_one_hotUnionTrueApply one-hot encoding to these date features.
If date_features=True, then all date features are
one-hot encoded by default.
modelstrtimegpt-1Model to use as a string. Options are: timegpt-1, and timegpt-1-long-horizon.
We recommend using timegpt-1-long-horizon for forecasting
if you want to predict more than one seasonal
period given the frequency of your data.
num_partitionsOptionalNoneNumber of partitions to use.
If None, the number of partitions will be equal
to the available parallel resources in distributed environments.
Returnspandas.DataFrameDataFrame with anomalies flagged with 1 detected by TimeGPT.