Forecasters#

LSTMForecaster#

Long short-term memory(LSTM) is a special type of recurrent neural network(RNN). We implement the basic version of LSTM - VanillaLSTM for this forecaster for time-series forecasting task. It has two LSTM layers, two dropout layer and a dense layer.

For the detailed algorithm description, please refer to here.

class bigdl.chronos.forecaster.lstm_forecaster.LSTMForecaster(past_seq_len, input_feature_num, output_feature_num, hidden_dim=32, layer_num=1, normalization=True, decomposition_kernel_size=0, dropout=0.1, optimizer='Adam', loss='mse', lr=0.001, metrics=['mse'], seed=None, distributed=False, workers_per_node=1, distributed_backend='ray')[source]#

Bases: bigdl.chronos.forecaster.base_forecaster.BasePytorchForecaster

Example

>>> #The dataset is split into x_train, x_val, x_test, y_train, y_val, y_test
>>> # 1. Initialize Forecaster directly
>>> forecaster = LSTMForecaster(past_seq_len=24,
                                input_feature_num=2,
                                output_feature_num=2,
                                ...)
>>>
>>> # 2. Initialize Forecaster from from_tsdataset
>>> forecaster = LSTMForecaster.from_tsdataset(tsdata, **kwargs)
>>> forecaster.fit(tsdata, epochs=2, ...)
>>> forecaster.to_local()  # if you set distributed=True
>>> test_pred = forecaster.predict(x_test)
>>> test_eval = forecaster.evaluate((x_test, y_test))
>>> forecaster.save({ckpt_name})
>>> forecaster.load({ckpt_name})

Build a LSTM Forecast Model.

Parameters

past_seq_len – Specify the history time steps (i.e. lookback).
input_feature_num – Specify the feature dimension.
output_feature_num – Specify the output dimension.
hidden_dim – int or list, Specify the hidden dim of each lstm layer. The value defaults to 32.
layer_num – Specify the number of lstm layer to be used. The value defaults to 1.
normalization – bool, Specify if to use normalization trick to alleviate distribution shift. It first subtractes the last value of the sequence and add back after the model forwarding.
decomposition_kernel_size – int, Specify the kernel size in moving average. The decomposition method will be applied if and only if decomposition_kernel_size is greater than 1, which first decomposes the raw sequence into a trend component by a moving average kernel and a remainder(seasonal) component. Then, two models are applied to each component and sum up the two outputs to get the final prediction. This value defaults to 0.
dropout – int or list, Specify the dropout close possibility (i.e. the close possibility to a neuron). This value defaults to 0.1.
optimizer – Specify the optimizer used for training. This value defaults to “Adam”.
loss – str or pytorch loss instance, Specify the loss function used for training. This value defaults to “mse”. You can choose from “mse”, “mae”, “huber_loss” or any customized loss instance you want to use.
lr – Specify the learning rate. This value defaults to 0.001.
metrics – A list contains metrics for evaluating the quality of forecasting. You may only choose from “mse” and “mae” for a distributed forecaster. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape” or a callable function for a non-distributed forecaster. If callable function, it signature should be func(y_true, y_pred), where y_true and y_pred are numpy ndarray.
seed – int, random seed for training. This value defaults to None.
distributed – bool, if init the forecaster in a distributed fashion. If True, the internal model will use an Orca Estimator. If False, the internal model will use a pytorch model. The value defaults to False.
workers_per_node – int, the number of worker you want to use. The value defaults to 1. The param is only effective when distributed is set to True.
distributed_backend – str, select from “ray” or “horovod”. The value defaults to “ray”.

build_jit(thread_num=1, use_ipex=False)#

Build jit model to speed up inference and reduce latency. The method is Not required to call before predict_with_jit or export_torchscript_file.

It is recommended to use when you want to:

1. Strictly control the thread to be used during inferencing.

2. Alleviate the cold start problem when you call predict_with_jit

for the first time.

Parameters

use_ipex – if to use intel-pytorch-extension for acceleration. Typically, intel-pytorch-extension will bring some acceleration while causing some unexpected error as well.
thread_num –

int, the num of thread limit. The value is set to 1 by
default where no limit is set.Besides, the environment variable

OMP_NUM_THREADS is suggested to be same as thread_num.

build_onnx(thread_num=1, sess_options=None)#

Build onnx model to speed up inference and reduce latency. The method is Not required to call before predict_with_onnx, evaluate_with_onnx or export_onnx_file. It is recommended to use when you want to:

1. Strictly control the thread to be used during inferencing.

2. Alleviate the cold start problem when you call predict_with_onnx for the first time.

Parameters

thread_num – int, the num of thread limit. The value is set to None by default where no limit is set. Besides, the environment variable OMP_NUM_THREADS is suggested to be same as thread_num.
sess_options – an onnxruntime.SessionOptions instance, if you set this other than None, a new onnxruntime session will be built on this setting and ignore other settings you assigned(e.g. thread_num…).

Example

>>> # to pre build onnx sess
>>> forecaster.build_onnx(thread_num=2)  # build onnx runtime sess for two threads
>>> pred = forecaster.predict_with_onnx(data)
>>> # ------------------------------------------------------
>>> # directly call onnx related method is also supported
>>> # default to build onnx runtime sess for single thread
>>> pred = forecaster.predict_with_onnx(data)

build_openvino(thread_num=1)#

Build openvino model to speed up inference and reduce latency. The method is Not required to call before predict_with_openvino.

It is recommended to use when you want to:

1. Strictly control the thread to be used during inferencing.

2. Alleviate the cold start problem when you call predict_with_openvino for the first time.

Parameters: thread_num – int, the num of thread limit. The value is set to 1 by default where no limit is set. Besides, the environment variable OMP_NUM_THREADS is suggested to be same as thread_num.

evaluate(data, batch_size=32, multioutput='raw_values', quantize=False, acceleration: bool = True)#

Evaluate using a trained forecaster.

If you want to evaluate on a single node(which is common practice), please call .to_local().evaluate(data, …)

Please note that evaluate result is calculated by scaled y and yhat. If you scaled your data (e.g. use .scale() on the TSDataset), please follow the following code snap to evaluate your result if you need to evaluate on unscaled data.

>>> from bigdl.chronos.metric.forecast_metrics import Evaluator
>>> y_hat = forecaster.predict(x)
>>> y_hat_unscaled = tsdata.unscale_numpy(y_hat) # or other customized unscale methods
>>> y_unscaled = tsdata.unscale_numpy(y) # or other customized unscale methods
>>> Evaluator.evaluate(metric=..., y_unscaled, y_hat_unscaled, multioutput=...)

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x, ‘y’: y}, where x and y’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – evaluate batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time).
multioutput – Defines aggregating of multiple output values. String in [‘raw_values’, ‘uniform_average’]. The value defaults to ‘raw_values’.The param is only effective when the forecaster is a non-distribtued version.
quantize – if use the quantized model to predict.
acceleration – bool variable indicates whether use original model. Default to True means use accelerated_model to predict, which requires to call one of .build_jit(), .build_onnx(), .build_openvino() and .optimize(), otherwise the original model will be used to predict.

Returns

A list of evaluation results. Each item represents a metric.

evaluate_with_onnx(data, batch_size=32, multioutput='raw_values', quantize=False)#

Evaluate using a trained forecaster with onnxruntime. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_onnx is valid and Forecaster will automatically build an onnxruntime session with default settings (thread num is 1).

Please note that evaluate result is calculated by scaled y and yhat. If you scaled your data (e.g. use .scale() on the TSDataset) please follow the following code snap to evaluate your result if you need to evaluate on unscaled data.

>>> from bigdl.chronos.metric.forecast_metrics import Evaluator
>>> y_hat = forecaster.predict_with_onnx(x)
>>> y_hat_unscaled = tsdata.unscale_numpy(y_hat) # or other customized unscale methods
>>> y_unscaled = tsdata.unscale_numpy(y) # or other customized unscale methods
>>> Evaluator.evaluate(metric=..., y_unscaled, y_hat_unscaled, multioutput=...)

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

should be the same as future_seq_len and output_feature_num.

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – evaluate batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time).
multioutput – Defines aggregating of multiple output values. String in [‘raw_values’, ‘uniform_average’]. The value defaults to ‘raw_values’.
quantize – if use the quantized onnx model to evaluate.

Returns

A list of evaluation results. Each item represents a metric.

export_onnx_file(dirname='fp32_onnx', quantized_dirname=None)#

Save the onnx model file to the disk.

Parameters

dirname – The dir location you want to save the onnx file.
quantized_dirname – The dir location you want to save the quantized onnx file.

export_openvino_file(dirname='fp32_openvino', quantized_dirname=None)#

Save the openvino model file to the disk.

Parameters

dirname – The dir location you want to save the openvino file.
quantized_dirname – The dir location you want to save the quantized openvino file.

export_torchscript_file(dirname='fp32_torchscript', quantized_dirname=None, save_pipeline=False, tsdata=None, drop_dt_col=True)#

Save the torchscript model file and the whole forecasting pipeline to the disk.

When the whole forecasting pipeline is saved, it can be used without Python environment. For example, when you finish developing a forecaster, you could call this method with “save_pipeline=True” to save the whole pipeline (data preprocessing, inference, data postprocessing) to torchscript (the forecaster will be saved as torchscript model too), then you could deploy the pipeline in C++ using libtorch APIs.

Currently the pipeline is similar to the following code:

>>> # preprocess
>>> tsdata.scale(scaler, fit=False) \
>>>       .roll(lookback, horizon, is_predict=True)
>>> preprocess_output = tsdata.to_numpy()
>>> # inference using trained forecaster
>>> # forecaster_module is the saved torchscript model
>>> inference_output = forecaster_module.forward(preprocess_output)
>>> # postprocess
>>> postprocess_output = tsdata.unscale_numpy(inference_output)

When deploying, the pipeline can be used by:

>>> // deployment in C++
>>> #include <torch/torch.h>
>>> #include <torch/script.h>
>>> // create input tensor from your data
>>> // The data to create the input tensor should have the same format as the
>>> // data used in developing
>>> torch::Tensor input = create_input_tensor(data);
>>> // load the pipeline
>>> torch::jit::script::Module forecasting_pipeline;
>>> forecasting_pipeline = torch::jit::load(path);
>>> // run pipeline
>>> torch::Tensor output = forecasting_pipeline.forward(input_tensor).toTensor();

The limitations of exporting the forecasting pipeline is same as limitations in TSDataset.export_jit():

Please make sure the value of each column can be converted to Pytorch tensor, for example, id “00” is not allowed because str can not be converted to a tensor, you should use integer (0, 1, ..) as id instead of string.

Some features in tsdataset.scale and tsdataset.roll are unavailable in this pipeline:

If self.roll_additional_feature is not None, it can’t be processed in scale and roll

id_sensitive, time_enc and label_len parameter is not supported in roll

Users are expected to call .scale(scaler, fit=True) before calling export_jit. Single roll operation is not supported for converting now.

Parameters

dirname – The dir location you want to save the torchscript file.
quantized_dirname – The dir location you want to save the quantized torchscript model.
save_pipeline – Whether to save the whole forecasting pipeline, defaluts to False. If set to True, the whole forecasting pipeline will be saved in “dirname/chronos_forecasting_pipeline.pt”, if set to False, only the torchscript model will be saved.
tsdata – The TSDataset instance used when developing the forecaster. The parameter should be used only when save_pipeline is True.
drop_dt_col – Whether to delete the datetime column, defaults to True. The parameter is valid only when save_pipeline is True. Since datetime value (like “2022-12-12”) can’t be converted to Pytorch tensor, you can choose different ways to workaround this. If set to True, the datetime column will be deleted, then you also need to skip the datetime column when reading data from data source (like csv files) in deployment environment to keep the same structure as the data used in development; if set to False, the datetime column will not be deleted, and you need to make sure the datetime colunm can be successfully converted to Pytorch tensor when reading data in deployment environment. For example, you can set each data in datetime column to an int (or other vaild types) value, since datetime column is not necessary in preprocessing and postprocessing, the value can be arbitrary.

fit(data, validation_data=None, epochs=1, batch_size=32, validation_mode='output', earlystop_patience=1, use_trial_id=None)#

Fit(Train) the forecaster.

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x, ‘y’: y}, where x and y’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
validation_data –
Validation sample for validation loop. Defaults to ‘None’. If you do not input data for ‘validation_data’, the validation_step will be skipped. Validation data will be ignored under distributed mode. The validation_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x, ‘y’: y}, where x and y’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
epochs – Number of epochs you want to train. The value defaults to 1.
batch_size – Number of batch size you want to train. The value defaults to 32. If you input a pytorch dataloader for data, the batch_size will follow the batch_size setted in data.if the forecaster is distributed, the batch_size will be evenly distributed to all workers.
validation_mode –
A str represent the operation mode while having ‘validation_data’. Defaults to ‘output’. The validation_mode includes the following types:

1. output:

If you choose ‘output’ for validation_mode, it will return a dict that records the

average validation loss of each epoch.

2. earlystop:

Monitor the val_loss and stop training when it stops improving.

3. best_epoch:

Monitor the val_loss. And load the checkpoint of the epoch with the smallest

val_loss after the training.
earlystop_patience – Number of checks with no improvement after which training will be stopped. It takes effect when ‘validation_mode’ is ‘earlystop’. Under the default configuration, one check happens after every training epoch.
use_trail_id – choose a internal according to trial_id, which is used only in multi-objective search.

Returns

Validation loss if ‘validation_data’ is not None.

get_context(thread_num=None, optimize=True)#

Obtain context manager from forecaster.

Parameters

thread_num – int, the num of thread limit. The value is set to None by default where no limit is set.
optimize – bool variable indicates whether use original model. Default to True means use accelerated_model to generate context manager, which requires to call .optimize(), otherwise the original model will be used.

Returns

a context manager.

get_model()#

Returns the learned PyTorch model.

Returns: a pytorch model instance

load(checkpoint_file, quantize_checkpoint_file=None)#

restore the forecaster.

Parameters

checkpoint_file – The checkpoint file location you want to load the forecaster.
quantize_checkpoint_file – The checkpoint file location you want to load the quantized forecaster.

optimize(train_data, validation_data=None, batch_size: int = 32, thread_num: Optional[int] = None, accelerator: Optional[str] = None, precision: Optional[str] = None, metric: str = 'mse', accuracy_criterion: Optional[float] = None)#

This method will traverse existing optimization methods(onnxruntime, openvino, jit, …) and save the model with minimum latency under the given data and search restrictions(accelerator, precision, accuracy_criterion) in forecaster.accelerated_model. This method is required to call before predict and evaluate. Now this function is only for non-distributed model.

Parameters

train_data –
Data used for training model. Users should be careful with this parameter since this data might be exposed to the model, which causing data leak. The train_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

The batch_size of this dataloader is important as well, users may want to set it

to the same batch size you may want to use the model in real deploy environment.

E.g. batch size should be set to 1 if you would like to use the accelerated model

in an online service.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
validation_data(optional) –
This is only needed when users care about the possible accuracy drop. The validation_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – Number of batch size you want to use the model in real deploy environment. The value defaults to 32. If you input a pytorch dataloader for train_data, the batch_size will follow the batch_size setted in train_data.
thread_num – int, the num of thread limit. The value is set to None by default where no limit is set.
accelerator – (optional) Use accelerator ‘None’, ‘onnxruntime’, ‘openvino’, ‘jit’, defaults to None. If not None, then will only find the model with this specific accelerator.
precision – (optional) Supported type: ‘int8’, ‘bf16’, ‘fp32’. Defaults to None which represents no precision limit. If not None, then will only find the model with this specific precision.
metric – (optional) A str represent corresponding metric which is used for calculating accuracy.
accuracy_criterion – (optional) a float represents tolerable accuracy drop percentage, defaults to None meaning no accuracy control.

Example

>>> # obtain optimized model
>>> forecaster.optimize(train_data, val_data, thread_num=1)
>>> pred = forecaster.predict(data)

predict(data, batch_size=32, quantize=False, acceleration: bool = True)#

Predict using a trained forecaster.

if you want to predict on a single node(which is common practice), please call .to_local().predict(x, …)

Parameters

data –
The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x}, where x’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume memory.
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time).
quantize – if use the quantized model to predict.
acceleration – bool variable indicates whether use original model. Default to True means use accelerated_model to predict, which requires to call one of .build_jit(), .build_onnx(), .build_openvino() and .optimize(), otherwise the original model will be used to predict.

Returns

A numpy array with shape (num_samples, horizon, target_dim) if data is a numpy ndarray or a dataloader. A xshard item with format {‘prediction’: result}, where result is a numpy array with shape (num_samples, horizon, target_dim) if data is a xshard item.

predict_interval(data, validation_data=None, batch_size=32, repetition_times=5)#

Calculate confidence interval of data based on Monte Carlo dropout(MC dropout). Related paper : https://arxiv.org/abs/1709.01907

Parameters

data –
The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
validation_data –
The validation_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time).
repetition_times – Defines repeate how many times to calculate model uncertainty based on MC Dropout.

Returns

prediction and standard deviation which are both numpy array with shape (num_samples, horizon, target_dim)

predict_with_jit(data, batch_size=32, quantize=False)#

Predict using a trained forecaster with jit. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_jit is valid and Forecaster will automatically build an jit session with default settings (thread num is 1).

Parameters

data –

The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.

