twoStepsBenchmark function

Regress and bends a time series with a lower frequency one

twoStepsBenchmark bends a time series with a time series of a lower frequency. The procedure involved is a Prais-Winsten regression, then an additive Denton benchmark.

Therefore, the resulting time series is the sum of a regression fit and of a smoothed part. The smoothed part minimizes the sum of squares of its differences.

The resulting time series is equal to the low-frequency series after aggregation within the benchmark window.

twoStepsBenchmark(hfserie,lfserie,include.differenciation=FALSE,include.rho=FALSE,
                  set.coeff=NULL,set.const=NULL,
                  start.coeff.calc=NULL,end.coeff.calc=NULL,
                  start.benchmark=NULL,end.benchmark=NULL,
                  start.domain=NULL,end.domain=NULL,outliers=NULL,
                  ...)

annualBenchmark(hfserie,lfserie,
                include.differenciation=FALSE,include.rho=FALSE,
                set.coeff=NULL,set.const=NULL,
                start.coeff.calc=start(lfserie)[1L],
                end.coeff.calc=end(lfserie)[1L],
                start.benchmark=start(lfserie)[1L],
                end.benchmark=end.coeff.calc[1L]+1L,
                start.domain=start(hfserie),
                end.domain=c(end.benchmark[1L]+2L,frequency(hfserie)),
                outliers=NULL)

Arguments

• hfserie: the bended time series. It can be a matrix time series.

• lfserie: a time series whose frequency divides the frequency of hfserie.

• include.differenciation: a boolean of length 1. If TRUE, lfserie and hfserie are differentiated before the estimation of the regression.

• include.rho: a boolean of length 1. If TRUE, the regression includes an autocorrelation parameter for the residuals. The applied procedure is a Prais-Winsten estimation.

• set.coeff: an optional numeric, that allows the user to set the regression coefficients instead of evaluating them. If hfserie is not a matrix, set.coeff can be an unnamed numeric of length 1. Otherwise, set.coeff has to be a named numeric, which will set the corresponding coefficients instead of evaluating them. Each column name of hfserie and each outlier set with the outlier arg initialize a coefficient with the same name, that can be set through set.coeff. The default name for a non-matrix time series is then "hfserie", By example, a LS2003 and the time series can be set using set.coeff=c(hfserie=3,LS2003=1).

• set.const: an optional numeric of length 1, that sets the regression constant. The constant is actually an automatically added column to hfserie. Using set.constant=3 is equivalent to using set.coeff=c(constant=3).

• start.coeff.calc: an optional start for the estimation of the coefficients of the regression. Should be a numeric of length 1 or 2, like a window for lfserie. If NULL, the start is defined by lfserie's window.

• end.coeff.calc: an optional end for the estimation of the coefficients of the regression. Should be a numeric of length 1 or 2, like a window for lfserie. If NULL, the end is defined by lfserie's window.

• start.benchmark: an optional start for lfserie to bend hfserie. Should be a numeric of length 1 or 2, like a window for lfserie. If NULL, the start is defined by lfserie's window.

• end.benchmark: an optional end for lfserie to bend hfserie. Should be a numeric of length 1 or 2, like a window for lfserie. If NULL, the start is defined by lfserie's window.

• start.domain: an optional for the output high-frequency series. It also defines the smoothing window : The low-frequency residuals will be extrapolated until they contain the smallest low-frequency window that is around the high-frequency domain window. Should be a numeric of length 1 or 2, like a window for hfserie. If NULL, the start is defined by hfserie's window.

• end.domain: an optional end for the output high-frequency series. It also defines the smoothing window : The low-frequency residuals will be extrapolated until they contain the smallest low-frequency window that is around the high-frequency domain window. Should be a numeric of length 1 or 2, like a window for hfserie. If NULL, the start is defined by hfserie's window.

• outliers: an optional named list of numeric vectors, whose pattern is like list(AO2008T2=c(0,0,3,2),LS2002=c(0.1,0.1,0.1,0.1)) where :

  • "AO" stands for additive outlier or "LS" for level shift
  • The integer that follows stands for the outlier starting year
  • an optional integer, preceded by the letter T, stands for the low-frequency cycle of the outlier start.
  • The numeric vector values stands for the disaggregated value of the outlier and its length must be a multiple of hf / lf

  The outliers coefficients are evaluated though the regression process, like any coefficient. Therefore, if any outlier is outside of the coefficient calculation window, it should be fixed using set.coeff.

• ...: if the dots contain a cl item, its value overwrites the value of the returned call. This feature allows to build wrappers.

Returns

twoStepsBenchark returns an object of class "twoStepsBenchmark".

The function summary can be used to obtain and print a summary of the regression used by the benchmark. The functions plot and autoplot (the generic from ggplot2) produce graphics of the benchmarked serie and the bending serie. The functions in_disaggr , in_revisions , in_scatter

produce comparisons on which plot and autoplot can also be used.

The generic accessor functions as.ts, prais, coefficients, residuals, fitted.values, model.list, se, rho extract various useful features of the returned value.

An object of class "twoStepsBenchmark" is a list containing the following components : - benchmarked.serie: a time series, that is the result of the benchmark. It is equal to fitted.values + smoothed.part.

• fitted.values: a time series, that is the high-frequency series as it is after having applied the regression coefficients. Compared to the fitted values of the regression, which can be retrieved inside the regression component, it has a high-frequency time series and can eventually be integrated if include.differenciation is TRUE.

• regression: an object of class praislm, it is the regression on which relies the benchmark. It can be extracted with the function prais

• smoothed.part: the smoothed part of the two-steps benchmark. It is the smoothed difference between the fitted.values and lfserie.

• model.list: a list containing all the arguments submitted to the function.

• call: the matched call (either of twoStepsBenchmark or annualBenchmark)

Details

annualBenchmark is a wrapper of the main function, that applies more specifically to annual series, and changes the default window parameters to the ones that are commonly used by quarterly national accounts.

Examples

## How to use annualBenchmark or twoStepsBenchark

benchmark <- twoStepsBenchmark(hfserie = turnover,
                               lfserie = construction,
                               include.differenciation = TRUE)
as.ts(benchmark)
coef(benchmark)
summary(benchmark)
library(ggplot2)
autoplot(in_sample(benchmark))

## How to manually set the coefficient

benchmark2 <- twoStepsBenchmark(hfserie = turnover,
                                lfserie = construction,
                                include.differenciation = TRUE,
                                set.coeff = 0.1)
coef(benchmark2)