Package 'MAPA' reference manual

Title:	Multiple Aggregation Prediction Algorithm
Description:	Functions and wrappers for using the Multiple Aggregation Prediction Algorithm (MAPA) for time series forecasting. MAPA models and forecasts time series at multiple temporal aggregation levels, thus strengthening and attenuating the various time series components for better holistic estimation of its structure. For details see Kourentzes et al. (2014) <doi:10.1016/j.ijforecast.2013.09.006>.
Authors:	Nikolaos Kourentzes [aut, cre], Fotios Petropoulos [aut]
Maintainer:	Nikolaos Kourentzes <[email protected]>
License:	GPL (>= 2)
Version:	2.0.6
Built:	2024-11-11 03:14:24 UTC
Source:	https://github.com/trnnick/mapa

Total Non-elective G&A Admissions (FFCEs)

Description

UK NHS Total Non-elective G&A Admissions (FFCEs). April 2008 – June 2013.

Usage

admissionsadmissions

Format

Time series data

Source

UK Department of Health: Monthly Activity Return

Examples

tsdisplay(admissions)
tsdisplay(admissions)

Multiple Aggregation Prediction Algorithm (Wrapper)

Description

Wrapper to estimate and produce MAPA in- and out-of-sample forecasts. Uses mapaest and mapafor.

Usage

mapa(y, ppy, fh=ppy, ifh=1, minimumAL=1, maximumAL=ppy, 
     comb=c("w.mean","w.median","mean","median","wght"), paral=c(0,1,2), 
     display=c(0,1), outplot=c(0,1), hybrid=c(TRUE,FALSE), model="ZZZ", 
     type=c("ets","es"), conf.lvl=NULL, xreg=NULL, pr.comp=0, ...)
mapa(y, ppy, fh=ppy, ifh=1, minimumAL=1, maximumAL=ppy, 
     comb=c("w.mean","w.median","mean","median","wght"), paral=c(0,1,2), 
     display=c(0,1), outplot=c(0,1), hybrid=c(TRUE,FALSE), model="ZZZ", 
     type=c("ets","es"), conf.lvl=NULL, xreg=NULL, pr.comp=0, ...)

Arguments

`y`	In sample observations of a time series (vector). If y == "paper" then it prints paper reference.
`ppy`	Periods in a season of the time series at the sampled frequency. If insample is a ts object then this is taken from its frequency, unless overriden.
`fh`	Forecast horizon. Default = ppy.
`ifh`	Lower aggregation level to use. Default = 1.
`minimumAL`	Lowest aggregation level to use. Default = 1.
`maximumAL`	Highest aggregation level to use. Default = ppy, maximumAL>1.
`comb`	Combination operator. This can be: "mean"; "median"; "wght" - where each aggregation level is weighted inversly to aggregation; "w.mean" - level and trend components are averaged, but seasonal and xreg follow the wght combination; "w.median" - as w.mean, but with median. It is suggested that for data with high sampling frequency to use one of the "w.mean" and "w.median".
`paral`	Use parallel processing. 0 = no; 1 = yes (requires initialised cluster); 2 = yes and initialise cluster. Default is 0.
`display`	Display calculation progress in console. 0 = no; 1 = yes. Default is 0.
`outplot`	Provide output plot. 0 = no; 1 = yes. Default is 1.
`hybrid`	Provide hybrid forecasts, as in Kourentzes et al. paper. If minimumAL > 1 then the minimumAL ETS forecasts are used. Default is TRUE.
`model`	Allow only that type of ETS at each aggregation level. This follows similar coding to the ets function. The first letter refers to the error type ("A", "M" or "Z"); the second letter refers to the trend type ("N","A","Ad","M","Md", "Z", "X" or "Y"); and the third letter refers to the season type ("N","A","M", "Z", "X" or "Y"). The letters mean: "N"=none, "A"=additive, "M"=multiplicative, "Z"=automatically selected, "X"=automatically select between none and additive and "Y"=automatically select between none and multiplicative. A "d" for trend implies damped. "X" and "Y" supported only by type=="es". If used with type=="ets" a warning will be given and they will default to "Z". By default model="ZZZ". If due to sample limitation ETS cannot be calculated at an aggregation level for the selected model, then no estimation is done for that specific level.
`type`	What type of exponential smoothing implementation to use. "es" = use from the smooth package; "ets" = use from the forecast package. Default is "es"
`conf.lvl`	Vector of confidence level for prediction intervals. Values must be (0,1). If conf.lvl == NULL then no intervals are calculated. For example to get the intervals for 80% and 95% use conf.lvl=c(0.8,0.95).
`xreg`	Vector or matrix of exogenous variables to be included in the MAPA. If matrix then rows are observations and columns are variables. Must be at least as long as in-sample. Additional observations are unused. Note that including xreg will force type="es".
`pr.comp`	MAPAx can use principal component analysis to preprocess xreg. When comp is -1 then the number of retained components is chosen automatically. When comp=0 then no pre-processing is performed and the original xreg is used. Any other value represents the number of principal components retained.
`...`	Pass additional arguments to es or ets.