param batch_size: predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time). Defaults to 32. None for all-data-single-time inference.
param quantize: if use the quantized jit model to predict. Not support yet.
return: A numpy array with shape (num_samples, horizon, target_dim).

predict_with_onnx(data, batch_size=32, quantize=False)#

Predict using a trained forecaster with onnxruntime. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_onnx is valid and Forecaster will automatically build an onnxruntime session with default settings (thread num is 1).

Parameters

data –
The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time). Defaults to 32. None for all-data-single-time inference.
quantize – if use the quantized onnx model to predict.

Returns

A numpy array with shape (num_samples, horizon, target_dim).

predict_with_openvino(data, batch_size=32, quantize=False)#

Predict using a trained forecaster with openvino. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_openvino is valid and Forecaster will automatically build an openvino session with default settings (thread num is 1).

Parameters

data –

The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.

param batch_size: predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time). Defaults to 32. None for all-data-single-time inference.
param quantize: if use the quantized openvino model to predict.
return: A numpy array with shape (num_samples, horizon, target_dim).

quantize(calib_data=None, val_data=None, metric=None, conf=None, framework='pytorch_fx', approach='static', tuning_strategy='bayesian', relative_drop=None, absolute_drop=None, timeout=0, max_trials=1, sess_options=None, thread_num=None)#

Quantize the forecaster.

Parameters

calib_data –
Required for static quantization. Support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
val_data –
for evaluation. Support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
metric – A str represent the metrics for tunning the quality of quantization. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape”.
conf – A path to conf yaml file for quantization. Default to None, using default config.
framework – A str represent the framework for quantization. You may choose from “pytorch_fx”, “pytorch_ipex”, “onnxrt_integerops”, “onnxrt_qlinearops”, “openvino”. Default: ‘pytorch_fx’. Consistent with Intel Neural Compressor.
approach – str, ‘static’ or ‘dynamic’. Default to ‘static’. OpenVINO supports static mode only, if set to ‘dynamic’, it will be replaced with ‘static’.
tuning_strategy – str, ‘bayesian’, ‘basic’, ‘mse’ or ‘sigopt’. Default to ‘bayesian’.
relative_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 0.1 means that we accept a 10% increase in the metrics error.
absolute_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 5 means that we can only accept metrics smaller than 5.
timeout – Tuning timeout (seconds). Default to 0, which means early stop. Combine with max_trials field to decide when to exit.
max_trials – Max tune times. Default to 1. Combine with timeout field to decide when to exit. “timeout=0, max_trials=1” means it will try quantization only once and return satisfying best model.
sess_options – The session option for onnxruntime, only valid when framework contains ‘onnxrt_integerops’ or ‘onnxrt_qlinearops’, otherwise will be ignored.
thread_num – int, the num of thread limit. The value is set to None by default where no limit is set

save(checkpoint_file, quantize_checkpoint_file=None)#

Save the forecaster.

Please note that if you only want the pytorch model or onnx model file, you can call .get_model() or .export_onnx_file(). The checkpoint file generated by .save() method can only be used by .load().

Parameters

checkpoint_file – The location you want to save the forecaster.
quantize_checkpoint_file – The location you want to save quantized forecaster.

search_summary()#: Return search summary of HPO.

to_local()#

Transform a distributed forecaster to a local (non-distributed) one.

Common practice is to use distributed training (fit) and predict/ evaluate with onnx or other frameworks on a single node. To do so, you need to call .to_local() and transform the forecaster to a non- distributed one.

The optimizer is refreshed, incremental training after to_local might have some problem.

Returns: a forecaster instance.

tune(data, validation_data, target_metric, direction, directions=None, n_trials=2, n_parallels=1, epochs=1, batch_size=32, acceleration=False, input_sample=None, **kwargs)#

Search the hyper parameter.

Parameters

data – train data, as numpy ndarray tuple (x, y)
validation_data – validation data, as numpy ndarray tuple (x,y)
target_metric – the target metric to optimize, a string or an instance of torchmetrics.metric.Metric
direction – in which direction to optimize the target metric, “maximize” - larger the better “minimize” - smaller the better
n_trials – number of trials to run
n_parallels – number of parallel processes used to run trials. to use parallel tuning you need to use a RDB url for storage and specify study_name. For more information, refer to Nano AutoML user guide.
epochs – the number of epochs to run in each trial fit, defaults to 1
batch_size – number of batch size for each trial fit, defaults to 32
acceleration – Whether to automatically consider the model after inference acceleration in the search process. It will only take effect if target_metric contains “latency”. Default value is False.
input_sample – A set of inputs for trace, defaults to None if you have trace before or model is a LightningModule with any dataloader attached.
kwargs – some other parameters could be used for tuning, most useful one is sampler from SamplerType.Grid, SamplerType.Random and SamplerType.TPE so on.

classmethod from_tsdataset(tsdataset, past_seq_len=None, **kwargs)[source]#

Build a LSTM Forecaster Model.

Parameters

tsdataset – Train tsdataset, a bigdl.chronos.data.tsdataset.TSDataset instance.
past_seq_len – Specify the history time steps (i.e. lookback). Do not specify the ‘past_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_torch_data_loader’.
kwargs – Specify parameters of Forecaster, e.g. loss and optimizer, etc. More info, please refer to LSTMForecaster.__init__ methods.

Returns

A LSTM Forecaster Model.

class bigdl.chronos.forecaster.tf.lstm_forecaster.LSTMForecaster(past_seq_len, input_feature_num, output_feature_num, hidden_dim=32, layer_num=1, dropout=0.1, optimizer='Adam', loss='mse', lr=0.001, metrics=['mse'], seed=None, distributed=False, workers_per_node=1, distributed_backend='ray')[source]#

Bases: bigdl.chronos.forecaster.tf.base_forecaster.BaseTF2Forecaster

Example

>>> #The dataset is split into x_train, x_val, x_test, y_train, y_val, y_test
>>> forecaster = LSTMForecaster(past_seq_len=24,
                                input_feature_num=2,
                                output_feature_num=2,
                                ...)
>>> forecaster.fit((x_train, y_train))
>>> test_pred = forecaster.predict(x_test)
>>> test_eval = forecaster.evaluate((x_test, y_test))
>>> forecaster.save({ckpt_dir_name})
>>> forecaster.load({ckpt_dir_name})

Build a LSTM Forecast Model.

Parameters

past_seq_len – Specify the history time steps (i.e. lookback).
input_feature_num – Specify the feature dimension.
output_feature_num – Specify the output dimension.
hidden_dim – int or list, Specify the hidden dim of each lstm layer. The value defaults to 32.
layer_num – Specify the number of lstm layer to be used. The value defaults to 1.
dropout – int or list, Specify the dropout close possibility (i.e. the close possibility to a neuron). This value defaults to 0.1.
optimizer – Specify the optimizer used for training. This value defaults to “Adam”.
loss – Str or a tf.keras.losses.Loss instance, specify the loss function used for training. This value defaults to “mse”. You can choose from “mse”, “mae” and “huber_loss” or any customized loss instance you want to use.
lr – Specify the learning rate. This value defaults to 0.001.
metrics – A list contains metrics for evaluating the quality of forecasting. You may only choose from “mse” and “mae” for a distributed forecaster. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape” or a callable function for a non-distributed forecaster. If callable function, it signature should be func(y_true, y_pred), where y_true and y_pred are numpy ndarray.
seed – int, random seed for training. This value defaults to None.
distributed – bool, if init the forecaster in a distributed fashion. If True, the internal model will use an Orca Estimator. If False, the internal model will use a Keras model. The value defaults to False.
workers_per_node – int, the number of worker you want to use. The value defaults to 1. The param is only effective when distributed is set to True.
distributed_backend – str, select from “ray” or “horovod”. The value defaults to “ray”.

classmethod from_tsdataset(tsdataset, past_seq_len=None, **kwargs)[source]#

Build a LSTMForecaster Model

Parameters

tsdataset – A bigdl.chronos.data.tsdataset.TSDataset instance.
past_seq_len – past_seq_len: Specify the history time steps (i.e. lookback). Do not specify the ‘past_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_tf_dataset’.
kwargs – Specify parameters of Forecaster, e.g. loss and optimizer, etc. More info, please refer to LSTMForecaster.__init__ methods.

Returns

A LSTMForecaster Model

evaluate(data, batch_size=32, multioutput='raw_values', quantize=False)#

>>> from bigdl.chronos.metric.forecaster_metrics import Evaluator
>>> y_hat = forecaster.predict(x)
>>> y_hat_unscaled = tsdata.unscale_numpy(y_hat) # or other customized unscale methods
>>> y_unscaled = tsdata.unscale_numpy(y) # or other customized unscale methods
>>> Evaluator.evaluate(metric=..., y_unscaled, y_hat_unscaled, multioutput=...)

Params data: The data support following formats:

1. A numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. A tf.data.Dataset:

A TFDataset instance which contains x and y with same shape as the tuple.

x’s shape is (num_samples, lookback, feature_dim),

y’s shape is (num_samples, horizon, target_dim).

If set distributed to True, we do not recommend using tf.data.Dataset,

please replace with tsdataset or numpy.ndarray.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a tfdataset,

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
Params batch_size: evaluate batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time).
Params multioutput_value: Defines aggregating of multiple output values. String in [‘raw_values’, ‘uniform_average’]. The value defaults to ‘raw_values’.The param is only effective when the forecaster is a non-distribtued version.
Parameters: quantize – if use the quantized model to predict.
Returns: A list of evaluation results. Each item represents a metric.

fit(data, epochs=1, batch_size=32)#

Fit(Train) the forecaster.

Parameters

data –

The data support following formats:

1. A numpy ndarray tuple (x, y):
x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim
should be the same as past_seq_len and input_feature_num.
y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim
should be the same as future_seq_len and output_feature_num.

2. A tf.data.Dataset:
A TFDataset instance which contains x and y with same shape as the tuple.
x’s shape is (num_samples, lookback, feature_dim),
y’s shape is (num_samples, horizon, target_dim).
If set distributed to True, we do not recommend using tf.data.Dataset,
please replace with tsdataset or numpy.ndarray.

3. A bigdl.chronos.data.tsdataset.TSDataset instance.
Forecaster will automatically process the TSDataset.
By default, TSDataset will be transformed to a tfdataset,
Users may call roll on the TSDataset before calling fit
Then the training speed will be faster but will consume more memory.

Params epochs

Number of epochs you want to train. The value defaults to 1.

Params batch_size

Number of batch size you want to train. The value defaults to 32. Do not specify the batch_size, if your data in the form of tf.data datasets.

get_model()#

Returns the learned Keras model.

Returns: a keras model instance

load(checkpoint_file)#

Load the forecaster.

Params checkpoint_file: The checkpoint file location you want to load the forecaster.

predict(data, batch_size=32, quantize=False)#

Predict using a trained forecaster.

Params data: The data support following formats:

1. A numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. A tfdataset

A TFDataset instance which contains x and y with same shape as the tuple.

the tfdataset needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a tfdataset,

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
Params batch_size: predict batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time). The value default to 32. If set to None, the model will be used directly for inference.
Parameters: quantize – if use the quantized model to predict.
Returns: A numpy array with shape (num_samples, horizon, target_dim).

quantize(input_data=None, target_data=None, metric=None, conf=None, framework='tensorflow', approach='static', tuning_strategy='bayesian', relative_drop=None, absolute_drop=None, timeout=0, max_trials=1, sess_options=None, thread_num=None)#

Quantize the forecaster.

Parameters

input_data –
Input data which is used for training. Support following formats:

1. a numpy ndarray:

The shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. TensorFlow tensor:

The shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

3. an unbatched tf.data.Dataset. Should return a tuple of (inputs, targets).

Input data will be used as calibration dataset for static quantization,

as well as be used for generating input_sample to calculate latency.

To avoid data leak during calibration, please use training dataset.
target_data – Target data. It could be either Numpy array(s) or TensorFlow tensor(s) while the length should be consistent with input_data. If input_data is dataset, target_data will be ignored.
metric – A str represent the metrics for tunning the quality of quantization. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape”.
conf – A path to conf yaml file for quantization. Default to None, using default config.
framework – A str represent the framework for quantization. You may choose from “tensorflow”, “onnxrt_integerops”, “onnxrt_qlinearops”, “openvino”. Default: ‘tensorflow’.
approach – str, ‘static’ or ‘dynamic’. Default to ‘static’. Only ‘static’ approach is supported now.
tuning_strategy – str, ‘bayesian’, ‘basic’, ‘mse’ or ‘sigopt’. Default to ‘bayesian’.
relative_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 0.1 means that we accept a 10% increase in the metrics error.
absolute_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 5 means that we can only accept metrics smaller than 5.
timeout – Tuning timeout (seconds). Default to 0, which means early stop. Combine with max_trials field to decide when to exit.
max_trials – Max tune times. Default to 1. Combine with timeout field to decide when to exit. “timeout=0, max_trials=1” means it will try quantization only once and return satisfying best model.
sess_options – The session option for onnxruntime, only valid when framework contains ‘onnxrt_integerops’ or ‘onnxrt_qlinearops’, otherwise will be ignored.
thread_num – int, the num of thread limit, only valid when framework contains ‘onnxrt_integerops’ or ‘onnxrt_qlinearops’ or ‘openvino’. The value is set to None by default where no limit is set.

save(checkpoint_file)#

Save the forecaster.

Params checkpoint_file: The location you want to save the forecaster.

to_local()#

Transform a distributed forecaster to a local (non-distributed) one.

you need to call .to_local() and transform the forecaster to a non- distributed one.

Seq2SeqForecaster#

Seq2SeqForecaster wraps a sequence to sequence model based on LSTM, and is suitable for multivariant & multistep time series forecasting.

class bigdl.chronos.forecaster.seq2seq_forecaster.Seq2SeqForecaster(past_seq_len, future_seq_len, input_feature_num, output_feature_num, lstm_hidden_dim=64, lstm_layer_num=2, teacher_forcing=False, normalization=True, decomposition_kernel_size=0, dropout=0.1, optimizer='Adam', loss='mse', lr=0.001, metrics=['mse'], seed=None, distributed=False, workers_per_node=1, distributed_backend='ray')[source]#

Bases: bigdl.chronos.forecaster.base_forecaster.BasePytorchForecaster

Example

>>> #The dataset is split into x_train, x_val, x_test, y_train, y_val, y_test
>>> # 1. Initialize Forecaster directly
>>> forecaster = Seq2SeqForecaster(past_seq_len=24,
                                   future_seq_len=2,
                                   input_feature_num=1,
                                   output_feature_num=1,
                                   ...)
>>> # 2. Initialize Forecaster from from_tsdataset
>>> forecaster = Seq2SeqForecaster.from_tsdataset(tsdata, ...)
>>> forecaster.fit(tsdata, ...)
>>> forecaster.to_local()  # if you set distributed=True
>>> test_pred = forecaster.predict(x_test)
>>> test_eval = forecaster.evaluate((x_test, y_test))
>>> forecaster.save({ckpt_name})
>>> forecaster.load({ckpt_name})

Build a Seq2Seq Forecast Model.

Parameters

past_seq_len – Specify the history time steps (i.e. lookback).
future_seq_len – Specify the output time steps (i.e. horizon).
input_feature_num – Specify the feature dimension.
output_feature_num – Specify the output dimension.
lstm_hidden_dim – LSTM hidden channel for decoder and encoder. The value defaults to 64.
lstm_layer_num – LSTM layer number for decoder and encoder. The value defaults to 2.
teacher_forcing – If use teacher forcing in training. The value defaults to False.
normalization – bool, Specify if to use normalization trick to alleviate distribution shift. It first subtractes the last value of the sequence and add back after the model forwarding.
decomposition_kernel_size – int, Specify the kernel size in moving average. The decomposition method will be applied if and only if decomposition_kernel_size is greater than 1, which first decomposes the raw sequence into a trend component by a moving average kernel and a remainder(seasonal) component. Then, two models are applied to each component and sum up the two outputs to get the final prediction. This value defaults to 0.
dropout – Specify the dropout close possibility (i.e. the close possibility to a neuron). This value defaults to 0.1.
optimizer – Specify the optimizer used for training. This value defaults to “Adam”.
loss – str or pytorch loss instance, Specify the loss function used for training. This value defaults to “mse”. You can choose from “mse”, “mae”, “huber_loss” or any customized loss instance you want to use.
lr – Specify the learning rate. This value defaults to 0.001.
metrics – A list contains metrics for evaluating the quality of forecasting. You may only choose from “mse” and “mae” for a distributed forecaster. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape” or a callable function for a non-distributed forecaster. If callable function, it signature should be func(y_true, y_pred), where y_true and y_pred are numpy ndarray.
seed – int, random seed for training. This value defaults to None.
distributed – bool, if init the forecaster in a distributed fashion. If True, the internal model will use an Orca Estimator. If False, the internal model will use a pytorch model. The value defaults to False.
workers_per_node – int, the number of worker you want to use. The value defaults to 1. The param is only effective when distributed is set to True.
distributed_backend – str, select from “ray” or “horovod”. The value defaults to “ray”.

build_jit(thread_num=1, use_ipex=False)#

Build jit model to speed up inference and reduce latency. The method is Not required to call before predict_with_jit or export_torchscript_file.

It is recommended to use when you want to:

1. Strictly control the thread to be used during inferencing.

2. Alleviate the cold start problem when you call predict_with_jit

for the first time.

Parameters

