x12work: Run x12 on an R TS-object

View source: R/x12work.R

x12workR Documentation

Run x12 on an R TS-object

Description

A wrapper function for the x12 binaries. It creates a specification file for an R time series and runs x12, afterwards the output is read into R.

Usage

x12work(tso,period=frequency(tso),file="Rout",
  series.span=NULL,series.modelspan=NULL,
 	transform.function="auto",transform.power=NULL,transform.adjust=NULL,
	regression.variables=NULL,regression.user=NULL,regression.file=NULL,
	regression.usertype=NULL,regression.centeruser=NULL,regression.start=NULL,
	regression.aictest=NULL,
	outlier.types=NULL,outlier.critical=NULL,outlier.span=NULL,outlier.method=NULL,
	identify=FALSE,identify.diff=NULL,identify.sdiff=NULL,identify.maxlag=NULL,
	arima.model=NULL,arima.smodel=NULL,arima.ar=NULL,arima.ma=NULL,
	automdl=FALSE,automdl.acceptdefault=FALSE,automdl.balanced=TRUE,
	automdl.maxorder=c(3,2),automdl.maxdiff=c(1,1),
	forecast_years=NULL,backcast_years=NULL,forecast_conf=.95,
	forecast_save="ftr",
	estimate=FALSE,estimate.outofsample=TRUE,
	check=TRUE,check.maxlag=NULL,
	slidingspans=FALSE,
	slidingspans.fixmdl=NULL,slidingspans.fixreg=NULL,
	slidingspans.length=NULL,slidingspans.numspans=NULL,
	slidingspans.outlier=NULL,
	slidingspans.additivesa=NULL,slidingspans.start=NULL,
	history=FALSE,
	history.estimates=NULL,history.fixmdl=FALSE,
	history.fixreg=NULL,history.outlier=NULL,
	history.sadjlags=NULL,history.trendlags=NULL,
	history.start=NULL,history.target=NULL,
	x11.sigmalim=c(1.5,2.5),x11.type=NULL,x11.sfshort=FALSE,x11.samode=NULL,
	x11.seasonalma=NULL,x11.trendma=NULL,
	x11.appendfcst=TRUE,x11.appendbcst=FALSE,x11.calendarsigma=NULL,
	x11.excludefcst=TRUE,x11.final="user",
	x11regression=FALSE,
	tblnames=NULL,Rtblnames=NULL,
	x12path=NULL,use="x12",keep_x12out=TRUE,showWarnings=TRUE)

		

Arguments

tso

a time series object.

period

frequency of the time series.

file

path to the output directory and filename, default is the working directory and Rout.*.

series.span

vector of length 4, limiting the data used for the calculations and analysis to a certain time interval.
Start and end date of said time interval can be specified by 4 integers in the format c(start year, start seasonal period, end year, end seasonal period) If the start or end date of the time series object should be used, the respective year and seasonal period are to be set to NA.

series.modelspan

vector of length 4, defining the start and end date of the time interval of the data that should be used to determine all regARIMA model coefficients. Specified in the same way as span.

transform.function

transform parameter for x12 ("auto", "log", "none").

transform.power

numeric value specifying the power of the Box Cox power transformation.

transform.adjust

determines the type of adjustment to be performed, i.e. transform.adjust="lom" for length-of-month adjustment on monthly data, transform.adjust="loq" for length-of-quarter adjustment on quarterly data or transform.adjust="lpyear" for leap year adjustment of monthly or quarterly data (which is only allowed when either transform.power=0 or transform.function="log").

regression.variables

character or character vector representing the names of the regression variables.

regression.user

character or character vector defining the user parameters in the regression argument.

regression.file

path to the file containing the data values of all regression.user variables.

regression.usertype

character or character vector assigning a type of model-estimated regression effect on each user parameter in the regression argument ("seasonal", "td", "lpyear", "user", ...).
By specifying a character vector of length greater one each variable can be given its own type. Otherwise the same type will be used for all user parameters.

regression.centeruser

character specifying the removal of the (sample) mean or the seasonal means from the user parameters in the regression argument ("mean", "seasonal").
Default is no modification of the respective user-defined regressors.

regression.start

start date for the values of the regression.user variables, specified as a vector of two integers in the format c(year, seasonal period).

regression.aictest

character vector defining the regression variables for which an AIC test is to be performed.

outlier.types

to enable the "outlier" specification in the spc file, this parameter has to be defined by a character or character vector determining the method(s) used for outlier detection ("AO", "LS", "TC", "all").

outlier.critical

