MAPAForecaster

MAPAForecaster

class MAPAForecaster(aggregation_levels=None, base_forecaster=None, agg_method='mean', decompose_type='multiplicative', forecast_combine='mean', imputation_method='ffill', sp=6, weights=None)[source]

MAPAForecaster implements the Multiple Aggregation Prediction Algorithm (MAPA).

The MAPA method combines forecasts from different temporal aggregations of the time series to improve accuracy and robustness. It allows for multiple base forecasting methods and also supports various aggregation and combination strategies.

Implementation Details:

The algorithm works in the following steps:

1. Data Preparation:

   • Handles missing values using the specified imputation method

   • For multiplicative decomposition, ensures all values are positive by adding an offset if necessary

2. For each aggregation level:

   • Aggregates the time series using the specified method (mean/sum)

   • Determines if seasonal decomposition should be enabled:

     • Calculates seasonal_period as sp // level

     • seasonal_enabled is True if all these conditions are met:

       • The original seasonal period (sp) is divisible by the level

       • The calculated seasonal_period is > 1

       • The time series length is >= 2 * seasonal_period

     • seasonal_enabled is False if level >= sp

   • Decomposes the series using STL decomposition:

     • Extracts trend using rolling averages if seasonal_enabled=False

     • Uses STLTransformer if seasonal_enabled=True

     • Stores seasonal patterns for later use

   • Fits the base forecaster on the trend component

3. For prediction:

   • Generates forecasts using each level’s base forecaster

   • If seasonal_enabled for that level:

     • Retrieves stored seasonal pattern

     • Applies seasonal adjustments to forecasts

   • Combines forecasts from all levels using specified method:

     • Simple mean

     • Median

     • Weighted mean (if weights provided)

   • Reverses any transformations applied during data preparation

Based on R package: https://github.com/trnnick/mapa

Parameters:

aggregation_levelslist of int, default=None

The levels at which the time series will be aggregated. If None, the levels will default to [1, 2, 4].

For example, with daily data:

• Level 1: Original daily data

• Level 2: Aggregate every 2 days

• Level 4: Aggregate every 4 days

Lower levels capture short-term patterns while higher levels capture trends.

base_forecastersktime-compatible forecaster, default=None

The forecasting model to be used for each aggregation level.

If None, defaults to:

• ExponentialSmoothing(trend=”add”, seasonal=”add”, sp=sp) if statsmodel present

• NaiveForecaster(strategy=”mean”) if statsmodel not present

agg_methodstr, default=”mean”

Method used to aggregate the time series at different temporal levels.

Options are:

• “mean”: Takes average of the periods (e.g., average of each 2-day period)

• “sum”: Sums the values (useful for additive measures like sales)

decompose_typestr, default=”multiplicative”

The type of decomposition used in time series decomposition.

Options are:

• “additive”: Components are added (trend + seasonal + residual)

• “multiplicative”: Components are multiplied (trend * seasonal * residual)

forecast_combinestr, default=”mean”

Method used to combine the forecasts from different aggregation levels.

Options are:

• “mean”: Simple average of all forecasts

• “median”: Takes the median forecast

• “weighted_mean”: Uses supplied weights for weighted average

imputation_methodstr, default=”ffill”

Method used for imputing missing values in the time series.

Options include:

• “ffill”: Forward fill (propagate last valid observation forward)

• “bfill”: Backward fill (use next valid observation)

• “interpolate”: Linear interpolation between valid observations

spint, default=6

Seasonal periodicity of the time series.

weightslist of float, default=None

Optional weights to apply when combining forecasts. Only used if forecast_combine=”weighted_mean”. Must have same length as aggregation_levels. Weights are normalized to sum to 1.

Attributes:

cutoff

Cut-off = “present time” state of forecaster.

fh

Forecasting horizon that was passed.

is_fitted

Whether fit has been called.

state

State of the estimator.

Methods

check_is_fitted([method_name])	Check if the estimator has been fitted.
clone()	Obtain a clone of the object with same hyper-parameters and config.
clone_tags(estimator[, tag_names])	Clone tags from another object as dynamic override.
create_test_instance([parameter_set])	Construct an instance of the class, using first test parameter set.
create_test_instances_and_names([parameter_set])	Create list of all test instances and a list of names for them.
fit(y[, X, fh])	Fit forecaster to training data.
fit_predict(y[, X, fh, X_pred])	Fit and forecast time series at future horizon.
get_class_tag(tag_name[, tag_value_default])	Get class tag value from class, with tag level inheritance from parents.
get_class_tags()	Get class tags from class, with tag level inheritance from parent classes.
get_config()	Get config flags for self.
get_fitted_params([deep])	Get fitted parameters.
get_param_defaults()	Get object's parameter defaults.
get_param_names([sort])	Get object's parameter names.
get_params([deep])	Get a dict of parameters values for this object.
get_pretrained_params([deep])	Get pretrained parameters of this estimator.
get_tag(tag_name[, tag_value_default, ...])	Get tag value from instance, with tag level inheritance and overrides.
get_tags()	Get tags from instance, with tag level inheritance and overrides.
get_test_params([parameter_set])	Return testing parameter settings for the estimator.
is_composite()	Check if the object is composed of other BaseObjects.
load_from_path(serial)	Load object from file location.
load_from_serial(serial)	Load object from serialized memory container.
predict([fh, X])	Forecast time series at future horizon.
predict_interval([fh, X, coverage])	Compute/return prediction interval forecasts.
predict_proba([fh, X, marginal])	Compute/return fully probabilistic forecasts.
predict_quantiles([fh, X, alpha])	Compute/return quantile forecasts.
predict_residuals([y, X])	Return residuals of time series forecasts.
predict_var([fh, X, cov])	Compute/return variance forecasts.
pretrain(y[, X, fh])	Pre-train forecaster on panel (global) data.
reset()	Reset the object to a clean post-init state.
save([path, serialization_format])	Save serialized self to bytes-like object or to (.zip) file.
score(y[, X, fh])	Scores forecast against ground truth, using MAPE (non-symmetric).
set_config(**config_dict)	Set config flags to given values.
set_params(**params)	Set the parameters of this object.
set_random_state([random_state, deep, ...])	Set random_state pseudo-random seed parameters for self.
set_tags(**tag_dict)	Set instance level tag overrides to given values.
update(y[, X, update_params])	Update cutoff value and, optionally, fitted parameters.
update_predict(y[, cv, X, update_params, ...])	Make predictions and update model iteratively over the test set.
update_predict_single([y, fh, X, update_params])	Update model with new data and make forecasts.