use_ipex – if to use intel-pytorch-extension for acceleration. Typically, intel-pytorch-extension will bring some acceleration while causing some unexpected error as well.
thread_num –

int, the num of thread limit. The value is set to 1 by
default where no limit is set.Besides, the environment variable

OMP_NUM_THREADS is suggested to be same as thread_num.

build_onnx(thread_num=1, sess_options=None)#

1. Strictly control the thread to be used during inferencing.

2. Alleviate the cold start problem when you call predict_with_onnx for the first time.

Parameters

thread_num – int, the num of thread limit. The value is set to None by default where no limit is set. Besides, the environment variable OMP_NUM_THREADS is suggested to be same as thread_num.
sess_options – an onnxruntime.SessionOptions instance, if you set this other than None, a new onnxruntime session will be built on this setting and ignore other settings you assigned(e.g. thread_num…).

Example

>>> # to pre build onnx sess
>>> forecaster.build_onnx(thread_num=2)  # build onnx runtime sess for two threads
>>> pred = forecaster.predict_with_onnx(data)
>>> # ------------------------------------------------------
>>> # directly call onnx related method is also supported
>>> # default to build onnx runtime sess for single thread
>>> pred = forecaster.predict_with_onnx(data)

build_openvino(thread_num=1)#

Build openvino model to speed up inference and reduce latency. The method is Not required to call before predict_with_openvino.

It is recommended to use when you want to:

1. Strictly control the thread to be used during inferencing.

2. Alleviate the cold start problem when you call predict_with_openvino for the first time.

Parameters: thread_num – int, the num of thread limit. The value is set to 1 by default where no limit is set. Besides, the environment variable OMP_NUM_THREADS is suggested to be same as thread_num.

evaluate(data, batch_size=32, multioutput='raw_values', quantize=False, acceleration: bool = True)#

Evaluate using a trained forecaster.

If you want to evaluate on a single node(which is common practice), please call .to_local().evaluate(data, …)

>>> from bigdl.chronos.metric.forecast_metrics import Evaluator
>>> y_hat = forecaster.predict(x)
>>> y_hat_unscaled = tsdata.unscale_numpy(y_hat) # or other customized unscale methods
>>> y_unscaled = tsdata.unscale_numpy(y) # or other customized unscale methods
>>> Evaluator.evaluate(metric=..., y_unscaled, y_hat_unscaled, multioutput=...)

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x, ‘y’: y}, where x and y’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – evaluate batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time).
multioutput – Defines aggregating of multiple output values. String in [‘raw_values’, ‘uniform_average’]. The value defaults to ‘raw_values’.The param is only effective when the forecaster is a non-distribtued version.
quantize – if use the quantized model to predict.
acceleration – bool variable indicates whether use original model. Default to True means use accelerated_model to predict, which requires to call one of .build_jit(), .build_onnx(), .build_openvino() and .optimize(), otherwise the original model will be used to predict.

Returns

A list of evaluation results. Each item represents a metric.

evaluate_with_onnx(data, batch_size=32, multioutput='raw_values', quantize=False)#

Evaluate using a trained forecaster with onnxruntime. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_onnx is valid and Forecaster will automatically build an onnxruntime session with default settings (thread num is 1).

>>> from bigdl.chronos.metric.forecast_metrics import Evaluator
>>> y_hat = forecaster.predict_with_onnx(x)
>>> y_hat_unscaled = tsdata.unscale_numpy(y_hat) # or other customized unscale methods
>>> y_unscaled = tsdata.unscale_numpy(y) # or other customized unscale methods
>>> Evaluator.evaluate(metric=..., y_unscaled, y_hat_unscaled, multioutput=...)

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

should be the same as future_seq_len and output_feature_num.

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – evaluate batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time).
multioutput – Defines aggregating of multiple output values. String in [‘raw_values’, ‘uniform_average’]. The value defaults to ‘raw_values’.
quantize – if use the quantized onnx model to evaluate.

Returns

A list of evaluation results. Each item represents a metric.

export_onnx_file(dirname='fp32_onnx', quantized_dirname=None)#

Save the onnx model file to the disk.

Parameters

dirname – The dir location you want to save the onnx file.
quantized_dirname – The dir location you want to save the quantized onnx file.

export_openvino_file(dirname='fp32_openvino', quantized_dirname=None)#

Save the openvino model file to the disk.

Parameters

dirname – The dir location you want to save the openvino file.
quantized_dirname – The dir location you want to save the quantized openvino file.

export_torchscript_file(dirname='fp32_torchscript', quantized_dirname=None, save_pipeline=False, tsdata=None, drop_dt_col=True)#

Save the torchscript model file and the whole forecasting pipeline to the disk.

Currently the pipeline is similar to the following code:

>>> # preprocess
>>> tsdata.scale(scaler, fit=False) \
>>>       .roll(lookback, horizon, is_predict=True)
>>> preprocess_output = tsdata.to_numpy()
>>> # inference using trained forecaster
>>> # forecaster_module is the saved torchscript model
>>> inference_output = forecaster_module.forward(preprocess_output)
>>> # postprocess
>>> postprocess_output = tsdata.unscale_numpy(inference_output)

When deploying, the pipeline can be used by:

>>> // deployment in C++
>>> #include <torch/torch.h>
>>> #include <torch/script.h>
>>> // create input tensor from your data
>>> // The data to create the input tensor should have the same format as the
>>> // data used in developing
>>> torch::Tensor input = create_input_tensor(data);
>>> // load the pipeline
>>> torch::jit::script::Module forecasting_pipeline;
>>> forecasting_pipeline = torch::jit::load(path);
>>> // run pipeline
>>> torch::Tensor output = forecasting_pipeline.forward(input_tensor).toTensor();

The limitations of exporting the forecasting pipeline is same as limitations in TSDataset.export_jit():

Please make sure the value of each column can be converted to Pytorch tensor, for example, id “00” is not allowed because str can not be converted to a tensor, you should use integer (0, 1, ..) as id instead of string.

Some features in tsdataset.scale and tsdataset.roll are unavailable in this pipeline:

If self.roll_additional_feature is not None, it can’t be processed in scale and roll

id_sensitive, time_enc and label_len parameter is not supported in roll

Users are expected to call .scale(scaler, fit=True) before calling export_jit. Single roll operation is not supported for converting now.

Parameters

dirname – The dir location you want to save the torchscript file.
quantized_dirname – The dir location you want to save the quantized torchscript model.
save_pipeline – Whether to save the whole forecasting pipeline, defaluts to False. If set to True, the whole forecasting pipeline will be saved in “dirname/chronos_forecasting_pipeline.pt”, if set to False, only the torchscript model will be saved.
tsdata – The TSDataset instance used when developing the forecaster. The parameter should be used only when save_pipeline is True.
drop_dt_col – Whether to delete the datetime column, defaults to True. The parameter is valid only when save_pipeline is True. Since datetime value (like “2022-12-12”) can’t be converted to Pytorch tensor, you can choose different ways to workaround this. If set to True, the datetime column will be deleted, then you also need to skip the datetime column when reading data from data source (like csv files) in deployment environment to keep the same structure as the data used in development; if set to False, the datetime column will not be deleted, and you need to make sure the datetime colunm can be successfully converted to Pytorch tensor when reading data in deployment environment. For example, you can set each data in datetime column to an int (or other vaild types) value, since datetime column is not necessary in preprocessing and postprocessing, the value can be arbitrary.

fit(data, validation_data=None, epochs=1, batch_size=32, validation_mode='output', earlystop_patience=1, use_trial_id=None)#

Fit(Train) the forecaster.

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x, ‘y’: y}, where x and y’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
validation_data –
Validation sample for validation loop. Defaults to ‘None’. If you do not input data for ‘validation_data’, the validation_step will be skipped. Validation data will be ignored under distributed mode. The validation_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x, ‘y’: y}, where x and y’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
epochs – Number of epochs you want to train. The value defaults to 1.
batch_size – Number of batch size you want to train. The value defaults to 32. If you input a pytorch dataloader for data, the batch_size will follow the batch_size setted in data.if the forecaster is distributed, the batch_size will be evenly distributed to all workers.
validation_mode –
A str represent the operation mode while having ‘validation_data’. Defaults to ‘output’. The validation_mode includes the following types:

1. output:

If you choose ‘output’ for validation_mode, it will return a dict that records the

average validation loss of each epoch.

2. earlystop:

Monitor the val_loss and stop training when it stops improving.

3. best_epoch:

Monitor the val_loss. And load the checkpoint of the epoch with the smallest

val_loss after the training.
earlystop_patience – Number of checks with no improvement after which training will be stopped. It takes effect when ‘validation_mode’ is ‘earlystop’. Under the default configuration, one check happens after every training epoch.
use_trail_id – choose a internal according to trial_id, which is used only in multi-objective search.

Returns

Validation loss if ‘validation_data’ is not None.

classmethod from_tsdataset(tsdataset, past_seq_len=None, future_seq_len=None, **kwargs)#

Build a Forecaster Model.

Parameters

tsdataset – Train tsdataset, a bigdl.chronos.data.tsdataset.TSDataset instance.
past_seq_len – int or “auto”, Specify the history time steps (i.e. lookback). Do not specify the ‘past_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_torch_data_loader’. If “auto”, the mode of time series’ cycle length will be taken as the past_seq_len.
future_seq_len – int or list, Specify the output time steps (i.e. horizon). Do not specify the ‘future_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_torch_data_loader’.
kwargs – Specify parameters of Forecaster, e.g. loss and optimizer, etc. More info, please refer to Forecaster.__init__ methods.

Returns

A Forecaster Model.

get_context(thread_num=None, optimize=True)#

Obtain context manager from forecaster.

Parameters

thread_num – int, the num of thread limit. The value is set to None by default where no limit is set.
optimize – bool variable indicates whether use original model. Default to True means use accelerated_model to generate context manager, which requires to call .optimize(), otherwise the original model will be used.

Returns

a context manager.

get_model()#

Returns the learned PyTorch model.

Returns: a pytorch model instance

load(checkpoint_file, quantize_checkpoint_file=None)#

restore the forecaster.

Parameters

checkpoint_file – The checkpoint file location you want to load the forecaster.
quantize_checkpoint_file – The checkpoint file location you want to load the quantized forecaster.

Parameters

train_data –
Data used for training model. Users should be careful with this parameter since this data might be exposed to the model, which causing data leak. The train_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

The batch_size of this dataloader is important as well, users may want to set it

to the same batch size you may want to use the model in real deploy environment.

E.g. batch size should be set to 1 if you would like to use the accelerated model

in an online service.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
validation_data(optional) –
This is only needed when users care about the possible accuracy drop. The validation_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – Number of batch size you want to use the model in real deploy environment. The value defaults to 32. If you input a pytorch dataloader for train_data, the batch_size will follow the batch_size setted in train_data.
thread_num – int, the num of thread limit. The value is set to None by default where no limit is set.
accelerator – (optional) Use accelerator ‘None’, ‘onnxruntime’, ‘openvino’, ‘jit’, defaults to None. If not None, then will only find the model with this specific accelerator.
precision – (optional) Supported type: ‘int8’, ‘bf16’, ‘fp32’. Defaults to None which represents no precision limit. If not None, then will only find the model with this specific precision.
metric – (optional) A str represent corresponding metric which is used for calculating accuracy.
accuracy_criterion – (optional) a float represents tolerable accuracy drop percentage, defaults to None meaning no accuracy control.

Example

>>> # obtain optimized model
>>> forecaster.optimize(train_data, val_data, thread_num=1)
>>> pred = forecaster.predict(data)

predict(data, batch_size=32, quantize=False, acceleration: bool = True)#

Predict using a trained forecaster.

if you want to predict on a single node(which is common practice), please call .to_local().predict(x, …)

Parameters

data –
The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x}, where x’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume memory.
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time).
quantize – if use the quantized model to predict.
acceleration – bool variable indicates whether use original model. Default to True means use accelerated_model to predict, which requires to call one of .build_jit(), .build_onnx(), .build_openvino() and .optimize(), otherwise the original model will be used to predict.

Returns

predict_interval(data, validation_data=None, batch_size=32, repetition_times=5)#

Calculate confidence interval of data based on Monte Carlo dropout(MC dropout). Related paper : https://arxiv.org/abs/1709.01907

Parameters

data –
The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
validation_data –
The validation_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time).
repetition_times – Defines repeate how many times to calculate model uncertainty based on MC Dropout.

Returns

prediction and standard deviation which are both numpy array with shape (num_samples, horizon, target_dim)

predict_with_jit(data, batch_size=32, quantize=False)#

Predict using a trained forecaster with jit. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_jit is valid and Forecaster will automatically build an jit session with default settings (thread num is 1).

Parameters

data –

The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.

param batch_size: predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time). Defaults to 32. None for all-data-single-time inference.
param quantize: if use the quantized jit model to predict. Not support yet.
return: A numpy array with shape (num_samples, horizon, target_dim).

predict_with_onnx(data, batch_size=32, quantize=False)#

Predict using a trained forecaster with onnxruntime. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_onnx is valid and Forecaster will automatically build an onnxruntime session with default settings (thread num is 1).

Parameters

data –
The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time). Defaults to 32. None for all-data-single-time inference.
quantize – if use the quantized onnx model to predict.

Returns

A numpy array with shape (num_samples, horizon, target_dim).

predict_with_openvino(data, batch_size=32, quantize=False)#

Predict using a trained forecaster with openvino. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_openvino is valid and Forecaster will automatically build an openvino session with default settings (thread num is 1).

Parameters

data –

The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.

param batch_size: predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time). Defaults to 32. None for all-data-single-time inference.
param quantize: if use the quantized openvino model to predict.
return: A numpy array with shape (num_samples, horizon, target_dim).

Quantize the forecaster.

Parameters

calib_data –
Required for static quantization. Support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
val_data –
for evaluation. Support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
metric – A str represent the metrics for tunning the quality of quantization. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape”.
conf – A path to conf yaml file for quantization. Default to None, using default config.
framework – A str represent the framework for quantization. You may choose from “pytorch_fx”, “pytorch_ipex”, “onnxrt_integerops”, “onnxrt_qlinearops”, “openvino”. Default: ‘pytorch_fx’. Consistent with Intel Neural Compressor.
approach – str, ‘static’ or ‘dynamic’. Default to ‘static’. OpenVINO supports static mode only, if set to ‘dynamic’, it will be replaced with ‘static’.
tuning_strategy – str, ‘bayesian’, ‘basic’, ‘mse’ or ‘sigopt’. Default to ‘bayesian’.
relative_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 0.1 means that we accept a 10% increase in the metrics error.
absolute_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 5 means that we can only accept metrics smaller than 5.
timeout – Tuning timeout (seconds). Default to 0, which means early stop. Combine with max_trials field to decide when to exit.
max_trials – Max tune times. Default to 1. Combine with timeout field to decide when to exit. “timeout=0, max_trials=1” means it will try quantization only once and return satisfying best model.
sess_options – The session option for onnxruntime, only valid when framework contains ‘onnxrt_integerops’ or ‘onnxrt_qlinearops’, otherwise will be ignored.
thread_num – int, the num of thread limit. The value is set to None by default where no limit is set

save(checkpoint_file, quantize_checkpoint_file=None)#

Save the forecaster.

Please note that if you only want the pytorch model or onnx model file, you can call .get_model() or .export_onnx_file(). The checkpoint file generated by .save() method can only be used by .load().

Parameters

checkpoint_file – The location you want to save the forecaster.
quantize_checkpoint_file – The location you want to save quantized forecaster.

search_summary()#: Return search summary of HPO.

to_local()#

Transform a distributed forecaster to a local (non-distributed) one.

The optimizer is refreshed, incremental training after to_local might have some problem.

Returns: a forecaster instance.

tune(data, validation_data, target_metric, direction, directions=None, n_trials=2, n_parallels=1, epochs=1, batch_size=32, acceleration=False, input_sample=None, **kwargs)#

Search the hyper parameter.

Parameters

data – train data, as numpy ndarray tuple (x, y)
validation_data – validation data, as numpy ndarray tuple (x,y)
target_metric – the target metric to optimize, a string or an instance of torchmetrics.metric.Metric
direction – in which direction to optimize the target metric, “maximize” - larger the better “minimize” - smaller the better
n_trials – number of trials to run
n_parallels – number of parallel processes used to run trials. to use parallel tuning you need to use a RDB url for storage and specify study_name. For more information, refer to Nano AutoML user guide.
epochs – the number of epochs to run in each trial fit, defaults to 1
batch_size – number of batch size for each trial fit, defaults to 32
acceleration – Whether to automatically consider the model after inference acceleration in the search process. It will only take effect if target_metric contains “latency”. Default value is False.
input_sample – A set of inputs for trace, defaults to None if you have trace before or model is a LightningModule with any dataloader attached.
kwargs – some other parameters could be used for tuning, most useful one is sampler from SamplerType.Grid, SamplerType.Random and SamplerType.TPE so on.

class bigdl.chronos.forecaster.tf.seq2seq_forecaster.Seq2SeqForecaster(past_seq_len, future_seq_len, input_feature_num, output_feature_num, lstm_hidden_dim=64, lstm_layer_num=2, teacher_forcing=False, dropout=0.1, optimizer='Adam', loss='mse', lr=0.001, metrics=['mse'], seed=None, distributed=False, workers_per_node=1, distributed_backend='ray')[source]#