Details

This function calls mapaest and mapafor internally.

Value

`infor`	In-sample forecasts.
`outfor`	Out-of-sample forecasts.
`PI`	Prediction intervals for given confidence levels.
`MSE`	In-sample MSE error.
`MAE`	In-sample MAE error.

Note

The calculation of the prediction intervals is based on the empirical multiple step ahead MSE. To speed up calculations set conf.lvl=NULL. If very long forecast horizons are requested then once no more t+h MSE can be calculated the following approximation is used: $\sqrt{MSE_{t+1}}*\sqrt{h}$ for the error.

Author(s)

Nikolaos Kourentzes, [email protected]; Fotios Petropoulos.

References

Kourentzes N., Petropoulos F., Trapero J.R. (2014) Improving forecasting by estimating time series structural components across multiple frequencies. International Journal of Forecasting, 30(2), 291–302.
Kourentzes N., Petropoulos F. (2015) Forecasting with multivariate temporal aggregation: The case of promotional modelling. International Journal of Production Economics.
You can find more information about MAPA at Nikos' blog.

Examples

out <- mapa(admissions)
out <- mapa(admissions)

MAPA Internal Calculation of Forecasts

Description

The following function produces a simple MAPA forecast from a given origin. This is meant to be an internal function. Use mapafor instead.

Usage

mapacalc(y, mapafit, fh = 0, comb = c("w.mean","w.median","mean","median","wght"), 
         outplot = c(0,1,2), hybrid = c(TRUE,FALSE), xreg=NULL)
mapacalc(y, mapafit, fh = 0, comb = c("w.mean","w.median","mean","median","wght"), 
         outplot = c(0,1,2), hybrid = c(TRUE,FALSE), xreg=NULL)

Arguments

`y`	In sample observations of a time series (vector).
`mapafit`	Fitted MAPA model (from mapaest).
`fh`	Forecast horizon. Default = ppy.
`comb`	Combination operator. This can be: "mean"; "median"; "wght" - where each aggregation level is weighted inversly to aggregation; "w.mean" - level and trend components are averaged, but seasonal and xreg follow the wght combination; "w.median" - as w.mean, but with median. It is suggested that for data with high sampling frequency to use one of the "w.mean" and "w.median".
`outplot`	Provide output plot. 0 = no; 1 = time series and forecast only; 2 = time series, forecasts and components. For the components the spectral colouring scheme is used. Dark red is aggregation level 1. Default is 1.
`hybrid`	Provide hybrid forecasts, as in Kourentzes et al. paper. If minimumAL > 1 then the minimumAL ETS forecasts are used. Default is TRUE.
`xreg`	Vector or matrix of exogenous variables to be included in the MAPA. If matrix then rows are observations and columns are variables. Must be at least as long as in-sample plus fh. Additional observations are unused.

Value

`forecasts`	Vector with forecasts.
`components`	Array with MAPA components.

Author(s)

Nikolaos Kourentzes, [email protected]; Fotios Petropoulos.