number specifying the critical value used for outlier detection (same value used for all types of outliers) or named list (possible names of list elements being AO,LS and TC) where each list element specifies the respective critical value used for detecting the corresponding type of outlier.
If not specified, the default critical value is used.

outlier.span

vector of length 2, defining the span for outlier detection.

outlier.method

character determining how detected outliers should be added to the model ("addone", "addall"). If not specified,"addone" is used by default.

identify

Object of class "logical" - if TRUE, the "identify" specification will be enabled in the spc file.

identify.diff

number or vector representing the orders of nonseasonal differences specified, default is 0.

identify.sdiff

number or vector representing the orders of seasonal differences specified, default is 0.

identify.maxlag

number of lags specified for the ACFs and PACFs, default is 36 for monthly series and 12 for quarterly series.

arima.model

vector of length 3, defining the arima parameters.

arima.smodel

vector of length 3, defining the sarima parameters.

arima.ar

numeric or character vector specifying the initial values for nonseasonal and seasonal autoregressive parameters in the order that they appear in the arima.model argument. Empty positions are created with NA.

arima.ma

numeric or character vector specifying the initial values for all moving average parameters in the order that they appear in the arima.model argument. Empty positions are created with NA.

automdl

TRUE/FALSE for activating auto modeling.

automdl.acceptdefault

logical for automdl defining whether the default model should be chosen if the Ljung-Box Q statistic for its model residuals is acceptable.

automdl.balanced

logical for automdl defining whether the automatic model procedure will tend towards balanced models. TRUE yields the same preference as the TRAMO program.

automdl.maxorder

vector of length 2, maximum order for automdl. Empty positions are created with NA.

automdl.maxdiff

vector of length 2, maximum diff. order for automdl. Empty positions are created with NA.

forecast_years

number of years to forecast, default is 1 year.

backcast_years

number of years to backcast, default is no backcasts.

forecast_conf

probability for the confidence interval of forecasts

forecast_save

character either "ftr"(in transformed scaling) or "fct"(in original scaling)

estimate

if TRUE, the term "estimate" will be added to the spc file.

estimate.outofsample

logical defining whether "out of sample" or "within sample" forecast errors should be used in calculating the average magnitude of forecast errors over the last three years.

check

TRUE/FALSE for activating the "check" specification in the spc file.

check.maxlag

the number of lags requested for the residual sample ACF and PACF, default is 24 for monthly series and 8 for quarterly series.

slidingspans

if TRUE, "slidingspans" specification will be enabled in the spc file.

slidingspans.fixmdl

("yes" (default), "no", "clear").

slidingspans.fixreg

character or character vector specifying the trading day, holiday, outlier or other user-defined regression effects to be fixed ("td", "holiday", "outlier", "user"). All other regression coefficients will be re-estimated for each sliding span.

slidingspans.length

numeric value specifying the length of each span in months or quarters (>3 years, <17 years).

slidingspans.numspans

numeric value specifying the number of sliding spans used to generate output for comparisons (must be between 2 and 4, inclusive).

slidingspans.outlier

("keep" (default), "remove", "yes").

slidingspans.additivesa

("difference" (default), "percent").

slidingspans.start

specified as a vector of two integers in the format c(start year, start seasonal period).

history

if TRUE, the history specification will be enabled.

history.estimates

character or character vector determining which estimates from the regARIMA modeling and/or the x11 seasonal adjustment will be analyzed in the history analysis ("sadj" (default), "sadjchng", "trend", "trendchng", "seasonal", "aic", "fcst").

history.fixmdl

logical determining whether the regARIMA model will be re-estimated during the history analysis.

history.fixreg

character or character vector specifying the trading day, holiday, outlier or other user-defined regression effects to be fixed ("td", "holiday", "outlier", "user"). All other coefficients will be re-estimated for each history span.

history.outlier

("keep" (default), "remove", "auto")

history.sadjlags

integer or vector specifying up to 5 revision lags (each >0) that will be analyzed in the revisions analysis of lagged seasonal adjustments.

history.trendlags

integer or vector specifying up to 5 revision lags (each >0) that will be used in the revision history of the lagged trend components.

history.start

specified as a vector of two integers in the format c(start year, start seasonal period).

history.target

character determining whether the revisions of the seasonal adjustments and trends calculated at the lags specified in history.sadjlags and history.trendlags should be defined by the deviation from the concurrent estimate or the deviation from the final estimate ("final" (default), "concurrent").

x11.sigmalim

vector of length 2, defining the limits for sigma in the x11 methodology, used to downweight extreme irregular values in the internal seasonal adjustment iterations.

x11.type

