Conformal Models¶

A collection of conformal prediction models for pre-trained global forecasting models.

class darts.models.forecasting.conformal_models.ConformalModel(model, quantiles, symmetric=True, cal_length=None, cal_stride=1, cal_num_samples=500, random_state=None)[source]¶

Bases: GlobalForecastingModel, ABC

Base Conformal Prediction Model.

Base class for any conformal prediction model. A conformal model calibrates the predictions from any pre-trained global forecasting model. It does not have to be trained, and can generate calibrated forecasts directly using the underlying trained forecasting model. Since it is a probabilistic model, you can generate forecasts in two ways (when calling predict(), historical_forecasts(), …):

Predict the calibrated quantile intervals directly: Pass parameters predict_likelihood_parameters=True, and num_samples=1 to the forecast method.
Predict stochastic samples from the calibrated quantile intervals: Pass parameters predict_likelihood_parameters=False, and num_samples>>1 to the forecast method.

Conformal models can be applied to any of Darts’ global forecasting model, as long as the model has been fitted before. In general the workflow of the models to produce one calibrated forecast/prediction is as follows:

Extract a calibration set: The calibration set for each conformal forecast is automatically extracted from the most recent past of your input series relative to the forecast start point. The number of calibration examples (forecast errors / non-conformity scores) to consider can be defined at model creation with parameter cal_length. Note that when using cal_stride>1, a longer history is required since the calibration examples are generated with stridden historical forecasts.
Generate historical forecasts on the calibration set (using the forecasting model) with a stride cal_stride.
Compute the errors/non-conformity scores (specific to each conformal model) on these historical forecasts
Compute the quantile values from the errors / non-conformity scores (using our desired quantiles set at model creation with parameter quantiles).
Compute the conformal prediction: Using these quantile values, add calibrated intervals to (or adjust the existing intervals of) the forecasting model’s predictions.

Some notes:

When computing historical_forecasts(), backtest(), residuals(), … the above is applied for each forecast (the forecasting model’s historical forecasts are only generated once for efficiency).
For multi-horizon forecasts, the above is applied for each step in the horizon separately.

Parameters

model (GlobalForecastingModel) – A pre-trained global forecasting model. See the list of models here.
quantiles (list[float]) – A list of quantiles centered around the median q=0.5 to use. For example quantiles [0.1, 0.2, 0.5, 0.8 0.9] correspond to two intervals with (0.9 - 0.1) = 80%, and (0.8 - 0.2) 60% coverage around the median (model forecast).
symmetric (bool) – Whether to use symmetric non-conformity scores. If False, uses asymmetric scores (individual scores for lower- and upper quantile interval bounds).
cal_length (Optional[int, None]) – The number of past forecast errors / non-conformity scores to use as calibration for each conformal forecast (and each step in the horizon). If None, considers all scores.
cal_stride (int) – The stride to apply when computing the historical forecasts and non-conformity scores on the calibration set. The actual conformal forecasts can have a different stride given with parameter stride in downstream tasks (e.g. historical forecasts, backtest, …)
cal_num_samples (int) – The number of samples to generate for each calibration forecast (if model is a probabilistic forecasting model). The non-conformity scores are computed on the quantile values of these forecasts (using quantiles quantiles). Uses 1 for deterministic models. The actual conformal forecasts can have a different number of samples given with parameter num_samples in downstream tasks (e.g. predict, historical forecasts, …).
random_state (Optional[int, None]) – Control the randomness of probabilistic conformal forecasts (sample generation) across different runs.

Attributes

`considers_static_covariates`	Whether the model considers static covariates, if there are any.
`extreme_lags`	A 8-tuple containing in order: (min target lag, max target lag, min past covariate lag, max past covariate lag, min future covariate lag, max future covariate lag, output shift, max target lag train (only for RNNModel)).
`min_train_samples`	The minimum number of samples for training the model.
`output_chunk_length`	Number of time steps predicted at once by the model, not defined for statistical models.
`output_chunk_shift`	Number of time steps that the output/prediction starts after the end of the input.
`supports_future_covariates`	Whether model supports future covariates
`supports_likelihood_parameter_prediction`	Whether model instance supports direct prediction of likelihood parameters
`supports_multivariate`	Whether the model considers more than one variate in the time series.
`supports_optimized_historical_forecasts`	Whether the model supports optimized historical forecasts
`supports_past_covariates`	Whether model supports past covariates
`supports_probabilistic_prediction`	Checks if the forecasting model with this configuration supports probabilistic predictions.
`supports_sample_weight`	Whether model supports sample weight for training.
`supports_static_covariates`	Whether model supports static covariates
`supports_transferrable_series_prediction`	Whether the model supports prediction for any input series.
`uses_future_covariates`	Whether the model uses future covariates, once fitted.
`uses_past_covariates`	Whether the model uses past covariates, once fitted.
`uses_static_covariates`	Whether the model uses static covariates, once fitted.

likelihood
model_params

Methods

`backtest`(series[, past_covariates, ...])	Compute error values that the model produced for historical forecasts on (potentially multiple) series.
`fit`(series[, past_covariates, future_covariates])	Fit/train the underlying forecasting model on (potentially multiple) series.
`generate_fit_encodings`(series[, ...])	Generates the covariate encodings that were used/generated for fitting the model and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together.
`generate_fit_predict_encodings`(n, series[, ...])	Generates covariate encodings for training and inference/prediction and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together.
`generate_predict_encodings`(n, series[, ...])	Generates covariate encodings for the inference/prediction set and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together.
`gridsearch`(parameters, series[, ...])	Find the best hyper-parameters among a given set using a grid search.
`historical_forecasts`(series[, ...])	Generates calibrated historical forecasts by simulating predictions at various points in time throughout the history of the provided (potentially multiple) series.
`load`(path)	Loads the model from a given path or file handle.
`predict`(n[, series, past_covariates, ...])	Forecasts calibrated quantile intervals (or samples from calibrated intervals) for n time steps after the end of the series.
`residuals`(series[, past_covariates, ...])	Compute the residuals that the model produced for historical forecasts on (potentially multiple) series.
`save`([path])	Saves the conformal model under a given path or file handle.

backtest(series, past_covariates=None, future_covariates=None, historical_forecasts=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=False, metric=<function mape>, reduction=<function mean>, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, metric_kwargs=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)[source]¶

Compute error values that the model produced for historical forecasts on (potentially multiple) series.

If historical_forecasts are provided, the metric(s) (given by the metric function) is evaluated directly on all forecasts and actual values. The same series and last_points_only value must be passed that were used to generate the historical forecasts. Finally, the method returns an optional reduction (the mean by default) of all these metric scores.

If historical_forecasts is None, it first generates the historical forecasts with the parameters given below (see ConformalModel.historical_forecasts() for more info) and then evaluates as described above.

The metric(s) can be further customized metric_kwargs (e.g. control the aggregation over components, time steps, multiple series, other required arguments such as q for quantile metrics, …).

Notes