References

Kourentzes N., Petropoulos F., Trapero J.R. (2014) Improving forecasting by estimating time series structural components across multiple frequencies. International Journal of Forecasting, 30(2), 291–302.
Kourentzes N., Petropoulos F. (2015) Forecasting with multivariate temporal aggregation: The case of promotional modelling. International Journal of Production Economics.
You can find more information about MAPA at Nikos' blog.

Examples

mapafit <- mapaest(admissions,outplot=0)
mapacalc(admissions,mapafit,outplot=2)
mapafit <- mapaest(admissions,outplot=0)
mapacalc(admissions,mapafit,outplot=2)

MAPA Estimation

Description

The following function estimates MAPA and saves all fitted model.

Usage

mapaest(y, ppy, minimumAL = 1, maximumAL = ppy, paral = c(0,1,2), 
	      display = c(0,1), outplot = c(0,1), model = "ZZZ", type=c("ets","es"), 
	      xreg = NULL, pr.comp = 0, ...)
mapaest(y, ppy, minimumAL = 1, maximumAL = ppy, paral = c(0,1,2), 
	      display = c(0,1), outplot = c(0,1), model = "ZZZ", type=c("ets","es"), 
	      xreg = NULL, pr.comp = 0, ...)

Arguments

`y`	In sample observations of a time series (vector).
`ppy`	Periods in a season of the time series at the sampled frequency. If insample is a ts object then this is taken from its frequency, unless overriden.
`minimumAL`	Lowest aggregation level to use. Default = 1, maximumAL>1.
`maximumAL`	Highest aggregation level to use. Default = ppy.
`paral`	Use parallel processing. 0 = no; 1 = yes (requires initialised cluster); 2 = yes and initialise cluster. Default is 0.
`display`	Display calculation progress in console. 0 = no; 1 = yes. Default is 0.
`outplot`	Provide output plot. 0 = no; 1 = yes. Default is 0.
`model`	Allow only that type of ETS at each aggregation level. This follows similar coding to the ets function. The first letter refers to the error type ("A", "M" or "Z"); the second letter refers to the trend type ("N","A","Ad","M","Md", "Z", "X" or "Y"); and the third letter refers to the season type ("N","A","M", "Z", "X" or "Y"). The letters mean: "N"=none, "A"=additive, "M"=multiplicative, "Z"=automatically selected, "X"=automatically select between none and additive and "Y"=automatically select between none and multiplicative. A "d" for trend implies damped. "X" and "Y" supported only by type=="es". If used with type=="ets" a warning will be given and they will default to "Z". By default model="ZZZ". If due to sample limitation ETS cannot be calculated at an aggregation level for the selected model, then no estimation is done for that specific level. For aggregation levels that seasonality becomes 1 then a non-seasonal model is estimated.
`type`	What type of exponential smoothing implementation to use. "es" = use from the smooth package; "ets" = use from the forecast package. Default is "es"
`xreg`	Vector or matrix of exogenous variables to be included in the MAPA. If matrix then rows are observations and columns are variables. Must be at least as long as in-sample. Additional observations are unused. Note that including xreg will force type="es".
`pr.comp`	MAPAx can use principal component analysis to preprocess xreg. When comp is -1 then the number of retained components is chosen automatically. When comp=0 then no pre-processing is performed and the original xreg is used. Any other value represents the number of principal components retained.
`...`	Pass additional arguments to es or ets.

Value

mapafit

Estimated MAPA model structure.

Author(s)

Nikolaos Kourentzes, [email protected]; Fotios Petropoulos.

References

Kourentzes N., Petropoulos F., Trapero J.R. (2014) Improving forecasting by estimating time series structural components across multiple frequencies. International Journal of Forecasting, 30(2), 291–302.
Kourentzes N., Petropoulos F. (2015) Forecasting with multivariate temporal aggregation: The case of promotional modelling. International Journal of Production Economics.
You can find more information about MAPA at Nikos' blog.

Examples

mapafit <- mapaest(admissions)
mapafit <- mapaest(admissions)

