[Y,OutpFile,ErrFile,Model,X] = x12(X,...)
[Y,OutpFile,ErrFile,Model,X] = x12(X,Range,...)
[Y1,Y2,...,OutpFile,ErrFile,Model,X] = x12(X,Range,...)
See the option 'output='
for the types of output data available from X12.
X
[ tseries ] - Input data that will seasonally adjusted or filtered by the Census X12 Arima.
Range
[ numeric ] - Date range on which the X12 will be run; if not specified or Inf the entire available range will be used.
Y
, Y1
, Y2
, ... [ tseries ] - Requested output data, by default only one type of output is returned, the seasonlly adjusted data; see the option 'output='
.
OutpFile
[ cellstr ] - Contents of the output log files produced by X12; each cell contains the log file for one type of output requested.
ErrFile
[ cellstr ] - Contents of the error files produced by X12; each cell contains the error file for one type of output requested.
Model
[ struct ] - Struct array with model specifications and parameter estimates for each of the ARIMA models fitted; Model
matches the size of X
is 2nd and higher dimensions.
X
[ tseries ] - Original input data with forecasts and/or backcasts appended if the options 'forecast='
and/or 'backcast='
are used.
'backcast='
[ numeric | 0
] - Run a backcast based on the fitted ARIMA model for this number of periods back to improve on the seasonal adjustment; see help on the x11
specs in the X13-ARIMA-SEATS manual. The backcast is included in the output argument X
.
'cleanup='
[ true
| false
] - Delete temporary X12 files when done; the temporary files are named iris_x12a.*
.
'log='
[ true
| false
] - Logarithmise the input data before, and de-logarithmise the output data back after, running x12
.
'forecast='
[ numeric | 0
] - Run a forecast based on the fitted ARIMA model for this number of periods ahead to improve on the seasonal adjustment; see help on the x11
specs in the X13-ARIMA-SEATS manual. The forecast is included in the output argument X
.
'display='
[ true
| false
] - Display X12 output messages in command window; if false the messages will be saved in a TXT file.
'dummy='
[ tseries | empty ] - User dummy variable or variables (in case of a multivariate tseries object) used in X13-ARIMA-SEATS regression; the dummy variables must also include values for forecasts and backcasts if you request them; the type of the dummy can be specified in the option 'dummyType='
.
'dummyType='
[ 'ao'
| 'holiday'
| 'td'
] - Type of the user dummy (which is specified through the option 'dummy='
); the three basic types of dummies are additive outlier ('ao'
), holiday flows ('holiday'
), and trading days ('td'
); see the X13-ARIMA-SEATS or X13-ARIMA documentation for more details (available from the U.S.Census Bureau website), look for the section on the REGRESSION spec, options 'user' and 'usertype'.
'mode='
[ 'auto'
| 'add'
| 'logadd'
| 'mult'
| 'pseudoadd'
| 'sign'
] - Seasonal adjustment mode (see help on the x11
specs in the X13-ARIMA-SEATS manual); 'auto'
means that series with only positive or only negative numbers will be adjusted in the 'mult'
(multiplicative) mode, while series with combined positive and negative numbers in the 'add'
(additive) mode.
'maxIter='
[ numeric | 1500
] - Maximum number of iterations for the X12 estimation procedure. See help on the estimation
specs in the X13-ARIMA-SEATS manual.
'maxOrder='
[ numeric | [2,1]
] - A 1-by-2 vector with maximum order for the regular ARMA model (can be 1
, 2
, 3
, or 4
) and maximum order for the seasonal ARMA model (can be 1
or 2
). See help on the automdl
specs in the X13-ARIMA-SEATS manual.
'missing=' [ true
| false
] - Allow for in-sample missing observations, and fill in values predicted by an estimated ARIMA process; if false
, the seasonal adjustment will not run and a warning will be thrown.
'output='
[ char | cellstr | 'SA'
] - List of requested output data; the cellstr or comma-separated list can combine any number of the request specifications listed below in subsection Output request; See also help on the x11
specs in the X13-ARIMA-SEATS manual.
'saveAs='
[ char | empty ] - Name (or a whole path) under which X13-ARIMA-SEATS output files will be saved.
'specFile='
[ char | 'default'
] - Name of the X13-ARIMA-SEATS spec file; if 'default'
the IRIS default spec file will be used, see description.
'tdays='
[ true
| false
] - Correct for the number of trading days. See help on the x11regression
specs in the X13-ARIMA-SEATS manual.
'tempDir='
[ char | function_handle | '.'
] - Directory in which X13-ARIMA-SEATS temporary files will be created; if the directory does not exist, it will be created at the beginning and deleted at the end of the execution (unless 'cleanup=' false
).
'tolerance='
[ numeric | 1e-5
] - Convergence tolerance for the X13 estimation procedure. See help on the estimation
specs in the X13-ARIMA-SEATS manual.
The option `'output=' can combine any number of the following requests:
'SA'
- seasonally adjusted series;
'SF'
- seasonal factors;
'TC'
- trend-cycle component;
'IR'
- irregular component;
'MV'
- the original input series with missing values fitted by running an estimated ARIMA model.
If you keep 'missing=' false
(this is the default for backward compatibility), x12
will not run on series with in-sample missing observations, and a warning will be thrown.
If you set 'missing=' true
, you allow for in-sample missing observations. The X13-ARIMA-SEATS program handles missing observations by filling in values predicted by the estimated ARIMA process. You can request the series with missing values filled in by including MV
in the option 'output='
.
The default X13-ARIMA-SEATS spec file is +thirdparty/x12/default.spc
. You can create your own spec file to include options that are not available through the IRIS interface. You can use the following pre-defined placeholders letting IRIS fill in some of the information needed (check out the default file):
$series_data$
is replaced with a column vector of input observations;$series_freq$
is replaced with a number representing the date frequency: either 4 for quarterly, or 12 for monthly (other frequencies are currenlty not supported by X13-ARIMA-SEATS);$series_startyear$
is replaced with the start year of the input series;$series_startper$
is replaced with the start quarter or month of the input series;$transform_function$
is replaced with log
or none
depending on the mode selected by the user;$forecast_maxlead$
is replaced with the requested number of ARIMA forecast periods used to extend the series before seasonal adjustment.$forecast_maxlead$
is replaced with the requested number of ARIMA forecast periods used to extend the series before seasonal adjustment.$tolerance$
is replaced with the requested convergence tolerance in the estimation
spec.$maxiter$
is replaced with the requested maximum number of iterations in the estimation
spec.$maxorder$
is replaced with two numbers separated by a blank space: maximum order of regular ARIMA, and maximum order of seasonal ARIMA.$x11_mode$
is replaced with the requested mode: 'add'
for additive, 'mult'
for multiplicative, 'pseudoadd'
for pseudo-additive, or 'logadd'
for log-additive;$x12_save$
is replaced with the list of the requested output series: 'd10'
for seasonals, 'd11'
for final seasonally adjusted series, 'd12'
for trend-cycle, 'd13'
for irregular component.Two of the placeholders, '$series_data$
and $x12_output$
, are required; if they are not found in the spec file, IRIS throws an error.
The ARIMA model specification, Model
, is a struct with three fields:
.spec
- a cell array with the first cell giving the structure of the non-seasonal ARIMA, and the second cell giving the structure of the seasonal ARIMA; both specifications follow the usual Box-Jenkins notation, e.g. [0 1 1]
.
.ar
- a numeric array with the point estimates of the AR coefficients (non-seasonal and seasonal).
.ma
- a numeric array with the point estimates of the MA coefficients (non-seasonal and seasonal).
If you wish to run x12
on the entire range on which the input time series is defined, and do not use any options, you can omit the second input argument (the date range). These following three calls to x12
do exactly the same:
xsa = x12(x);
xsa = x12(x,Inf);
xsa = x12(x,get(x,'range'));
If you wish to specify some of the options, you have to enter a date range or use Inf
:
xsa = x12(x,Inf,'mode=','add');