Refresh a specification with constraints

Functions x13_refresh and regarima_refresh allow to create a new specification by updating a specification used for a previous estimation. Some selected parameters will be kept fixed (previous estimation results) while others will be freed for re-estimation in a domain of constraints. See details and examples.

Usage

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

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

Arguments

spec: the current specification to be refreshed ("result_spec").
refspec: the reference specification used to define the domain considered for re-estimation ("domain_spec"). By default this is the "RG5c" or "RSA5" specification.
policy: the refresh policy to apply (see details).
period, start, end: additional parameters used to specify the span on which additive outliers (AO) are introduced when policy = "Current" or to specify the span on which outliers will be re-detected when policy = "Outliers" or policy = "Outliers_StochasticComponent", is this case end is unused. If start is not specified, outliers will be re-identified on the whole series. Span definition: period: numeric, number of observations in a year (12, 4...). start and end: defined as arrays of two elements: year and first period (for example, period = 12 and c(1980, 1) stands for January 1980) The dates corresponding start and end are included in the span definition.

Value

a new specification, an object of class "JD3_X13_SPEC" or "JD3_REGARIMA_SPEC".

Details

The selection of constraints to be kept fixed or re-estimated is called a revision policy. User-defined parameters are always copied to the new refreshed specifications. In X-13 only the reg-arima part can be refreshed. X-11 decomposition will be completely re-run, keeping all the user-defined parameters from the original specification.

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);
Fixed: applying the current pre-adjustment reg-arima model and replacing forecasts by new raw data points;
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;
FreeParameters: all regression and Arima model coefficients are re-estimated, regression variables and Arima orders are kept fixed;
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;
Outliers_StochasticComponent: same as "Outliers" but Arima model orders (p,d,q)(P,D,Q) can also be re-identified;
Complete: All the parameters are re-identified and re-estimated, unless constrained in the domain spec.

References

More information on revision policies in JDemetra+ online documentation: https://jdemetra-new-documentation.netlify.app/a-rev-policies

Examples

# \donttest{
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
y_new <- window(y, end = c(2017, 6))

# specification for first estimation
spec_x13_1 <- x13_spec("rsa5c")

# first estimation
sa_x13 <- x13(y_raw, spec_x13_1)

# refreshing the specification
current_result_spec <- sa_x13$result_spec
current_domain_spec <- sa_x13$estimation_spec

# policy = "Fixed"
spec_x13_ref <- x13_refresh(current_result_spec, # point spec to be refreshed
    current_domain_spec, # domain spec (set of constraints)
    policy = "Fixed"
)
# 2nd estimation with refreshed specification
sa_x13_ref <- x13(y_new, spec_x13_ref)

# policy = "Outliers"
spec_x13_ref <- x13_refresh(current_result_spec,
    current_domain_spec,
    policy = "Outliers",
    period = 12,
    start = c(2017, 1)
) # outliers will be re-detected from January 2017 included
# 2nd estimation with refreshed specification
sa_x13_ref <- x13(y_new, spec_x13_ref)

# policy = "Current"
spec_x13_ref <- x13_refresh(current_result_spec,
    current_domain_spec,
    policy = "Current",
    period = 12,
    start = c(2017, 1),
    end = end(y_new)
)

# 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
sa_x13_ref <- x13(y_new, spec_x13_ref)

# Same procedure using regarima_refresh
# specification for first estimation
spec_1 <- regarima_spec("rg3")

# First estimation
reg_a_model <- regarima(y_raw, spec_1)
reg_a_model$estimation_spec
#> Specification
#> 
#> Series
#> Serie span: All 
#> Preliminary Check: Yes
#> 
#> Estimate
#> Model span: All 
#> 
#> Tolerance: 1e-07
#> 
#> Transformation
#> Function: AUTO
#> AIC difference: -2
#> Adjust: NONE
#> 
#> Regression
#> No calendar regressor
#> 
#> Easter: No
#> 
#> Pre-specified outliers: 0
#> Ramps: No
#> 
#> Outliers
#> Detection span: All 
#> Outliers type: 
#> 	- AO, critical value : 0 (Auto)
#> 	- LS, critical value : 0 (Auto)
#> 	- TC, critical value : 0 (Auto)
#> TC rate: 0.7 (Auto)
#> Method: ADDONE (Auto)
#> 
#> ARIMA
#> SARIMA model: (0,1,1) (0,1,1)
#> 
#> SARIMA coefficients:
#>  theta(1) btheta(1) 
#>         0         0 

# Refreshing the specification
current_result_spec <- reg_a_model$result_spec
current_domain_spec <- reg_a_model$estimation_spec

# Policy = "Fixed"
spec_1_ref <- regarima_refresh(
    current_result_spec, # point spec to be refreshed
    current_domain_spec, # domain spec (set of constraints)
    policy = "Fixed"
)
# 2nd estimation with refreshed specification
reg_a_model_ref <- regarima(y_new, spec_1_ref)
# }