Darts has several metrics to evaluate probabilistic forecasts. For conformal models, we recommend using quantile interval metrics (see here). You can specify which intervals to evaluate by setting metric_kwargs={‘q_interval’: my_intervals}. To check all intervals used by your conformal model my_model, you can set {'q_interval': my_model.q_interval}.

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – A (sequence of) target time series used to successively compute the historical forecasts. Will use the past of this series for calibration. The series should not have any overlap with the series used to train the forecasting model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) past-observed covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) future-known covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
historical_forecasts (Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]], None]) – Optionally, the (or a sequence of / a sequence of sequences of) historical forecasts time series to be evaluated. Corresponds to the output of historical_forecasts(). The same series and last_points_only values must be passed that were used to generate the historical forecasts. If provided, will skip historical forecasting and ignore all parameters except series, last_points_only, metric, and reduction.
forecast_horizon (int) – The forecast horizon for the predictions.
num_samples (int) – Number of times a prediction is sampled from the calibrated quantile predictions using linear interpolation in-between the quantiles. For larger values, the sample distribution approximates the calibrated quantile predictions.
train_length (Optional[int, None]) – Currently ignored by conformal models.
start (Union[Timestamp, int, None]) –
Optionally, the first point in time at which a prediction is computed. This parameter supports: int, pandas.Timestamp, and None. If an int, it is either the index position of the first prediction point for series with a pd.DatetimeIndex, or the index value for series with a pd.RangeIndex. The latter can be changed to the index position with start_format=”position”. If a pandas.Timestamp, it is the time stamp of the first prediction point. If None, the first prediction point will automatically be set to:
- the first predictable point if retrain is False, or retrain is a Callable and the first predictable point is earlier than the first trainable point.
- the first trainable point if retrain is True or int (given train_length), or retrain is a Callable and the first trainable point is earlier than the first predictable point.
- the first trainable point (given train_length) otherwise
Note: If the model uses a shifted output (output_chunk_shift > 0), then the first predicted point is also shifted by output_chunk_shift points into the future. Note: Raises a ValueError if start yields a time outside the time index of series. Note: If start is outside the possible historical forecasting times, will ignore the parameter (default behavior with None) and start at the first trainable/predictable point.
start_format (Literal[‘position’, ‘value’]) – Defines the start format. If set to 'position', start corresponds to the index position of the first predicted point and can range from (-len(series), len(series) - 1). If set to 'value', start corresponds to the index value/label of the first predicted point. Will raise an error if the value is not in series’ index. Default: 'value'.
stride (int) – The number of time steps between two consecutive predictions.
retrain (Union[bool, int, Callable[…, bool]]) – Currently ignored by conformal models.
overlap_end (bool) – Whether the returned forecasts can go beyond the series’ end or not.
last_points_only (bool) – Whether to return only the last point of each historical forecast. If set to True, the method returns a single TimeSeries (for each time series in series) containing the successive point forecasts. Otherwise, returns a list of historical TimeSeries forecasts.
metric (Union[Callable[…, Union[float, list[float], ndarray, list[ndarray]]], list[Callable[…, Union[float, list[float], ndarray, list[ndarray]]]]]) –
A metric function or a list of metric functions. Each metric must either be a Darts metric (see here), or a custom metric that has an identical signature as Darts’ metrics, uses decorators multi_ts_support() and multi_ts_support(), and returns the metric score.
reduction (Optional[Callable[…, float], None]) – A function used to combine the individual error scores obtained when last_points_only is set to False. When providing several metric functions, the function will receive the argument axis = 1 to obtain single value for each metric function. If explicitly set to None, the method will return a list of the individual error scores instead. Set to np.mean by default.
verbose (bool) – Whether to print the progress.
show_warnings (bool) – Whether to show warnings related to historical forecasts optimization, or parameters start and train_length.
predict_likelihood_parameters (bool) – If set to True, generates the quantile predictions directly. Only supported with num_samples = 1.
enable_optimization (bool) – Whether to use the optimized version of historical_forecasts when supported and available. Default: True.
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
Optionally, a dictionary of BaseDataTransformer or Pipeline to apply to the corresponding series (possibles keys; “series”, “past_covariates”, “future_covariates”). If provided, all input series must be in the un-transformed space. For fittable transformer / pipeline:
- if retrain=True, the data transformer re-fit on the training data at each historical forecast step (currently ignored by conformal models).
- if retrain=False, the data transformer transforms the series once before all the forecasts.
The fitted transformer is used to transform the input during both training and prediction. If the transformation is invertible, the forecasts will be inverse-transformed. Only effective when historical_forecasts=None.
metric_kwargs (Union[dict[str, Any], list[dict[str, Any]], None]) – Additional arguments passed to metric(), such as ‘n_jobs’ for parallelization, ‘component_reduction’ for reducing the component wise metrics, seasonality ‘m’ for scaled metrics, etc. Will pass arguments to each metric separately and only if they are present in the corresponding metric signature. Parameter ‘insample’ for scaled metrics (e.g. mase`, rmsse, …) is ignored, as it is handled internally.
fit_kwargs (Optional[dict[str, Any], None]) – Currently ignored by conformal models.
predict_kwargs (Optional[dict[str, Any], None]) – Optionally, some additional arguments passed to the model predict() method.
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – Currently ignored by conformal models.

Return type

Union[float, ndarray, list[float], list[ndarray]]

Returns

float – A single backtest score for single uni/multivariate series, a single metric function and:
- historical_forecasts generated with last_points_only=True
- historical_forecasts generated with last_points_only=False and using a backtest reduction
np.ndarray – An numpy array of backtest scores. For single series and one of:
- a single metric function, historical_forecasts generated with last_points_only=False and backtest reduction=None. The output has shape (n forecasts, *).
- multiple metric functions and historical_forecasts generated with last_points_only=False. The output has shape (*, n metrics) when using a backtest reduction, and (n forecasts, *, n metrics) when reduction=None
- multiple uni/multivariate series including series_reduction and at least one of component_reduction=None or time_reduction=None for “per time step metrics”
list[float] – Same as for type float but for a sequence of series. The returned metric list has length len(series) with the float metric for each input series.
list[np.ndarray] – Same as for type np.ndarray but for a sequence of series. The returned metric list has length len(series) with the np.ndarray metrics for each input series.

property considers_static_covariates: bool¶

Whether the model considers static covariates, if there are any.

Return type: bool

property extreme_lags: tuple[Optional[int], Optional[int], Optional[int], Optional[int], Optional[int], Optional[int], int, Optional[int]]¶

A 8-tuple containing in order: (min target lag, max target lag, min past covariate lag, max past covariate lag, min future covariate lag, max future covariate lag, output shift, max target lag train (only for RNNModel)). If 0 is the index of the first prediction, then all lags are relative to this index.

See examples below.

If the model wasn’t fitted with:

target (concerning RegressionModels only): then the first element should be None.
past covariates: then the third and fourth elements should be None.
future covariates: then the fifth and sixth elements should be None.

Should be overridden by models that use past or future covariates, and/or for model that have minimum target lag and maximum target lags potentially different from -1 and 0.

Notes

maximum target lag (second value) cannot be None and is always larger than or equal to 0.

Examples

>>> model = LinearRegressionModel(lags=3, output_chunk_length=2)
>>> model.fit(train_series)
>>> model.extreme_lags
(-3, 1, None, None, None, None, 0, None)
>>> model = LinearRegressionModel(lags=3, output_chunk_length=2, output_chunk_shift=2)
>>> model.fit(train_series)
>>> model.extreme_lags
(-3, 1, None, None, None, None, 2, None)
>>> model = LinearRegressionModel(lags=[-3, -5], lags_past_covariates = 4, output_chunk_length=7)
>>> model.fit(train_series, past_covariates=past_covariates)
>>> model.extreme_lags
(-5, 6, -4, -1,  None, None, 0, None)
>>> model = LinearRegressionModel(lags=[3, 5], lags_future_covariates = [4, 6], output_chunk_length=7)
>>> model.fit(train_series, future_covariates=future_covariates)
>>> model.extreme_lags
(-5, 6, None, None, 4, 6, 0, None)
>>> model = NBEATSModel(input_chunk_length=10, output_chunk_length=7)
>>> model.fit(train_series)
>>> model.extreme_lags
(-10, 6, None, None, None, None, 0, None)
>>> model = NBEATSModel(input_chunk_length=10, output_chunk_length=7, lags_future_covariates=[4, 6])
>>> model.fit(train_series, future_covariates)
>>> model.extreme_lags
(-10, 6, None, None, 4, 6, 0, None)

Return type: tuple[Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], int, Optional[int, None]]

fit(series, past_covariates=None, future_covariates=None, **kwargs)[source]¶

Fit/train the underlying forecasting model on (potentially multiple) series.

Optionally, one or multiple past and/or future covariates series can be provided as well, depending on the forecasting model used. The number of covariates series must match the number of target series.

Notes

Conformal Models do not require calling fit(), since they use pre-trained global forecasting models. You can call predict() directly. Also, make sure that the input series used in predict() corresponds to a calibration set, and not the same as used during training with fit().

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – One or several target time series. The model will be trained to forecast these time series. The series may or may not be multivariate, but if multiple series are provided they must have the same number of components.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – One or several past-observed covariate time series. These time series will not be forecast, but can be used by some models as an input. The covariate(s) may or may not be multivariate, but if multiple covariates are provided they must have the same number of components. If past_covariates is provided, it must contain the same number of series as series.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – One or several future-known covariate time series. These time series will not be forecast, but can be used by some models as an input. The covariate(s) may or may not be multivariate, but if multiple covariates are provided they must have the same number of components. If future_covariates is provided, it must contain the same number of series as series.
**kwargs – Optional keyword arguments that will passed to the underlying forecasting model’s fit() method.

Returns

Fitted model.

Return type

self

generate_fit_encodings(series, past_covariates=None, future_covariates=None)¶

Generates the covariate encodings that were used/generated for fitting the model and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together. The encodings are generated by the encoders defined at model creation with parameter add_encoders. Pass the same series, past_covariates, and future_covariates that you used to train/fit the model.

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – The series or sequence of series with the target values used when fitting the model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the series or sequence of series with the past-observed covariates used when fitting the model.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the series or sequence of series with the future-known covariates used when fitting the model.

Returns

A tuple of (past covariates, future covariates). Each covariate contains the original as well as the encoded covariates.

Return type

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶

Generates covariate encodings for training and inference/prediction and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together. The encodings are generated by the encoders defined at model creation with parameter add_encoders. Pass the same series, past_covariates, and future_covariates that you intend to use for training and prediction.

Parameters

n (int) – The number of prediction time steps after the end of series intended to be used for prediction.
series (Union[TimeSeries, Sequence[TimeSeries]]) – The series or sequence of series with target values intended to be used for training and prediction.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the past-observed covariates series intended to be used for training and prediction. The dimensions must match those of the covariates used for training.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the future-known covariates series intended to be used for prediction. The dimensions must match those of the covariates used for training.

Returns

A tuple of (past covariates, future covariates). Each covariate contains the original as well as the encoded covariates.

Return type

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶

Generates covariate encodings for the inference/prediction set and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together. The encodings are generated by the encoders defined at model creation with parameter add_encoders. Pass the same series, past_covariates, and future_covariates that you intend to use for prediction.

Parameters

n (int) – The number of prediction time steps after the end of series intended to be used for prediction.
series (Union[TimeSeries, Sequence[TimeSeries]]) – The series or sequence of series with target values intended to be used for prediction.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the past-observed covariates series intended to be used for prediction. The dimensions must match those of the covariates used for training.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the future-known covariates series intended to be used for prediction. The dimensions must match those of the covariates used for training.

Returns

A tuple of (past covariates, future covariates). Each covariate contains the original as well as the encoded covariates.

Return type

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

classmethod gridsearch(parameters, series, past_covariates=None, future_covariates=None, forecast_horizon=None, stride=1, start=None, start_format='value', last_points_only=False, show_warnings=True, val_series=None, use_fitted_values=False, metric=<function mape>, reduction=<function mean>, verbose=False, n_jobs=1, n_random_samples=None, data_transformers=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)¶

Find the best hyper-parameters among a given set using a grid search.

This function has 3 modes of operation: Expanding window mode, split mode and fitted value mode. The three modes of operation evaluate every possible combination of hyper-parameter values provided in the parameters dictionary by instantiating the model_class subclass of ForecastingModel with each combination, and returning the best-performing model with regard to the metric function. The metric function is expected to return an error value, thus the model resulting in the smallest metric output will be chosen.

The relationship of the training data and test data depends on the mode of operation.

Expanding window mode (activated when forecast_horizon is passed): For every hyperparameter combination, the model is repeatedly trained and evaluated on different splits of series. This process is accomplished by using the backtest() function as a subroutine to produce historic forecasts starting from start that are compared against the ground truth values of series. Note that the model is retrained for every single prediction, thus this mode is slower.

Split window mode (activated when val_series is passed): This mode will be used when the val_series argument is passed. For every hyper-parameter combination, the model is trained on series and evaluated on val_series.

Fitted value mode (activated when use_fitted_values is set to True): For every hyper-parameter combination, the model is trained on series and evaluated on the resulting fitted values. Not all models have fitted values, and this method raises an error if the model doesn’t have a fitted_values member. The fitted values are the result of the fit of the model on series. Comparing with the fitted values can be a quick way to assess the model, but one cannot see if the model is overfitting the series.

Derived classes must ensure that a single instance of a model will not share parameters with the other instances, e.g., saving models in the same path. Otherwise, an unexpected behavior can arise while running several models in parallel (when n_jobs != 1). If this cannot be avoided, then gridsearch should be redefined, forcing n_jobs = 1.

Currently this method only supports deterministic predictions (i.e. when models’ predictions have only 1 sample).

Parameters

model_class – The ForecastingModel subclass to be tuned for ‘series’.
parameters (dict) – A dictionary containing as keys hyperparameter names, and as values lists of values for the respective hyperparameter.
series (TimeSeries) – The target series used as input and target for training.
past_covariates (Optional[TimeSeries, None]) – Optionally, a past-observed covariate series. This applies only if the model supports past covariates.
future_covariates (Optional[TimeSeries, None]) – Optionally, a future-known covariate series. This applies only if the model supports future covariates.
forecast_horizon (Optional[int, None]) – The integer value of the forecasting horizon. Activates expanding window mode.
stride (int) – Only used in expanding window mode. The number of time steps between two consecutive predictions.
start (Union[Timestamp, float, int, None]) –
Only used in expanding window mode. Optionally, the first point in time at which a prediction is computed. This parameter supports: float, int, pandas.Timestamp, and None. If a float, it is the proportion of the time series that should lie before the first prediction point. If an int, it is either the index position of the first prediction point for series with a pd.DatetimeIndex, or the index value for series with a pd.RangeIndex. The latter can be changed to the index position with start_format=”position”. If a pandas.Timestamp, it is the time stamp of the first prediction point. If None, the first prediction point will automatically be set to:
- the first predictable point if retrain is False, or retrain is a Callable and the first predictable point is earlier than the first trainable point.
- the first trainable point if retrain is True or int (given train_length), or retrain is a Callable and the first trainable point is earlier than the first predictable point.
- the first trainable point (given train_length) otherwise
Note: If start is not within the trainable / forecastable points, uses the closest valid start point that
is a round multiple of stride ahead of start. Raises a ValueError, if no valid start point exists.

Note: If the model uses a shifted output (output_chunk_shift > 0), then the first predicted point is also
shifted by output_chunk_shift points into the future.

Note: If start is outside the possible historical forecasting times, will ignore the parameter
(default behavior with None) and start at the first trainable/predictable point.
start_format (Literal[‘position’, ‘value’]) – Only used in expanding window mode. Defines the start format. Only effective when start is an integer and series is indexed with a pd.RangeIndex. If set to ‘position’, start corresponds to the index position of the first predicted point and can range from (-len(series), len(series) - 1). If set to ‘value’, start corresponds to the index value/label of the first predicted point. Will raise an error if the value is not in series’ index. Default: 'value'
last_points_only (bool) – Only used in expanding window mode. Whether to use the whole forecasts or only the last point of each forecast to compute the error.
show_warnings (bool) – Only used in expanding window mode. Whether to show warnings related to the start parameter.
val_series (Optional[TimeSeries, None]) – The TimeSeries instance used for validation in split mode. If provided, this series must start right after the end of series; so that a proper comparison of the forecast can be made.
use_fitted_values (bool) – If True, uses the comparison with the fitted values. Raises an error if fitted_values is not an attribute of model_class.
metric (Callable[[TimeSeries, TimeSeries], float]) –
A metric function that returns the error between two TimeSeries as a float value . Must either be one of Darts’ “aggregated over time” metrics (see here), or a custom metric that as input two TimeSeries and returns the error
reduction (Callable[[ndarray], float]) – A reduction function (mapping array to float) describing how to aggregate the errors obtained on the different validation series when backtesting. By default it’ll compute the mean of errors.
verbose – Whether to print the progress.
n_jobs (int) – The number of jobs to run in parallel. Parallel jobs are created only when there are two or more parameters combinations to evaluate. Each job will instantiate, train, and evaluate a different instance of the model. Defaults to 1 (sequential). Setting the parameter to -1 means using all the available cores.
n_random_samples (Union[int, float, None]) – The number/ratio of hyperparameter combinations to select from the full parameter grid. This will perform a random search instead of using the full grid. If an integer, n_random_samples is the number of parameter combinations selected from the full grid and must be between 0 and the total number of parameter combinations. If a float, n_random_samples is the ratio of parameter combinations selected from the full grid and must be between 0 and 1. Defaults to None, for which random selection will be ignored.
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
Optionally, a dictionary of BaseDataTransformer or Pipeline to apply to the corresponding series (possibles keys; “series”, “past_covariates”, “future_covariates”). If provided, all input series must be in the un-transformed space. For fittable transformer / pipeline:
- if retrain=True, the data transformer re-fit on the training data at each historical forecast step.
- if retrain=False, the data transformer transforms the series once before all the forecasts.
The fitted transformer is used to transform the input during both training and prediction. If the transformation is invertible, the forecasts will be inverse-transformed.
fit_kwargs (Optional[dict[str, Any], None]) – Additional arguments passed to the model fit() method.
predict_kwargs (Optional[dict[str, Any], None]) – Additional arguments passed to the model predict() method.
sample_weight (Union[TimeSeries, str, None]) – Optionally, some sample weights to apply to the target series labels for training. Only effective when retrain is not False. They are applied per observation, per label (each step in output_chunk_length), and per component. If a series, then those weights are used. If the weight series only have a single component / column, then the weights are applied globally to all components in series. Otherwise, for component-specific weights, the number of components must match those of series. If a string, then the weights are generated using built-in weighting functions. The available options are “linear” or “exponential” decay - the further in the past, the lower the weight.

Returns

A tuple containing an untrained model_class instance created from the best-performing hyper-parameters, along with a dictionary containing these best hyper-parameters, and metric score for the best hyper-parameters.

Return type

ForecastingModel, Dict, float

historical_forecasts(series, past_covariates=None, future_covariates=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=True, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)[source]¶

Generates calibrated historical forecasts by simulating predictions at various points in time throughout the history of the provided (potentially multiple) series. This process involves retrospectively applying the model to different time steps, as if the forecasts were made in real-time at those specific moments. This allows for an evaluation of the model’s performance over the entire duration of the series, providing insights into its predictive accuracy and robustness across different historical periods.

Currently, conformal models only support the pre-trained historical forecasts mode (retrain=False). Parameters retrain and train_length are ignored.

Pre-trained Mode: First, all historical forecasts are generated using the underlying pre-trained global forecasting model (see ForecastingModel.historical_forecasts() for more info). Then it repeatedly builds a calibration set by either expanding from the beginning of the historical forecasts or by using a fixed-length moving window with length cal_length (the start point can also be configured with start and start_format). The next forecast of length forecast_horizon is then calibrated on this calibration set. Subsequently, the end of the calibration set is moved forward by stride time steps, and the process is repeated.

By default, with last_points_only=True, this method returns a single time series (or a sequence of time series when series is also a sequence of series) composed of the last point from each calibrated historical forecast. This time series will thus have a frequency of series.freq * stride. If last_points_only=False, it will instead return a list (or a sequence of lists) with all calibrated historical forecasts of length forecast_horizon and frequency series.freq.

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – A (sequence of) target time series used to successively compute the historical forecasts. Will use the past of this series for calibration. The series should not have any overlap with the series used to train the forecasting model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) past-observed covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) future-known covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
forecast_horizon (int) – The forecast horizon for the predictions.
num_samples (int) – Number of times a prediction is sampled from the calibrated quantile predictions using linear interpolation in-between the quantiles. For larger values, the sample distribution approximates the calibrated quantile predictions.
train_length (Optional[int, None]) – Currently ignored by conformal models.
start (Union[Timestamp, int, None]) –
Optionally, the first point in time at which a prediction is computed. This parameter supports: int, pandas.Timestamp, and None. If an int, it is either the index position of the first prediction point for series with a pd.DatetimeIndex, or the index value for series with a pd.RangeIndex. The latter can be changed to the index position with start_format=”position”. If a pandas.Timestamp, it is the time stamp of the first prediction point. If None, the first prediction point will automatically be set to:
- the first predictable point if retrain is False, or retrain is a Callable and the first predictable point is earlier than the first trainable point.
- the first trainable point if retrain is True or int (given train_length), or retrain is a Callable and the first trainable point is earlier than the first predictable point.
- the first trainable point (given train_length) otherwise
Note: If the model uses a shifted output (output_chunk_shift > 0), then the first predicted point is also shifted by output_chunk_shift points into the future. Note: Raises a ValueError if start yields a time outside the time index of series. Note: If start is outside the possible historical forecasting times, will ignore the parameter (default behavior with None) and start at the first trainable/predictable point.
start_format (Literal[‘position’, ‘value’]) – Defines the start format. If set to 'position', start corresponds to the index position of the first predicted point and can range from (-len(series), len(series) - 1). If set to 'value', start corresponds to the index value/label of the first predicted point. Will raise an error if the value is not in series’ index. Default: 'value'.
stride (int) – The number of time steps between two consecutive predictions. Must be a round-multiple of cal_stride (set at model creation) and >=cal_stride.
retrain (Union[bool, int, Callable[…, bool]]) – Currently ignored by conformal models.
overlap_end (bool) – Whether the returned forecasts can go beyond the series’ end or not.
last_points_only (bool) – Whether to return only the last point of each historical forecast. If set to True, the method returns a single TimeSeries (for each time series in series) containing the successive point forecasts. Otherwise, returns a list of historical TimeSeries forecasts.
verbose (bool) – Whether to print the progress.
show_warnings (bool) – Whether to show warnings related to historical forecasts optimization, or parameters start and train_length.
predict_likelihood_parameters (bool) – If set to True, generates the quantile predictions directly. Only supported with num_samples = 1.
enable_optimization (bool) – Whether to use the optimized version of historical_forecasts when supported and available. Default: True.
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
Optionally, a dictionary of BaseDataTransformer or Pipeline to apply to the corresponding series (possibles keys; “series”, “past_covariates”, “future_covariates”). If provided, all input series must be in the un-transformed space. For fittable transformer / pipeline:
- if retrain=True, the data transformer re-fit on the training data at each historical forecast step (currently ignored by conformal models).
- if retrain=False, the data transformer transforms the series once before all the forecasts.
The fitted transformer is used to transform the input during both training and prediction. If the transformation is invertible, the forecasts will be inverse-transformed.
fit_kwargs (Optional[dict[str, Any], None]) – Currently ignored by conformal models.
predict_kwargs (Optional[dict[str, Any], None]) – Optionally, some additional arguments passed to the model predict() method.
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – Currently ignored by conformal models.

Return type

Union[TimeSeries, list[TimeSeries], list[list[TimeSeries]]]

Returns

TimeSeries – A single historical forecast for a single series and last_points_only=True: it contains only the predictions at step forecast_horizon from all historical forecasts.
list[TimeSeries] – A list of historical forecasts for:
- a sequence (list) of series and last_points_only=True: for each series, it contains only the predictions at step forecast_horizon from all historical forecasts.
- a single series and last_points_only=False: for each historical forecast, it contains the entire horizon forecast_horizon.
list[list[TimeSeries]] – A list of lists of historical forecasts for a sequence of series and last_points_only=False. For each series, and historical forecast, it contains the entire horizon forecast_horizon. The outer list is over the series provided in the input sequence, and the inner lists contain the historical forecasts for each series.

property likelihood: str¶

Return type: str

static load(path)[source]¶

Loads the model from a given path or file handle.

Parameters: path (Union[str, PathLike, BinaryIO]) – Path or file handle from which to load the model.
Return type: ConformalModel

property min_train_samples: int¶

The minimum number of samples for training the model.

Return type: int

property model_params: dict¶

Return type: dict

property output_chunk_length: Optional[int]¶

Number of time steps predicted at once by the model, not defined for statistical models.

Return type: Optional[int, None]

property output_chunk_shift: int¶

Number of time steps that the output/prediction starts after the end of the input.

Return type: int

predict(n, series=None, past_covariates=None, future_covariates=None, num_samples=1, verbose=False, predict_likelihood_parameters=False, show_warnings=True, **kwargs)[source]¶

Forecasts calibrated quantile intervals (or samples from calibrated intervals) for n time steps after the end of the series.

It is important that the input series for prediction correspond to a calibration set - a set different to the series that the underlying forecasting model was trained on.

Since it is a probabilistic model, you can generate forecasts in two ways:

Predict the calibrated quantile intervals directly: Pass parameters predict_likelihood_parameters=True, and num_samples=1 to the forecast method.
Predict stochastic samples from the calibrated quantile intervals: Pass parameters predict_likelihood_parameters=False, and num_samples>>1 to the forecast method.

Under the hood, the simplified workflow to produce one calibrated forecast/prediction for every step in the horizon n is as follows (note: cal_length and cal_stride can be set at model creation):

Extract a calibration set: The calibration set for each conformal forecast is automatically extracted from the most recent past of your input series relative to the forecast start point. The number of calibration examples (forecast errors / non-conformity scores) to consider can be defined at model creation with parameter cal_length. Note that when using cal_stride>1, a longer history is required since the calibration examples are generated with stridden historical forecasts.
Generate historical forecasts on the calibration set (using the forecasting model) with a stride cal_stride.
Compute the errors/non-conformity scores (specific to each conformal model) on these historical forecasts
Compute the quantile values from the errors / non-conformity scores (using our desired quantiles set at model creation with parameter quantiles).
Compute the conformal prediction: Using these quantile values, add calibrated intervals to (or adjust the existing intervals of) the forecasting model’s predictions.

Parameters

n (int) – Forecast horizon - the number of time steps after the end of the series for which to produce predictions.
series (Union[TimeSeries, Sequence[TimeSeries], None]) – A series or sequence of series, representing the history of the target series whose future is to be predicted. Will use the past of this series for calibration. The series should not have any overlap with the series used to train the forecasting model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) past-observed covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) future-known covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
num_samples (int) – Number of times a prediction is sampled from the calibrated quantile predictions using linear interpolation in-between the quantiles. For larger values, the sample distribution approximates the calibrated quantile predictions.
verbose (bool) – Whether to print the progress.
predict_likelihood_parameters (bool) – If set to True, generates the quantile predictions directly. Only supported with num_samples = 1.
show_warnings (bool) – Whether to show warnings related auto-regression and past covariates usage.
**kwargs – Optional keyword arguments that will passed to the underlying forecasting model’s predict() and historical_forecasts() methods.

Returns

If series is not specified, this function returns a single time series containing the n next points after then end of the training series. If series is given and is a simple TimeSeries, this function returns the n next points after the end of series. If series is given and is a sequence of several time series, this function returns a sequence where each element contains the corresponding n points forecasts.

Return type

Union[TimeSeries, Sequence[TimeSeries]]

residuals(series, past_covariates=None, future_covariates=None, historical_forecasts=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=True, metric=<function err>, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, metric_kwargs=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None, values_only=False)[source]¶

Compute the residuals that the model produced for historical forecasts on (potentially multiple) series.

This function computes the difference (or one of Darts’ “per time step” metrics) between the actual observations from series and the fitted values obtained by training the model on series (or using a pre-trained model with retrain=False). Not all models support fitted values, so we use historical forecasts as an approximation for them.

In sequence this method performs:

use pre-computed historical_forecasts or compute historical forecasts for each series (see historical_forecasts() for more details). How the historical forecasts are generated can be configured with parameters num_samples, train_length, start, start_format, forecast_horizon, stride, retrain, last_points_only, fit_kwargs, and predict_kwargs.
compute a backtest using a “per time step” metric between the historical forecasts and series per component/column and time step (see backtest() for more details). By default, uses the residuals err() (error) as a metric.
create and return TimeSeries (or simply a np.ndarray with values_only=True) with the time index from historical forecasts, and values from the metrics per component and time step.

This method works for single or multiple univariate or multivariate series. It uses the median prediction (when dealing with stochastic forecasts).

Notes

Darts has several metrics to evaluate probabilistic forecasts. For conformal models, we recommend using “per time step” quantile interval metrics (see here). You can specify which intervals to evaluate by setting metric_kwargs={‘q_interval’: my_intervals}. To check all intervals used by your conformal model my_model, you can set {'q_interval': my_model.q_interval}.

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – A (sequence of) target time series used to successively compute the historical forecasts. Will use the past of this series for calibration. The series should not have any overlap with the series used to train the forecasting model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) past-observed covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) future-known covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
historical_forecasts (Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]], None]) – Optionally, the (or a sequence of / a sequence of sequences of) historical forecasts time series to be evaluated. Corresponds to the output of historical_forecasts(). The same series and last_points_only values must be passed that were used to generate the historical forecasts. If provided, will skip historical forecasting and ignore all parameters except series, last_points_only, metric, and reduction.
forecast_horizon (int) – The forecast horizon for the predictions.
num_samples (int) – Number of times a prediction is sampled from the calibrated quantile predictions using linear interpolation in-between the quantiles. For larger values, the sample distribution approximates the calibrated quantile predictions.
train_length (Optional[int, None]) – Currently ignored by conformal models.
start (Union[Timestamp, int, None]) –
Optionally, the first point in time at which a prediction is computed. This parameter supports: int, pandas.Timestamp, and None. If an int, it is either the index position of the first prediction point for series with a pd.DatetimeIndex, or the index value for series with a pd.RangeIndex. The latter can be changed to the index position with start_format=”position”. If a pandas.Timestamp, it is the time stamp of the first prediction point. If None, the first prediction point will automatically be set to:
- the first predictable point if retrain is False, or retrain is a Callable and the first predictable point is earlier than the first trainable point.
- the first trainable point if retrain is True or int (given train_length), or retrain is a Callable and the first trainable point is earlier than the first predictable point.
- the first trainable point (given train_length) otherwise
Note: If the model uses a shifted output (output_chunk_shift > 0), then the first predicted point is also shifted by output_chunk_shift points into the future. Note: Raises a ValueError if start yields a time outside the time index of series. Note: If start is outside the possible historical forecasting times, will ignore the parameter (default behavior with None) and start at the first trainable/predictable point.
start_format (Literal[‘position’, ‘value’]) – Defines the start format. If set to 'position', start corresponds to the index position of the first predicted point and can range from (-len(series), len(series) - 1). If set to 'value', start corresponds to the index value/label of the first predicted point. Will raise an error if the value is not in series’ index. Default: 'value'.
stride (int) – The number of time steps between two consecutive predictions.
retrain (Union[bool, int, Callable[…, bool]]) – Currently ignored by conformal models.
overlap_end (bool) – Whether the returned forecasts can go beyond the series’ end or not.
last_points_only (bool) – Whether to return only the last point of each historical forecast. If set to True, the method returns a single TimeSeries (for each time series in series) containing the successive point forecasts. Otherwise, returns a list of historical TimeSeries forecasts.
metric (Callable[…, Union[float, list[float], ndarray, list[ndarray]]]) –
Either one of Darts’ “per time step” metrics (see here), or a custom metric that has an identical signature as Darts’ “per time step” metrics, uses decorators multi_ts_support() and multi_ts_support(), and returns one value per time step.
verbose (bool) – Whether to print the progress.
show_warnings (bool) – Whether to show warnings related to historical forecasts optimization, or parameters start and train_length.
predict_likelihood_parameters (bool) – If set to True, generates the quantile predictions directly. Only supported with num_samples = 1.
enable_optimization (bool) – Whether to use the optimized version of historical_forecasts when supported and available. Default: True.
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
Optionally, a dictionary of BaseDataTransformer or Pipeline to apply to the corresponding series (possibles keys; “series”, “past_covariates”, “future_covariates”). If provided, all input series must be in the un-transformed space. For fittable transformer / pipeline:
- if retrain=True, the data transformer re-fit on the training data at each historical forecast step (currently ignored by conformal models).
- if retrain=False, the data transformer transforms the series once before all the forecasts.
The fitted transformer is used to transform the input during both training and prediction. If the transformation is invertible, the forecasts will be inverse-transformed. Only effective when historical_forecasts=None.
metric_kwargs (Optional[dict[str, Any], None]) – Additional arguments passed to metric(), such as ‘n_jobs’ for parallelization, ‘m’ for scaled metrics, etc. Will pass arguments only if they are present in the corresponding metric signature. Ignores reduction arguments “series_reduction”, “component_reduction”, “time_reduction”, and parameter ‘insample’ for scaled metrics (e.g. mase`, rmsse, …), as they are handled internally.
fit_kwargs (Optional[dict[str, Any], None]) – Currently ignored by conformal models.
predict_kwargs (Optional[dict[str, Any], None]) – Optionally, some additional arguments passed to the model predict() method.
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – Currently ignored by conformal models.
values_only (bool) – Whether to return the residuals as np.ndarray. If False, returns residuals as TimeSeries.

