SDK Reference

---

NixtlaClient

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

Constructs all the necessary attributes for the NixtlaClient object.

	Type	Default	Details
api_key	Optional	None	The authorization api_key interacts with the Nixtla API. If not provided, it will be inferred by the NIXTLA_API_KEY environment variable.
base_url	Optional	None	Custom base_url. Pass only if provided.
max_retries	int	6	The 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_interval	int	10	The 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_time	int	360	The 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

 TimeGPT (*args, **kwargs)

*Class TimeGPT is deprecated; use NixtlaClient instead.

This class is deprecated and may be removed in future releases. Please use NixtlaClient instead.*

---

NixtlaClient.validate_api_key

 NixtlaClient.validate_api_key (log:bool=True)

Returns True if your api_key is valid.

---

NixtlaClient.validate_token

 NixtlaClient.validate_token ()

this is deprecated in favor of validate_api_key

---

NixtlaClient.plot

 NixtlaClient.plot (df:pandas.core.frame.DataFrame,
                    forecasts_df:Optional[pandas.core.frame.DataFrame]=Non
                    e, id_col:str='unique_id', time_col:str='ds',
                    target_col:str='y', unique_ids:Union[List[str],NoneTyp
                    e,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.

	Type	Default	Details
df	DataFrame		The 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_df	Optional	None	DataFrame with columns [unique_id, ds] and models.
id_col	str	unique_id	Column that identifies each serie.
time_col	str	ds	Column that identifies each timestep, its values can be timestamps or integers.
target_col	str	y	Column that contains the target.
unique_ids	Union	None	Time Series to plot. If None, time series are selected randomly.
plot_random	bool	True	Select time series to plot randomly.
models	Optional	None	List of models to plot.
level	Optional	None	List of prediction intervals to plot if paseed.
max_insample_length	Optional	None	Max number of train/insample observations to be plotted.
plot_anomalies	bool	False	Plot anomalies for each prediction interval.
engine	str	matplotlib	Library used to plot. ‘plotly’, ‘plotly-resampler’ or ‘matplotlib’.
resampler_kwargs	Optional	None	Kwargs 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.

---

NixtlaClient.forecast

 NixtlaClient.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,
                        quantiles:Optional[List[float]]=None,
                        finetune_steps:int=0, finetune_loss:str='default',
                        clean_ex_first:bool=True,
                        validate_api_key:bool=False,
                        add_history:bool=False,
                        date_features:Union[bool,List[str]]=False, date_fe
                        atures_to_one_hot:Union[bool,List[str]]=True,
                        model:str='timegpt-1',
                        num_partitions:Optional[int]=None)

Forecast your time series using TimeGPT.

	Type	Default	Details
df	DataFrame		The 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.
h	int		Forecast horizon.
freq	Optional	None	Frequency of the data. By default, the freq will be inferred automatically. See pandas’ available frequencies.
id_col	str	unique_id	Column that identifies each serie.
time_col	str	ds	Column that identifies each timestep, its values can be timestamps or integers.
target_col	str	y	Column that contains the target.
X_df	Optional	None	DataFrame with [unique_id, ds] columns and df’s future exogenous.
level	Optional	None	Confidence levels between 0 and 100 for prediction intervals.
quantiles	Optional	None	Quantiles 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_steps	int	0	Number of steps used to finetune learning TimeGPT in the new data.
finetune_loss	str	default	Loss function to use for finetuning. Options are: default, mae, mse, rmse, mape, and smape.
clean_ex_first	bool	True	Clean exogenous signal before making forecasts using TimeGPT.
validate_api_key	bool	False	If True, validates api_key before sending requests.
add_history	bool	False	Return fitted values of the model.
date_features	Union	False	Features 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_hot	Union	True	Apply one-hot encoding to these date features. If date_features=True, then all date features are one-hot encoded by default.
model	str	timegpt-1	Model 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_partitions	Optional	None	Number of partitions to use. If None, the number of partitions will be equal to the available parallel resources in distributed environments.
Returns	pandas.DataFrame		DataFrame with TimeGPT forecasts for point predictions and probabilistic predictions (if level is not None).

---

NixtlaClient.cross_validation

 NixtlaClient.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[Un
                                ion[int,float]]]=None,
                                quantiles:Optional[List[float]]=None,
                                validate_api_key: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[s
                                tr]]=True, model:str='timegpt-1',
                                num_partitions:Optional[int]=None)

Perform cross validation in your time series using TimeGPT.

	Type	Default	Details
df	DataFrame		The 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.
h	int		Forecast horizon.
freq	Optional	None	Frequency of the data. By default, the freq will be inferred automatically. See pandas’ available frequencies.
id_col	str	unique_id	Column that identifies each serie.
time_col	str	ds	Column that identifies each timestep, its values can be timestamps or integers.
target_col	str	y	Column that contains the target.
level	Optional	None	Confidence level between 0 and 100 for prediction intervals.
quantiles	Optional	None	Quantiles 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_key	bool	False	If True, validates api_key before sending requests.
n_windows	int	1	Number of windows to evaluate.
step_size	Optional	None	Step size between each cross validation window. If None it will be equal to h.
finetune_steps	int	0	Number of steps used to finetune TimeGPT in the new data.
finetune_loss	str	default	Loss function to use for finetuning. Options are: default, mae, mse, rmse, mape, and smape.
clean_ex_first	bool	True	Clean exogenous signal before making forecasts using TimeGPT.
date_features	Union	False	Features 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_hot	Union	True	Apply one-hot encoding to these date features. If date_features=True, then all date features are one-hot encoded by default.
model	str	timegpt-1	Model 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_partitions	Optional	None	Number of partitions to use. If None, the number of partitions will be equal to the available parallel resources in distributed environments.
Returns	pandas.DataFrame		DataFrame with cross validation forecasts.

---

NixtlaClient.detect_anomalies

 NixtlaClient.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_api_key:bool=False,
                                date_features:Union[bool,List[str]]=False,
                                date_features_to_one_hot:Union[bool,List[s
                                tr]]=True, model:str='timegpt-1',
                                num_partitions:Optional[int]=None)

Detect anomalies in your time series using TimeGPT.

	Type	Default	Details
df	DataFrame		The 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.
freq	Optional	None	Frequency of the data. By default, the freq will be inferred automatically. See pandas’ available frequencies.
id_col	str	unique_id	Column that identifies each serie.
time_col	str	ds	Column that identifies each timestep, its values can be timestamps or integers.
target_col	str	y	Column that contains the target.
level	Union	99	Confidence level between 0 and 100 for detecting the anomalies.
clean_ex_first	bool	True	Clean exogenous signal before making forecasts using TimeGPT.
validate_api_key	bool	False	If True, validates api_key before sending requests.
date_features	Union	False	Features 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_hot	Union	True	Apply one-hot encoding to these date features. If date_features=True, then all date features are one-hot encoded by default.
model	str	timegpt-1	Model 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_partitions	Optional	None	Number of partitions to use. If None, the number of partitions will be equal to the available parallel resources in distributed environments.
Returns	pandas.DataFrame		DataFrame with anomalies flagged with 1 detected by TimeGPT.