Bases: bigdl.chronos.forecaster.tf.base_forecaster.BaseTF2Forecaster

Example

>>> #The dataset is split into x_train, x_val, x_test, y_train, y_val, y_test
>>> forecaster = Seq2SeqForecaster(past_seq_len=24,
                                   future_seq_len=2,
                                   input_feature_num=1,
                                   output_feature_num=1,
                                   ...)
>>> forecaster.fit((x_train, y_train))
>>> test_pred = forecaster.predict(x_test)
>>> test_eval = forecaster.evaluate((x_test, y_test))
>>> forecaster.save({ckpt_dir_name})
>>> forecaster.load({ckpt_dir_name})

Build a Seq2Seq Forecast Model.

Parameters

past_seq_len – Specify the history time steps (i.e. lookback).
future_seq_len – Specify the output time steps (i.e. horizon).
input_feature_num – Specify the feature dimension.
output_feature_num – Specify the output dimension.
lstm_hidden_dim – LSTM hidden channel for decoder and encoder. The value defaults to 64.
lstm_layer_num – LSTM layer number for decoder and encoder. The value defaults to 2.
teacher_forcing – If use teacher forcing in training. The value defaults to False.
dropout – Specify the dropout close possibility (i.e. the close possibility to a neuron). This value defaults to 0.1.
optimizer – Specify the optimizer used for training. This value defaults to “Adam”.
loss – Str or a tf.keras.losses.Loss instance, specify the loss function used for training. This value defaults to “mse”. You can choose from “mse”, “mae” and “huber_loss” or any customized loss instance you want to use.
lr – Specify the learning rate. This value defaults to 0.001.
metrics – A list contains metrics for evaluating the quality of forecasting. You may only choose from “mse” and “mae” for a distributed forecaster. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape” or a callable function for a non-distributed forecaster. If callable function, it signature should be func(y_true, y_pred), where y_true and y_pred are numpy ndarray.
seed – int, random seed for training. This value defaults to None.
distributed – bool, if init the forecaster in a distributed fashion. If True, the internal model will use an Orca Estimator. If False, the internal model will use a Keras model. The value defaults to False.
workers_per_node – int, the number of worker you want to use. The value defaults to 1. The param is only effective when distributed is set to True.
distributed_backend – str, select from “ray” or “horovod”. The value defaults to “ray”.

evaluate(data, batch_size=32, multioutput='raw_values', quantize=False)#

>>> from bigdl.chronos.metric.forecaster_metrics import Evaluator
>>> y_hat = forecaster.predict(x)
>>> y_hat_unscaled = tsdata.unscale_numpy(y_hat) # or other customized unscale methods
>>> y_unscaled = tsdata.unscale_numpy(y) # or other customized unscale methods
>>> Evaluator.evaluate(metric=..., y_unscaled, y_hat_unscaled, multioutput=...)

Params data: The data support following formats:

1. A numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. A tf.data.Dataset:

A TFDataset instance which contains x and y with same shape as the tuple.

x’s shape is (num_samples, lookback, feature_dim),

y’s shape is (num_samples, horizon, target_dim).

If set distributed to True, we do not recommend using tf.data.Dataset,

please replace with tsdataset or numpy.ndarray.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a tfdataset,

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
Params batch_size: evaluate batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time).
Params multioutput_value: Defines aggregating of multiple output values. String in [‘raw_values’, ‘uniform_average’]. The value defaults to ‘raw_values’.The param is only effective when the forecaster is a non-distribtued version.
Parameters: quantize – if use the quantized model to predict.
Returns: A list of evaluation results. Each item represents a metric.

fit(data, epochs=1, batch_size=32)#

Fit(Train) the forecaster.

Parameters

data –

The data support following formats:

1. A numpy ndarray tuple (x, y):
x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim
should be the same as past_seq_len and input_feature_num.
y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim
should be the same as future_seq_len and output_feature_num.

2. A tf.data.Dataset:
A TFDataset instance which contains x and y with same shape as the tuple.
x’s shape is (num_samples, lookback, feature_dim),
y’s shape is (num_samples, horizon, target_dim).
If set distributed to True, we do not recommend using tf.data.Dataset,
please replace with tsdataset or numpy.ndarray.

3. A bigdl.chronos.data.tsdataset.TSDataset instance.
Forecaster will automatically process the TSDataset.
By default, TSDataset will be transformed to a tfdataset,
Users may call roll on the TSDataset before calling fit
Then the training speed will be faster but will consume more memory.

Params epochs

Number of epochs you want to train. The value defaults to 1.

Params batch_size

Number of batch size you want to train. The value defaults to 32. Do not specify the batch_size, if your data in the form of tf.data datasets.

classmethod from_tsdataset(tsdataset, past_seq_len=None, future_seq_len=None, **kwargs)#

Build a Forecaster Model

Parameters

tsdataset – A bigdl.chronos.data.tsdataset.TSDataset instance.
past_seq_len – Specify history time step (i.e. lookback) Do not specify the ‘past_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_tf_dataset’.
future_seq_len – Specify output time step (i.e. horizon) Do not specify the ‘future_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_tf_dataset’.
kwargs – Specify parameters of Forecaster, e.g. loss and optimizer, etc. More info, please refer to Forecaster.__init__ methods.

Returns

A Forecaster Model

get_model()#

Returns the learned Keras model.

Returns: a keras model instance

load(checkpoint_file)#

Load the forecaster.

Params checkpoint_file: The checkpoint file location you want to load the forecaster.

predict(data, batch_size=32, quantize=False)#

Predict using a trained forecaster.

Params data: The data support following formats:

1. A numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. A tfdataset

A TFDataset instance which contains x and y with same shape as the tuple.

the tfdataset needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a tfdataset,

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
Params batch_size: predict batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time). The value default to 32. If set to None, the model will be used directly for inference.
Parameters: quantize – if use the quantized model to predict.
Returns: A numpy array with shape (num_samples, horizon, target_dim).

Quantize the forecaster.

Parameters

input_data –
Input data which is used for training. Support following formats:

1. a numpy ndarray:

The shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. TensorFlow tensor:

The shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

3. an unbatched tf.data.Dataset. Should return a tuple of (inputs, targets).

Input data will be used as calibration dataset for static quantization,

as well as be used for generating input_sample to calculate latency.

To avoid data leak during calibration, please use training dataset.
target_data – Target data. It could be either Numpy array(s) or TensorFlow tensor(s) while the length should be consistent with input_data. If input_data is dataset, target_data will be ignored.
metric – A str represent the metrics for tunning the quality of quantization. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape”.
conf – A path to conf yaml file for quantization. Default to None, using default config.
framework – A str represent the framework for quantization. You may choose from “tensorflow”, “onnxrt_integerops”, “onnxrt_qlinearops”, “openvino”. Default: ‘tensorflow’.
approach – str, ‘static’ or ‘dynamic’. Default to ‘static’. Only ‘static’ approach is supported now.
tuning_strategy – str, ‘bayesian’, ‘basic’, ‘mse’ or ‘sigopt’. Default to ‘bayesian’.
relative_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 0.1 means that we accept a 10% increase in the metrics error.
absolute_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 5 means that we can only accept metrics smaller than 5.
timeout – Tuning timeout (seconds). Default to 0, which means early stop. Combine with max_trials field to decide when to exit.
max_trials – Max tune times. Default to 1. Combine with timeout field to decide when to exit. “timeout=0, max_trials=1” means it will try quantization only once and return satisfying best model.
sess_options – The session option for onnxruntime, only valid when framework contains ‘onnxrt_integerops’ or ‘onnxrt_qlinearops’, otherwise will be ignored.
thread_num – int, the num of thread limit, only valid when framework contains ‘onnxrt_integerops’ or ‘onnxrt_qlinearops’ or ‘openvino’. The value is set to None by default where no limit is set.

save(checkpoint_file)#

Save the forecaster.

Params checkpoint_file: The location you want to save the forecaster.

to_local()#

Transform a distributed forecaster to a local (non-distributed) one.

you need to call .to_local() and transform the forecaster to a non- distributed one.

TCNForecaster#

Temporal Convolutional Networks (TCN) is a neural network that use convolutional architecture rather than recurrent networks. It supports multi-step and multi-variant cases. Causal Convolutions enables large scale parallel computing which makes TCN has less inference time than RNN based model such as LSTM.

class bigdl.chronos.forecaster.tcn_forecaster.TCNForecaster(past_seq_len, future_seq_len, input_feature_num, output_feature_num, dummy_encoder=False, num_channels=[16, 16, 16], kernel_size=3, normalization=True, decomposition_kernel_size=0, repo_initialization=True, dropout=0.1, optimizer='Adam', loss='mse', lr=0.001, metrics=['mse'], seed=None, distributed=False, workers_per_node=1, distributed_backend='ray')[source]#

Bases: bigdl.chronos.forecaster.base_forecaster.BasePytorchForecaster

Example

>>> #The dataset is split into x_train, x_val, x_test, y_train, y_val, y_test
>>> # 1. Initialize Forecaster directly
>>> forecaster = TCNForecaster(past_seq_len=24,
                               future_seq_len=5,
                               input_feature_num=1,
                               output_feature_num=1,
                               ...)
>>>
>>> # 2. Initialize Forecaster from from_tsdataset
>>> forecaster = TCNForecaster.from_tsdataset(tsdata, ...)
>>> forecaster.fit(tsdata, ...)
>>> forecaster.to_local()  # if you set distributed=True
>>> test_pred = forecaster.predict(x_test)
>>> test_eval = forecaster.evaluate((x_test, y_test))
>>> forecaster.save({ckpt_name})
>>> forecaster.load({ckpt_name})

Build a TCN Forecast Model.

TCN Forecast may fall into local optima. Please set repo_initialization to False to alleviate the issue. You can also change a random seed to work around.

Parameters

past_seq_len – Specify the history time steps (i.e. lookback).
future_seq_len – Specify the output time steps (i.e. horizon).
input_feature_num – Specify the feature dimension.
output_feature_num – Specify the output dimension.
dummy_encoder – bool, no encoder is applied if True, which will turn TCNForecaster to a Linear Model. If True, input_feature_num should equals to output_feature_num.
num_channels – Specify the convolutional layer filter number in TCN’s encoder. This value defaults to [16]*3.
kernel_size – Specify convolutional layer filter height in TCN’s encoder. This value defaults to 3.
normalization – bool, Specify if to use normalization trick to alleviate distribution shift. It first subtractes the last value of the sequence and add back after the model forwarding.
decomposition_kernel_size – int, Specify the kernel size in moving average. The decomposition method will be applied if and only if decomposition_kernel_size is greater than 1, which first decomposes the raw sequence into a trend component by a moving average kernel and a remainder(seasonal) component. Then, two models are applied to each component and sum up the two outputs to get the final prediction. This value defaults to 0.
repo_initialization – if to use framework default initialization, True to use paper author’s initialization and False to use the framework’s default initialization. The value defaults to True.
dropout – Specify the dropout close possibility (i.e. the close possibility to a neuron). This value defaults to 0.1.
optimizer – Specify the optimizer used for training. This value defaults to “Adam”.
loss – str or pytorch loss instance, Specify the loss function used for training. This value defaults to “mse”. You can choose from “mse”, “mae”, “huber_loss” or any customized loss instance you want to use.
lr – Specify the learning rate. This value defaults to 0.001.
metrics – A list contains metrics for evaluating the quality of forecasting. You may only choose from “mse” and “mae” for a distributed forecaster. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape” or a callable function for a non-distributed forecaster. If callable function, it signature should be func(y_true, y_pred), where y_true and y_pred are numpy ndarray.
seed – int, random seed for training. This value defaults to None.
distributed – bool, if init the forecaster in a distributed fashion. If True, the internal model will use an Orca Estimator. If False, the internal model will use a pytorch model. The value defaults to False.
workers_per_node – int, the number of worker you want to use. The value defaults to 1. The param is only effective when distributed is set to True.
distributed_backend – str, select from “ray” or “horovod”. The value defaults to “ray”.

build_jit(thread_num=1, use_ipex=False)#

Build jit model to speed up inference and reduce latency. The method is Not required to call before predict_with_jit or export_torchscript_file.

It is recommended to use when you want to:

1. Strictly control the thread to be used during inferencing.

2. Alleviate the cold start problem when you call predict_with_jit

for the first time.

Parameters

use_ipex – if to use intel-pytorch-extension for acceleration. Typically, intel-pytorch-extension will bring some acceleration while causing some unexpected error as well.
thread_num –

int, the num of thread limit. The value is set to 1 by
default where no limit is set.Besides, the environment variable

OMP_NUM_THREADS is suggested to be same as thread_num.

build_onnx(thread_num=1, sess_options=None)#

1. Strictly control the thread to be used during inferencing.

2. Alleviate the cold start problem when you call predict_with_onnx for the first time.

Parameters

thread_num – int, the num of thread limit. The value is set to None by default where no limit is set. Besides, the environment variable OMP_NUM_THREADS is suggested to be same as thread_num.
sess_options – an onnxruntime.SessionOptions instance, if you set this other than None, a new onnxruntime session will be built on this setting and ignore other settings you assigned(e.g. thread_num…).

Example

>>> # to pre build onnx sess
>>> forecaster.build_onnx(thread_num=2)  # build onnx runtime sess for two threads
>>> pred = forecaster.predict_with_onnx(data)
>>> # ------------------------------------------------------
>>> # directly call onnx related method is also supported
>>> # default to build onnx runtime sess for single thread
>>> pred = forecaster.predict_with_onnx(data)

build_openvino(thread_num=1)#

Build openvino model to speed up inference and reduce latency. The method is Not required to call before predict_with_openvino.

It is recommended to use when you want to:

1. Strictly control the thread to be used during inferencing.

2. Alleviate the cold start problem when you call predict_with_openvino for the first time.

Parameters: thread_num – int, the num of thread limit. The value is set to 1 by default where no limit is set. Besides, the environment variable OMP_NUM_THREADS is suggested to be same as thread_num.

evaluate(data, batch_size=32, multioutput='raw_values', quantize=False, acceleration: bool = True)#

Evaluate using a trained forecaster.

If you want to evaluate on a single node(which is common practice), please call .to_local().evaluate(data, …)

>>> from bigdl.chronos.metric.forecast_metrics import Evaluator
>>> y_hat = forecaster.predict(x)
>>> y_hat_unscaled = tsdata.unscale_numpy(y_hat) # or other customized unscale methods
>>> y_unscaled = tsdata.unscale_numpy(y) # or other customized unscale methods
>>> Evaluator.evaluate(metric=..., y_unscaled, y_hat_unscaled, multioutput=...)

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x, ‘y’: y}, where x and y’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – evaluate batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time).
multioutput – Defines aggregating of multiple output values. String in [‘raw_values’, ‘uniform_average’]. The value defaults to ‘raw_values’.The param is only effective when the forecaster is a non-distribtued version.
quantize – if use the quantized model to predict.
acceleration – bool variable indicates whether use original model. Default to True means use accelerated_model to predict, which requires to call one of .build_jit(), .build_onnx(), .build_openvino() and .optimize(), otherwise the original model will be used to predict.

Returns

A list of evaluation results. Each item represents a metric.

evaluate_with_onnx(data, batch_size=32, multioutput='raw_values', quantize=False)#

Evaluate using a trained forecaster with onnxruntime. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_onnx is valid and Forecaster will automatically build an onnxruntime session with default settings (thread num is 1).

>>> from bigdl.chronos.metric.forecast_metrics import Evaluator
>>> y_hat = forecaster.predict_with_onnx(x)
>>> y_hat_unscaled = tsdata.unscale_numpy(y_hat) # or other customized unscale methods
>>> y_unscaled = tsdata.unscale_numpy(y) # or other customized unscale methods
>>> Evaluator.evaluate(metric=..., y_unscaled, y_hat_unscaled, multioutput=...)

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

should be the same as future_seq_len and output_feature_num.

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – evaluate batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time).
multioutput – Defines aggregating of multiple output values. String in [‘raw_values’, ‘uniform_average’]. The value defaults to ‘raw_values’.
quantize – if use the quantized onnx model to evaluate.

Returns

A list of evaluation results. Each item represents a metric.

export_onnx_file(dirname='fp32_onnx', quantized_dirname=None)#

Save the onnx model file to the disk.

Parameters

dirname – The dir location you want to save the onnx file.
quantized_dirname – The dir location you want to save the quantized onnx file.

export_openvino_file(dirname='fp32_openvino', quantized_dirname=None)#

Save the openvino model file to the disk.

Parameters

dirname – The dir location you want to save the openvino file.
quantized_dirname – The dir location you want to save the quantized openvino file.

export_torchscript_file(dirname='fp32_torchscript', quantized_dirname=None, save_pipeline=False, tsdata=None, drop_dt_col=True)#

Save the torchscript model file and the whole forecasting pipeline to the disk.

Currently the pipeline is similar to the following code:

>>> # preprocess
>>> tsdata.scale(scaler, fit=False) \
>>>       .roll(lookback, horizon, is_predict=True)
>>> preprocess_output = tsdata.to_numpy()
>>> # inference using trained forecaster
>>> # forecaster_module is the saved torchscript model
>>> inference_output = forecaster_module.forward(preprocess_output)
>>> # postprocess
>>> postprocess_output = tsdata.unscale_numpy(inference_output)

When deploying, the pipeline can be used by:

