Refresh a specification with constraints — refresh • rjd3tramoseats

Functions tramoseats_refresh and tramo_refresh allow to create a new specification by updating an existing one. Some selected parameters will be kept fixed while others will be freed within the boundaries of a reference specification. In practice each freed parameter of the specification to be updated (spec) is replaced by the corresponding parameter of the reference specification (refspec). See details and examples.

Usage

tramo_refresh(
  spec,
  refspec = NULL,
  policy = c("FreeParameters", "Complete", "Outliers_StochasticComponent", "Outliers",
    "FixedParameters", "FixedAutoRegressiveParameters", "Fixed", "Current"),
  period = 0,
  start = NULL,
  end = NULL
)

tramoseats_refresh(
  spec,
  refspec = NULL,
  policy = c("FreeParameters", "Complete", "Outliers_StochasticComponent", "Outliers",
    "FixedParameters", "FixedAutoRegressiveParameters", "Fixed", "Current"),
  period = 0,
  start = NULL,
  end = NULL
)

Arguments

spec: specification to be refreshed Object of class "JD3_tramoseats_SPEC" or "JD3_tramo_SPEC", can be obtained as an output of tramoseats_spec or tramo_spec and customised with set_ functions, see tramoseats_spec documentation
refspec: reference specification By default "rsa4" or "tr5" specification. Object of class "JD3_tramoseats_SPEC" or "JD3_tramo_SPEC", can be obtained as an output of tramoseats_spec or tramo_spec and customised with set_ functions, see tramoseats_spec documentation
policy: refresh policy to apply (see details)
period, start, end: additional parameters used to specify the span when policy = "Current" or policy = "Outliers" or policy = "Outliers_StochasticComponent" period: numeric, number of observations in a year (12, 4...), compulsory, if false or missing, re-estimation with refreshed specification won't work. When policy = "Outliers" or policy = "Outliers_StochasticComponent" start has to be specified as the date from which outliers will be re-identified end is not used, if specified it will be ignored. When policy = "Current" start and end have to be both specified and indicate the span on which additive outliers (AO) will be added. Span definition: start and end: defined as arrays of two elements: year and first period (for example, period = 12 and start=c(1980, 1) stands for January 1980)

Value

a new specification, an object of class "JD3_tramoseats_SPEC" or "JD3_tramo_SPEC".

Details

A particular selection of parameters to be kept fixed or re-estimated is called a revision policy.

Available refresh policies are:

Current: applying the current pre-adjustment reg-arima model and handling the new raw data points, or any sub-span of the series as Additive Outliers (defined as new intervention variables); SEATS and Benchmarking part parameters are untouched.
Fixed: applying the current pre-adjustment reg-arima model and replacing forecasts by new raw data points; SEATS and Benchmarking part parameters are untouched.
FixedParameters: pre-adjustment reg-arima model is partially modified: regression coefficients will be re-estimated but regression variables, Arima orders and coefficients are unchanged;
FixedAutoRegressiveParameters: same as FixedParameters but Arima Moving Average coefficients (MA) are also re-estimated, Auto-regressive (AR) coefficients are kept fixed; SEATS and Benchmarking part parameters are untouched.
FreeParameters: all regression and Arima model coefficients are re-estimated, regression variables and Arima orders are kept fixed; SEATS and Benchmarking part parameters are untouched.
Outliers: regression variables and Arima orders are kept fixed, but outliers will be re-detected on the defined span, thus all regression and Arima model coefficients are re-estimated; SEATS and Benchmarking part parameters are untouched.
Outliers_StochasticComponent: same as "Outliers" but Arima model orders (p,d,q)(P,D,Q) can also be re-identified; SEATS and Benchmarking part parameters are untouched.
Complete: All the parameters are re-identified and re-estimated, unless constrained in the domain spec. SEATS and Benchmarking part parameters are entirely reset to values in the reference spec.

References