Return type

Union[TimeSeries, list[TimeSeries], list[list[TimeSeries]]]

Returns

TimeSeries – Residual TimeSeries for a single series and historical_forecasts generated with last_points_only=True.
list[TimeSeries] – A list of residual TimeSeries for a sequence (list) of series with last_points_only=True. The residual list has length len(series).
list[list[TimeSeries]] – A list of lists of residual TimeSeries for a sequence of series with last_points_only=False. The outer residual list has length len(series). The inner lists consist of the residuals from all possible series-specific historical forecasts.

save(path=None, **pkl_kwargs)[source]¶

Saves the conformal model under a given path or file handle.

Additionally, two files are stored if self.model is a TorchForecastingModel.

Example for saving and loading a ConformalNaiveModel:

from darts.datasets import AirPassengersDataset
from darts.models import ConformalNaiveModel, LinearRegressionModel

series = AirPassengersDataset().load()
forecasting_model = LinearRegressionModel(lags=4).fit(series)

model = ConformalNaiveModel(
    model=forecasting_model,
    quantiles=[0.1, 0.5, 0.9],
)

model.save("my_model.pkl")
model_loaded = ConformalNaiveModel.load("my_model.pkl")

Parameters

path (Union[str, PathLike, BinaryIO, None]) – Path or file handle under which to save the ensemble model at its current state. If no path is specified, the ensemble model is automatically saved under "{ConformalNaiveModel}_{YYYY-mm-dd_HH_MM_SS}.pkl". If the forecasting model is a TorchForecastingModel, two files (model object and checkpoint) are saved under "{path}.{ModelClass}.pt" and "{path}.{ModelClass}.ckpt".
pkl_kwargs – Keyword arguments passed to pickle.dump()

Return type

None

property supports_future_covariates: bool¶

Whether model supports future covariates

Return type: bool

property supports_likelihood_parameter_prediction: bool¶

Whether model instance supports direct prediction of likelihood parameters

Return type: bool

property supports_multivariate: bool¶

Whether the model considers more than one variate in the time series.

Return type: bool

property supports_optimized_historical_forecasts: bool¶

Whether the model supports optimized historical forecasts

Return type: bool

property supports_past_covariates: bool¶

Whether model supports past covariates

Return type: bool

property supports_probabilistic_prediction: bool¶

Checks if the forecasting model with this configuration supports probabilistic predictions.

By default, returns False. Needs to be overwritten by models that do support probabilistic predictions.

Return type: bool

property supports_sample_weight: bool¶

Whether model supports sample weight for training.

Return type: bool

property supports_static_covariates: bool¶

Whether model supports static covariates

Return type: bool

property supports_transferrable_series_prediction: bool¶

Whether the model supports prediction for any input series.

Return type: bool

property uses_future_covariates: bool¶

Whether the model uses future covariates, once fitted.

Return type: bool

property uses_past_covariates: bool¶

Whether the model uses past covariates, once fitted.

Return type: bool

property uses_static_covariates: bool¶

Whether the model uses static covariates, once fitted.

Return type: bool

class darts.models.forecasting.conformal_models.ConformalNaiveModel(model, quantiles, symmetric=True, cal_length=None, cal_stride=1, cal_num_samples=500, random_state=None)[source]¶

Bases: ConformalModel

Naive Conformal Prediction Model.

A probabilistic model that adds calibrated intervals around the median forecast from a pre-trained global forecasting model. It does not have to be trained and can generated calibrated forecasts directly using the underlying trained forecasting model. It supports two symmetry modes:

symmetric=True:
- The lower and upper interval bounds are calibrated with the same magnitude.
- Non-conformity scores: uses metric ae() (see absolute error ae()) to compute the non-conformity scores on the calibration set.
symmetric=False
- The lower and upper interval bounds are calibrated separately.
- Non-conformity scores: uses metric err() (see error err()) to compute the non-conformity scores on the calibration set for the upper bounds, an -err() for the lower bounds.

Since it is a probabilistic model, you can generate forecasts in two ways (when calling predict(), historical_forecasts(), …):

Predict the calibrated quantile intervals directly: Pass parameters predict_likelihood_parameters=True, and num_samples=1 to the forecast method.
Predict stochastic samples from the calibrated quantile intervals: Pass parameters predict_likelihood_parameters=False, and num_samples>>1 to the forecast method.