>>> // deployment in C++
>>> #include <torch/torch.h>
>>> #include <torch/script.h>
>>> // create input tensor from your data
>>> // The data to create the input tensor should have the same format as the
>>> // data used in developing
>>> torch::Tensor input = create_input_tensor(data);
>>> // load the pipeline
>>> torch::jit::script::Module forecasting_pipeline;
>>> forecasting_pipeline = torch::jit::load(path);
>>> // run pipeline
>>> torch::Tensor output = forecasting_pipeline.forward(input_tensor).toTensor();

The limitations of exporting the forecasting pipeline is same as limitations in TSDataset.export_jit():

Please make sure the value of each column can be converted to Pytorch tensor, for example, id “00” is not allowed because str can not be converted to a tensor, you should use integer (0, 1, ..) as id instead of string.

Some features in tsdataset.scale and tsdataset.roll are unavailable in this pipeline:

If self.roll_additional_feature is not None, it can’t be processed in scale and roll

id_sensitive, time_enc and label_len parameter is not supported in roll

Users are expected to call .scale(scaler, fit=True) before calling export_jit. Single roll operation is not supported for converting now.

Parameters

dirname – The dir location you want to save the torchscript file.
quantized_dirname – The dir location you want to save the quantized torchscript model.
save_pipeline – Whether to save the whole forecasting pipeline, defaluts to False. If set to True, the whole forecasting pipeline will be saved in “dirname/chronos_forecasting_pipeline.pt”, if set to False, only the torchscript model will be saved.
tsdata – The TSDataset instance used when developing the forecaster. The parameter should be used only when save_pipeline is True.
drop_dt_col – Whether to delete the datetime column, defaults to True. The parameter is valid only when save_pipeline is True. Since datetime value (like “2022-12-12”) can’t be converted to Pytorch tensor, you can choose different ways to workaround this. If set to True, the datetime column will be deleted, then you also need to skip the datetime column when reading data from data source (like csv files) in deployment environment to keep the same structure as the data used in development; if set to False, the datetime column will not be deleted, and you need to make sure the datetime colunm can be successfully converted to Pytorch tensor when reading data in deployment environment. For example, you can set each data in datetime column to an int (or other vaild types) value, since datetime column is not necessary in preprocessing and postprocessing, the value can be arbitrary.

fit(data, validation_data=None, epochs=1, batch_size=32, validation_mode='output', earlystop_patience=1, use_trial_id=None)#

Fit(Train) the forecaster.

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x, ‘y’: y}, where x and y’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
validation_data –
Validation sample for validation loop. Defaults to ‘None’. If you do not input data for ‘validation_data’, the validation_step will be skipped. Validation data will be ignored under distributed mode. The validation_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x, ‘y’: y}, where x and y’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
epochs – Number of epochs you want to train. The value defaults to 1.
batch_size – Number of batch size you want to train. The value defaults to 32. If you input a pytorch dataloader for data, the batch_size will follow the batch_size setted in data.if the forecaster is distributed, the batch_size will be evenly distributed to all workers.
validation_mode –
A str represent the operation mode while having ‘validation_data’. Defaults to ‘output’. The validation_mode includes the following types:

1. output:

If you choose ‘output’ for validation_mode, it will return a dict that records the

average validation loss of each epoch.

2. earlystop:

Monitor the val_loss and stop training when it stops improving.

3. best_epoch:

Monitor the val_loss. And load the checkpoint of the epoch with the smallest

val_loss after the training.
earlystop_patience – Number of checks with no improvement after which training will be stopped. It takes effect when ‘validation_mode’ is ‘earlystop’. Under the default configuration, one check happens after every training epoch.
use_trail_id – choose a internal according to trial_id, which is used only in multi-objective search.

Returns

Validation loss if ‘validation_data’ is not None.

classmethod from_tsdataset(tsdataset, past_seq_len=None, future_seq_len=None, **kwargs)#

Build a Forecaster Model.

Parameters

tsdataset – Train tsdataset, a bigdl.chronos.data.tsdataset.TSDataset instance.
past_seq_len – int or “auto”, Specify the history time steps (i.e. lookback). Do not specify the ‘past_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_torch_data_loader’. If “auto”, the mode of time series’ cycle length will be taken as the past_seq_len.
future_seq_len – int or list, Specify the output time steps (i.e. horizon). Do not specify the ‘future_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_torch_data_loader’.
kwargs – Specify parameters of Forecaster, e.g. loss and optimizer, etc. More info, please refer to Forecaster.__init__ methods.

Returns

A Forecaster Model.

get_context(thread_num=None, optimize=True)#

Obtain context manager from forecaster.

Parameters

thread_num – int, the num of thread limit. The value is set to None by default where no limit is set.
optimize – bool variable indicates whether use original model. Default to True means use accelerated_model to generate context manager, which requires to call .optimize(), otherwise the original model will be used.

Returns

a context manager.

get_model()#

Returns the learned PyTorch model.

Returns: a pytorch model instance

load(checkpoint_file, quantize_checkpoint_file=None)#

restore the forecaster.

Parameters

checkpoint_file – The checkpoint file location you want to load the forecaster.
quantize_checkpoint_file – The checkpoint file location you want to load the quantized forecaster.

Parameters

train_data –
Data used for training model. Users should be careful with this parameter since this data might be exposed to the model, which causing data leak. The train_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

The batch_size of this dataloader is important as well, users may want to set it

to the same batch size you may want to use the model in real deploy environment.

E.g. batch size should be set to 1 if you would like to use the accelerated model

in an online service.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
validation_data(optional) –
This is only needed when users care about the possible accuracy drop. The validation_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – Number of batch size you want to use the model in real deploy environment. The value defaults to 32. If you input a pytorch dataloader for train_data, the batch_size will follow the batch_size setted in train_data.
thread_num – int, the num of thread limit. The value is set to None by default where no limit is set.
accelerator – (optional) Use accelerator ‘None’, ‘onnxruntime’, ‘openvino’, ‘jit’, defaults to None. If not None, then will only find the model with this specific accelerator.
precision – (optional) Supported type: ‘int8’, ‘bf16’, ‘fp32’. Defaults to None which represents no precision limit. If not None, then will only find the model with this specific precision.
metric – (optional) A str represent corresponding metric which is used for calculating accuracy.
accuracy_criterion – (optional) a float represents tolerable accuracy drop percentage, defaults to None meaning no accuracy control.

Example

>>> # obtain optimized model
>>> forecaster.optimize(train_data, val_data, thread_num=1)
>>> pred = forecaster.predict(data)

predict(data, batch_size=32, quantize=False, acceleration: bool = True)#

Predict using a trained forecaster.

if you want to predict on a single node(which is common practice), please call .to_local().predict(x, …)

Parameters

data –
The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x}, where x’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume memory.
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time).
quantize – if use the quantized model to predict.
acceleration – bool variable indicates whether use original model. Default to True means use accelerated_model to predict, which requires to call one of .build_jit(), .build_onnx(), .build_openvino() and .optimize(), otherwise the original model will be used to predict.

Returns

predict_interval(data, validation_data=None, batch_size=32, repetition_times=5)#

Calculate confidence interval of data based on Monte Carlo dropout(MC dropout). Related paper : https://arxiv.org/abs/1709.01907

Parameters

data –
The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
validation_data –
The validation_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time).
repetition_times – Defines repeate how many times to calculate model uncertainty based on MC Dropout.

Returns

prediction and standard deviation which are both numpy array with shape (num_samples, horizon, target_dim)

predict_with_jit(data, batch_size=32, quantize=False)#

Predict using a trained forecaster with jit. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_jit is valid and Forecaster will automatically build an jit session with default settings (thread num is 1).

Parameters

data –

The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.

param batch_size: predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time). Defaults to 32. None for all-data-single-time inference.
param quantize: if use the quantized jit model to predict. Not support yet.
return: A numpy array with shape (num_samples, horizon, target_dim).

predict_with_onnx(data, batch_size=32, quantize=False)#

Predict using a trained forecaster with onnxruntime. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_onnx is valid and Forecaster will automatically build an onnxruntime session with default settings (thread num is 1).

Parameters

data –
The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time). Defaults to 32. None for all-data-single-time inference.
quantize – if use the quantized onnx model to predict.

Returns

A numpy array with shape (num_samples, horizon, target_dim).

predict_with_openvino(data, batch_size=32, quantize=False)#

Predict using a trained forecaster with openvino. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_openvino is valid and Forecaster will automatically build an openvino session with default settings (thread num is 1).

Parameters

data –

The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.

param batch_size: predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time). Defaults to 32. None for all-data-single-time inference.
param quantize: if use the quantized openvino model to predict.
return: A numpy array with shape (num_samples, horizon, target_dim).

Quantize the forecaster.

Parameters

calib_data –
Required for static quantization. Support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
val_data –
for evaluation. Support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
metric – A str represent the metrics for tunning the quality of quantization. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape”.
conf – A path to conf yaml file for quantization. Default to None, using default config.
framework – A str represent the framework for quantization. You may choose from “pytorch_fx”, “pytorch_ipex”, “onnxrt_integerops”, “onnxrt_qlinearops”, “openvino”. Default: ‘pytorch_fx’. Consistent with Intel Neural Compressor.
approach – str, ‘static’ or ‘dynamic’. Default to ‘static’. OpenVINO supports static mode only, if set to ‘dynamic’, it will be replaced with ‘static’.
tuning_strategy – str, ‘bayesian’, ‘basic’, ‘mse’ or ‘sigopt’. Default to ‘bayesian’.
relative_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 0.1 means that we accept a 10% increase in the metrics error.
absolute_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 5 means that we can only accept metrics smaller than 5.
timeout – Tuning timeout (seconds). Default to 0, which means early stop. Combine with max_trials field to decide when to exit.
max_trials – Max tune times. Default to 1. Combine with timeout field to decide when to exit. “timeout=0, max_trials=1” means it will try quantization only once and return satisfying best model.
sess_options – The session option for onnxruntime, only valid when framework contains ‘onnxrt_integerops’ or ‘onnxrt_qlinearops’, otherwise will be ignored.
thread_num – int, the num of thread limit. The value is set to None by default where no limit is set

save(checkpoint_file, quantize_checkpoint_file=None)#

Save the forecaster.

Please note that if you only want the pytorch model or onnx model file, you can call .get_model() or .export_onnx_file(). The checkpoint file generated by .save() method can only be used by .load().

Parameters

checkpoint_file – The location you want to save the forecaster.
quantize_checkpoint_file – The location you want to save quantized forecaster.

search_summary()#: Return search summary of HPO.

to_local()#

Transform a distributed forecaster to a local (non-distributed) one.

The optimizer is refreshed, incremental training after to_local might have some problem.

Returns: a forecaster instance.

tune(data, validation_data, target_metric, direction, directions=None, n_trials=2, n_parallels=1, epochs=1, batch_size=32, acceleration=False, input_sample=None, **kwargs)#

Search the hyper parameter.

Parameters

data – train data, as numpy ndarray tuple (x, y)
validation_data – validation data, as numpy ndarray tuple (x,y)
target_metric – the target metric to optimize, a string or an instance of torchmetrics.metric.Metric
direction – in which direction to optimize the target metric, “maximize” - larger the better “minimize” - smaller the better
n_trials – number of trials to run
n_parallels – number of parallel processes used to run trials. to use parallel tuning you need to use a RDB url for storage and specify study_name. For more information, refer to Nano AutoML user guide.
epochs – the number of epochs to run in each trial fit, defaults to 1
batch_size – number of batch size for each trial fit, defaults to 32
acceleration – Whether to automatically consider the model after inference acceleration in the search process. It will only take effect if target_metric contains “latency”. Default value is False.
input_sample – A set of inputs for trace, defaults to None if you have trace before or model is a LightningModule with any dataloader attached.
kwargs – some other parameters could be used for tuning, most useful one is sampler from SamplerType.Grid, SamplerType.Random and SamplerType.TPE so on.

class bigdl.chronos.forecaster.tf.tcn_forecaster.TCNForecaster(past_seq_len, future_seq_len, input_feature_num, output_feature_num, num_channels=[16, 16, 16], kernel_size=3, normalization=False, repo_initialization=True, dropout=0.1, optimizer='Adam', loss='mse', lr=0.001, metrics=['mse'], seed=None, distributed=False, workers_per_node=1, distributed_backend='ray')[source]#

Bases: bigdl.chronos.forecaster.tf.base_forecaster.BaseTF2Forecaster

Example

>>> #The dataset is split into x_train, x_val, x_test, y_train, y_val, y_test
>>> forecaster = TCNForecaster(past_seq_len=24,
                               future_seq_len=5,
                               input_feature_num=1,
                               output_feature_num=1,
                               ...)
>>> forecaster.fit((x_train, y_train))
>>> forecaster.save({ckpt_name})
>>> forecaster.load({ckpt_name})

Build a TCN Forecast Model.

TCN Forecast may fall into local optima. Please set repo_initialization to False to alleviate the issue. You can also change a random seed to work around.

Parameters

past_seq_len – Specify the history time steps (i.e. lookback).
future_seq_len – Specify the output time steps (i.e. horizon).
input_feature_num – Specify the feature dimension.
output_feature_num – Specify the output dimension.
num_channels – Specify the convolutional layer filter number in TCN’s encoder. This value defaults to [16]*3.
kernel_size – Specify convolutional layer filter height in TCN’s encoder. This value defaults to 3.
normalization – bool, Specify if to use normalization trick to alleviate distribution shift. It first subtractes the last value of the sequence and add back after the model forwarding. This value defaults to False.
repo_initialization – if to use framework default initialization, True to use paper author’s initialization and False to use the framework’s default initialization. The value defaults to True.
dropout – Specify the dropout close possibility (i.e. the close possibility to a neuron). This value defaults to 0.1.
optimizer – Specify the optimizer used for training. This value defaults to “Adam”.
loss – Str or a tf.keras.losses.Loss instance, specify the loss function used for training. This value defaults to “mse”. You can choose from “mse”, “mae” and “huber_loss” or any customized loss instance you want to use.
lr – Specify the learning rate. This value defaults to 0.001.
metrics – A list contains metrics for evaluating the quality of forecasting. You may only choose from “mse” and “mae” for a distributed forecaster. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape” or a callable function for a non-distributed forecaster. If callable function, it signature should be func(y_true, y_pred), where y_true and y_pred are numpy ndarray.
seed – int, random seed for training. This value defaults to None.
distributed – bool, if init the forecaster in a distributed fashion. If True, the internal model will use an Orca Estimator. If False, the internal model will use a pytorch model. The value defaults to False.
workers_per_node – int, the number of worker you want to use. The value defaults to 1. The param is only effective when distributed is set to True.
distributed_backend – str, select from “ray” or “horovod”. The value defaults to “ray”.

evaluate(data, batch_size=32, multioutput='raw_values', quantize=False)#

>>> from bigdl.chronos.metric.forecaster_metrics import Evaluator
>>> y_hat = forecaster.predict(x)
>>> y_hat_unscaled = tsdata.unscale_numpy(y_hat) # or other customized unscale methods
>>> y_unscaled = tsdata.unscale_numpy(y) # or other customized unscale methods
>>> Evaluator.evaluate(metric=..., y_unscaled, y_hat_unscaled, multioutput=...)

Params data: The data support following formats:

1. A numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. A tf.data.Dataset:

A TFDataset instance which contains x and y with same shape as the tuple.

x’s shape is (num_samples, lookback, feature_dim),

y’s shape is (num_samples, horizon, target_dim).

If set distributed to True, we do not recommend using tf.data.Dataset,

please replace with tsdataset or numpy.ndarray.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a tfdataset,

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
Params batch_size: evaluate batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time).
Params multioutput_value: Defines aggregating of multiple output values. String in [‘raw_values’, ‘uniform_average’]. The value defaults to ‘raw_values’.The param is only effective when the forecaster is a non-distribtued version.
Parameters: quantize – if use the quantized model to predict.
Returns: A list of evaluation results. Each item represents a metric.

fit(data, epochs=1, batch_size=32)#

Fit(Train) the forecaster.

Parameters

data –

The data support following formats:

1. A numpy ndarray tuple (x, y):
x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim
should be the same as past_seq_len and input_feature_num.
y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim
should be the same as future_seq_len and output_feature_num.

2. A tf.data.Dataset:
A TFDataset instance which contains x and y with same shape as the tuple.
x’s shape is (num_samples, lookback, feature_dim),
y’s shape is (num_samples, horizon, target_dim).
If set distributed to True, we do not recommend using tf.data.Dataset,
please replace with tsdataset or numpy.ndarray.

3. A bigdl.chronos.data.tsdataset.TSDataset instance.
Forecaster will automatically process the TSDataset.
By default, TSDataset will be transformed to a tfdataset,
Users may call roll on the TSDataset before calling fit
Then the training speed will be faster but will consume more memory.

Params epochs

Number of epochs you want to train. The value defaults to 1.

Params batch_size

Number of batch size you want to train. The value defaults to 32. Do not specify the batch_size, if your data in the form of tf.data datasets.

classmethod from_tsdataset(tsdataset, past_seq_len=None, future_seq_len=None, **kwargs)#

Build a Forecaster Model

Parameters

tsdataset – A bigdl.chronos.data.tsdataset.TSDataset instance.
past_seq_len – Specify history time step (i.e. lookback) Do not specify the ‘past_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_tf_dataset’.
future_seq_len – Specify output time step (i.e. horizon) Do not specify the ‘future_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_tf_dataset’.
kwargs – Specify parameters of Forecaster, e.g. loss and optimizer, etc. More info, please refer to Forecaster.__init__ methods.