More information on revision policies in JDemetra+ documentation: https://doc.jdemetra.org/a-rev-policies

Examples

if (FALSE) { # rjd3toolkit::get_java_version() >= rjd3toolkit::minimal_java_version
library("rjd3toolkit")
y <- rjd3toolkit::ABS$X0.2.08.10.M
# raw series for first estimation
y_raw <- window(y, end = c(2016, 12))
# raw series for second (refreshed) estimation: new data points
y_new <- window(y, end = c(2017, 6))
# \donttest{
# Example 1 : refresh mechanism
# Create reference spec, here the default "rsa3"
rsa3<- tramoseats_spec("rsa3")
# Customize this spec
## Tramo part
### For example, disable automatic arima modelling
user_spec <- set_automodel(rsa3, enabled = FALSE)
### set a user-defined arima model
user_spec <- set_arima(
   user_spec,
   mean = 0.2,
   mean.type = "Fixed",
   p = 1,
   d = 2,
   q = 0,
   bp = 1,
   bd = 1,
   bq = 0,
   coef = c(0.6, 0.7),
   coef.type = c("Initial", "Fixed")
)
#print(user_spec)

## Customize the x11 part
user_spec<-set_seats(user_spec,
                    fcasts = -2,
                    bcasts = -1,
                    trend.boundary=0.6,
                    seas.boundary=0.75,
                    algorithm= "KalmanSmoother")
#print(user_spec)
user_spec<- set_benchmarking(
   user_spec,
   enabled = TRUE,
   target = "Original",
   rho = 0.7,
   lambda = 0.5,
   forecast = TRUE,
   bias = "Multiplicative")
#print(user_spec)
# Use policy: "Outliers_StochasticComponent"
tramoseats_spec_ref <- tramoseats_refresh(spec= user_spec,
                           refspec= rsa3,
                           policy = "Outliers_StochasticComponent"
)
# print(tramoseats_spec_ref)
# user defined reg-arima model is reset and outliers will be re-identified
# on the whole series as no start and end specified, SEATS and Benchmarking parameters
# are left unchanged
# Use policy: "Complete"
tramoseats_spec_ref <- tramoseats_refresh(spec= user_spec,
                           refspec= rsa3,
                           policy = "Complete"
)
# print(tramoseats_spec_ref)
# all user defined parameters are reset and replaced with "rsa3" parameters,
# Example 2 : practical re-estimation use-case
sa_tramoseats <- tramoseats(y_raw, user_spec)
# refreshing the specification resulting from the first estimation
# to partially adapt to new data
spec_to_refresh <- sa_tramoseats$result_spec
reference_spec <- sa_tramoseats$estimation_spec
# policy = "Fixed"
spec_tramoseats_ref <- tramoseats_refresh(spec_to_refresh,
                            reference_spec,
                            policy = "Fixed"
)
# 2nd estimation with refreshed specification
sa_tramoseats_ref <- tramoseats(y_new, spec_tramoseats_ref)
# policy = "Outliers"
spec_tramoseats_ref <- tramoseats_refresh(spec_to_refresh,
                           reference_spec,
                           policy = "Outliers",
                           period = 12,
                           start = c(2017, 1)
)
# outliers will be re-detected from January 2017 included
# 2nd estimation with refreshed specification
sa_tramoseats_ref <- tramoseats(y_new, spec_tramoseats_ref)

# policy = "Current"

spec_tramoseats_ref <- tramoseats_refresh(spec_to_refresh,
                           reference_spec,
                           policy = "Current",
                           period = 12,
                           start = c(2017, 1),
                           end = end(y_new)
)
sa_tramoseats_ref <- tramoseats(y_new, spec_tramoseats_ref)
# }
# Points from January 2017 (included) until the end of the series will be
# treated as Additive Outliers, the previous reg-Arima model being otherwise
# kept fixed 2nd estimation with refreshed specification
}