Extract a calibration set: The calibration set for each conformal forecast is automatically extracted from the most recent past of your input series relative to the forecast start point. The number of calibration examples (forecast errors / non-conformity scores) to consider can be defined at model creation with parameter cal_length. Note that when using cal_stride>1, a longer history is required since the calibration examples are generated with stridden historical forecasts.
Generate historical forecasts on the calibration set (using the forecasting model) with a stride cal_stride.
Compute the errors/non-conformity scores (as defined above) on these historical forecasts
Compute the quantile values from the errors / non-conformity scores (using our desired quantiles set at model creation with parameter quantiles).
Compute the conformal prediction: Using these quantile values, add calibrated intervals to the forecasting model’s predictions.

Some notes:

When computing historical_forecasts(), backtest(), residuals(), … the above is applied for each forecast (the forecasting model’s historical forecasts are only generated once for efficiency).
For multi-horizon forecasts, the above is applied for each step in the horizon separately.

Parameters

model (GlobalForecastingModel) –
A pre-trained global forecasting model. See the list of models here.
quantiles (list[float]) – A list of quantiles centered around the median q=0.5 to use. For example quantiles [0.1, 0.2, 0.5, 0.8 0.9] correspond to two intervals with (0.9 - 0.1) = 80%, and (0.8 - 0.2) 60% coverage around the median (model forecast).
symmetric (bool) – Whether to use symmetric non-conformity scores. If True, uses metric ae() (see ae()) to compute the non-conformity scores. If False, uses metric -err() (see err()) for the lower, and err() for the upper quantile interval bound.
cal_length (Optional[int, None]) – The number of past forecast errors / non-conformity scores to use as calibration for each conformal forecast (and each step in the horizon). If None, considers all scores.
cal_stride (int) – The stride to apply when computing the historical forecasts and non-conformity scores on the calibration set. The actual conformal forecasts can have a different stride given with parameter stride in downstream tasks (e.g. historical forecasts, backtest, …)
cal_num_samples (int) – The number of samples to generate for each calibration forecast (if model is a probabilistic forecasting model). The non-conformity scores are computed on the quantile values of these forecasts (using quantiles quantiles). Uses 1 for deterministic models. The actual conformal forecasts can have a different number of samples given with parameter num_samples in downstream tasks (e.g. predict, historical forecasts, …).
random_state (Optional[int, None]) – Control the randomness of probabilistic conformal forecasts (sample generation) across different runs.

Attributes

`considers_static_covariates`	Whether the model considers static covariates, if there are any.
`extreme_lags`	A 8-tuple containing in order: (min target lag, max target lag, min past covariate lag, max past covariate lag, min future covariate lag, max future covariate lag, output shift, max target lag train (only for RNNModel)).
`min_train_samples`	The minimum number of samples for training the model.
`output_chunk_length`	Number of time steps predicted at once by the model, not defined for statistical models.
`output_chunk_shift`	Number of time steps that the output/prediction starts after the end of the input.
`supports_future_covariates`	Whether model supports future covariates
`supports_likelihood_parameter_prediction`	Whether model instance supports direct prediction of likelihood parameters
`supports_multivariate`	Whether the model considers more than one variate in the time series.
`supports_optimized_historical_forecasts`	Whether the model supports optimized historical forecasts
`supports_past_covariates`	Whether model supports past covariates
`supports_probabilistic_prediction`	Checks if the forecasting model with this configuration supports probabilistic predictions.
`supports_sample_weight`	Whether model supports sample weight for training.
`supports_static_covariates`	Whether model supports static covariates
`supports_transferrable_series_prediction`	Whether the model supports prediction for any input series.
`uses_future_covariates`	Whether the model uses future covariates, once fitted.
`uses_past_covariates`	Whether the model uses past covariates, once fitted.
`uses_static_covariates`	Whether the model uses static covariates, once fitted.

likelihood
model_params

Methods

`backtest`(series[, past_covariates, ...])	Compute error values that the model produced for historical forecasts on (potentially multiple) series.
`fit`(series[, past_covariates, future_covariates])	Fit/train the underlying forecasting model on (potentially multiple) series.
`generate_fit_encodings`(series[, ...])	Generates the covariate encodings that were used/generated for fitting the model and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together.
`generate_fit_predict_encodings`(n, series[, ...])	Generates covariate encodings for training and inference/prediction and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together.
`generate_predict_encodings`(n, series[, ...])	Generates covariate encodings for the inference/prediction set and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together.
`gridsearch`(parameters, series[, ...])	Find the best hyper-parameters among a given set using a grid search.
`historical_forecasts`(series[, ...])	Generates calibrated historical forecasts by simulating predictions at various points in time throughout the history of the provided (potentially multiple) series.
`load`(path)	Loads the model from a given path or file handle.
`predict`(n[, series, past_covariates, ...])	Forecasts calibrated quantile intervals (or samples from calibrated intervals) for n time steps after the end of the series.
`residuals`(series[, past_covariates, ...])	Compute the residuals that the model produced for historical forecasts on (potentially multiple) series.
`save`([path])	Saves the conformal model under a given path or file handle.

Compute error values that the model produced for historical forecasts on (potentially multiple) series.

The metric(s) can be further customized metric_kwargs (e.g. control the aggregation over components, time steps, multiple series, other required arguments such as q for quantile metrics, …).