Returns

A Forecaster Model

get_model()#

Returns the learned Keras model.

Returns: a keras model instance

load(checkpoint_file)#

Load the forecaster.

Params checkpoint_file: The checkpoint file location you want to load the forecaster.

predict(data, batch_size=32, quantize=False)#

Predict using a trained forecaster.

Params data: The data support following formats:

1. A numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. A tfdataset

A TFDataset instance which contains x and y with same shape as the tuple.

the tfdataset needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a tfdataset,

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
Params batch_size: predict batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time). The value default to 32. If set to None, the model will be used directly for inference.
Parameters: quantize – if use the quantized model to predict.
Returns: A numpy array with shape (num_samples, horizon, target_dim).

Quantize the forecaster.

Parameters

input_data –
Input data which is used for training. Support following formats:

1. a numpy ndarray:

The shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. TensorFlow tensor:

The shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

3. an unbatched tf.data.Dataset. Should return a tuple of (inputs, targets).

Input data will be used as calibration dataset for static quantization,

as well as be used for generating input_sample to calculate latency.

To avoid data leak during calibration, please use training dataset.
target_data – Target data. It could be either Numpy array(s) or TensorFlow tensor(s) while the length should be consistent with input_data. If input_data is dataset, target_data will be ignored.
metric – A str represent the metrics for tunning the quality of quantization. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape”.
conf – A path to conf yaml file for quantization. Default to None, using default config.
framework – A str represent the framework for quantization. You may choose from “tensorflow”, “onnxrt_integerops”, “onnxrt_qlinearops”, “openvino”. Default: ‘tensorflow’.
approach – str, ‘static’ or ‘dynamic’. Default to ‘static’. Only ‘static’ approach is supported now.
tuning_strategy – str, ‘bayesian’, ‘basic’, ‘mse’ or ‘sigopt’. Default to ‘bayesian’.
relative_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 0.1 means that we accept a 10% increase in the metrics error.
absolute_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 5 means that we can only accept metrics smaller than 5.
timeout – Tuning timeout (seconds). Default to 0, which means early stop. Combine with max_trials field to decide when to exit.
max_trials – Max tune times. Default to 1. Combine with timeout field to decide when to exit. “timeout=0, max_trials=1” means it will try quantization only once and return satisfying best model.
sess_options – The session option for onnxruntime, only valid when framework contains ‘onnxrt_integerops’ or ‘onnxrt_qlinearops’, otherwise will be ignored.
thread_num – int, the num of thread limit, only valid when framework contains ‘onnxrt_integerops’ or ‘onnxrt_qlinearops’ or ‘openvino’. The value is set to None by default where no limit is set.

save(checkpoint_file)#

Save the forecaster.

Params checkpoint_file: The location you want to save the forecaster.

to_local()#

Transform a distributed forecaster to a local (non-distributed) one.

you need to call .to_local() and transform the forecaster to a non- distributed one.

AutoformerForecaster#

Autoformer is a neural network that use transformer architecture with autocorrelation. It supports multi-step and multi-variant cases. It shows significant accuracy improvement while longer training/inference time than TCN.

class bigdl.chronos.forecaster.autoformer_forecaster.AutoformerForecaster(past_seq_len, future_seq_len, input_feature_num, output_feature_num, freq, label_len=None, output_attention=False, moving_avg=25, d_model=128, embed='timeF', dropout=0.05, factor=3, n_head=8, d_ff=256, activation='gelu', e_layers=2, d_layers=1, optimizer='Adam', loss='mse', lr=0.0001, lr_scheduler_milestones=[3, 4, 5, 6, 7, 8, 9, 10], metrics=['mse'], seed=None, distributed=False, workers_per_node=1, distributed_backend='ray')[source]#

Bases: bigdl.chronos.forecaster.abstract.Forecaster

Build a AutoformerForecaster Forecast Model.

Parameters

past_seq_len – Specify the history time steps (i.e. lookback).
future_seq_len – Specify the output time steps (i.e. horizon).
input_feature_num – Specify the feature dimension.
output_feature_num – Specify the output dimension.
freq – Freq for time features encoding. You may choose from “s”, “t”,”h”,”d”,”w”,”m” for second, minute, hour, day, week or month.
label_len – Start token length of AutoFormer decoder.
optimizer – Specify the optimizer used for training. This value defaults to “Adam”.
loss – str or pytorch loss instance, Specify the loss function used for training. This value defaults to “mse”. You can choose from “mse”, “mae”, “huber_loss” or any customized loss instance you want to use.
lr – Specify the learning rate. This value defaults to 0.001.
lr_scheduler_milestones – Specify the milestones parameters in torch.optim.lr_scheduler.MultiStepLR.This value defaults to [3, 4, 5, 6, 7, 8, 9, 10]. If you don’t want to use scheduler, set this parameter to None to disbale lr_scheduler.
metrics – A list contains metrics for evaluating the quality of forecasting. You may only choose from “mse” and “mae” for a distributed forecaster. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape” or a callable function for a non-distributed forecaster. If callable function, it signature should be func(y_true, y_pred), where y_true and y_pred are numpy ndarray.
seed – int, random seed for training. This value defaults to None.
distributed – bool, if init the forecaster in a distributed fashion. If True, the internal model will use an Orca Estimator. If False, the internal model will use a pytorch model. The value defaults to False.
workers_per_node – int, the number of worker you want to use. The value defaults to 1. The param is only effective when distributed is set to True.
distributed_backend – str, select from “ray” or “horovod”. The value defaults to “ray”.
kwargs – other hyperparameter please refer to zhouhaoyi/Informer2020

tune(data, validation_data, target_metric='mse', direction='minimize', directions=None, n_trials=2, n_parallels=1, epochs=1, batch_size=32, acceleration=False, input_sample=None, **kwargs)[source]#

Search the hyper parameter.

Parameters

data –
The data support following formats:

1. numpy ndarrays: generate from TSDataset.roll, be sure to set label_len > 0 and time_enc = True
validation_data –
validation data, The data support following formats:

1. numpy ndarrays: generate from TSDataset.roll, be sure to set label_len > 0 and time_enc = True
target_metric – the target metric to optimize, a string or an instance of torchmetrics.metric.Metric, default to ‘mse’.
direction – in which direction to optimize the target metric, “maximize” - larger the better “minimize” - smaller the better default to “minimize”.
n_trials – number of trials to run
n_parallels – number of parallel processes used to run trials. to use parallel tuning you need to use a RDB url for storage and specify study_name. For more information, refer to Nano AutoML user guide.
epochs – the number of epochs to run in each trial fit, defaults to 1
batch_size – number of batch size for each trial fit, defaults to 32
acceleration – Whether to automatically consider the model after inference acceleration in the search process. It will only take effect if target_metric contains “latency”. Default value is False.
input_sample – A set of inputs for trace, defaults to None if you have trace before or model is a LightningModule with any dataloader attached.

search_summary()[source]#: Return search summary of HPO.

fit(data, validation_data=None, epochs=1, batch_size=32, validation_mode='output', earlystop_patience=1, use_trial_id=None)[source]#

Fit(Train) the forecaster.

Parameters

data –
The data support following formats:

1. numpy ndarrays: generate from TSDataset.roll, be sure to set label_len > 0 and time_enc = True

2. pytorch dataloader: generate from TSDataset.to_torch_data_loader, be sure to set label_len > 0 and time_enc = True

3. A bigdl.chronos.data.tsdataset.TSDataset instance
validation_data –
Validation sample for validation loop. Defaults to ‘None’. If you do not input data for ‘validation_data’, the validation_step will be skipped. The validation_data support following formats:

1. numpy ndarrays: generate from TSDataset.roll, be sure to set label_len > 0 and time_enc = True

2. pytorch dataloader: generate from TSDataset.to_torch_data_loader, be sure to set label_len > 0 and time_enc = True

3. A bigdl.chronos.data.tsdataset.TSDataset instance
epochs – Number of epochs you want to train. The value defaults to 1.
batch_size – Number of batch size you want to train. The value defaults to 32. if you input a pytorch dataloader for data, the batch_size will follow the batch_size setted in data.
validation_mode –
A str represent the operation mode while having ‘validation_data’. Defaults to ‘output’. The validation_mode includes the following types:

1. output:

If you choose ‘output’ for validation_mode, it will return a dict that records the

average validation loss of each epoch.

2. earlystop:

Monitor the val_loss and stop training when it stops improving.

3. best_epoch:

Monitor the val_loss. And load the checkpoint of the epoch with the smallest

val_loss after the training.
earlystop_patience – Number of checks with no improvement after which training will be stopped. It takes effect when ‘validation_mode’ is ‘earlystop’. Under the default configuration, one check happens after every training epoch.
use_trail_id – choose a internal according to trial_id, which is used only in multi-objective search.

get_context(thread_num=None)[source]#

Obtain context manager from forecaster. :param thread_num: int, the num of thread limit. The value is set to None by

default where no limit is set.

Returns: a context manager.

predict(data, batch_size=32)[source]#

Predict using a trained forecaster.

Parameters

data –
The data support following formats:

1. numpy ndarrays: generate from TSDataset.roll, be sure to set label_len > 0 and time_enc = True

2. pytorch dataloader: generate from TSDataset.to_torch_data_loader, be sure to set label_len > 0, time_enc = True and is_predict = True

3. A bigdl.chronos.data.tsdataset.TSDataset instance
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time).

Returns

A list of numpy ndarray

evaluate(data, batch_size=32)[source]#

Predict using a trained forecaster.

Parameters

data –
The data support following formats:

1. numpy ndarrays: generate from TSDataset.roll, be sure to set label_len > 0 and time_enc = True

2. pytorch dataloader: generate from TSDataset.to_torch_data_loader, be sure to set label_len > 0 and time_enc = True

3. A bigdl.chronos.data.tsdataset.TSDataset instance
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time).

Returns

A dict, currently returns the loss rather than metrics

predict_interval(data, validation_data=None, batch_size=32, repetition_times=5)[source]#

Calculate confidence interval of data based on Monte Carlo dropout(MC dropout). Related paper : https://arxiv.org/abs/1709.01907

Parameters

data –
The data support following formats:

1. numpy ndarrays: generate from TSDataset.roll, be sure to set label_len > 0 and time_enc = True

2. pytorch dataloader: generate from TSDataset.to_torch_data_loader, be sure to set label_len > 0, time_enc = True

3. A bigdl.chronos.data.tsdataset.TSDataset instance
validation_data –
The validation_data support following formats:

1. numpy ndarrays: generate from TSDataset.roll, be sure to set label_len > 0 and time_enc = True

2. pytorch dataloader: generate from TSDataset.to_torch_data_loader, be sure to set label_len > 0, time_enc = True

3. A bigdl.chronos.data.tsdataset.TSDataset instance
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time).

:param repetition_timesDefines repeate how many times to calculate model: uncertainty based on MC Dropout.

Returns: prediction and standard deviation which are both numpy array with shape (num_samples, horizon, target_dim)

get_model()[source]#

Returns the learned PyTorch Lightning model.

Returns: a pytorch lightning model instance

load(checkpoint_file)[source]#

restore the forecaster.

Parameters: checkpoint_file – The checkpoint file location you want to load the forecaster.

save(checkpoint_file)[source]#

save the forecaster.

Parameters: checkpoint_file – The checkpoint file location you want to load the forecaster.

classmethod from_tsdataset(tsdataset, past_seq_len=None, future_seq_len=None, label_len=None, freq=None, **kwargs)[source]#

Build a Forecaster Model.

Parameters

tsdataset – A bigdl.chronos.data.tsdataset.TSDataset instance.
past_seq_len – int or “auto”, Specify the history time steps (i.e. lookback). Do not specify the ‘past_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_torch_data_loader’. If “auto”, the mode of time series’ cycle length will be taken as the past_seq_len.
future_seq_len – int or list, Specify the output time steps (i.e. horizon). Do not specify the ‘future_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_torch_data_loader’.
kwargs – Specify parameters of Forecaster, e.g. loss and optimizer, etc. More info, please refer to Forecaster.__init__ methods.

Returns

A Forecaster Model.

NBeatsForecaster#

Neural basis expansion analysis for interpretable time series forecasting (N-BEATS) is a deep neural architecture based on backward and forward residual links and a very deep stack of fully-connected layers. Nbeats can solve univariate time series point forecasting problems, being interpretable, and fast to train.

class bigdl.chronos.forecaster.nbeats_forecaster.NBeatsForecaster(past_seq_len, future_seq_len, stack_types=('generic', 'generic'), nb_blocks_per_stack=3, thetas_dim=(4, 8), share_weights_in_stack=False, hidden_layer_units=256, nb_harmonics=None, optimizer='Adam', loss='mse', lr=0.001, metrics=['mse'], seed=None, distributed=False, workers_per_node=1, distributed_backend='ray')[source]#

Bases: bigdl.chronos.forecaster.base_forecaster.BasePytorchForecaster

Example

>>> # 1. Initialize Forecaster directly
>>> forecaster = NBeatForecaster(paste_seq_len=10,
                                 future_seq_len=1,
                                 stack_types=("generic", "generic"),
                                 ...)
>>>
>>> # 2. The from_tsdataset method can also initialize a NBeatForecaster.
>>> forecaster.from_tsdataset(tsdata, **kwargs)
>>> forecaster.fit(tsdata)
>>> forecaster.to_local() # if you set distributed=True

Build a NBeats Forecaster Model.

Parameters

past_seq_len – Specify the history time steps (i.e. lookback).
future_seq_len – Specify the output time steps (i.e. horizon).
stack_types – Specifies the type of stack, including “generic”, “trend”, “seasnoality”. This value defaults to (“generic”, “generic”). If set distributed=True, the second type should not be “generic”, use “seasonality” or “trend”, e.g. (“generic”, “trend”).
nb_blocks_per_stack – Specify the number of blocks contained in each stack, This value defaults to 3.
thetas_dim – Expansion Coefficients of Multilayer FC Networks. if type is “generic”, Extended length factor, if type is “trend” then polynomial coefficients, if type is “seasonality” expressed as a change within each step.
share_weights_in_stack – Share block weights for each stack., This value defaults to False.
hidden_layer_units – Number of fully connected layers with per block. This values defaults to 256.
nb_harmonics – Only available in “seasonality” type, specifies the time step of backward, This value defaults is None.
dropout – Specify the dropout close possibility (i.e. the close possibility to a neuron). This value defaults to 0.1.
optimizer – Specify the optimizer used for training. This value defaults to “Adam”.
loss – str or pytorch loss instance, Specify the loss function used for training. This value defaults to “mse”. You can choose from “mse”, “mae”, “huber_loss” or any customized loss instance you want to use.
lr – Specify the learning rate. This value defaults to 0.001.
metrics – A list contains metrics for evaluating the quality of forecasting. You may only choose from “mse” and “mae” for a distributed forecaster. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape” or a callable function for a non-distributed forecaster. If callable function, it signature should be func(y_true, y_pred), where y_true and y_pred are numpy ndarray.
seed – int, random seed for training. This value defaults to None.
distributed – bool, if init the forecaster in a distributed fashion. If True, the internal model will use an Orca Estimator. If False, the internal model will use a pytorch model. The value defaults to False.
workers_per_node – int, the number of worker you want to use. The value defaults to 1. The param is only effective when distributed is set to True.
distributed_backend – str, select from “ray” or “horovod”. The value defaults to “ray”.

build_jit(thread_num=1, use_ipex=False)#

Build jit model to speed up inference and reduce latency. The method is Not required to call before predict_with_jit or export_torchscript_file.

It is recommended to use when you want to:

1. Strictly control the thread to be used during inferencing.

2. Alleviate the cold start problem when you call predict_with_jit

for the first time.

Parameters

use_ipex – if to use intel-pytorch-extension for acceleration. Typically, intel-pytorch-extension will bring some acceleration while causing some unexpected error as well.
thread_num –

int, the num of thread limit. The value is set to 1 by
default where no limit is set.Besides, the environment variable

OMP_NUM_THREADS is suggested to be same as thread_num.

build_onnx(thread_num=1, sess_options=None)#

1. Strictly control the thread to be used during inferencing.

2. Alleviate the cold start problem when you call predict_with_onnx for the first time.

Parameters

thread_num – int, the num of thread limit. The value is set to None by default where no limit is set. Besides, the environment variable OMP_NUM_THREADS is suggested to be same as thread_num.
sess_options – an onnxruntime.SessionOptions instance, if you set this other than None, a new onnxruntime session will be built on this setting and ignore other settings you assigned(e.g. thread_num…).

Example

>>> # to pre build onnx sess
>>> forecaster.build_onnx(thread_num=2)  # build onnx runtime sess for two threads
>>> pred = forecaster.predict_with_onnx(data)
>>> # ------------------------------------------------------
>>> # directly call onnx related method is also supported
>>> # default to build onnx runtime sess for single thread
>>> pred = forecaster.predict_with_onnx(data)

build_openvino(thread_num=1)#

Build openvino model to speed up inference and reduce latency. The method is Not required to call before predict_with_openvino.

It is recommended to use when you want to:

1. Strictly control the thread to be used during inferencing.

2. Alleviate the cold start problem when you call predict_with_openvino for the first time.

