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_dtcol=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():

  1. 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.

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

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

    2. id_sensitive, time_enc and label_len parameter is not supported in roll

  3. 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_dtcol – 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_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.

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.

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)#

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_dtcol=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():

  1. 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.

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

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

    2. id_sensitive, time_enc and label_len parameter is not supported in roll

  3. 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_dtcol – 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_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.

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)#

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_dtcol=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():

  1. 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.

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

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

    2. id_sensitive, time_enc and label_len parameter is not supported in roll

  3. 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_dtcol – 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_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.

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 – train data, as numpy ndarray tuple (x, y, x_enc, y_enc)

  • validation_data – validation data, as numpy ndarray tuple (x, y, x_enc, y_enc)

  • 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.

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)#

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_dtcol=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():

  1. 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.

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

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

    2. id_sensitive, time_enc and label_len parameter is not supported in roll

  3. 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_dtcol – 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_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.

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
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.