Notes

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – A (sequence of) target time series used to successively compute the historical forecasts. Will use the past of this series for calibration. The series should not have any overlap with the series used to train the forecasting model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) past-observed covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) future-known covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
historical_forecasts (Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]], None]) – Optionally, the (or a sequence of / a sequence of sequences of) historical forecasts time series to be evaluated. Corresponds to the output of historical_forecasts(). The same series and last_points_only values must be passed that were used to generate the historical forecasts. If provided, will skip historical forecasting and ignore all parameters except series, last_points_only, metric, and reduction.
forecast_horizon (int) – The forecast horizon for the predictions.
num_samples (int) – Number of times a prediction is sampled from the calibrated quantile predictions using linear interpolation in-between the quantiles. For larger values, the sample distribution approximates the calibrated quantile predictions.
train_length (Optional[int, None]) – Currently ignored by conformal models.
start (Union[Timestamp, int, None]) –
Optionally, the first point in time at which a prediction is computed. This parameter supports: int, pandas.Timestamp, and None. If an int, it is either the index position of the first prediction point for series with a pd.DatetimeIndex, or the index value for series with a pd.RangeIndex. The latter can be changed to the index position with start_format=”position”. If a pandas.Timestamp, it is the time stamp of the first prediction point. If None, the first prediction point will automatically be set to:
- the first predictable point if retrain is False, or retrain is a Callable and the first predictable point is earlier than the first trainable point.
- the first trainable point if retrain is True or int (given train_length), or retrain is a Callable and the first trainable point is earlier than the first predictable point.
- the first trainable point (given train_length) otherwise
Note: If the model uses a shifted output (output_chunk_shift > 0), then the first predicted point is also shifted by output_chunk_shift points into the future. Note: Raises a ValueError if start yields a time outside the time index of series. Note: If start is outside the possible historical forecasting times, will ignore the parameter (default behavior with None) and start at the first trainable/predictable point.
start_format (Literal[‘position’, ‘value’]) – Defines the start format. If set to 'position', start corresponds to the index position of the first predicted point and can range from (-len(series), len(series) - 1). If set to 'value', start corresponds to the index value/label of the first predicted point. Will raise an error if the value is not in series’ index. Default: 'value'.
stride (int) – The number of time steps between two consecutive predictions.
retrain (Union[bool, int, Callable[…, bool]]) – Currently ignored by conformal models.
overlap_end (bool) – Whether the returned forecasts can go beyond the series’ end or not.
last_points_only (bool) – Whether to return only the last point of each historical forecast. If set to True, the method returns a single TimeSeries (for each time series in series) containing the successive point forecasts. Otherwise, returns a list of historical TimeSeries forecasts.
metric (Union[Callable[…, Union[float, list[float], ndarray, list[ndarray]]], list[Callable[…, Union[float, list[float], ndarray, list[ndarray]]]]]) –
A metric function or a list of metric functions. Each metric must either be a Darts metric (see here), or a custom metric that has an identical signature as Darts’ metrics, uses decorators multi_ts_support() and multi_ts_support(), and returns the metric score.
reduction (Optional[Callable[…, float], None]) – A function used to combine the individual error scores obtained when last_points_only is set to False. When providing several metric functions, the function will receive the argument axis = 1 to obtain single value for each metric function. If explicitly set to None, the method will return a list of the individual error scores instead. Set to np.mean by default.
verbose (bool) – Whether to print the progress.
show_warnings (bool) – Whether to show warnings related to historical forecasts optimization, or parameters start and train_length.
predict_likelihood_parameters (bool) – If set to True, generates the quantile predictions directly. Only supported with num_samples = 1.
enable_optimization (bool) – Whether to use the optimized version of historical_forecasts when supported and available. Default: True.
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
Optionally, a dictionary of BaseDataTransformer or Pipeline to apply to the corresponding series (possibles keys; “series”, “past_covariates”, “future_covariates”). If provided, all input series must be in the un-transformed space. For fittable transformer / pipeline:
- if retrain=True, the data transformer re-fit on the training data at each historical forecast step (currently ignored by conformal models).
- if retrain=False, the data transformer transforms the series once before all the forecasts.
The fitted transformer is used to transform the input during both training and prediction. If the transformation is invertible, the forecasts will be inverse-transformed. Only effective when historical_forecasts=None.
metric_kwargs (Union[dict[str, Any], list[dict[str, Any]], None]) – Additional arguments passed to metric(), such as ‘n_jobs’ for parallelization, ‘component_reduction’ for reducing the component wise metrics, seasonality ‘m’ for scaled metrics, etc. Will pass arguments to each metric separately and only if they are present in the corresponding metric signature. Parameter ‘insample’ for scaled metrics (e.g. mase`, rmsse, …) is ignored, as it is handled internally.
fit_kwargs (Optional[dict[str, Any], None]) – Currently ignored by conformal models.
predict_kwargs (Optional[dict[str, Any], None]) – Optionally, some additional arguments passed to the model predict() method.
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – Currently ignored by conformal models.

Return type

Union[float, ndarray, list[float], list[ndarray]]

Returns

float – A single backtest score for single uni/multivariate series, a single metric function and:
- historical_forecasts generated with last_points_only=True
- historical_forecasts generated with last_points_only=False and using a backtest reduction
np.ndarray – An numpy array of backtest scores. For single series and one of:
- a single metric function, historical_forecasts generated with last_points_only=False and backtest reduction=None. The output has shape (n forecasts, *).
- multiple metric functions and historical_forecasts generated with last_points_only=False. The output has shape (*, n metrics) when using a backtest reduction, and (n forecasts, *, n metrics) when reduction=None
- multiple uni/multivariate series including series_reduction and at least one of component_reduction=None or time_reduction=None for “per time step metrics”
list[float] – Same as for type float but for a sequence of series. The returned metric list has length len(series) with the float metric for each input series.
list[np.ndarray] – Same as for type np.ndarray but for a sequence of series. The returned metric list has length len(series) with the np.ndarray metrics for each input series.

property considers_static_covariates: bool¶

Whether the model considers static covariates, if there are any.

Return type: bool

property extreme_lags: tuple[Optional[int], Optional[int], Optional[int], Optional[int], Optional[int], Optional[int], int, Optional[int]]¶

See examples below.

If the model wasn’t fitted with:

target (concerning RegressionModels only): then the first element should be None.
past covariates: then the third and fourth elements should be None.
future covariates: then the fifth and sixth elements should be None.

Should be overridden by models that use past or future covariates, and/or for model that have minimum target lag and maximum target lags potentially different from -1 and 0.

Notes

maximum target lag (second value) cannot be None and is always larger than or equal to 0.

Examples

>>> model = LinearRegressionModel(lags=3, output_chunk_length=2)
>>> model.fit(train_series)
>>> model.extreme_lags
(-3, 1, None, None, None, None, 0, None)
>>> model = LinearRegressionModel(lags=3, output_chunk_length=2, output_chunk_shift=2)
>>> model.fit(train_series)
>>> model.extreme_lags
(-3, 1, None, None, None, None, 2, None)
>>> model = LinearRegressionModel(lags=[-3, -5], lags_past_covariates = 4, output_chunk_length=7)
>>> model.fit(train_series, past_covariates=past_covariates)
>>> model.extreme_lags
(-5, 6, -4, -1,  None, None, 0, None)
>>> model = LinearRegressionModel(lags=[3, 5], lags_future_covariates = [4, 6], output_chunk_length=7)
>>> model.fit(train_series, future_covariates=future_covariates)
>>> model.extreme_lags
(-5, 6, None, None, 4, 6, 0, None)
>>> model = NBEATSModel(input_chunk_length=10, output_chunk_length=7)
>>> model.fit(train_series)
>>> model.extreme_lags
(-10, 6, None, None, None, None, 0, None)
>>> model = NBEATSModel(input_chunk_length=10, output_chunk_length=7, lags_future_covariates=[4, 6])
>>> model.fit(train_series, future_covariates)
>>> model.extreme_lags
(-10, 6, None, None, 4, 6, 0, None)

Return type: tuple[Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], int, Optional[int, None]]

fit(series, past_covariates=None, future_covariates=None, **kwargs)¶

Fit/train the underlying forecasting model on (potentially multiple) series.

Notes

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – One or several target time series. The model will be trained to forecast these time series. The series may or may not be multivariate, but if multiple series are provided they must have the same number of components.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – One or several past-observed covariate time series. These time series will not be forecast, but can be used by some models as an input. The covariate(s) may or may not be multivariate, but if multiple covariates are provided they must have the same number of components. If past_covariates is provided, it must contain the same number of series as series.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – One or several future-known covariate time series. These time series will not be forecast, but can be used by some models as an input. The covariate(s) may or may not be multivariate, but if multiple covariates are provided they must have the same number of components. If future_covariates is provided, it must contain the same number of series as series.
**kwargs – Optional keyword arguments that will passed to the underlying forecasting model’s fit() method.

Returns

Fitted model.

Return type

self

generate_fit_encodings(series, past_covariates=None, future_covariates=None)¶

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – The series or sequence of series with the target values used when fitting the model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the series or sequence of series with the past-observed covariates used when fitting the model.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the series or sequence of series with the future-known covariates used when fitting the model.

Returns

A tuple of (past covariates, future covariates). Each covariate contains the original as well as the encoded covariates.

Return type

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶

Parameters

n (int) – The number of prediction time steps after the end of series intended to be used for prediction.
series (Union[TimeSeries, Sequence[TimeSeries]]) – The series or sequence of series with target values intended to be used for training and prediction.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the past-observed covariates series intended to be used for training and prediction. The dimensions must match those of the covariates used for training.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the future-known covariates series intended to be used for prediction. The dimensions must match those of the covariates used for training.

Returns

A tuple of (past covariates, future covariates). Each covariate contains the original as well as the encoded covariates.

Return type

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶

Parameters

n (int) – The number of prediction time steps after the end of series intended to be used for prediction.
series (Union[TimeSeries, Sequence[TimeSeries]]) – The series or sequence of series with target values intended to be used for prediction.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the past-observed covariates series intended to be used for prediction. The dimensions must match those of the covariates used for training.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the future-known covariates series intended to be used for prediction. The dimensions must match those of the covariates used for training.

Returns

A tuple of (past covariates, future covariates). Each covariate contains the original as well as the encoded covariates.

Return type

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

Find the best hyper-parameters among a given set using a grid search.

The relationship of the training data and test data depends on the mode of operation.

Currently this method only supports deterministic predictions (i.e. when models’ predictions have only 1 sample).

Parameters

model_class – The ForecastingModel subclass to be tuned for ‘series’.
parameters (dict) – A dictionary containing as keys hyperparameter names, and as values lists of values for the respective hyperparameter.
series (TimeSeries) – The target series used as input and target for training.
past_covariates (Optional[TimeSeries, None]) – Optionally, a past-observed covariate series. This applies only if the model supports past covariates.
future_covariates (Optional[TimeSeries, None]) – Optionally, a future-known covariate series. This applies only if the model supports future covariates.
forecast_horizon (Optional[int, None]) – The integer value of the forecasting horizon. Activates expanding window mode.
stride (int) – Only used in expanding window mode. The number of time steps between two consecutive predictions.
start (Union[Timestamp, float, int, None]) –
Only used in expanding window mode. Optionally, the first point in time at which a prediction is computed. This parameter supports: float, int, pandas.Timestamp, and None. If a float, it is the proportion of the time series that should lie before the first prediction point. If an int, it is either the index position of the first prediction point for series with a pd.DatetimeIndex, or the index value for series with a pd.RangeIndex. The latter can be changed to the index position with start_format=”position”. If a pandas.Timestamp, it is the time stamp of the first prediction point. If None, the first prediction point will automatically be set to:
- the first predictable point if retrain is False, or retrain is a Callable and the first predictable point is earlier than the first trainable point.
- the first trainable point if retrain is True or int (given train_length), or retrain is a Callable and the first trainable point is earlier than the first predictable point.
- the first trainable point (given train_length) otherwise
Note: If start is not within the trainable / forecastable points, uses the closest valid start point that
is a round multiple of stride ahead of start. Raises a ValueError, if no valid start point exists.

Note: If the model uses a shifted output (output_chunk_shift > 0), then the first predicted point is also
shifted by output_chunk_shift points into the future.

Note: If start is outside the possible historical forecasting times, will ignore the parameter
(default behavior with None) and start at the first trainable/predictable point.
start_format (Literal[‘position’, ‘value’]) – Only used in expanding window mode. Defines the start format. Only effective when start is an integer and series is indexed with a pd.RangeIndex. If set to ‘position’, start corresponds to the index position of the first predicted point and can range from (-len(series), len(series) - 1). If set to ‘value’, start corresponds to the index value/label of the first predicted point. Will raise an error if the value is not in series’ index. Default: 'value'
last_points_only (bool) – Only used in expanding window mode. Whether to use the whole forecasts or only the last point of each forecast to compute the error.
show_warnings (bool) – Only used in expanding window mode. Whether to show warnings related to the start parameter.
val_series (Optional[TimeSeries, None]) – The TimeSeries instance used for validation in split mode. If provided, this series must start right after the end of series; so that a proper comparison of the forecast can be made.
use_fitted_values (bool) – If True, uses the comparison with the fitted values. Raises an error if fitted_values is not an attribute of model_class.
metric (Callable[[TimeSeries, TimeSeries], float]) –
A metric function that returns the error between two TimeSeries as a float value . Must either be one of Darts’ “aggregated over time” metrics (see here), or a custom metric that as input two TimeSeries and returns the error
reduction (Callable[[ndarray], float]) – A reduction function (mapping array to float) describing how to aggregate the errors obtained on the different validation series when backtesting. By default it’ll compute the mean of errors.
verbose – Whether to print the progress.
n_jobs (int) – The number of jobs to run in parallel. Parallel jobs are created only when there are two or more parameters combinations to evaluate. Each job will instantiate, train, and evaluate a different instance of the model. Defaults to 1 (sequential). Setting the parameter to -1 means using all the available cores.
n_random_samples (Union[int, float, None]) – The number/ratio of hyperparameter combinations to select from the full parameter grid. This will perform a random search instead of using the full grid. If an integer, n_random_samples is the number of parameter combinations selected from the full grid and must be between 0 and the total number of parameter combinations. If a float, n_random_samples is the ratio of parameter combinations selected from the full grid and must be between 0 and 1. Defaults to None, for which random selection will be ignored.
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
Optionally, a dictionary of BaseDataTransformer or Pipeline to apply to the corresponding series (possibles keys; “series”, “past_covariates”, “future_covariates”). If provided, all input series must be in the un-transformed space. For fittable transformer / pipeline:
- if retrain=True, the data transformer re-fit on the training data at each historical forecast step.
- if retrain=False, the data transformer transforms the series once before all the forecasts.
The fitted transformer is used to transform the input during both training and prediction. If the transformation is invertible, the forecasts will be inverse-transformed.
fit_kwargs (Optional[dict[str, Any], None]) – Additional arguments passed to the model fit() method.
predict_kwargs (Optional[dict[str, Any], None]) – Additional arguments passed to the model predict() method.
sample_weight (Union[TimeSeries, str, None]) – Optionally, some sample weights to apply to the target series labels for training. Only effective when retrain is not False. They are applied per observation, per label (each step in output_chunk_length), and per component. If a series, then those weights are used. If the weight series only have a single component / column, then the weights are applied globally to all components in series. Otherwise, for component-specific weights, the number of components must match those of series. If a string, then the weights are generated using built-in weighting functions. The available options are “linear” or “exponential” decay - the further in the past, the lower the weight.

Returns

Return type

ForecastingModel, Dict, float

Currently, conformal models only support the pre-trained historical forecasts mode (retrain=False). Parameters retrain and train_length are ignored.

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – A (sequence of) target time series used to successively compute the historical forecasts. Will use the past of this series for calibration. The series should not have any overlap with the series used to train the forecasting model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) past-observed covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) future-known covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
forecast_horizon (int) – The forecast horizon for the predictions.
num_samples (int) – Number of times a prediction is sampled from the calibrated quantile predictions using linear interpolation in-between the quantiles. For larger values, the sample distribution approximates the calibrated quantile predictions.
train_length (Optional[int, None]) – Currently ignored by conformal models.
start (Union[Timestamp, int, None]) –
Optionally, the first point in time at which a prediction is computed. This parameter supports: int, pandas.Timestamp, and None. If an int, it is either the index position of the first prediction point for series with a pd.DatetimeIndex, or the index value for series with a pd.RangeIndex. The latter can be changed to the index position with start_format=”position”. If a pandas.Timestamp, it is the time stamp of the first prediction point. If None, the first prediction point will automatically be set to:
- the first predictable point if retrain is False, or retrain is a Callable and the first predictable point is earlier than the first trainable point.
- the first trainable point if retrain is True or int (given train_length), or retrain is a Callable and the first trainable point is earlier than the first predictable point.
- the first trainable point (given train_length) otherwise
Note: If the model uses a shifted output (output_chunk_shift > 0), then the first predicted point is also shifted by output_chunk_shift points into the future. Note: Raises a ValueError if start yields a time outside the time index of series. Note: If start is outside the possible historical forecasting times, will ignore the parameter (default behavior with None) and start at the first trainable/predictable point.
start_format (Literal[‘position’, ‘value’]) – Defines the start format. If set to 'position', start corresponds to the index position of the first predicted point and can range from (-len(series), len(series) - 1). If set to 'value', start corresponds to the index value/label of the first predicted point. Will raise an error if the value is not in series’ index. Default: 'value'.
stride (int) – The number of time steps between two consecutive predictions. Must be a round-multiple of cal_stride (set at model creation) and >=cal_stride.
retrain (Union[bool, int, Callable[…, bool]]) – Currently ignored by conformal models.
overlap_end (bool) – Whether the returned forecasts can go beyond the series’ end or not.
last_points_only (bool) – Whether to return only the last point of each historical forecast. If set to True, the method returns a single TimeSeries (for each time series in series) containing the successive point forecasts. Otherwise, returns a list of historical TimeSeries forecasts.
verbose (bool) – Whether to print the progress.
show_warnings (bool) – Whether to show warnings related to historical forecasts optimization, or parameters start and train_length.
predict_likelihood_parameters (bool) – If set to True, generates the quantile predictions directly. Only supported with num_samples = 1.
enable_optimization (bool) – Whether to use the optimized version of historical_forecasts when supported and available. Default: True.
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
Optionally, a dictionary of BaseDataTransformer or Pipeline to apply to the corresponding series (possibles keys; “series”, “past_covariates”, “future_covariates”). If provided, all input series must be in the un-transformed space. For fittable transformer / pipeline:
- if retrain=True, the data transformer re-fit on the training data at each historical forecast step (currently ignored by conformal models).
- if retrain=False, the data transformer transforms the series once before all the forecasts.
The fitted transformer is used to transform the input during both training and prediction. If the transformation is invertible, the forecasts will be inverse-transformed.
fit_kwargs (Optional[dict[str, Any], None]) – Currently ignored by conformal models.
predict_kwargs (Optional[dict[str, Any], None]) – Optionally, some additional arguments passed to the model predict() method.
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – Currently ignored by conformal models.

Return type

Union[TimeSeries, list[TimeSeries], list[list[TimeSeries]]]

Returns

TimeSeries – A single historical forecast for a single series and last_points_only=True: it contains only the predictions at step forecast_horizon from all historical forecasts.
list[TimeSeries] – A list of historical forecasts for:
- a sequence (list) of series and last_points_only=True: for each series, it contains only the predictions at step forecast_horizon from all historical forecasts.
- a single series and last_points_only=False: for each historical forecast, it contains the entire horizon forecast_horizon.
list[list[TimeSeries]] – A list of lists of historical forecasts for a sequence of series and last_points_only=False. For each series, and historical forecast, it contains the entire horizon forecast_horizon. The outer list is over the series provided in the input sequence, and the inner lists contain the historical forecasts for each series.

property likelihood: str¶

Return type: str

static load(path)¶

Loads the model from a given path or file handle.

Parameters: path (Union[str, PathLike, BinaryIO]) – Path or file handle from which to load the model.
Return type: ConformalModel

property min_train_samples: int¶

The minimum number of samples for training the model.

Return type: int

property model_params: dict¶

Return type: dict

property output_chunk_length: Optional[int]¶

Number of time steps predicted at once by the model, not defined for statistical models.

Return type: Optional[int, None]

property output_chunk_shift: int¶

Number of time steps that the output/prediction starts after the end of the input.

Return type: int

predict(n, series=None, past_covariates=None, future_covariates=None, num_samples=1, verbose=False, predict_likelihood_parameters=False, show_warnings=True, **kwargs)¶

Forecasts calibrated quantile intervals (or samples from calibrated intervals) for n time steps after the end of the series.

It is important that the input series for prediction correspond to a calibration set - a set different to the series that the underlying forecasting model was trained on.

Since it is a probabilistic model, you can generate forecasts in two ways:

Predict the calibrated quantile intervals directly: Pass parameters predict_likelihood_parameters=True, and num_samples=1 to the forecast method.
Predict stochastic samples from the calibrated quantile intervals: Pass parameters predict_likelihood_parameters=False, and num_samples>>1 to the forecast method.

Under the hood, the simplified workflow to produce one calibrated forecast/prediction for every step in the horizon n is as follows (note: cal_length and cal_stride can be set at model creation):

Extract a calibration set: The calibration set for each conformal forecast is automatically extracted from the most recent past of your input series relative to the forecast start point. The number of calibration examples (forecast errors / non-conformity scores) to consider can be defined at model creation with parameter cal_length. Note that when using cal_stride>1, a longer history is required since the calibration examples are generated with stridden historical forecasts.
Generate historical forecasts on the calibration set (using the forecasting model) with a stride cal_stride.
Compute the errors/non-conformity scores (specific to each conformal model) on these historical forecasts
Compute the quantile values from the errors / non-conformity scores (using our desired quantiles set at model creation with parameter quantiles).
Compute the conformal prediction: Using these quantile values, add calibrated intervals to (or adjust the existing intervals of) the forecasting model’s predictions.

Parameters

n (int) – Forecast horizon - the number of time steps after the end of the series for which to produce predictions.
series (Union[TimeSeries, Sequence[TimeSeries], None]) – A series or sequence of series, representing the history of the target series whose future is to be predicted. Will use the past of this series for calibration. The series should not have any overlap with the series used to train the forecasting model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) past-observed covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) future-known covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
num_samples (int) – Number of times a prediction is sampled from the calibrated quantile predictions using linear interpolation in-between the quantiles. For larger values, the sample distribution approximates the calibrated quantile predictions.
verbose (bool) – Whether to print the progress.
predict_likelihood_parameters (bool) – If set to True, generates the quantile predictions directly. Only supported with num_samples = 1.
show_warnings (bool) – Whether to show warnings related auto-regression and past covariates usage.
**kwargs – Optional keyword arguments that will passed to the underlying forecasting model’s predict() and historical_forecasts() methods.

Returns

Return type

Union[TimeSeries, Sequence[TimeSeries]]

Compute the residuals that the model produced for historical forecasts on (potentially multiple) series.

In sequence this method performs:

use pre-computed historical_forecasts or compute historical forecasts for each series (see historical_forecasts() for more details). How the historical forecasts are generated can be configured with parameters num_samples, train_length, start, start_format, forecast_horizon, stride, retrain, last_points_only, fit_kwargs, and predict_kwargs.
compute a backtest using a “per time step” metric between the historical forecasts and series per component/column and time step (see backtest() for more details). By default, uses the residuals err() (error) as a metric.
create and return TimeSeries (or simply a np.ndarray with values_only=True) with the time index from historical forecasts, and values from the metrics per component and time step.

This method works for single or multiple univariate or multivariate series. It uses the median prediction (when dealing with stochastic forecasts).

Notes

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – A (sequence of) target time series used to successively compute the historical forecasts. Will use the past of this series for calibration. The series should not have any overlap with the series used to train the forecasting model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) past-observed covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) future-known covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
historical_forecasts (Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]], None]) – Optionally, the (or a sequence of / a sequence of sequences of) historical forecasts time series to be evaluated. Corresponds to the output of historical_forecasts(). The same series and last_points_only values must be passed that were used to generate the historical forecasts. If provided, will skip historical forecasting and ignore all parameters except series, last_points_only, metric, and reduction.
forecast_horizon (int) – The forecast horizon for the predictions.
num_samples (int) – Number of times a prediction is sampled from the calibrated quantile predictions using linear interpolation in-between the quantiles. For larger values, the sample distribution approximates the calibrated quantile predictions.
train_length (Optional[int, None]) – Currently ignored by conformal models.
start (Union[Timestamp, int, None]) –
Optionally, the first point in time at which a prediction is computed. This parameter supports: int, pandas.Timestamp, and None. If an int, it is either the index position of the first prediction point for series with a pd.DatetimeIndex, or the index value for series with a pd.RangeIndex. The latter can be changed to the index position with start_format=”position”. If a pandas.Timestamp, it is the time stamp of the first prediction point. If None, the first prediction point will automatically be set to:
- the first predictable point if retrain is False, or retrain is a Callable and the first predictable point is earlier than the first trainable point.
- the first trainable point if retrain is True or int (given train_length), or retrain is a Callable and the first trainable point is earlier than the first predictable point.
- the first trainable point (given train_length) otherwise
Note: If the model uses a shifted output (output_chunk_shift > 0), then the first predicted point is also shifted by output_chunk_shift points into the future. Note: Raises a ValueError if start yields a time outside the time index of series. Note: If start is outside the possible historical forecasting times, will ignore the parameter (default behavior with None) and start at the first trainable/predictable point.
start_format (Literal[‘position’, ‘value’]) – Defines the start format. If set to 'position', start corresponds to the index position of the first predicted point and can range from (-len(series), len(series) - 1). If set to 'value', start corresponds to the index value/label of the first predicted point. Will raise an error if the value is not in series’ index. Default: 'value'.
stride (int) – The number of time steps between two consecutive predictions.
retrain (Union[bool, int, Callable[…, bool]]) – Currently ignored by conformal models.
overlap_end (bool) – Whether the returned forecasts can go beyond the series’ end or not.
last_points_only (bool) – Whether to return only the last point of each historical forecast. If set to True, the method returns a single TimeSeries (for each time series in series) containing the successive point forecasts. Otherwise, returns a list of historical TimeSeries forecasts.
metric (Callable[…, Union[float, list[float], ndarray, list[ndarray]]]) –
Either one of Darts’ “per time step” metrics (see here), or a custom metric that has an identical signature as Darts’ “per time step” metrics, uses decorators multi_ts_support() and multi_ts_support(), and returns one value per time step.
verbose (bool) – Whether to print the progress.
show_warnings (bool) – Whether to show warnings related to historical forecasts optimization, or parameters start and train_length.
predict_likelihood_parameters (bool) – If set to True, generates the quantile predictions directly. Only supported with num_samples = 1.
enable_optimization (bool) – Whether to use the optimized version of historical_forecasts when supported and available. Default: True.
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
Optionally, a dictionary of BaseDataTransformer or Pipeline to apply to the corresponding series (possibles keys; “series”, “past_covariates”, “future_covariates”). If provided, all input series must be in the un-transformed space. For fittable transformer / pipeline:
- if retrain=True, the data transformer re-fit on the training data at each historical forecast step (currently ignored by conformal models).
- if retrain=False, the data transformer transforms the series once before all the forecasts.
The fitted transformer is used to transform the input during both training and prediction. If the transformation is invertible, the forecasts will be inverse-transformed. Only effective when historical_forecasts=None.
metric_kwargs (Optional[dict[str, Any], None]) – Additional arguments passed to metric(), such as ‘n_jobs’ for parallelization, ‘m’ for scaled metrics, etc. Will pass arguments only if they are present in the corresponding metric signature. Ignores reduction arguments “series_reduction”, “component_reduction”, “time_reduction”, and parameter ‘insample’ for scaled metrics (e.g. mase`, rmsse, …), as they are handled internally.
fit_kwargs (Optional[dict[str, Any], None]) – Currently ignored by conformal models.
predict_kwargs (Optional[dict[str, Any], None]) – Optionally, some additional arguments passed to the model predict() method.
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – Currently ignored by conformal models.
values_only (bool) – Whether to return the residuals as np.ndarray. If False, returns residuals as TimeSeries.

