twoStepsBenchmark {disaggR}R Documentation

Regress and bends a time-serie with a lower frequency one

Description

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

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

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

Usage

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-serie. It can be a matrix time-serie.

lfserie

a time-serie whose frequency divides the frequency of hfserie.

include.differenciation

a boolean of length 1. If TRUE, lfserie and hfserie are differenced 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-serie is then "hfserie", By example, a LS2003 and the time-serie 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 serie. 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 serie. 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 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 to 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.

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.

Value

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-serie, that is the result of the benchmark.

fitted.values

a time-serie, that is the high-frequency serie as it is after having applied the regression coefficients. The difference benchmarked.serie - fitted.values is then a smoothed residual, eventually integrated if include.differenciation=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.

model.list

a list containing all the arguments submitted to the function.

call

the matched call (either of twoStepsBenchmark or annualBenchmark)

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)


[Package disaggR version 1.0.1 Index]