MAPA Forecast

Description

The following function produces in- and out-of-sample MAPA forecasts, for multiple steps ahead. This is the recommended function to use in forecasting with MAPA.

Usage

mapafor(y, mapafit, fh = -1, ifh = 1, 
        comb = c("w.mean","w.median","mean","median","wght"), 
        outplot = c(0,1), hybrid = c(TRUE, FALSE), 
        conf.lvl = NULL, xreg=NULL)
mapafor(y, mapafit, fh = -1, ifh = 1, 
        comb = c("w.mean","w.median","mean","median","wght"), 
        outplot = c(0,1), hybrid = c(TRUE, FALSE), 
        conf.lvl = NULL, xreg=NULL)

Arguments

`y`	In sample observations of a time series (vector).
`mapafit`	Fitted MAPA model (from mapaest).
`fh`	Forecast horizon. Default = ppy.
`ifh`	In-sample forecast horizon. Default = 0.
`comb`	Combination operator. This can be: "mean"; "median"; "wght" - where each aggregation level is weighted inversly to aggregation; "w.mean" - level and trend components are averaged, but seasonal and xreg follow the wght combination; "w.median" - as w.mean, but with median. It is suggested that for data with high sampling frequency to use one of the "w.mean" and "w.median".
`outplot`	Provide output plot. 0 = no; 1 = yes. Default is 1.
`hybrid`	Provide hybrid forecasts, as in Kourentzes et al. paper. If minimumAL > 1 then the minimumAL ETS forecasts are used. Default is TRUE.
`conf.lvl`	Vector of confidence level for prediction intervals. Values must be (0,1). If conf.lvl == NULL then no intervals are calculated. For example to get the intervals for 80% and 95% use conf.lvl=c(0.8,0.95).
`xreg`	Vector or matrix of exogenous variables to be included in the MAPA. If matrix then rows are observations and columns are variables. Must be at least as long as in-sample plus fh. Additional observations are unused.

Value

`infor`	In-sample forecasts.
`outfor`	Out-of-sample forecasts.
`PI`	Prediction intervals for given confidence levels.
`MSE`	In-sample MSE error.
`MAE`	In-sample MAE error.

Note

Author(s)

Nikolaos Kourentzes, [email protected]; Fotios Petropoulos.

References

Kourentzes N., Petropoulos F., Trapero J.R. (2014) Improving forecasting by estimating time series structural components across multiple frequencies. International Journal of Forecasting, 30(2), 291–302.
Kourentzes N., Petropoulos F. (2015) Forecasting with multivariate temporal aggregation: The case of promotional modelling. International Journal of Production Economics.
You can find more information about MAPA at Nikos' blog.

Examples

mapafit <- mapaest(admissions,outplot=0)
out <- mapafor(admissions,mapafit)
mapafit <- mapaest(admissions,outplot=0)
out <- mapafor(admissions,mapafit)

MAPA Single Origin Forecast (Wrapper)

Description

The following function estimates MAPA and produces out-of-sample forecasts. It is not suggested, unless only simple single origin forecasts are required.

Usage

mapasimple(y, ppy=NULL, fh=ppy, minimumAL=1, maximumAL=ppy, 
           comb=c("w.mean","w.median","mean","median","wght"), 
           paral=c(0,1,2), display=c(0,1), 
           outplot=c(0,1), hybrid=c(TRUE,FALSE), model="ZZZ", 
           type=c("ets","es"), xreg=NULL, pr.comp=0, ...)
mapasimple(y, ppy=NULL, fh=ppy, minimumAL=1, maximumAL=ppy, 
           comb=c("w.mean","w.median","mean","median","wght"), 
           paral=c(0,1,2), display=c(0,1), 
           outplot=c(0,1), hybrid=c(TRUE,FALSE), model="ZZZ", 
           type=c("ets","es"), xreg=NULL, pr.comp=0, ...)

Arguments

