def fit(
self,
series: TimeSeries,
covariates: Optional[TimeSeries] = None,
num_block_rows: Optional[int] = None,
) -> "KalmanFilter":
"""
Initializes the Kalman filter using the N4SID algorithm.
Parameters
----------
series : TimeSeries
The series of outputs (observations) used to infer the underlying state space model.
This must be a deterministic series (containing one sample).
covariates : Optional[TimeSeries]
An optional series of inputs (control signal) that will also be used to infer the underlying state space
model. This must be a deterministic series (containing one sample).
num_block_rows : Optional[int]
The number of block rows to use in the block Hankel matrices used in the N4SID algorithm.
See the documentation of nfoursid.nfoursid.NFourSID for more information.
If not provided, the dimensionality of the state space model will be used, with a maximum of 10.
Returns
-------
self
Fitted Kalman filter.
"""
if covariates is not None:
self._expect_covariates = True
covariates = covariates.slice_intersect(series)
raise_if_not(
series.has_same_time_as(covariates),
"The number of timesteps in the series and the covariates must match.",
)
# TODO: Handle multiple timeseries. Needs reimplementation of NFourSID?
self.dim_y = series.width
outputs = series.pd_dataframe(copy=False)
outputs.columns = [f"y_{i}" for i in outputs.columns]
if covariates is not None:
self.dim_u = covariates.width
inputs = covariates.pd_dataframe(copy=False)
inputs.columns = [f"u_{i}" for i in inputs.columns]
input_columns = list(inputs.columns)
measurements = pd.concat([outputs, inputs], axis=1)
else:
measurements = outputs
input_columns = None
if num_block_rows is None:
num_block_rows = max(10, self.dim_x)
nfoursid = NFourSID(
measurements,
output_columns=list(outputs.columns),
input_columns=input_columns,
num_block_rows=num_block_rows,
)
nfoursid.subspace_identification()
state_space_identified, covariance_matrix = nfoursid.system_identification(
rank=self.dim_x)
self.kf = Kalman(state_space_identified, covariance_matrix)
return self
def gridsearch(model_class,
parameters: dict,
series: TimeSeries,
covariates: Optional[TimeSeries] = None,
forecast_horizon: Optional[int] = None,
start: Union[pd.Timestamp, float, int] = 0.5,
last_points_only: bool = False,
val_series: Optional[TimeSeries] = None,
use_fitted_values: bool = False,
metric: Callable[[TimeSeries, TimeSeries],
float] = metrics.mape,
reduction: Callable[[np.ndarray], float] = np.mean,
verbose=False) -> Tuple['ForecastingModel', Dict]:
"""
A function for finding the best hyper-parameters among a given set.
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 regards
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 `training_series` and `target_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 `training_series` or `target_series`, if
specified. 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.
Parameters
----------
model_class
The ForecastingModel subclass to be tuned for 'series'.
parameters
A dictionary containing as keys hyperparameter names, and as values lists of values for the
respective hyperparameter.
series
The TimeSeries instance used as input and target for training.
covariates
An optional covariate series. This applies only if the model supports covariates.
forecast_horizon
The integer value of the forecasting horizon used in expanding window mode.
start
The `int`, `float` or `pandas.Timestamp` that represents the starting point in the time index
of `training_series` from which predictions will be made to evaluate the model.
For a detailed description of how the different data types are interpreted, please see the documentation
for `ForecastingModel.backtest`.
last_points_only
Whether to use the whole forecasts or only the last point of each forecast to compute the error
val_series
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
If `True`, uses the comparison with the fitted values.
Raises an error if `fitted_values` is not an attribute of `model_class`.
metric
A function that takes two TimeSeries instances as inputs and returns a float error value.
reduction
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 progress.
Returns
-------
ForecastingModel, Dict
A tuple containing an untrained 'model_class' instance created from the best-performing hyper-parameters,
along with a dictionary containing these best hyper-parameters.
"""
raise_if_not(
(forecast_horizon is not None) + (val_series is not None) +
use_fitted_values == 1,
"Please pass exactly one of the arguments 'forecast_horizon', "
"'val_target_series' or 'use_fitted_values'.", logger)
if use_fitted_values:
raise_if_not(
hasattr(model_class(), "fitted_values"),
"The model must have a fitted_values attribute to compare with the train TimeSeries",
logger)
elif val_series is not None:
raise_if_not(
series.width == val_series.width,
"Training and validation series require the same number of components.",
logger)
if covariates is not None:
raise_if_not(
series.has_same_time_as(covariates),
'The provided series and covariates must have the '
'same time axes.')
min_error = float('inf')
best_param_combination = {}
# compute all hyperparameter combinations from selection
params_cross_product = list(product(*parameters.values()))
# TODO: We should find a better object oriented way of handling covariates in GlobalForecastingModel
fit_signature = signature(model_class.fit)
predict_signature = signature(model_class.predict)
# iterate through all combinations of the provided parameters and choose the best one
iterator = _build_tqdm_iterator(params_cross_product, verbose)
for param_combination in iterator:
param_combination_dict = dict(
list(zip(parameters.keys(), param_combination)))
model = model_class(**param_combination_dict)
if use_fitted_values: # fitted value mode
if covariates is not None and 'covariates' in fit_signature.parameters:
model.fit(series, covariates=covariates)
else:
model.fit(series)
fitted_values = TimeSeries.from_times_and_values(
series.time_index(), model.fitted_values)
error = metric(fitted_values, series)
elif val_series is None: # expanding window mode
error = model.backtest(series,
covariates,
start,
forecast_horizon,
metric=metric,
reduction=reduction,
last_points_only=last_points_only)
else: # split mode
if covariates is not None and 'covariates' in fit_signature.parameters:
model.fit(series, covariates=covariates)
else:
model.fit(series)
if covariates is not None and 'covariates' in predict_signature.parameters:
pred = model.predict(n=len(val_series),
covariates=covariates)
else:
pred = model.predict(n=len(val_series))
error = metric(pred, val_series)
if error < min_error:
min_error = error
best_param_combination = param_combination_dict
logger.info('Chosen parameters: ' + str(best_param_combination))
return model_class(**best_param_combination), best_param_combination
def filter(
self,
series: TimeSeries,
covariates: Optional[TimeSeries] = None,
num_samples: int = 1,
) -> TimeSeries:
"""
Sequentially applies the Kalman filter on the provided series of observations.
Parameters
----------
series : TimeSeries
The series of outputs (observations) used to infer the underlying outputs according to the specified Kalman
process. This must be a deterministic series (containing one sample).
covariates : Optional[TimeSeries]
An optional series of inputs (control signal), necessary if the Kalman filter was initialized with
covariates. This must be a deterministic series (containing one sample).
num_samples : int, default: 1
The number of samples to generate from the inferred distribution of the output z. If this is set to 1, the
output is a `TimeSeries` containing a single sample using the mean of the distribution.
Returns
-------
TimeSeries
A (stochastic) `TimeSeries` of the inferred output z, of the same width as the input series.
"""
super().filter(series)
raise_if(
self.kf is None,
"The Kalman filter has not been fitted yet. Call `fit()` first "
"or provide Kalman filter in constructor.",
)
raise_if_not(
series.width == self.dim_y,
"The provided TimeSeries dimensionality does not match "
"the output dimensionality of the Kalman filter.",
)
raise_if(
covariates is not None and not self._expect_covariates,
"Covariates were provided, but the Kalman filter was not fitted with covariates.",
)
if self._expect_covariates:
raise_if(
covariates is None,
"The Kalman filter was fitted with covariates, but these were not provided.",
)
raise_if_not(
covariates.is_deterministic,
"The covariates must be deterministic (observations).",
)
covariates = covariates.slice_intersect(series)
raise_if_not(
series.has_same_time_as(covariates),
"The number of timesteps in the series and the covariates must match.",
)
kf = deepcopy(self.kf)
y_values = series.values(copy=False)
if self._expect_covariates:
u_values = covariates.values(copy=False)
# set control signal to 0 if it contains NaNs:
u_values = np.nan_to_num(u_values, copy=True, nan=0.0)
else:
u_values = np.zeros((len(y_values), 0))
# For each time step, we'll sample "n_samples" from a multivariate Gaussian
# whose mean vector and covariance matrix come from the Kalman filter.
sampled_outputs = np.zeros((len(y_values), self.dim_y, num_samples))
for i in range(len(y_values)):
y = y_values[i, :].reshape(-1, 1)
u = u_values[i, :].reshape(-1, 1)
if np.isnan(y).any():
y = None
kf.step(y, u)
mean_vec = kf.y_filtereds[-1].reshape(self.dim_y, )
if num_samples == 1:
sampled_outputs[i, :, 0] = mean_vec
else:
# The measurement covariance matrix is given by the sum of the covariance matrix of the
# state estimate (transformed by C) and the covariance matrix of the measurement noise.
cov_matrix = (
kf.state_space.c @ kf.p_filtereds[-1] @ kf.state_space.c.T
+ kf.r)
sampled_outputs[i, :, :] = np.random.multivariate_normal(
mean_vec, cov_matrix, size=num_samples).T
return series.with_values(sampled_outputs)
def historical_forecasts(
self,
series: TimeSeries,
covariates: Optional[TimeSeries] = None,
start: Union[pd.Timestamp, float, int] = 0.5,
forecast_horizon: int = 1,
stride: int = 1,
retrain: bool = True,
overlap_end: bool = False,
last_points_only: bool = True,
verbose: bool = False) -> Union[TimeSeries, List[TimeSeries]]:
"""
Computes the historical forecasts the model would have produced with an expanding training window
and (by default) returns a time series created from the last point of each of these individual forecasts.
To this end, it repeatedly builds a training set from the beginning of `series`. It trains the
current model on the training set, emits a forecast of length equal to forecast_horizon, and then moves
the end of the training set forward by `stride` time steps.
By default, this method will return a single time series made up of the last point of each
historical forecast. This time series will thus have a frequency of `series.freq() * stride`.
If `last_points_only` is set to False, it will instead return a list of the historical forecasts.
By default, this method always re-trains the models on the entire available history,
corresponding to an expanding window strategy.
If `retrain` is set to False (useful for models for which training might be time-consuming, such as
deep learning models), the model will only be trained on the initial training window
(up to `start` time stamp), and only if it has not been trained before. Then, at every iteration, the
newly expanded input sequence will be fed to the model to produce the new output.
Parameters
----------
series
The target time series to use to successively train and evaluate the historical forecasts
covariates
An optional covariate series. This applies only if the model supports covariates.
start
The first point of time at which a prediction is computed for a future time.
This parameter supports 3 different data types: `float`, `int` and `pandas.Timestamp`.
In the case of `float`, the parameter will be treated as the proportion of the time series
that should lie before the first prediction point.
In the case of `int`, the parameter will be treated as an integer index to the time index of
`series` that will be used as first prediction time.
In case of `pandas.Timestamp`, this time stamp will be used to determine the first prediction time
directly.
forecast_horizon
The forecast horizon for the predictions
stride
The number of time steps between two consecutive predictions.
retrain
Whether to retrain the model for every prediction or not. Currently only `TorchForecastingModel`
instances such as `RNNModel`, `TCNModel`, `NBEATSModel` and `TransformerModel` support
setting `retrain` to `False`.
overlap_end
Whether the returned forecasts can go beyond the series' end or not
last_points_only
Whether to retain only the last point of each historical forecast.
If set to True, the method returns a single `TimeSeries` containing the successive point forecasts.
Otherwise returns a list of historical `TimeSeries` forecasts.
verbose
Whether to print progress
Returns
-------
TimeSeries or List[TimeSeries]
By default, a single TimeSeries instance created from the last point of each individual forecast.
If `last_points_only` is set to False, a list of the historical forecasts.
"""
if covariates is not None:
raise_if_not(
series.has_same_time_as(covariates),
'The provided series and covariates must have the same time index.'
)
# prepare the start parameter -> pd.Timestamp
start = get_timestamp_at_point(start, series)
# build the prediction times in advance (to be able to use tqdm)
if not overlap_end:
last_valid_pred_time = series.time_index()[-1 - forecast_horizon]
else:
last_valid_pred_time = series.time_index()[-2]
pred_times = [start]
while pred_times[-1] < last_valid_pred_time:
# compute the next prediction time and add it to pred times
pred_times.append(pred_times[-1] + series.freq() * stride)
# the last prediction time computed might have overshot last_valid_pred_time
if pred_times[-1] > last_valid_pred_time:
pred_times.pop(-1)
iterator = _build_tqdm_iterator(pred_times, verbose)
# Either store the whole forecasts or only the last points of each forecast, depending on last_points_only
forecasts = []
last_points_times = []
last_points_values = []
# TODO: We should find a better object oriented way of handling covariates in GlobalForecastingModel
fit_signature = signature(self.fit)
predict_signature = signature(self.predict)
# iterate and forecast
for pred_time in iterator:
train = series.drop_after(pred_time) # build the training series
if covariates is not None:
train_cov = covariates.drop_after(pred_time)
if retrain:
if covariates is not None and 'covariates' in fit_signature.parameters:
self.fit(series=train, covariates=train_cov)
else:
self.fit(series=train)
if covariates is not None and 'covariates' in predict_signature.parameters:
forecast = self.predict(n=forecast_horizon,
series=train,
covariates=train_cov)
else:
if 'series' in predict_signature.parameters:
forecast = self.predict(n=forecast_horizon, series=train)
else:
forecast = self.predict(n=forecast_horizon)
if last_points_only:
last_points_values.append(forecast.values()[-1])
last_points_times.append(forecast.end_time())
else:
forecasts.append(forecast)
if last_points_only:
return TimeSeries.from_times_and_values(
pd.DatetimeIndex(last_points_times),
np.array(last_points_values),
freq=series.freq() * stride)
return forecasts