Return type

Union[TimeSeries, list[TimeSeries], list[list[TimeSeries]]]

Returns

TimeSeries – Residual TimeSeries for a single series and historical_forecasts generated with last_points_only=True.
list[TimeSeries] – A list of residual TimeSeries for a sequence (list) of series with last_points_only=True. The residual list has length len(series).
list[list[TimeSeries]] – A list of lists of residual TimeSeries for a sequence of series with last_points_only=False. The outer residual list has length len(series). The inner lists consist of the residuals from all possible series-specific historical forecasts.

save(path=None, **pkl_kwargs)¶

Saves the conformal model under a given path or file handle.

Additionally, two files are stored if self.model is a TorchForecastingModel.

Example for saving and loading a ConformalNaiveModel:

from darts.datasets import AirPassengersDataset
from darts.models import ConformalNaiveModel, LinearRegressionModel

series = AirPassengersDataset().load()
forecasting_model = LinearRegressionModel(lags=4).fit(series)

model = ConformalNaiveModel(
    model=forecasting_model,
    quantiles=[0.1, 0.5, 0.9],
)

model.save("my_model.pkl")
model_loaded = ConformalNaiveModel.load("my_model.pkl")

Parameters

path (Union[str, PathLike, BinaryIO, None]) – Path or file handle under which to save the ensemble model at its current state. If no path is specified, the ensemble model is automatically saved under "{ConformalNaiveModel}_{YYYY-mm-dd_HH_MM_SS}.pkl". If the forecasting model is a TorchForecastingModel, two files (model object and checkpoint) are saved under "{path}.{ModelClass}.pt" and "{path}.{ModelClass}.ckpt".
pkl_kwargs – Keyword arguments passed to pickle.dump()

Return type

None

property supports_future_covariates: bool¶

Whether model supports future covariates

Return type: bool

property supports_likelihood_parameter_prediction: bool¶

Whether model instance supports direct prediction of likelihood parameters

Return type: bool

property supports_multivariate: bool¶

Whether the model considers more than one variate in the time series.

Return type: bool

property supports_optimized_historical_forecasts: bool¶

Whether the model supports optimized historical forecasts

Return type: bool

property supports_past_covariates: bool¶

Whether model supports past covariates

Return type: bool

property supports_probabilistic_prediction: bool¶

Checks if the forecasting model with this configuration supports probabilistic predictions.

By default, returns False. Needs to be overwritten by models that do support probabilistic predictions.

Return type: bool

property supports_sample_weight: bool¶

Whether model supports sample weight for training.

Return type: bool

property supports_static_covariates: bool¶

Whether model supports static covariates

Return type: bool

property supports_transferrable_series_prediction: bool¶

Whether the model supports prediction for any input series.

Return type: bool

property uses_future_covariates: bool¶

Whether the model uses future covariates, once fitted.

Return type: bool

property uses_past_covariates: bool¶

Whether the model uses past covariates, once fitted.

Return type: bool

property uses_static_covariates: bool¶

Whether the model uses static covariates, once fitted.

Return type: bool

class darts.models.forecasting.conformal_models.ConformalQRModel(model, quantiles, symmetric=True, cal_length=None, cal_stride=1, cal_num_samples=500, random_state=None)[source]¶

Bases: ConformalModel

Conformalized Quantile Regression Model.

A probabilistic model that calibrates the quantile predictions from a pre-trained probabilistic global forecasting model. It does not have to be trained and can generated calibrated forecasts directly using the underlying trained forecasting model. It supports two symmetry modes:

symmetric=True:
- The lower and upper quantile predictions are calibrated with the same magnitude.
- Non-conformity scores: uses metric incs_qr(symmetric=True) (see Non-Conformity Score for Quantile Regression incs_qr()) to compute the non-conformity scores on the calibration set.
symmetric=False
- The lower and upper quantile predictions are calibrated separately.
- Non-conformity scores: uses metric incs_qr(symmetric=False) (see Non-Conformity Score for Quantile Regression incs_qr()) to compute the non-conformity scores for the upper and lower bound separately.

Since it is a probabilistic model, you can generate forecasts in two ways (when calling predict(), historical_forecasts(), …):

Predict the calibrated quantile intervals directly: Pass parameters predict_likelihood_parameters=True, and num_samples=1 to the forecast method.
Predict stochastic samples from the calibrated quantile intervals: Pass parameters predict_likelihood_parameters=False, and num_samples>>1 to the forecast method.

Extract a calibration set: The calibration set for each conformal forecast is automatically extracted from the most recent past of your input series relative to the forecast start point. The number of calibration examples (forecast errors / non-conformity scores) to consider can be defined at model creation with parameter cal_length. Note that when using cal_stride>1, a longer history is required since the calibration examples are generated with stridden historical forecasts.
Generate historical forecasts (quantile predictions) on the calibration set (using the forecasting model) with a stride cal_stride.
Compute the errors/non-conformity scores (as defined above) on these historical quantile predictions
Compute the quantile values from the errors / non-conformity scores (using our desired quantiles set at model creation with parameter quantiles).
Compute the conformal prediction: Using these quantile values, calibrate the predicted quantiles from the forecasting model’s predictions.

Some notes:

When computing historical_forecasts(), backtest(), residuals(), … the above is applied for each forecast (the forecasting model’s historical forecasts are only generated once for efficiency).
For multi-horizon forecasts, the above is applied for each step in the horizon separately.

Parameters

model (GlobalForecastingModel) –
A pre-trained global forecasting model. See the list of models here.
quantiles (list[float]) – A list of quantiles centered around the median q=0.5 to use. For example quantiles [0.1, 0.2, 0.5, 0.8 0.9] correspond to two intervals with (0.9 - 0.1) = 80%, and (0.8 - 0.2) 60% coverage around the median (model forecast).
symmetric (bool) – Whether to use symmetric non-conformity scores. If True, uses symmetric metric incs_qr(…, symmetric=True) (see incs_qr()) to compute the non-conformity scores. If False, uses asymmetric metric incs_qr(…, symmetric=False) with individual scores for the lower- and upper quantile interval bounds.
cal_length (Optional[int, None]) – The number of past forecast errors / non-conformity scores to use as calibration for each conformal forecast (and each step in the horizon). If None, considers all scores.
cal_stride (int) – The stride to apply when computing the historical forecasts and non-conformity scores on the calibration set. The actual conformal forecasts can have a different stride given with parameter stride in downstream tasks (e.g. historical forecasts, backtest, …)
cal_num_samples (int) – The number of samples to generate for each calibration forecast (if model is a probabilistic forecasting model). The non-conformity scores are computed on the quantile values of these forecasts (using quantiles quantiles). Uses 1 for deterministic models. The actual conformal forecasts can have a different number of samples given with parameter num_samples in downstream tasks (e.g. predict, historical forecasts, …).
random_state (Optional[int, None]) – Control the randomness of probabilistic conformal forecasts (sample generation) across different runs.

Attributes

`considers_static_covariates`	Whether the model considers static covariates, if there are any.
`extreme_lags`	A 8-tuple containing in order: (min target lag, max target lag, min past covariate lag, max past covariate lag, min future covariate lag, max future covariate lag, output shift, max target lag train (only for RNNModel)).
`min_train_samples`	The minimum number of samples for training the model.
`output_chunk_length`	Number of time steps predicted at once by the model, not defined for statistical models.
`output_chunk_shift`	Number of time steps that the output/prediction starts after the end of the input.
`supports_future_covariates`	Whether model supports future covariates
`supports_likelihood_parameter_prediction`	Whether model instance supports direct prediction of likelihood parameters
`supports_multivariate`	Whether the model considers more than one variate in the time series.
`supports_optimized_historical_forecasts`	Whether the model supports optimized historical forecasts
`supports_past_covariates`	Whether model supports past covariates
`supports_probabilistic_prediction`	Checks if the forecasting model with this configuration supports probabilistic predictions.
`supports_sample_weight`	Whether model supports sample weight for training.
`supports_static_covariates`	Whether model supports static covariates
`supports_transferrable_series_prediction`	Whether the model supports prediction for any input series.
`uses_future_covariates`	Whether the model uses future covariates, once fitted.
`uses_past_covariates`	Whether the model uses past covariates, once fitted.
`uses_static_covariates`	Whether the model uses static covariates, once fitted.

likelihood
model_params

Methods

`backtest`(series[, past_covariates, ...])	Compute error values that the model produced for historical forecasts on (potentially multiple) series.
`fit`(series[, past_covariates, future_covariates])	Fit/train the underlying forecasting model on (potentially multiple) series.
`generate_fit_encodings`(series[, ...])	Generates the covariate encodings that were used/generated for fitting the model and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together.
`generate_fit_predict_encodings`(n, series[, ...])	Generates covariate encodings for training and inference/prediction and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together.
`generate_predict_encodings`(n, series[, ...])	Generates covariate encodings for the inference/prediction set and returns a tuple of past, and future covariates series with the original and encoded covariates stacked together.
`gridsearch`(parameters, series[, ...])	Find the best hyper-parameters among a given set using a grid search.
`historical_forecasts`(series[, ...])	Generates calibrated historical forecasts by simulating predictions at various points in time throughout the history of the provided (potentially multiple) series.
`load`(path)	Loads the model from a given path or file handle.
`predict`(n[, series, past_covariates, ...])	Forecasts calibrated quantile intervals (or samples from calibrated intervals) for n time steps after the end of the series.
`residuals`(series[, past_covariates, ...])	Compute the residuals that the model produced for historical forecasts on (potentially multiple) series.
`save`([path])	Saves the conformal model under a given path or file handle.

Compute error values that the model produced for historical forecasts on (potentially multiple) series.

The metric(s) can be further customized metric_kwargs (e.g. control the aggregation over components, time steps, multiple series, other required arguments such as q for quantile metrics, …).