Parameters: thread_num – int, the num of thread limit. The value is set to 1 by default where no limit is set. Besides, the environment variable OMP_NUM_THREADS is suggested to be same as thread_num.

evaluate(data, batch_size=32, multioutput='raw_values', quantize=False, acceleration: bool = True)#

Evaluate using a trained forecaster.

If you want to evaluate on a single node(which is common practice), please call .to_local().evaluate(data, …)

>>> from bigdl.chronos.metric.forecast_metrics import Evaluator
>>> y_hat = forecaster.predict(x)
>>> y_hat_unscaled = tsdata.unscale_numpy(y_hat) # or other customized unscale methods
>>> y_unscaled = tsdata.unscale_numpy(y) # or other customized unscale methods
>>> Evaluator.evaluate(metric=..., y_unscaled, y_hat_unscaled, multioutput=...)

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x, ‘y’: y}, where x and y’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – evaluate batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time).
multioutput – Defines aggregating of multiple output values. String in [‘raw_values’, ‘uniform_average’]. The value defaults to ‘raw_values’.The param is only effective when the forecaster is a non-distribtued version.
quantize – if use the quantized model to predict.
acceleration – bool variable indicates whether use original model. Default to True means use accelerated_model to predict, which requires to call one of .build_jit(), .build_onnx(), .build_openvino() and .optimize(), otherwise the original model will be used to predict.

Returns

A list of evaluation results. Each item represents a metric.

evaluate_with_onnx(data, batch_size=32, multioutput='raw_values', quantize=False)#

Evaluate using a trained forecaster with onnxruntime. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_onnx is valid and Forecaster will automatically build an onnxruntime session with default settings (thread num is 1).

>>> from bigdl.chronos.metric.forecast_metrics import Evaluator
>>> y_hat = forecaster.predict_with_onnx(x)
>>> y_hat_unscaled = tsdata.unscale_numpy(y_hat) # or other customized unscale methods
>>> y_unscaled = tsdata.unscale_numpy(y) # or other customized unscale methods
>>> Evaluator.evaluate(metric=..., y_unscaled, y_hat_unscaled, multioutput=...)

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

should be the same as future_seq_len and output_feature_num.

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – evaluate batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time).
multioutput – Defines aggregating of multiple output values. String in [‘raw_values’, ‘uniform_average’]. The value defaults to ‘raw_values’.
quantize – if use the quantized onnx model to evaluate.

Returns

A list of evaluation results. Each item represents a metric.

export_onnx_file(dirname='fp32_onnx', quantized_dirname=None)#

Save the onnx model file to the disk.

Parameters

dirname – The dir location you want to save the onnx file.
quantized_dirname – The dir location you want to save the quantized onnx file.

export_openvino_file(dirname='fp32_openvino', quantized_dirname=None)#

Save the openvino model file to the disk.

Parameters

dirname – The dir location you want to save the openvino file.
quantized_dirname – The dir location you want to save the quantized openvino file.

export_torchscript_file(dirname='fp32_torchscript', quantized_dirname=None, save_pipeline=False, tsdata=None, drop_dt_col=True)#

Save the torchscript model file and the whole forecasting pipeline to the disk.

Currently the pipeline is similar to the following code:

>>> # preprocess
>>> tsdata.scale(scaler, fit=False) \
>>>       .roll(lookback, horizon, is_predict=True)
>>> preprocess_output = tsdata.to_numpy()
>>> # inference using trained forecaster
>>> # forecaster_module is the saved torchscript model
>>> inference_output = forecaster_module.forward(preprocess_output)
>>> # postprocess
>>> postprocess_output = tsdata.unscale_numpy(inference_output)

When deploying, the pipeline can be used by:

>>> // deployment in C++
>>> #include <torch/torch.h>
>>> #include <torch/script.h>
>>> // create input tensor from your data
>>> // The data to create the input tensor should have the same format as the
>>> // data used in developing
>>> torch::Tensor input = create_input_tensor(data);
>>> // load the pipeline
>>> torch::jit::script::Module forecasting_pipeline;
>>> forecasting_pipeline = torch::jit::load(path);
>>> // run pipeline
>>> torch::Tensor output = forecasting_pipeline.forward(input_tensor).toTensor();

The limitations of exporting the forecasting pipeline is same as limitations in TSDataset.export_jit():

Please make sure the value of each column can be converted to Pytorch tensor, for example, id “00” is not allowed because str can not be converted to a tensor, you should use integer (0, 1, ..) as id instead of string.

Some features in tsdataset.scale and tsdataset.roll are unavailable in this pipeline:

If self.roll_additional_feature is not None, it can’t be processed in scale and roll

id_sensitive, time_enc and label_len parameter is not supported in roll

Users are expected to call .scale(scaler, fit=True) before calling export_jit. Single roll operation is not supported for converting now.

Parameters

dirname – The dir location you want to save the torchscript file.
quantized_dirname – The dir location you want to save the quantized torchscript model.
save_pipeline – Whether to save the whole forecasting pipeline, defaluts to False. If set to True, the whole forecasting pipeline will be saved in “dirname/chronos_forecasting_pipeline.pt”, if set to False, only the torchscript model will be saved.
tsdata – The TSDataset instance used when developing the forecaster. The parameter should be used only when save_pipeline is True.
drop_dt_col – Whether to delete the datetime column, defaults to True. The parameter is valid only when save_pipeline is True. Since datetime value (like “2022-12-12”) can’t be converted to Pytorch tensor, you can choose different ways to workaround this. If set to True, the datetime column will be deleted, then you also need to skip the datetime column when reading data from data source (like csv files) in deployment environment to keep the same structure as the data used in development; if set to False, the datetime column will not be deleted, and you need to make sure the datetime colunm can be successfully converted to Pytorch tensor when reading data in deployment environment. For example, you can set each data in datetime column to an int (or other vaild types) value, since datetime column is not necessary in preprocessing and postprocessing, the value can be arbitrary.

fit(data, validation_data=None, epochs=1, batch_size=32, validation_mode='output', earlystop_patience=1, use_trial_id=None)#

Fit(Train) the forecaster.

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x, ‘y’: y}, where x and y’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
validation_data –
Validation sample for validation loop. Defaults to ‘None’. If you do not input data for ‘validation_data’, the validation_step will be skipped. Validation data will be ignored under distributed mode. The validation_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x, ‘y’: y}, where x and y’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
epochs – Number of epochs you want to train. The value defaults to 1.
batch_size – Number of batch size you want to train. The value defaults to 32. If you input a pytorch dataloader for data, the batch_size will follow the batch_size setted in data.if the forecaster is distributed, the batch_size will be evenly distributed to all workers.
validation_mode –
A str represent the operation mode while having ‘validation_data’. Defaults to ‘output’. The validation_mode includes the following types:

1. output:

If you choose ‘output’ for validation_mode, it will return a dict that records the

average validation loss of each epoch.

2. earlystop:

Monitor the val_loss and stop training when it stops improving.

3. best_epoch:

Monitor the val_loss. And load the checkpoint of the epoch with the smallest

val_loss after the training.
earlystop_patience – Number of checks with no improvement after which training will be stopped. It takes effect when ‘validation_mode’ is ‘earlystop’. Under the default configuration, one check happens after every training epoch.
use_trail_id – choose a internal according to trial_id, which is used only in multi-objective search.

Returns

Validation loss if ‘validation_data’ is not None.

get_context(thread_num=None, optimize=True)#

Obtain context manager from forecaster.

Parameters

thread_num – int, the num of thread limit. The value is set to None by default where no limit is set.
optimize – bool variable indicates whether use original model. Default to True means use accelerated_model to generate context manager, which requires to call .optimize(), otherwise the original model will be used.

Returns

a context manager.

get_model()#

Returns the learned PyTorch model.

Returns: a pytorch model instance

load(checkpoint_file, quantize_checkpoint_file=None)#

restore the forecaster.

Parameters

checkpoint_file – The checkpoint file location you want to load the forecaster.
quantize_checkpoint_file – The checkpoint file location you want to load the quantized forecaster.

Parameters

train_data –
Data used for training model. Users should be careful with this parameter since this data might be exposed to the model, which causing data leak. The train_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

The batch_size of this dataloader is important as well, users may want to set it

to the same batch size you may want to use the model in real deploy environment.

E.g. batch size should be set to 1 if you would like to use the accelerated model

in an online service.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
validation_data(optional) –
This is only needed when users care about the possible accuracy drop. The validation_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – Number of batch size you want to use the model in real deploy environment. The value defaults to 32. If you input a pytorch dataloader for train_data, the batch_size will follow the batch_size setted in train_data.
thread_num – int, the num of thread limit. The value is set to None by default where no limit is set.
accelerator – (optional) Use accelerator ‘None’, ‘onnxruntime’, ‘openvino’, ‘jit’, defaults to None. If not None, then will only find the model with this specific accelerator.
precision – (optional) Supported type: ‘int8’, ‘bf16’, ‘fp32’. Defaults to None which represents no precision limit. If not None, then will only find the model with this specific precision.
metric – (optional) A str represent corresponding metric which is used for calculating accuracy.
accuracy_criterion – (optional) a float represents tolerable accuracy drop percentage, defaults to None meaning no accuracy control.

Example

>>> # obtain optimized model
>>> forecaster.optimize(train_data, val_data, thread_num=1)
>>> pred = forecaster.predict(data)

predict(data, batch_size=32, quantize=False, acceleration: bool = True)#

Predict using a trained forecaster.

if you want to predict on a single node(which is common practice), please call .to_local().predict(x, …)

Parameters

data –
The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. a xshard item:

each partition can be a dictionary of {‘x’: x}, where x’s shape

should follow the shape stated before.

3. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

4. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume memory.
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time).
quantize – if use the quantized model to predict.
acceleration – bool variable indicates whether use original model. Default to True means use accelerated_model to predict, which requires to call one of .build_jit(), .build_onnx(), .build_openvino() and .optimize(), otherwise the original model will be used to predict.

Returns

predict_interval(data, validation_data=None, batch_size=32, repetition_times=5)#

Calculate confidence interval of data based on Monte Carlo dropout(MC dropout). Related paper : https://arxiv.org/abs/1709.01907

Parameters

data –
The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
validation_data –
The validation_data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time).
repetition_times – Defines repeate how many times to calculate model uncertainty based on MC Dropout.

Returns

prediction and standard deviation which are both numpy array with shape (num_samples, horizon, target_dim)

predict_with_jit(data, batch_size=32, quantize=False)#

Predict using a trained forecaster with jit. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_jit is valid and Forecaster will automatically build an jit session with default settings (thread num is 1).

Parameters

data –

The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.

param batch_size: predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time). Defaults to 32. None for all-data-single-time inference.
param quantize: if use the quantized jit model to predict. Not support yet.
return: A numpy array with shape (num_samples, horizon, target_dim).

predict_with_onnx(data, batch_size=32, quantize=False)#

Predict using a trained forecaster with onnxruntime. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_onnx is valid and Forecaster will automatically build an onnxruntime session with default settings (thread num is 1).

Parameters

data –
The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
batch_size – predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time). Defaults to 32. None for all-data-single-time inference.
quantize – if use the quantized onnx model to predict.

Returns

A numpy array with shape (num_samples, horizon, target_dim).

predict_with_openvino(data, batch_size=32, quantize=False)#

Predict using a trained forecaster with openvino. The method can only be used when forecaster is a non-distributed version.

Directly call this method without calling build_openvino is valid and Forecaster will automatically build an openvino session with default settings (thread num is 1).

Parameters

data –

The data support following formats:

1. a numpy ndarray x:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

2. pytorch dataloader:

the dataloader needs to return at least x in each iteration

with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

If returns x and y only get x.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.

param batch_size: predict batch size. The value will not affect predict result but will affect resources cost(e.g. memory and time). Defaults to 32. None for all-data-single-time inference.
param quantize: if use the quantized openvino model to predict.
return: A numpy array with shape (num_samples, horizon, target_dim).

Quantize the forecaster.

Parameters

calib_data –
Required for static quantization. Support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
val_data –
for evaluation. Support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

2. pytorch dataloader:

the dataloader should return x, y in each iteration with the shape as following:

x’s shape is (num_samples, lookback, feature_dim) where lookback and feature_dim

should be the same as past_seq_len and input_feature_num.

y’s shape is (num_samples, horizon, target_dim), where horizon and target_dim

should be the same as future_seq_len and output_feature_num.

3. A bigdl.chronos.data.tsdataset.TSDataset instance:

Forecaster will automatically process the TSDataset.

By default, TSDataset will be transformed to a pytorch dataloader,

which is memory-friendly while a little bit slower.

Users may call roll on the TSDataset before calling fit

Then the training speed will be faster but will consume more memory.
metric – A str represent the metrics for tunning the quality of quantization. You may choose from “mse”, “mae”, “rmse”, “r2”, “mape”, “smape”.
conf – A path to conf yaml file for quantization. Default to None, using default config.
framework – A str represent the framework for quantization. You may choose from “pytorch_fx”, “pytorch_ipex”, “onnxrt_integerops”, “onnxrt_qlinearops”, “openvino”. Default: ‘pytorch_fx’. Consistent with Intel Neural Compressor.
approach – str, ‘static’ or ‘dynamic’. Default to ‘static’. OpenVINO supports static mode only, if set to ‘dynamic’, it will be replaced with ‘static’.
tuning_strategy – str, ‘bayesian’, ‘basic’, ‘mse’ or ‘sigopt’. Default to ‘bayesian’.
relative_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 0.1 means that we accept a 10% increase in the metrics error.
absolute_drop – Float, tolerable ralative accuracy drop. Default to None, e.g. set to 5 means that we can only accept metrics smaller than 5.
timeout – Tuning timeout (seconds). Default to 0, which means early stop. Combine with max_trials field to decide when to exit.
max_trials – Max tune times. Default to 1. Combine with timeout field to decide when to exit. “timeout=0, max_trials=1” means it will try quantization only once and return satisfying best model.
sess_options – The session option for onnxruntime, only valid when framework contains ‘onnxrt_integerops’ or ‘onnxrt_qlinearops’, otherwise will be ignored.
thread_num – int, the num of thread limit. The value is set to None by default where no limit is set

save(checkpoint_file, quantize_checkpoint_file=None)#

Save the forecaster.

Please note that if you only want the pytorch model or onnx model file, you can call .get_model() or .export_onnx_file(). The checkpoint file generated by .save() method can only be used by .load().

Parameters

checkpoint_file – The location you want to save the forecaster.
quantize_checkpoint_file – The location you want to save quantized forecaster.

search_summary()#: Return search summary of HPO.

to_local()#

Transform a distributed forecaster to a local (non-distributed) one.

The optimizer is refreshed, incremental training after to_local might have some problem.

Returns: a forecaster instance.

tune(data, validation_data, target_metric, direction, directions=None, n_trials=2, n_parallels=1, epochs=1, batch_size=32, acceleration=False, input_sample=None, **kwargs)#

Search the hyper parameter.

Parameters

data – train data, as numpy ndarray tuple (x, y)
validation_data – validation data, as numpy ndarray tuple (x,y)
target_metric – the target metric to optimize, a string or an instance of torchmetrics.metric.Metric
direction – in which direction to optimize the target metric, “maximize” - larger the better “minimize” - smaller the better
n_trials – number of trials to run
n_parallels – number of parallel processes used to run trials. to use parallel tuning you need to use a RDB url for storage and specify study_name. For more information, refer to Nano AutoML user guide.
epochs – the number of epochs to run in each trial fit, defaults to 1
batch_size – number of batch size for each trial fit, defaults to 32
acceleration – Whether to automatically consider the model after inference acceleration in the search process. It will only take effect if target_metric contains “latency”. Default value is False.
input_sample – A set of inputs for trace, defaults to None if you have trace before or model is a LightningModule with any dataloader attached.
kwargs – some other parameters could be used for tuning, most useful one is sampler from SamplerType.Grid, SamplerType.Random and SamplerType.TPE so on.

classmethod from_tsdataset(tsdataset, past_seq_len=None, future_seq_len=None, **kwargs)[source]#

Build a NBeats Forecaster Model.

Parameters

tsdataset – Train tsdataset, a bigdl.chronos.data.tsdataset.TSDataset instance.
past_seq_len – Specify the history time steps (i.e. lookback). Do not specify the ‘past_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_torch_data_loader’.
future_seq_len – Specify the output time steps (i.e. horizon). Do not specify the ‘future_seq_len’ if your tsdataset has called the ‘TSDataset.roll’ method or ‘TSDataset.to_torch_data_loader’.
kwargs – Specify parameters of Forecaster, e.g. loss and optimizer, etc. More info, please refer to NBeatsForecaster.__init__ methods.

Returns

A NBeats Forecaster Model.

TCMFForecaster#

Chronos TCMFForecaster provides an efficient way to forecast high dimensional time series.

TCMFForecaster is based on DeepGLO algorithm, which is a deep forecasting model which thinks globally and acts locally. You can refer to the deepglo paper for more details.

TCMFForecaster supports distributed training and inference. It is based on Orca PyTorch Estimator, which is an estimator to do PyTorch training/evaluation/prediction on Spark in a distributed fashion. Also you can choose to enable distributed training and inference or not.

Remarks:

You can refer to TCMFForecaster installation to install required packages.
Your operating system (OS) is required to be one of the following 64-bit systems: Ubuntu 16.04 or later and macOS 10.12.6 or later.