character, i.e. "summary", "trend" or "sa". If x11.type="trend", x11 will only be used to estimate the final trend-cycle as well as the irregular components and to adjust according to trading days. The default setting is type="sa" where a seasonal decomposition of the series is calculated.

x11.sfshort

logical controlling the seasonal filter to be used if the series is at most 5 years long. If TRUE, the arguments of the seasonalma filter will be used wherever possible. If FALSE, a stable seasonal filter will be used irrespective of seasonalma.

x11.samode

character defining the type of seasonal adjustment decomposition calculated ("mult", "add", "pseudoadd", "logadd").

x11.seasonalma

character or character vector of the format c("snxm","snxm", ...) defining which seasonal nxm moving average(s) should be used for which calendar months or quarters to estimate the seasonal factors. If only one ma is specified, the same ma will be used for all months or quarters. If not specified, the program will invoke an automatic choice.

x11.trendma

integer defining the type of Henderson moving average used for estimating the final trend cycle. If not specified, the program will invoke an automatic choice.

x11.appendfcst

logical defining whether forecasts should be included in certain x11 tables.

x11.appendbcst

logical defining whether forecasts should be included in certain x11 tables.

x11.calendarsigma

regulates the way the standard errors used for the detection and adjustment of extreme values should be computed ("all", "signif", "select" or no specification).

x11.excludefcst

logical defining if forecasts and backcasts from the regARIMA model should not be used in the generation of extreme values in the seasonal adjustment routines.

x11.final

character or character vector specifying which type(s) of prior adjustment factors should be removed from the final seasonally adjusted series ("AO", "LS", "TC", "user", "none").

x11regression

if TRUE, x11Regression will be performed using the respective regression and outlier commands above, i.e. regression.variables, regression.user, regression.file, regression.usertype, regression.centeruser and regression.start as well as outlier.critical, outlier.span and outlier.method.

tblnames

character vector of additional tables to be read into R.

Rtblnames

character vector naming the additional tables.

x12path

path to the x12 binaries, for example d:\x12a\x12a.exe.

use

"x12" or "x13", at the moment only "x12" is tested properly.

keep_x12out

if TRUE, the output files generated by x12 are stored in the folder "gra" in the output directory and are not deleted at the end of a successful run.

showWarnings

logical defining whether warnings and notes generated by x12 should be returned. Errors will be displayed in any case.

Details

Generates an x12 specification file, runs x12 and reads the output files.

Value

x12work returns an object of class "x12".

The function summary is used to print a summary of the diagnostics results.

An object of class "x12" is a list containing at least the following components:

a1

original time series

d10

final seasonal factors

d11

final seasonally adjusted data

d12

final trend cycle

d13

final irregular components

d16

combined adjustment factors

c17

final weights for irregular component

d9

final replacements for SI ratios

e2

differenced, transformed, seasonally adjusted data

d8

final unmodified SI ratios

b1

prior adjusted original series

forecast

point forecasts with prediction intervals

backcast

point backcasts with prediction intervals

dg

a list containing several seasonal adjustment and regARIMA modeling diagnostics, i.e.:
x11regress, transform, samode, seasonalma, trendma, arimamdl, automdl, regmdl, nout, nautoout, nalmostout, almostoutlier, crit, outlier, userdefined, autooutlier, peaks.seas, peaks.td, id.seas, id.rsdseas, spcrsd, spcori, spcsa, spcirr, q, q2, nmfail, loglikelihood, aic, aicc, bic, hq, aape, autotransform, ifout, res.acf, res.pacf, res.acf2,...

file

path to the output directory and filename

tblnames

tables read into R

Rtblnames

names of tables read into R

Note

Only working with available x12 binaries.

Author(s)

Alexander Kowarik, Angelika Meraner

Source

https://www.census.gov/data/software/x13as.html

References

Alexander Kowarik, Angelika Meraner, Matthias Templ, Daniel Schopfhauser (2014). Seasonal Adjustment with the R Packages x12 and x12GUI. Journal of Statistical Software, 62(2), 1-21. URL http://www.jstatsoft.org/v62/i02/.

See Also

x12, ts, summary.x12work, plot.x12work, x12-methods

Examples

### Examples
data(AirPassengers)
## Not run: 
x12out <- x12work(AirPassengers,x12path=".../x12a.exe",transform.function="auto",
		arima.model=c(0,1,1),arima.smodel=c(0,1,1),regression.variables="lpyear",
		x11.sigmalim=c(2.0,3.0),outlier.types="all",outlier.critical=list(LS=3.5,TC=3),
		x11.seasonalma="s3x3")
summary(x12out)
## End(Not run)	

statistikat/x12 documentation built on May 21, 2022, 8:01 a.m.