Notes

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – A (sequence of) target time series used to successively compute the historical forecasts. Will use the past of this series for calibration. The series should not have any overlap with the series used to train the forecasting model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) past-observed covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) future-known covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
historical_forecasts (Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]], None]) – Optionally, the (or a sequence of / a sequence of sequences of) historical forecasts time series to be evaluated. Corresponds to the output of historical_forecasts(). The same series and last_points_only values must be passed that were used to generate the historical forecasts. If provided, will skip historical forecasting and ignore all parameters except series, last_points_only, metric, and reduction.
forecast_horizon (int) – The forecast horizon for the predictions.
num_samples (int) – Number of times a prediction is sampled from the calibrated quantile predictions using linear interpolation in-between the quantiles. For larger values, the sample distribution approximates the calibrated quantile predictions.
train_length (Optional[int, None]) – Currently ignored by conformal models.
start (Union[Timestamp, int, None]) –
Optionally, the first point in time at which a prediction is computed. This parameter supports: int, pandas.Timestamp, and None. If an int, it is either the index position of the first prediction point for series with a pd.DatetimeIndex, or the index value for series with a pd.RangeIndex. The latter can be changed to the index position with start_format=”position”. If a pandas.Timestamp, it is the time stamp of the first prediction point. If None, the first prediction point will automatically be set to:
- the first predictable point if retrain is False, or retrain is a Callable and the first predictable point is earlier than the first trainable point.
- the first trainable point if retrain is True or int (given train_length), or retrain is a Callable and the first trainable point is earlier than the first predictable point.
- the first trainable point (given train_length) otherwise
Note: If the model uses a shifted output (output_chunk_shift > 0), then the first predicted point is also shifted by output_chunk_shift points into the future. Note: Raises a ValueError if start yields a time outside the time index of series. Note: If start is outside the possible historical forecasting times, will ignore the parameter (default behavior with None) and start at the first trainable/predictable point.
start_format (Literal[‘position’, ‘value’]) – Defines the start format. If set to 'position', start corresponds to the index position of the first predicted point and can range from (-len(series), len(series) - 1). If set to 'value', start corresponds to the index value/label of the first predicted point. Will raise an error if the value is not in series’ index. Default: 'value'.
stride (int) – The number of time steps between two consecutive predictions.
retrain (Union[bool, int, Callable[…, bool]]) – Currently ignored by conformal models.
overlap_end (bool) – Whether the returned forecasts can go beyond the series’ end or not.
last_points_only (bool) – Whether to return only the last point of each historical forecast. If set to True, the method returns a single TimeSeries (for each time series in series) containing the successive point forecasts. Otherwise, returns a list of historical TimeSeries forecasts.
metric (Union[Callable[…, Union[float, list[float], ndarray, list[ndarray]]], list[Callable[…, Union[float, list[float], ndarray, list[ndarray]]]]]) –
A metric function or a list of metric functions. Each metric must either be a Darts metric (see here), or a custom metric that has an identical signature as Darts’ metrics, uses decorators multi_ts_support() and multi_ts_support(), and returns the metric score.
reduction (Optional[Callable[…, float], None]) – A function used to combine the individual error scores obtained when last_points_only is set to False. When providing several metric functions, the function will receive the argument axis = 1 to obtain single value for each metric function. If explicitly set to None, the method will return a list of the individual error scores instead. Set to np.mean by default.
verbose (bool) – Whether to print the progress.
show_warnings (bool) – Whether to show warnings related to historical forecasts optimization, or parameters start and train_length.
predict_likelihood_parameters (bool) – If set to True, generates the quantile predictions directly. Only supported with num_samples = 1.
enable_optimization (bool) – Whether to use the optimized version of historical_forecasts when supported and available. Default: True.
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
Optionally, a dictionary of BaseDataTransformer or Pipeline to apply to the corresponding series (possibles keys; “series”, “past_covariates”, “future_covariates”). If provided, all input series must be in the un-transformed space. For fittable transformer / pipeline:
- if retrain=True, the data transformer re-fit on the training data at each historical forecast step (currently ignored by conformal models).
- if retrain=False, the data transformer transforms the series once before all the forecasts.
The fitted transformer is used to transform the input during both training and prediction. If the transformation is invertible, the forecasts will be inverse-transformed. Only effective when historical_forecasts=None.
metric_kwargs (Union[dict[str, Any], list[dict[str, Any]], None]) – Additional arguments passed to metric(), such as ‘n_jobs’ for parallelization, ‘component_reduction’ for reducing the component wise metrics, seasonality ‘m’ for scaled metrics, etc. Will pass arguments to each metric separately and only if they are present in the corresponding metric signature. Parameter ‘insample’ for scaled metrics (e.g. mase`, rmsse, …) is ignored, as it is handled internally.
fit_kwargs (Optional[dict[str, Any], None]) – Currently ignored by conformal models.
predict_kwargs (Optional[dict[str, Any], None]) – Optionally, some additional arguments passed to the model predict() method.
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – Currently ignored by conformal models.

Return type

Union[float, ndarray, list[float], list[ndarray]]

Returns

float – A single backtest score for single uni/multivariate series, a single metric function and:
- historical_forecasts generated with last_points_only=True
- historical_forecasts generated with last_points_only=False and using a backtest reduction
np.ndarray – An numpy array of backtest scores. For single series and one of:
- a single metric function, historical_forecasts generated with last_points_only=False and backtest reduction=None. The output has shape (n forecasts, *).
- multiple metric functions and historical_forecasts generated with last_points_only=False. The output has shape (*, n metrics) when using a backtest reduction, and (n forecasts, *, n metrics) when reduction=None
- multiple uni/multivariate series including series_reduction and at least one of component_reduction=None or time_reduction=None for “per time step metrics”
list[float] – Same as for type float but for a sequence of series. The returned metric list has length len(series) with the float metric for each input series.
list[np.ndarray] – Same as for type np.ndarray but for a sequence of series. The returned metric list has length len(series) with the np.ndarray metrics for each input series.

property considers_static_covariates: bool¶

Whether the model considers static covariates, if there are any.

Return type: bool

property extreme_lags: tuple[Optional[int], Optional[int], Optional[int], Optional[int], Optional[int], Optional[int], int, Optional[int]]¶

See examples below.

If the model wasn’t fitted with:

target (concerning RegressionModels only): then the first element should be None.
past covariates: then the third and fourth elements should be None.
future covariates: then the fifth and sixth elements should be None.

Should be overridden by models that use past or future covariates, and/or for model that have minimum target lag and maximum target lags potentially different from -1 and 0.

Notes

maximum target lag (second value) cannot be None and is always larger than or equal to 0.

Examples

>>> model = LinearRegressionModel(lags=3, output_chunk_length=2)
>>> model.fit(train_series)
>>> model.extreme_lags
(-3, 1, None, None, None, None, 0, None)
>>> model = LinearRegressionModel(lags=3, output_chunk_length=2, output_chunk_shift=2)
>>> model.fit(train_series)
>>> model.extreme_lags
(-3, 1, None, None, None, None, 2, None)
>>> model = LinearRegressionModel(lags=[-3, -5], lags_past_covariates = 4, output_chunk_length=7)
>>> model.fit(train_series, past_covariates=past_covariates)
>>> model.extreme_lags
(-5, 6, -4, -1,  None, None, 0, None)
>>> model = LinearRegressionModel(lags=[3, 5], lags_future_covariates = [4, 6], output_chunk_length=7)
>>> model.fit(train_series, future_covariates=future_covariates)
>>> model.extreme_lags
(-5, 6, None, None, 4, 6, 0, None)
>>> model = NBEATSModel(input_chunk_length=10, output_chunk_length=7)
>>> model.fit(train_series)
>>> model.extreme_lags
(-10, 6, None, None, None, None, 0, None)
>>> model = NBEATSModel(input_chunk_length=10, output_chunk_length=7, lags_future_covariates=[4, 6])
>>> model.fit(train_series, future_covariates)
>>> model.extreme_lags
(-10, 6, None, None, 4, 6, 0, None)

Return type: tuple[Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], int, Optional[int, None]]

fit(series, past_covariates=None, future_covariates=None, **kwargs)¶

Fit/train the underlying forecasting model on (potentially multiple) series.

Notes

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – One or several target time series. The model will be trained to forecast these time series. The series may or may not be multivariate, but if multiple series are provided they must have the same number of components.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – One or several past-observed covariate time series. These time series will not be forecast, but can be used by some models as an input. The covariate(s) may or may not be multivariate, but if multiple covariates are provided they must have the same number of components. If past_covariates is provided, it must contain the same number of series as series.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – One or several future-known covariate time series. These time series will not be forecast, but can be used by some models as an input. The covariate(s) may or may not be multivariate, but if multiple covariates are provided they must have the same number of components. If future_covariates is provided, it must contain the same number of series as series.
**kwargs – Optional keyword arguments that will passed to the underlying forecasting model’s fit() method.

Returns

Fitted model.

Return type

self

generate_fit_encodings(series, past_covariates=None, future_covariates=None)¶

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – The series or sequence of series with the target values used when fitting the model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the series or sequence of series with the past-observed covariates used when fitting the model.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the series or sequence of series with the future-known covariates used when fitting the model.

Returns

A tuple of (past covariates, future covariates). Each covariate contains the original as well as the encoded covariates.

Return type

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶

Parameters

n (int) – The number of prediction time steps after the end of series intended to be used for prediction.
series (Union[TimeSeries, Sequence[TimeSeries]]) – The series or sequence of series with target values intended to be used for training and prediction.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the past-observed covariates series intended to be used for training and prediction. The dimensions must match those of the covariates used for training.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the future-known covariates series intended to be used for prediction. The dimensions must match those of the covariates used for training.

Returns

A tuple of (past covariates, future covariates). Each covariate contains the original as well as the encoded covariates.

Return type

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶

Parameters

n (int) – The number of prediction time steps after the end of series intended to be used for prediction.
series (Union[TimeSeries, Sequence[TimeSeries]]) – The series or sequence of series with target values intended to be used for prediction.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the past-observed covariates series intended to be used for prediction. The dimensions must match those of the covariates used for training.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, the future-known covariates series intended to be used for prediction. The dimensions must match those of the covariates used for training.

Returns

A tuple of (past covariates, future covariates). Each covariate contains the original as well as the encoded covariates.

Return type

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

Find the best hyper-parameters among a given set using a grid search.

The relationship of the training data and test data depends on the mode of operation.

Currently this method only supports deterministic predictions (i.e. when models’ predictions have only 1 sample).

Parameters

model_class – The ForecastingModel subclass to be tuned for ‘series’.
parameters (dict) – A dictionary containing as keys hyperparameter names, and as values lists of values for the respective hyperparameter.
series (TimeSeries) – The target series used as input and target for training.
past_covariates (Optional[TimeSeries, None]) – Optionally, a past-observed covariate series. This applies only if the model supports past covariates.
future_covariates (Optional[TimeSeries, None]) – Optionally, a future-known covariate series. This applies only if the model supports future covariates.
forecast_horizon (Optional[int, None]) – The integer value of the forecasting horizon. Activates expanding window mode.
stride (int) – Only used in expanding window mode. The number of time steps between two consecutive predictions.
start (Union[Timestamp, float, int, None]) –
Only used in expanding window mode. Optionally, the first point in time at which a prediction is computed. This parameter supports: float, int, pandas.Timestamp, and None. If a float, it is the proportion of the time series that should lie before the first prediction point. If an int, it is either the index position of the first prediction point for series with a pd.DatetimeIndex, or the index value for series with a pd.RangeIndex. The latter can be changed to the index position with start_format=”position”. If a pandas.Timestamp, it is the time stamp of the first prediction point. If None, the first prediction point will automatically be set to:
- the first predictable point if retrain is False, or retrain is a Callable and the first predictable point is earlier than the first trainable point.
- the first trainable point if retrain is True or int (given train_length), or retrain is a Callable and the first trainable point is earlier than the first predictable point.
- the first trainable point (given train_length) otherwise
Note: If start is not within the trainable / forecastable points, uses the closest valid start point that
is a round multiple of stride ahead of start. Raises a ValueError, if no valid start point exists.

Note: If the model uses a shifted output (output_chunk_shift > 0), then the first predicted point is also
shifted by output_chunk_shift points into the future.

Note: If start is outside the possible historical forecasting times, will ignore the parameter
(default behavior with None) and start at the first trainable/predictable point.
start_format (Literal[‘position’, ‘value’]) – Only used in expanding window mode. Defines the start format. Only effective when start is an integer and series is indexed with a pd.RangeIndex. If set to ‘position’, start corresponds to the index position of the first predicted point and can range from (-len(series), len(series) - 1). If set to ‘value’, start corresponds to the index value/label of the first predicted point. Will raise an error if the value is not in series’ index. Default: 'value'
last_points_only (bool) – Only used in expanding window mode. Whether to use the whole forecasts or only the last point of each forecast to compute the error.
show_warnings (bool) – Only used in expanding window mode. Whether to show warnings related to the start parameter.
val_series (Optional[TimeSeries, None]) – The TimeSeries instance used for validation in split mode. If provided, this series must start right after the end of series; so that a proper comparison of the forecast can be made.
use_fitted_values (bool) – If True, uses the comparison with the fitted values. Raises an error if fitted_values is not an attribute of model_class.
metric (Callable[[TimeSeries, TimeSeries], float]) –
A metric function that returns the error between two TimeSeries as a float value . Must either be one of Darts’ “aggregated over time” metrics (see here), or a custom metric that as input two TimeSeries and returns the error
reduction (Callable[[ndarray], float]) – A reduction function (mapping array to float) describing how to aggregate the errors obtained on the different validation series when backtesting. By default it’ll compute the mean of errors.
verbose – Whether to print the progress.
n_jobs (int) – The number of jobs to run in parallel. Parallel jobs are created only when there are two or more parameters combinations to evaluate. Each job will instantiate, train, and evaluate a different instance of the model. Defaults to 1 (sequential). Setting the parameter to -1 means using all the available cores.
n_random_samples (Union[int, float, None]) – The number/ratio of hyperparameter combinations to select from the full parameter grid. This will perform a random search instead of using the full grid. If an integer, n_random_samples is the number of parameter combinations selected from the full grid and must be between 0 and the total number of parameter combinations. If a float, n_random_samples is the ratio of parameter combinations selected from the full grid and must be between 0 and 1. Defaults to None, for which random selection will be ignored.
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
Optionally, a dictionary of BaseDataTransformer or Pipeline to apply to the corresponding series (possibles keys; “series”, “past_covariates”, “future_covariates”). If provided, all input series must be in the un-transformed space. For fittable transformer / pipeline:
- if retrain=True, the data transformer re-fit on the training data at each historical forecast step.
- if retrain=False, the data transformer transforms the series once before all the forecasts.
The fitted transformer is used to transform the input during both training and prediction. If the transformation is invertible, the forecasts will be inverse-transformed.
fit_kwargs (Optional[dict[str, Any], None]) – Additional arguments passed to the model fit() method.
predict_kwargs (Optional[dict[str, Any], None]) – Additional arguments passed to the model predict() method.
sample_weight (Union[TimeSeries, str, None]) – Optionally, some sample weights to apply to the target series labels for training. Only effective when retrain is not False. They are applied per observation, per label (each step in output_chunk_length), and per component. If a series, then those weights are used. If the weight series only have a single component / column, then the weights are applied globally to all components in series. Otherwise, for component-specific weights, the number of components must match those of series. If a string, then the weights are generated using built-in weighting functions. The available options are “linear” or “exponential” decay - the further in the past, the lower the weight.

Returns

Return type

ForecastingModel, Dict, float

Currently, conformal models only support the pre-trained historical forecasts mode (retrain=False). Parameters retrain and train_length are ignored.

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – A (sequence of) target time series used to successively compute the historical forecasts. Will use the past of this series for calibration. The series should not have any overlap with the series used to train the forecasting model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) past-observed covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) future-known covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
forecast_horizon (int) – The forecast horizon for the predictions.
num_samples (int) – Number of times a prediction is sampled from the calibrated quantile predictions using linear interpolation in-between the quantiles. For larger values, the sample distribution approximates the calibrated quantile predictions.
train_length (Optional[int, None]) – Currently ignored by conformal models.
start (Union[Timestamp, int, None]) –
Optionally, the first point in time at which a prediction is computed. This parameter supports: int, pandas.Timestamp, and None. If an int, it is either the index position of the first prediction point for series with a pd.DatetimeIndex, or the index value for series with a pd.RangeIndex. The latter can be changed to the index position with start_format=”position”. If a pandas.Timestamp, it is the time stamp of the first prediction point. If None, the first prediction point will automatically be set to:
- the first predictable point if retrain is False, or retrain is a Callable and the first predictable point is earlier than the first trainable point.
- the first trainable point if retrain is True or int (given train_length), or retrain is a Callable and the first trainable point is earlier than the first predictable point.
- the first trainable point (given train_length) otherwise
Note: If the model uses a shifted output (output_chunk_shift > 0), then the first predicted point is also shifted by output_chunk_shift points into the future. Note: Raises a ValueError if start yields a time outside the time index of series. Note: If start is outside the possible historical forecasting times, will ignore the parameter (default behavior with None) and start at the first trainable/predictable point.
start_format (Literal[‘position’, ‘value’]) – Defines the start format. If set to 'position', start corresponds to the index position of the first predicted point and can range from (-len(series), len(series) - 1). If set to 'value', start corresponds to the index value/label of the first predicted point. Will raise an error if the value is not in series’ index. Default: 'value'.
stride (int) – The number of time steps between two consecutive predictions. Must be a round-multiple of cal_stride (set at model creation) and >=cal_stride.
retrain (Union[bool, int, Callable[…, bool]]) – Currently ignored by conformal models.
overlap_end (bool) – Whether the returned forecasts can go beyond the series’ end or not.
last_points_only (bool) – Whether to return only the last point of each historical forecast. If set to True, the method returns a single TimeSeries (for each time series in series) containing the successive point forecasts. Otherwise, returns a list of historical TimeSeries forecasts.
verbose (bool) – Whether to print the progress.
show_warnings (bool) – Whether to show warnings related to historical forecasts optimization, or parameters start and train_length.
predict_likelihood_parameters (bool) – If set to True, generates the quantile predictions directly. Only supported with num_samples = 1.
enable_optimization (bool) – Whether to use the optimized version of historical_forecasts when supported and available. Default: True.
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
Optionally, a dictionary of BaseDataTransformer or Pipeline to apply to the corresponding series (possibles keys; “series”, “past_covariates”, “future_covariates”). If provided, all input series must be in the un-transformed space. For fittable transformer / pipeline:
- if retrain=True, the data transformer re-fit on the training data at each historical forecast step (currently ignored by conformal models).
- if retrain=False, the data transformer transforms the series once before all the forecasts.
The fitted transformer is used to transform the input during both training and prediction. If the transformation is invertible, the forecasts will be inverse-transformed.
fit_kwargs (Optional[dict[str, Any], None]) – Currently ignored by conformal models.
predict_kwargs (Optional[dict[str, Any], None]) – Optionally, some additional arguments passed to the model predict() method.
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – Currently ignored by conformal models.

Return type

Union[TimeSeries, list[TimeSeries], list[list[TimeSeries]]]

Returns

TimeSeries – A single historical forecast for a single series and last_points_only=True: it contains only the predictions at step forecast_horizon from all historical forecasts.
list[TimeSeries] – A list of historical forecasts for:
- a sequence (list) of series and last_points_only=True: for each series, it contains only the predictions at step forecast_horizon from all historical forecasts.
- a single series and last_points_only=False: for each historical forecast, it contains the entire horizon forecast_horizon.
list[list[TimeSeries]] – A list of lists of historical forecasts for a sequence of series and last_points_only=False. For each series, and historical forecast, it contains the entire horizon forecast_horizon. The outer list is over the series provided in the input sequence, and the inner lists contain the historical forecasts for each series.

property likelihood: str¶

Return type: str

static load(path)¶

Loads the model from a given path or file handle.

Parameters: path (Union[str, PathLike, BinaryIO]) – Path or file handle from which to load the model.
Return type: ConformalModel

property min_train_samples: int¶

The minimum number of samples for training the model.

Return type: int

property model_params: dict¶

Return type: dict

property output_chunk_length: Optional[int]¶

Number of time steps predicted at once by the model, not defined for statistical models.

Return type: Optional[int, None]

property output_chunk_shift: int¶

Number of time steps that the output/prediction starts after the end of the input.

Return type: int

predict(n, series=None, past_covariates=None, future_covariates=None, num_samples=1, verbose=False, predict_likelihood_parameters=False, show_warnings=True, **kwargs)¶

Forecasts calibrated quantile intervals (or samples from calibrated intervals) for n time steps after the end of the series.

It is important that the input series for prediction correspond to a calibration set - a set different to the series that the underlying forecasting model was trained on.

Since it is a probabilistic model, you can generate forecasts in two ways:

Predict the calibrated quantile intervals directly: Pass parameters predict_likelihood_parameters=True, and num_samples=1 to the forecast method.
Predict stochastic samples from the calibrated quantile intervals: Pass parameters predict_likelihood_parameters=False, and num_samples>>1 to the forecast method.

Under the hood, the simplified workflow to produce one calibrated forecast/prediction for every step in the horizon n is as follows (note: cal_length and cal_stride can be set at model creation):

Extract a calibration set: The calibration set for each conformal forecast is automatically extracted from the most recent past of your input series relative to the forecast start point. The number of calibration examples (forecast errors / non-conformity scores) to consider can be defined at model creation with parameter cal_length. Note that when using cal_stride>1, a longer history is required since the calibration examples are generated with stridden historical forecasts.
Generate historical forecasts on the calibration set (using the forecasting model) with a stride cal_stride.
Compute the errors/non-conformity scores (specific to each conformal model) on these historical forecasts
Compute the quantile values from the errors / non-conformity scores (using our desired quantiles set at model creation with parameter quantiles).
Compute the conformal prediction: Using these quantile values, add calibrated intervals to (or adjust the existing intervals of) the forecasting model’s predictions.

Parameters

n (int) – Forecast horizon - the number of time steps after the end of the series for which to produce predictions.
series (Union[TimeSeries, Sequence[TimeSeries], None]) – A series or sequence of series, representing the history of the target series whose future is to be predicted. Will use the past of this series for calibration. The series should not have any overlap with the series used to train the forecasting model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) past-observed covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) future-known covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
num_samples (int) – Number of times a prediction is sampled from the calibrated quantile predictions using linear interpolation in-between the quantiles. For larger values, the sample distribution approximates the calibrated quantile predictions.
verbose (bool) – Whether to print the progress.
predict_likelihood_parameters (bool) – If set to True, generates the quantile predictions directly. Only supported with num_samples = 1.
show_warnings (bool) – Whether to show warnings related auto-regression and past covariates usage.
**kwargs – Optional keyword arguments that will passed to the underlying forecasting model’s predict() and historical_forecasts() methods.

Returns

Return type

Union[TimeSeries, Sequence[TimeSeries]]

Compute the residuals that the model produced for historical forecasts on (potentially multiple) series.

In sequence this method performs:

use pre-computed historical_forecasts or compute historical forecasts for each series (see historical_forecasts() for more details). How the historical forecasts are generated can be configured with parameters num_samples, train_length, start, start_format, forecast_horizon, stride, retrain, last_points_only, fit_kwargs, and predict_kwargs.
compute a backtest using a “per time step” metric between the historical forecasts and series per component/column and time step (see backtest() for more details). By default, uses the residuals err() (error) as a metric.
create and return TimeSeries (or simply a np.ndarray with values_only=True) with the time index from historical forecasts, and values from the metrics per component and time step.

This method works for single or multiple univariate or multivariate series. It uses the median prediction (when dealing with stochastic forecasts).

Notes

Parameters

series (Union[TimeSeries, Sequence[TimeSeries]]) – A (sequence of) target time series used to successively compute the historical forecasts. Will use the past of this series for calibration. The series should not have any overlap with the series used to train the forecasting model.
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) past-observed covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – Optionally, a (sequence of) future-known covariate time series for every input time series in series. Their dimension must match that of the past covariates used for training. Will use this series for calibration.
historical_forecasts (Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]], None]) – Optionally, the (or a sequence of / a sequence of sequences of) historical forecasts time series to be evaluated. Corresponds to the output of historical_forecasts(). The same series and last_points_only values must be passed that were used to generate the historical forecasts. If provided, will skip historical forecasting and ignore all parameters except series, last_points_only, metric, and reduction.
forecast_horizon (int) – The forecast horizon for the predictions.
num_samples (int) – Number of times a prediction is sampled from the calibrated quantile predictions using linear interpolation in-between the quantiles. For larger values, the sample distribution approximates the calibrated quantile predictions.
train_length (Optional[int, None]) – Currently ignored by conformal models.
start (Union[Timestamp, int, None]) –
Optionally, the first point in time at which a prediction is computed. This parameter supports: int, pandas.Timestamp, and None. If an int, it is either the index position of the first prediction point for series with a pd.DatetimeIndex, or the index value for series with a pd.RangeIndex. The latter can be changed to the index position with start_format=”position”. If a pandas.Timestamp, it is the time stamp of the first prediction point. If None, the first prediction point will automatically be set to:
- the first predictable point if retrain is False, or retrain is a Callable and the first predictable point is earlier than the first trainable point.
- the first trainable point if retrain is True or int (given train_length), or retrain is a Callable and the first trainable point is earlier than the first predictable point.
- the first trainable point (given train_length) otherwise
Note: If the model uses a shifted output (output_chunk_shift > 0), then the first predicted point is also shifted by output_chunk_shift points into the future. Note: Raises a ValueError if start yields a time outside the time index of series. Note: If start is outside the possible historical forecasting times, will ignore the parameter (default behavior with None) and start at the first trainable/predictable point.
start_format (Literal[‘position’, ‘value’]) – Defines the start format. If set to 'position', start corresponds to the index position of the first predicted point and can range from (-len(series), len(series) - 1). If set to 'value', start corresponds to the index value/label of the first predicted point. Will raise an error if the value is not in series’ index. Default: 'value'.
stride (int) – The number of time steps between two consecutive predictions.
retrain (Union[bool, int, Callable[…, bool]]) – Currently ignored by conformal models.
overlap_end (bool) – Whether the returned forecasts can go beyond the series’ end or not.
last_points_only (bool) – Whether to return only the last point of each historical forecast. If set to True, the method returns a single TimeSeries (for each time series in series) containing the successive point forecasts. Otherwise, returns a list of historical TimeSeries forecasts.
metric (Callable[…, Union[float, list[float], ndarray, list[ndarray]]]) –
Either one of Darts’ “per time step” metrics (see here), or a custom metric that has an identical signature as Darts’ “per time step” metrics, uses decorators multi_ts_support() and multi_ts_support(), and returns one value per time step.
verbose (bool) – Whether to print the progress.
show_warnings (bool) – Whether to show warnings related to historical forecasts optimization, or parameters start and train_length.
predict_likelihood_parameters (bool) – If set to True, generates the quantile predictions directly. Only supported with num_samples = 1.
enable_optimization (bool) – Whether to use the optimized version of historical_forecasts when supported and available. Default: True.
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
Optionally, a dictionary of BaseDataTransformer or Pipeline to apply to the corresponding series (possibles keys; “series”, “past_covariates”, “future_covariates”). If provided, all input series must be in the un-transformed space. For fittable transformer / pipeline:
- if retrain=True, the data transformer re-fit on the training data at each historical forecast step (currently ignored by conformal models).
- if retrain=False, the data transformer transforms the series once before all the forecasts.
The fitted transformer is used to transform the input during both training and prediction. If the transformation is invertible, the forecasts will be inverse-transformed. Only effective when historical_forecasts=None.
metric_kwargs (Optional[dict[str, Any], None]) – Additional arguments passed to metric(), such as ‘n_jobs’ for parallelization, ‘m’ for scaled metrics, etc. Will pass arguments only if they are present in the corresponding metric signature. Ignores reduction arguments “series_reduction”, “component_reduction”, “time_reduction”, and parameter ‘insample’ for scaled metrics (e.g. mase`, rmsse, …), as they are handled internally.
fit_kwargs (Optional[dict[str, Any], None]) – Currently ignored by conformal models.
predict_kwargs (Optional[dict[str, Any], None]) – Optionally, some additional arguments passed to the model predict() method.
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – Currently ignored by conformal models.
values_only (bool) – Whether to return the residuals as np.ndarray. If False, returns residuals as TimeSeries.