`y`	In sample observations of a time series (vector). If y == "paper" then it prints paper reference.
`ppy`	Periods in a season of the time series at the sampled frequency. If insample is a ts object then this is taken from its frequency, unless overriden.
`fh`	Forecast horizon. Default = ppy.
`minimumAL`	Lowest aggregation level to use. Default = 1, maximumAL>1.
`maximumAL`	Highest aggregation level to use. Default = ppy.
`comb`	Combination operator. This can be: "mean"; "median"; "wght" - where each aggregation level is weighted inversly to aggregation; "w.mean" - level and trend components are averaged, but seasonal and xreg follow the wght combination; "w.median" - as w.mean, but with median. It is suggested that for data with high sampling frequency to use one of the "w.mean" and "w.median".
`paral`	Use parallel processing. 0 = no; 1 = yes (requires initialised cluster); 2 = yes and initialise cluster. Default is 0.
`display`	Display calculation progress in console. 0 = no; 1 = yes. Default is 0.
`outplot`	Provide output plot. 0 = no; 1 = time series and forecast only; 2 = time series, forecasts and components. For the components the spectral colouring scheme is used. Dark red is aggregation level 1. Default is 1.
`hybrid`	Provide hybrid forecasts, as in Kourentzes et al. paper. If minimumAL > 1 then the minimumAL ETS forecasts are used. Default is TRUE.
`model`	Allow only that type of ETS at each aggregation level. This follows similar coding to the ets function. The first letter refers to the error type ("A", "M" or "Z"); the second letter refers to the trend type ("N","A","Ad","M","Md", "Z", "X" or "Y"); and the third letter refers to the season type ("N","A","M", "Z", "X" or "Y"). The letters mean: "N"=none, "A"=additive, "M"=multiplicative, "Z"=automatically selected, "X"=automatically select between none and additive and "Y"=automatically select between none and multiplicative. A "d" for trend implies damped. "X" and "Y" supported only by type=="es". If used with type=="ets" a warning will be given and they will default to "Z". By default model="ZZZ". If due to sample limitation ETS cannot be calculated at an aggregation level for the selected model, then no estimation is done for that specific level. For aggregation levels that seasonality becomes 1 then a non-seasonal model is estimated.
`type`	What type of exponential smoothing implementation to use. "es" = use from the smooth package; "ets" = use from the forecast package. Default is "es"
`xreg`	Vector or matrix of exogenous variables to be included in the MAPA. If matrix then rows are observations and columns are variables. Must be at least as long as in-sample. Additional observations are unused. Note that including xreg will force type="es".
`pr.comp`	MAPAx can use principal component analysis to preprocess xreg. When comp is -1 then the number of retained components is chosen automatically. When comp=0 then no pre-processing is performed and the original xreg is used. Any other value represents the number of principal components retained.
`...`	Pass additional arguments to es or ets.

Details

This function calls mapaest and mapacalc internally.

Value

`forecasts`	Vector with forecasts.
`components`	Array with MAPA components, if output="all".

Author(s)

Nikolaos Kourentzes, [email protected]; Fotios Petropoulos.

References

Kourentzes N., Petropoulos F., Trapero J.R. (2014) Improving forecasting by estimating time series structural components across multiple frequencies. International Journal of Forecasting, 30(2), 291–302.
Kourentzes N., Petropoulos F. (2015) Forecasting with multivariate temporal aggregation: The case of promotional modelling. International Journal of Production Economics.
You can find more information about MAPA at Nikos' blog.

Examples

mapasimple(admissions)
mapasimple(admissions)

Produce estimated MAPA fit plot

Description

The following function plots the fitted components at each aggregation level of an estimated MAPA. The plot is the same as the one that can be produced optionally by mapaest.

Usage

  ## S3 method for class 'mapa.fit'
plot(x, xreg.plot=c(TRUE,FALSE),...)
## S3 method for class 'mapa.fit'
plot(x, xreg.plot=c(TRUE,FALSE),...)

Arguments

`x`	Fitted MAPA model (from mapaest).
`xreg.plot`	Add infromation about xreg in the figure.
`...`	Additional arguments.

Author(s)

