R: Run x12 on an R TS-object

x12work {x12}

R 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/.

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)

[Package x12 version 1.10.3 Index]