Return type

Union[TimeSeries, list[TimeSeries], list[list[TimeSeries]]]

Returns

TimeSeries – Residual TimeSeries for a single series and historical_forecasts generated with last_points_only=True.
list[TimeSeries] – A list of residual TimeSeries for a sequence (list) of series with last_points_only=True. The residual list has length len(series).
list[list[TimeSeries]] – A list of lists of residual TimeSeries for a sequence of series with last_points_only=False. The outer residual list has length len(series). The inner lists consist of the residuals from all possible series-specific historical forecasts.

save(path=None, **pkl_kwargs)¶

Saves the conformal model under a given path or file handle.

Additionally, two files are stored if self.model is a TorchForecastingModel.

Example for saving and loading a ConformalNaiveModel:

from darts.datasets import AirPassengersDataset
from darts.models import ConformalNaiveModel, LinearRegressionModel

series = AirPassengersDataset().load()
forecasting_model = LinearRegressionModel(lags=4).fit(series)

model = ConformalNaiveModel(
    model=forecasting_model,
    quantiles=[0.1, 0.5, 0.9],
)

model.save("my_model.pkl")
model_loaded = ConformalNaiveModel.load("my_model.pkl")

Parameters

path (Union[str, PathLike, BinaryIO, None]) – Path or file handle under which to save the ensemble model at its current state. If no path is specified, the ensemble model is automatically saved under "{ConformalNaiveModel}_{YYYY-mm-dd_HH_MM_SS}.pkl". If the forecasting model is a TorchForecastingModel, two files (model object and checkpoint) are saved under "{path}.{ModelClass}.pt" and "{path}.{ModelClass}.ckpt".
pkl_kwargs – Keyword arguments passed to pickle.dump()

Return type

None

property supports_future_covariates: bool¶

Whether model supports future covariates

Return type: bool

property supports_likelihood_parameter_prediction: bool¶

Whether model instance supports direct prediction of likelihood parameters

Return type: bool

property supports_multivariate: bool¶

Whether the model considers more than one variate in the time series.

Return type: bool

property supports_optimized_historical_forecasts: bool¶

Whether the model supports optimized historical forecasts

Return type: bool

property supports_past_covariates: bool¶

Whether model supports past covariates

Return type: bool

property supports_probabilistic_prediction: bool¶

Checks if the forecasting model with this configuration supports probabilistic predictions.

By default, returns False. Needs to be overwritten by models that do support probabilistic predictions.

Return type: bool

property supports_sample_weight: bool¶

Whether model supports sample weight for training.

Return type: bool

property supports_static_covariates: bool¶

Whether model supports static covariates

Return type: bool

property supports_transferrable_series_prediction: bool¶

Whether the model supports prediction for any input series.

Return type: bool

property uses_future_covariates: bool¶

Whether the model uses future covariates, once fitted.

Return type: bool

property uses_past_covariates: bool¶

Whether the model uses past covariates, once fitted.

Return type: bool

property uses_static_covariates: bool¶

Whether the model uses static covariates, once fitted.

Return type: bool

CatBoost model

Croston method