source

NixtlaClient

 NixtlaClient (api_key:Optional[str]=None, base_url:Optional[str]=None,
               timeout:int=60, max_retries:int=6, retry_interval:int=10,
               max_wait_time:int=360)

Client to interact with the Nixtla API.

TypeDefaultDetails
api_keyOptionalNoneThe authorization api_key interacts with the Nixtla API.
If not provided, will use the NIXTLA_API_KEY environment variable.
base_urlOptionalNoneCustom base_url.
If not provided, will use the NIXTLA_BASE_URL environment variable.
timeoutint60Request timeout in seconds. Set this to None to disable it.
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.

source

NixtlaClient.validate_api_key

 NixtlaClient.validate_api_key (log:bool=True)

Returns True if your api_key is valid.


source

NixtlaClient.forecast

 NixtlaClient.forecast (df:~AnyDFType, h:typing.Annotated[int,Gt(gt=0)],
                        freq:Union[str,int,pandas._libs.tslibs.offsets.Bas
                        eOffset,NoneType]=None, id_col:str='unique_id',
                        time_col:str='ds', target_col:str='y',
                        X_df:Optional[~AnyDFType]=None,
                        level:Optional[list[Union[int,float]]]=None,
                        quantiles:Optional[list[float]]=None,
                        finetune_steps:typing.Annotated[int,Ge(ge=0)]=0,
                        finetune_depth:Literal[1,2,3,4,5]=1, finetune_loss
                        :Literal['default','mae','mse','rmse','mape','smap
                        e']='default',
                        finetuned_model_id:Optional[str]=None,
                        clean_ex_first:bool=True,
                        hist_exog_list:Optional[list[str]]=None,
                        validate_api_key:bool=False,
                        add_history:bool=False, date_features:Union[bool,l
                        ist[Union[str,Callable]]]=False, date_features_to_
                        one_hot:Union[bool,list[str]]=False, model:Literal
                        ['azureai','timegpt-1','timegpt-1-long-
                        horizon']='timegpt-1', num_partitions:Optional[Ann
                        otated[int,Gt(gt=0)]]=None,
                        feature_contributions:bool=False)

Forecast your time series using TimeGPT.

TypeDefaultDetails
dfAnyDFTypeThe 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.
hAnnotatedForecast horizon.
freqUnionNoneFrequency of the timestamps. If None, it 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.
quantilesOptionalNoneQuantiles to forecast, list between (0, 1).
level and quantiles should not be used simultaneously.
The output dataframe will have the quantile columns
formatted as TimeGPT-q-(100 * q) for each q.
100 * q represents percentiles but we choose this notation
to avoid having dots in column names.
finetune_stepsAnnotated0Number of steps used to finetune learning TimeGPT in the
new data.
finetune_depthLiteral1The depth of the finetuning. Uses a scale from 1 to 5, where 1 means little finetuning,
and 5 means that the entire model is finetuned.
finetune_lossLiteraldefaultLoss function to use for finetuning. Options are: default, mae, mse, rmse, mape, and smape.
finetuned_model_idOptionalNoneID of previously fine-tuned model to use.
clean_ex_firstboolTrueClean exogenous signal before making forecasts using TimeGPT.
hist_exog_listOptionalNoneColumn names of the historical exogenous features.
validate_api_keyboolFalseIf True, validates api_key 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_hotUnionFalseApply one-hot encoding to these date features.
If date_features=True, then all date features are
one-hot encoded by default.
modelLiteraltimegpt-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.
feature_contributionsboolFalse
ReturnsAnyDFTypeDataFrame with TimeGPT forecasts for point predictions and probabilistic
predictions (if level is not None).

source

NixtlaClient.cross_validation

 NixtlaClient.cross_validation (df:~AnyDFType,
                                h:typing.Annotated[int,Gt(gt=0)], freq:Uni
                                on[str,int,pandas._libs.tslibs.offsets.Bas
                                eOffset,NoneType]=None,
                                id_col:str='unique_id', time_col:str='ds',
                                target_col:str='y', level:Optional[list[Un
                                ion[int,float]]]=None,
                                quantiles:Optional[list[float]]=None,
                                validate_api_key:bool=False, n_windows:typ
                                ing.Annotated[int,Gt(gt=0)]=1, step_size:O
                                ptional[Annotated[int,Gt(gt=0)]]=None, fin
                                etune_steps:typing.Annotated[int,Ge(ge=0)]
                                =0, finetune_depth:Literal[1,2,3,4,5]=1, f
                                inetune_loss:Literal['default','mae','mse'
                                ,'rmse','mape','smape']='default',
                                finetuned_model_id:Optional[str]=None,
                                refit:bool=True, clean_ex_first:bool=True,
                                hist_exog_list:Optional[list[str]]=None,
                                date_features:Union[bool,list[str]]=False,
                                date_features_to_one_hot:Union[bool,list[s
                                tr]]=False, model:Literal['azureai','timeg
                                pt-1','timegpt-1-long-
                                horizon']='timegpt-1', num_partitions:Opti
                                onal[Annotated[int,Gt(gt=0)]]=None)

Perform cross validation in your time series using TimeGPT.

TypeDefaultDetails
dfAnyDFTypeThe 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.
hAnnotatedForecast horizon.
freqUnionNoneFrequency of the timestamps. If None, it 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 prediction intervals.
quantilesOptionalNoneQuantiles to forecast, list between (0, 1).
level and quantiles should not be used simultaneously.
The output dataframe will have the quantile columns
formatted as TimeGPT-q-(100 * q) for each q.
100 * q represents percentiles but we choose this notation
to avoid having dots in column names.
validate_api_keyboolFalseIf True, validates api_key before sending requests.
n_windowsAnnotated1Number of windows to evaluate.
step_sizeOptionalNoneStep size between each cross validation window. If None it will be equal to h.
finetune_stepsAnnotated0Number of steps used to finetune TimeGPT in the
new data.
finetune_depthLiteral1The depth of the finetuning. Uses a scale from 1 to 5, where 1 means little finetuning,
and 5 means that the entire model is finetuned.
finetune_lossLiteraldefaultLoss function to use for finetuning. Options are: default, mae, mse, rmse, mape, and smape.
finetuned_model_idOptionalNoneID of previously fine-tuned model to use.
refitboolTrueFine-tune the model in each window. If False, only fine-tunes on the first window.
Only used if finetune_steps > 0.
clean_ex_firstboolTrueClean exogenous signal before making forecasts using TimeGPT.
hist_exog_listOptionalNoneColumn names of the historical exogenous features.
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_hotUnionFalseApply one-hot encoding to these date features.
If date_features=True, then all date features are
one-hot encoded by default.
modelLiteraltimegpt-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.
ReturnsAnyDFTypeDataFrame with cross validation forecasts.

source

NixtlaClient.detect_anomalies

 NixtlaClient.detect_anomalies (df:~AnyDFType,
                                freq:Union[str,int,pandas._libs.tslibs.off
                                sets.BaseOffset,NoneType]=None,
                                id_col:str='unique_id', time_col:str='ds',
                                target_col:str='y',
                                level:Union[int,float]=99,
                                finetuned_model_id:Optional[str]=None,
                                clean_ex_first:bool=True,
                                validate_api_key:bool=False,
                                date_features:Union[bool,list[str]]=False,
                                date_features_to_one_hot:Union[bool,list[s
                                tr]]=False, model:Literal['azureai','timeg
                                pt-1','timegpt-1-long-
                                horizon']='timegpt-1', num_partitions:Opti
                                onal[Annotated[int,Gt(gt=0)]]=None)

Detect anomalies in your time series using TimeGPT.

TypeDefaultDetails
dfAnyDFTypeThe 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.
freqUnionNoneFrequency of the timestamps. If None, it 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.
finetuned_model_idOptionalNoneID of previously fine-tuned model to use.
clean_ex_firstboolTrueClean exogenous signal before making forecasts
using TimeGPT.
validate_api_keyboolFalseIf True, validates api_key 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_hotUnionFalseApply one-hot encoding to these date features.
If date_features=True, then all date features are
one-hot encoded by default.
modelLiteraltimegpt-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.
ReturnsAnyDFTypeDataFrame with anomalies flagged by TimeGPT.

source

NixtlaClient.usage

 NixtlaClient.usage ()

Query consumed requests and limits


source

NixtlaClient.finetune

 NixtlaClient.finetune
                        (df:Union[pandas.core.frame.DataFrame,polars.dataf
                        rame.frame.DataFrame], freq:Union[str,int,pandas._
                        libs.tslibs.offsets.BaseOffset,NoneType]=None,
                        id_col:str='unique_id', time_col:str='ds',
                        target_col:str='y',
                        finetune_steps:typing.Annotated[int,Ge(ge=0)]=10,
                        finetune_depth:Literal[1,2,3,4,5]=1, finetune_loss
                        :Literal['default','mae','mse','rmse','mape','smap
                        e']='default', output_model_id:Optional[str]=None,
                        finetuned_model_id:Optional[str]=None, model:Liter
                        al['azureai','timegpt-1','timegpt-1-long-
                        horizon']='timegpt-1')

Fine-tune TimeGPT to your series.

TypeDefaultDetails
dfUnionThe 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.
freqUnionNoneFrequency of the timestamps. If None, it 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.
finetune_stepsAnnotated10Number of steps used to finetune learning TimeGPT in the new data.
finetune_depthLiteral1The depth of the finetuning. Uses a scale from 1 to 5, where 1 means little finetuning,
and 5 means that the entire model is finetuned.
finetune_lossLiteraldefaultLoss function to use for finetuning. Options are: default, mae, mse, rmse, mape, and smape.
output_model_idOptionalNoneID to assign to the fine-tuned model. If None, an UUID is used.
finetuned_model_idOptionalNoneID of previously fine-tuned model to use as base.
modelLiteraltimegpt-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.
ReturnsstrID of the fine-tuned model

source

NixtlaClient.finetuned_models

 NixtlaClient.finetuned_models ()

List fine-tuned models


source

NixtlaClient.delete_finetuned_model

 NixtlaClient.delete_finetuned_model (finetuned_model_id:str)

Delete a previously fine-tuned model

TypeDetails
finetuned_model_idstrID of the fine-tuned model to be deleted.
ReturnsboolWhether delete was successful.

source

NixtlaClient.plot

 NixtlaClient.plot (df:Union[pandas.core.frame.DataFrame,polars.dataframe.
                    frame.DataFrame,NoneType]=None, forecasts_df:Union[pan
                    das.core.frame.DataFrame,polars.dataframe.frame.DataFr
                    ame,NoneType]=None, id_col:str='unique_id',
                    time_col:str='ds', target_col:str='y', unique_ids:Unio
                    n[list[str],NoneType,numpy.ndarray]=None,
                    plot_random:bool=True, max_ids:int=8,
                    models:Optional[list[str]]=None,
                    level:Optional[list[Union[int,float]]]=None,
                    max_insample_length:Optional[int]=None,
                    plot_anomalies:bool=False,
                    engine:Literal['matplotlib','plotly','plotly-
                    resampler']='matplotlib',
                    resampler_kwargs:Optional[dict]=None, ax:Union[Forward
                    Ref('plt.Axes'),numpy.ndarray,ForwardRef('plotly.graph
                    _objects.Figure'),NoneType]=None)

Plot forecasts and insample values.

TypeDefaultDetails
dfUnionNoneThe 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_dfUnionNoneDataFrame 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.
max_idsint8Maximum number of ids to plot.
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.
engineLiteralmatplotlibLibrary used to plot. ‘matplotlib’, ‘plotly’ or ‘plotly-resampler’.
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.
axUnionNoneObject where plots will be added.