Nikolaos Kourentzes, [email protected].

References

Kourentzes N., Petropoulos F., Trapero J.R. (2014) Improving forecasting by estimating time series structural components across multiple frequencies. International Journal of Forecasting, 30(2), 291–302.
Kourentzes N., Petropoulos F. (2015) Forecasting with multivariate temporal aggregation: The case of promotional modelling. International Journal of Production Economics.
You can find more information about MAPA at Nikos' blog.

Examples

mapafit <- mapaest(admissions,outplot=0)
plot(mapafit)
mapafit <- mapaest(admissions,outplot=0)
plot(mapafit)

Produce estimated MAPA fit plot (OBSOLETE!)

Description

The following function plots the fitted components at each aggregation level of an estimated MAPA. The plot is the same as the one that can be produced optionally by mapaest.

Usage

plotmapa(mapafit)
plotmapa(mapafit)

Arguments

mapafit

Fitted MAPA model (from mapaest).

Note

The function 'plotmapa' is deprecated. Use plot() instead.

Author(s)

Nikolaos Kourentzes, [email protected]; Fotios Petropoulos.

References

Kourentzes N., Petropoulos F., Trapero J.R. (2014) Improving forecasting by estimating time series structural components across multiple frequencies. International Journal of Forecasting, 30(2), 291–302.
Kourentzes N., Petropoulos F. (2015) Forecasting with multivariate temporal aggregation: The case of promotional modelling. International Journal of Production Economics.
You can find more information about MAPA at Nikos' blog.

Examples

mapafit <- mapaest(admissions,outplot=0)
plotmapa(mapafit)
mapafit <- mapaest(admissions,outplot=0)
plotmapa(mapafit)

Non-overlapping temporal aggregation

Description

Non-overlapping temporal aggregation.

Usage

tsaggr(y,fout,fmean=c(FALSE,TRUE),outplot=c(FALSE,TRUE))
tsaggr(y,fout,fmean=c(FALSE,TRUE),outplot=c(FALSE,TRUE))

Arguments

`y`	Time series vector (can be ts object).
`fout`	Vector containing desirable aggregation levels. Must be positive and integer. If larger than length(y) then it is ignored.
`fmean`	If TRUE the aggregated is done using mean, otherwise sum is used.
`outplot`	If TRUE a plot of the original series and the aggregated ones is produced.

Value

`out`	List of temporally aggregated series. If y was a ts object, then 'out' has ts objects with appropriate frequencies. Any non-integer frequency is set equal to 1. Series are named ALx, where x is the aggregation level.
`all`	An array containing all aggregated series in the original frequency. Series are named ALx, where x is the aggregation level.
`idx`	List of indices used to produce 'out' from 'all': y.out[[i]] <- y.all[y.idx[[i]],i]. Series are named ALx, where x is the aggregation level.

Author(s)

Nikolaos Kourentzes, [email protected].

Examples

out <- tsaggr(admissions,fout=2:12,fmean=TRUE,outplot=TRUE)
out <- tsaggr(admissions,fout=2:12,fmean=TRUE,outplot=TRUE)

Package 'MAPA'

Help Index

Total Non-elective G&A Admissions (FFCEs)

Description

Usage

Format

Source

Examples

Multiple Aggregation Prediction Algorithm (Wrapper)

Description

Usage

Arguments

Details

Value

Note

Author(s)

References

See Also

Examples

MAPA Internal Calculation of Forecasts

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

MAPA Estimation

Description

Usage

Arguments

Value

Author(s)

References

See Also

Examples

MAPA Forecast

Description

Usage

Arguments

Value

Note

Author(s)

References

See Also

Examples

MAPA Single Origin Forecast (Wrapper)

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Produce estimated MAPA fit plot

Description

Usage

Arguments

Author(s)

References

See Also

Examples

Produce estimated MAPA fit plot (OBSOLETE!)

Description

Usage

Arguments

Note

Author(s)

References

See Also

Examples

Non-overlapping temporal aggregation

Description

Usage

Arguments

Value

Author(s)