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]