class bigdl.chronos.forecaster.tcmf_forecaster.TCMFForecaster(vbsize=128, hbsize=256, num_channels_X=[32, 32, 32, 32, 32, 1], num_channels_Y=[16, 16, 16, 16, 16, 1], kernel_size=7, dropout=0.1, rank=64, kernel_size_Y=7, learning_rate=0.0005, normalize=False, use_time=True, svd=True)[source]#

Bases: bigdl.chronos.forecaster.abstract.Forecaster

Example

>>> import numpy as np
>>> model = TCMFForecaster()
>>> fit_params = dict(val_len=12,
                   start_date="2020-1-1",
                   freq="5min",
                   y_iters=1,
                   init_FX_epoch=1,
                   max_FX_epoch=1,
                   max_TCN_epoch=1,
                   alt_iters=2)
>>> ndarray_input = {'id': np.arange(300), 'y': np.random.rand(300, 480)}
>>> model.fit(ndarray_input, fit_params)
>>> horizon = np.random.randint(1, 50)
>>> yhat = model.predict(horizon=horizon)
>>> model.save({tempdirname})
>>> loaded_model = TCMFForecaster.load({tempdirname}, is_xshards_distributed=False)
>>> data_new = np.random.rand(300, horizon)
>>> model.evaluate(target_value=dict({"y": data_new}), metric=['mse'])
>>> model.fit_incremental({"y": data_new})
>>> yhat_incr = model.predict(horizon=horizon)

Build a TCMF Forecast Model.

Parameters

vbsize – int, default is 128. Vertical batch size, which is the number of cells per batch.
hbsize – int, default is 256. Horizontal batch size, which is the number of time series per batch.
num_channels_X – list, default=[32, 32, 32, 32, 32, 1]. List containing channel progression of temporal convolution network for local model
num_channels_Y – list, default=[16, 16, 16, 16, 16, 1] List containing channel progression of temporal convolution network for hybrid model.
kernel_size – int, default is 7. Kernel size for local models
dropout – float, default is 0.1. Dropout rate during training
rank – int, default is 64. The rank in matrix factorization of global model.
kernel_size_Y – int, default is 7. Kernel size of hybrid model
learning_rate – float, default is 0.0005
normalize – boolean, false by default. Whether to normalize input data for training.
use_time – boolean, default is True. Whether to use time coveriates.
svd – boolean, default is False. Whether factor matrices are initialized by NMF

fit(x, val_len=24, start_date='2020-4-1', freq='1H', covariates=None, dti=None, period=24, y_iters=10, init_FX_epoch=100, max_FX_epoch=300, max_TCN_epoch=300, alt_iters=10, num_workers=None)[source]#

Fit the model on x from scratch

Parameters

x – the input for fit. Only dict of ndarray and SparkXShards of dict of ndarray are supported. Example: {‘id’: id_arr, ‘y’: data_ndarray}, and data_ndarray is of shape (n, T), where n is the number f target time series and T is the number of time steps.
val_len – int, default is 24. Validation length. We will use the last val_len time points as validation data.
start_date – str or datetime-like. Start date time for the time-series. e.g. “2020-01-01”
freq – str or DateOffset, default is ‘H’ Frequency of data
covariates – 2-D ndarray or None. The shape of ndarray should be (r, T), where r is the number of covariates and T is the number of time points. Global covariates for all time series. If None, only default time coveriates will be used while use_time is True. If not, the time coveriates used is the stack of input covariates and default time coveriates.
dti – DatetimeIndex or None. If None, use default fixed frequency DatetimeIndex generated with start_date and freq.
period – int, default is 24. Periodicity of input time series, leave it out if not known
y_iters – int, default is 10. Number of iterations while training the hybrid model.
init_FX_epoch – int, default is 100. Number of iterations while initializing factors
max_FX_epoch – int, default is 300. Max number of iterations while training factors.
max_TCN_epoch – int, default is 300. Max number of iterations while training the local model.
alt_iters – int, default is 10. Number of iterations while alternate training.
num_workers – the number of workers you want to use for fit. If None, it defaults to num_ray_nodes in the created OrcaRayContext or 1 if there is no active OrcaRayContext.

fit_incremental(x_incr, covariates_incr=None, dti_incr=None)[source]#

Incrementally fit the model. Note that we only incrementally fit X_seq (TCN in global model)

Parameters

x_incr – incremental data to be fitted. It should be of the same format as input x in fit, which is a dict of ndarray or SparkXShards of dict of ndarray. Example: {‘id’: id_arr, ‘y’: incr_ndarray}, and incr_ndarray is of shape (n, T_incr) , where n is the number of target time series, T_incr is the number of time steps incremented. You can choose not to input ‘id’ in x_incr, but if you do, the elements of id in x_incr should be the same as id in x of fit.
covariates_incr – covariates corresponding to x_incr. 2-D ndarray or None. The shape of ndarray should be (r, T_incr), where r is the number of covariates. Global covariates for all time series. If None, only default time coveriates will be used while use_time is True. If not, the time coveriates used is the stack of input covariates and default time coveriates.
dti_incr – dti corresponding to the x_incr. DatetimeIndex or None. If None, use default fixed frequency DatetimeIndex generated with the last date of x in fit and freq.

evaluate(target_value, metric=['mae'], target_covariates=None, target_dti=None, num_workers=None)[source]#

Evaluate the model

Parameters

target_value – target value for evaluation. We interpret its second dimension of as the horizon length for evaluation.
metric – the metrics. A list of metric names.
target_covariates – covariates corresponding to target_value. 2-D ndarray or None. The shape of ndarray should be (r, horizon), where r is the number of covariates. Global covariates for all time series. If None, only default time coveriates will be used while use_time is True. If not, the time coveriates used is the stack of input covariates and default time coveriates.
target_dti – dti corresponding to target_value. DatetimeIndex or None. If None, use default fixed frequency DatetimeIndex generated with the last date of x in fit and freq.
num_workers – the number of workers to use in evaluate. If None, it defaults to num_ray_nodes in the created OrcaRayContext or 1 if there is no active OrcaRayContext.

Returns

A list of evaluation results. Each item represents a metric.

predict(horizon=24, future_covariates=None, future_dti=None, num_workers=None)[source]#

Predict using a trained forecaster.

Parameters

horizon – horizon length to look forward.
future_covariates – covariates corresponding to future horizon steps data to predict. 2-D ndarray or None. The shape of ndarray should be (r, horizon), where r is the number of covariates. Global covariates for all time series. If None, only default time coveriates will be used while use_time is True. If not, the time coveriates used is the stack of input covariates and default time coveriates.
future_dti – dti corresponding to future horizon steps data to predict. DatetimeIndex or None. If None, use default fixed frequency DatetimeIndex generated with the last date of x in fit and freq.
num_workers – the number of workers to use in predict. If None, it defaults to num_ray_nodes in the created OrcaRayContext or 1 if there is no active OrcaRayContext.

Returns

A numpy ndarray with shape of (nd, horizon), where nd is the same number of time series as input x in fit_eval.

save(path)[source]#

Save the forecaster.

Parameters: path – Path to target saved file.

is_xshards_distributed()[source]#

Check whether model is distributed by input xshards.

Returns: True if the model is distributed by input xshards

classmethod load(path, is_xshards_distributed=False, minPartitions=None)[source]#

Load a saved model.

Parameters

path – The location you want to save the forecaster.
is_xshards_distributed – Whether the model is distributed trained with input of dict of SparkXshards.
minPartitions – The minimum partitions for the XShards.

Returns

the model loaded

MTNetForecaster#

MTNet is a memory-network based solution for multivariate time-series forecasting. In a specific task of multivariate time-series forecasting, we have several variables observed in time series and we want to forecast some or all of the variables’ value in a future time stamp.

MTNet is proposed by paper A Memory-Network Based Solution for Multivariate Time-Series Forecasting.

For the detailed algorithm description, please refer to here.

class bigdl.chronos.forecaster.tf.mtnet_forecaster.MTNetForecaster(target_dim=1, feature_dim=1, long_series_num=1, series_length=1, ar_window_size=1, cnn_height=1, cnn_hid_size=32, rnn_hid_sizes=[16, 32], lr=0.001, loss='mae', cnn_dropout=0.2, rnn_dropout=0.2, metric='mean_squared_error', uncertainty: bool = False)[source]#

Bases: bigdl.chronos.forecaster.abstract.Forecaster

Example

>>> #The dataset is split into x_train, x_val, x_test, y_train, y_val, y_test
>>> model = MTNetForecaster(target_dim=1,
                            feature_dim=x_train.shape[-1],
                            long_series_num=6,
                            series_length=2
                            )
>>> model.fit(data=(x_train, y_train),
              validation_data=(x_val, y_val),
              epochs=2,
              batch_size=32)
>>> model.predict(x_test, batch_size=batch_size)

Build a MTNet Forecast Model.

Parameters

target_dim – the dimension of model output
feature_dim – the dimension of input feature
long_series_num – the number of series for the long-term memory series
series_length – the series size for long-term and short-term memory series
ar_window_size – the auto regression window size in MTNet
cnn_hid_size – the hidden layer unit for cnn in encoder
rnn_hid_sizes – the hidden layers unit for rnn in encoder
cnn_height – cnn filter height in MTNet
metric – the metric for validation and evaluation
uncertainty – whether to enable calculation of uncertainty
lr – learning rate
loss – the target function you want to optimize on
cnn_dropout – the dropout possibility for cnn in encoder
rnn_dropout – the dropout possibility for rnn in encoder

fit(data, epochs=2, batch_size=32, validation_data=None)[source]#

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, (long_series_num+1)*series_length, feature_dim)

y’s shape is (num_samples, target_dim)
epochs – Number of epochs you want to train. The value defaults to 2.
batch_size – Number of batch size you want to train. The value defaults to 32.
validation_data – Data on which to evaluate the loss and any model metrics at the end of each epoch. The model will not be trained on this data.

predict(data, batch_size=32)[source]#

Parameters

data –
The data support following formats:

1. data’s shape is (num_samples, (long_series_num+1)*series_length, feature_dim)
batch_size – predict batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time).

Returns

A numpy.ndarray with shape of (num_samples, feature_dum).

evaluate(data, metric=['mae'], batch_size=32, multioutput='raw_values')[source]#

Parameters

data –
The data support following formats:

1. a numpy ndarray tuple (x, y):

x’s shape is (num_samples, (long_series_num+1)*series_length, feature_dim)

y’s shape is (num_samples, target_dim)
metric – metric is the evaluation metric name to optimize, e.g. [“mae”].
batch_size – evaluate batch size. The value will not affect evaluate result but will affect resources cost(e.g. memory and time).
multioutput – Defines aggregating of multiple output values. String in [‘raw_values’, ‘uniform_average’]. The value defaults to ‘raw_values’.

Returns

A list of evaluation results. Calculation results for each metrics.

save(checkpoint_file)[source]#

Save the forecaster.

Parameters: checkpoint_file – The location you want to save the forecaster.

load(checkpoint_file)[source]#

Load the forecaster.

Parameters: checkpoint_file – The checkpoint file location you want to load the forecaster.

ARIMAForecaster#

AutoRegressive Integrated Moving Average (ARIMA) is a class of statistical models for analyzing and forecasting time series data. It consists of 3 components: AR (AutoRegressive), I (Integrated) and MA (Moving Average). In ARIMAForecaster we use the SARIMA model (Seasonal ARIMA), which is an extension of ARIMA that additionally supports the direct modeling of the seasonal component of the time series.

class bigdl.chronos.forecaster.arima_forecaster.ARIMAForecaster(p=2, q=2, seasonality_mode=True, P=3, Q=1, m=7, metric='mse')[source]#

Bases: bigdl.chronos.forecaster.abstract.Forecaster

Example

>>> #The dataset is split into data, validation_data
>>> model = ARIMAForecaster(p=2, q=2, seasonality_mode=False)
>>> model.fit(data, validation_data)
>>> predict_result = model.predict(horizon=24)

Build a ARIMA Forecast Model. User can customize p, q, seasonality_mode, P, Q, m, metric for the ARIMA model, the differencing term (d) and seasonal differencing term (D) are automatically estimated from the data. For details of the ARIMA model hyperparameters, refer to https://alkaline-ml.com/pmdarima/modules/generated/pmdarima.arima.ARIMA.html#pmdarima.arima.ARIMA.

Parameters

p – hyperparameter p for the ARIMA model.
q – hyperparameter q for the ARIMA model.
seasonality_mode – hyperparameter seasonality_mode for the ARIMA model.
P – hyperparameter P for the ARIMA model.
Q – hyperparameter Q for the ARIMA model.
m – hyperparameter m for the ARIMA model.
metric – the metric for validation and evaluation. For regression, we support Mean Squared Error: (“mean_squared_error”, “MSE” or “mse”), Mean Absolute Error: (“mean_absolute_error”,”MAE” or “mae”), Mean Absolute Percentage Error: (“mean_absolute_percentage_error”, “MAPE”, “mape”) Cosine Proximity: (“cosine_proximity”, “cosine”)

fit(data, validation_data)[source]#

Fit(Train) the forecaster.

Parameters

data – A 1-D numpy array as the training data
validation_data – A 1-D numpy array as the evaluation data

predict(horizon, rolling=False)[source]#

Predict using a trained forecaster.

Parameters

horizon – the number of steps forward to predict
rolling – whether to use rolling prediction

Returns

A list in length of horizon reflects the predict result.

evaluate(validation_data, metrics=['mse'], rolling=False)[source]#

Evaluate using a trained forecaster.

Parameters

validation_data – A 1-D numpy array as the evaluation data
metrics – A list contains metrics for test/valid data.

Returns

A list in length of len(metrics), where states the metrics in order.

save(checkpoint_file)[source]#

Save the forecaster.

Parameters: checkpoint_file – The location you want to save the forecaster.

restore(checkpoint_file)[source]#

Restore the forecaster.

Parameters: checkpoint_file – The checkpoint file location you want to load the forecaster.

ProphetForecaster#

Prophet is a procedure for forecasting time series data based on an additive model where non-linear trends are fit with yearly, weekly, and daily seasonality, plus holiday effects. It works best with time series that have strong seasonal effects and several seasons of historical data. Prophet is robust to missing data and shifts in the trend, and typically handles outliers well.

For the detailed algorithm description, please refer to here.

class bigdl.chronos.forecaster.prophet_forecaster.ProphetForecaster(changepoint_prior_scale=0.05, seasonality_prior_scale=10.0, holidays_prior_scale=10.0, seasonality_mode='additive', changepoint_range=0.8, metric='mse')[source]#

Bases: bigdl.chronos.forecaster.abstract.Forecaster

Example

>>> #The dataset is split into data, validation_data
>>> model = ProphetForecaster(changepoint_prior_scale=0.05, seasonality_mode='additive')
>>> model.fit(data, validation_data)
>>> predict_result = model.predict(horizon=24)

Build a Prophet Forecast Model. User can customize changepoint_prior_scale, seasonality_prior_scale, holidays_prior_scale, seasonality_mode, changepoint_range and metric of the Prophet model, for details of the Prophet model hyperparameters, refer to https://facebook.github.io/prophet/docs/diagnostics.html#hyperparameter-tuning.

Parameters

changepoint_prior_scale – hyperparameter changepoint_prior_scale for the Prophet model.
seasonality_prior_scale – hyperparameter seasonality_prior_scale for the Prophet model.
holidays_prior_scale – hyperparameter holidays_prior_scale for the Prophet model.
seasonality_mode – hyperparameter seasonality_mode for the Prophet model.
changepoint_range – hyperparameter changepoint_range for the Prophet model.
metric – the metric for validation and evaluation. For regression, we support Mean Squared Error: (“mean_squared_error”, “MSE” or “mse”), Mean Absolute Error: (“mean_absolute_error”,”MAE” or “mae”), Mean Absolute Percentage Error: (“mean_absolute_percentage_error”, “MAPE”, “mape”) Cosine Proximity: (“cosine_proximity”, “cosine”)

fit(data, validation_data=None)[source]#

Fit(Train) the forecaster.

Parameters

data – training data, a pandas dataframe with Td rows, and 2 columns, with column ‘ds’ indicating date and column ‘y’ indicating value and Td is the time dimension
validation_data – evaluation data, should be the same type as data

Returns

the evaluation metric value

predict(horizon=1, freq='D', ds_data=None)[source]#

Predict using a trained forecaster.

Parameters

horizon – the number of steps forward to predict, the value defaults to 1.
freq – the freqency of the predicted dataframe, defaulted to day(“D”), the frequency can be anything from the pandas list of frequency strings here: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#timeseries-offset-aliases
ds_data – a dataframe that has 1 column ‘ds’ indicating date.

Returns

A pandas DataFrame of length horizon, including “trend” and “seasonality” and inference values, etc. where the “yhat” column is the inference value.

evaluate(data, metrics=['mse'])[source]#

Evaluate using a trained forecaster.

Parameters

data – evaluation data, a pandas dataframe with Td rows, and 2 columns, with column ‘ds’ indicating date and column ‘y’ indicating value and Td is the time dimension
metrics – A list contains metrics for test/valid data.

Returns

A list of evaluation results. Calculation results for each metrics.

save(checkpoint_file)[source]#

Save the forecaster.

Parameters: checkpoint_file – The location you want to save the forecaster, should be a json file

restore(checkpoint_file)[source]#

Restore the forecaster.

Parameters: checkpoint_file – The checkpoint file location you want to load the forecaster.