

    \filetitle{x12}{Access to X12 seasonal adjustment program}{tseries/x12}

	\paragraph{Syntax with a single type of output requested}
 
 \begin{verbatim}
 [Y,OUTPUTFILE,ERRORFILE,MODEL,X] = x12(X)
 [Y,OUTPUTFILE,ERRORFILE,MODEL,X] = x12(X,RANGE,...)
 \end{verbatim}
 \paragraph{Syntax with mutliple types of output requested}
 
 \begin{verbatim}
 [Y1,Y2,...,OUTPUTFILE,ERRORFILE,MODEL,X] = x12(X,RANGE,...)
 \end{verbatim}
 See the option \texttt{'output='} for the types of output data available
 from X12.
 
 \paragraph{Input arguments}
 
 \begin{itemize}
 \item
   \texttt{X} {[} tseries {]} - Input data that will seasonally adjusted
   or filtered by the Census X12 Arima.
 \item
   \texttt{RANGE} {[} numeric {]} - Date range on which the X12 will be
   run; if not specified or Inf the entire available range will be used.
 \end{itemize}
 \paragraph{Output arguments}
 
 \begin{itemize}
 \item
   \texttt{Y}, \texttt{Y1}, \texttt{Y2}, \ldots{} {[} tseries {]} -
   Requested output data, by default only one type of output is returned,
   the seasonlly adjusted data; see the option \texttt{'output='}.
 \item
   \texttt{OUTPUTFILE} {[} cellstr {]} - Contents of the output log files
   produced by X12; each cell contains the log file for one type of
   output requested.
 \item
   \texttt{ERRORFILE} {[} cellstr {]} - Contents of the error files
   produced by X12; each cell contains the error file for one type of
   output requested.
 \item
   \texttt{MODEL} {[} struct {]} - Struct array with model specifications
   and parameter estimates for each of the ARIMA models fitted;
   \texttt{MODEL} matches the size of \texttt{X} is 2nd and higher
   dimensions.
 \item
   \texttt{X} {[} tseries {]} - Original input data with forecasts and/or
   backcasts appended if the options \texttt{'forecast='} and/or
   \texttt{'backcast='} are used.
 \end{itemize}
 \paragraph{Options}
 
 \begin{itemize}
 \item
   \texttt{'backcast='} {[} numeric \textbar{} \emph{\texttt{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
   \texttt{x11} specs in the X12-ARIMA manual. The backcast is included
   in the output argument \texttt{X}.
 \item
   \texttt{'cleanup='} {[} \emph{\texttt{true}} \textbar{} \texttt{false}
   {]} - Delete temporary X12 files when done; the temporary files are
   named \texttt{iris\_x12a.*}.
 \item
   \texttt{'log='} {[} \texttt{true} \textbar{} \emph{\texttt{false}} {]}
   - Logarithmise the input data before, and de-logarithmise the output
   data back after, running \texttt{x12}.
 \item
   \texttt{'forecast='} {[} numeric \textbar{} \emph{\texttt{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
   \texttt{x11} specs in the X12-ARIMA manual. The forecast is included
   in the output argument \texttt{X}.
 \item
   \texttt{'display='} {[} \texttt{true} \textbar{} \emph{\texttt{false}}
   {]} - Display X12 output messages in command window; if false the
   messages will be saved in a TXT file.
 \item
   \texttt{'dummy='} {[} tseries \textbar{} \emph{empty} {]} - Dummy
   variable or variables (in case of a multivariate tseries object) used
   in X12-ARIMA regression; the dummy variables can also include values
   for forecasts and backcasts if you request them.
 \item
   \texttt{'dummyType='} {[} \texttt{'ao'} \textbar{}
   \emph{\texttt{'holiday'}} \textbar{} \texttt{'td'} {]} - Type of
   dummy; see the X12-ARIMA documentation.
 \item
   \texttt{'mode='} {[} \emph{\texttt{'auto'}} \textbar{} \texttt{'add'}
   \textbar{} \texttt{'logadd'} \textbar{} \texttt{'mult'} \textbar{}
   \texttt{'pseudoadd'} \textbar{} \texttt{'sign'} {]} - Seasonal
   adjustment mode (see help on the \texttt{x11} specs in the X12-ARIMA
   manual); \texttt{'auto'} means that series with only positive or only
   negative numbers will be adjusted in the \texttt{'mult'}
   (multiplicative) mode, while series with combined positive and
   negative numbers in the \texttt{'add'} (additive) mode.
 \item
   \texttt{'maxIter='} {[} numeric \textbar{} \emph{\texttt{1500}} {]} -
   Maximum number of iterations for the X12 estimation procedure. See
   help on the \texttt{estimation} specs in the X12-ARIMA manual.
 \item
   \texttt{'maxOrder='} {[} numeric \textbar{} \emph{\texttt{{[}2,1{]}}}
   {]} - A 1-by--2 vector with maximum order for the regular ARMA model
   (can be \texttt{1}, \texttt{2}, \texttt{3}, or \texttt{4}) and maximum
   order for the seasonal ARMA model (can be \texttt{1} or \texttt{2}).
   See help on the \texttt{automdl} specs in the X12-ARIMA manual.
 \item
   \texttt{'output='} {[} char \textbar{} cellstr \textbar{}
   \emph{\texttt{'SA'}} {]} - List of requested output data; the cellstr
   or comma-separated list can combine \texttt{'IR'} for the irregular
   component, \texttt{'SA'} for the final seasonally adjusted series,
   \texttt{'SF'} for seasonal factors, and \texttt{'TC'} for the
   trend-cycle. See also help on the \texttt{x11} specs in the X12-ARIMA
   manual.
 \item
   \texttt{'saveAs='} {[} char \textbar{} \emph{empty} {]} - Name (or a
   whole path) under which X12-ARIMA output files will be saved.
 \item
   \texttt{'specFile='} {[} char \textbar{} \emph{\texttt{'default'}} {]}
   - Name of the X12-ARIMA spec file; if \texttt{'default'} the IRIS
   default spec file will be used, see description.
 \item
   \texttt{'tdays='} {[} \texttt{true} \textbar{} \emph{\texttt{false}}
   {]} - Correct for the number of trading days. See help on the
   \texttt{x11regression} specs in the X12-ARIMA manual.
 \item
   \texttt{'tolerance='} {[} numeric \textbar{} \emph{\texttt{1e-5}} {]}
   - Convergence tolerance for the X12 estimation procedure. See help on
   the \texttt{estimation} specs in the X12-ARIMA manual.
 \end{itemize}
 \paragraph{Description}
 
 \subparagraph{Spec file}
 
 The default X12-ARIMA spec file is \texttt{+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):
 
 \begin{itemize}
 \item
   \texttt{\$series\_data\$} is replaced with a column vector of input
   observations;
 \item
   \texttt{\$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 X12-ARIMA);
 \item
   \texttt{\$series\_startyear\$} is replaced with the start year of the
   input series;
 \item
   \texttt{\$series\_startper\$} is replaced with the start quarter or
   month of the input series;
 \item
   \texttt{\$transform\_function\$} is replaced with \texttt{log} or
   \texttt{none} depending on the mode selected by the user;
 \item
   \texttt{\$forecast\_maxlead\$} is replaced with the requested number
   of ARIMA forecast periods used to extend the series before seasonal
   adjustment.
 \item
   \texttt{\$forecast\_maxlead\$} is replaced with the requested number
   of ARIMA forecast periods used to extend the series before seasonal
   adjustment.
 \item
   \texttt{\$tolerance\$} is replaced with the requested convergence
   tolerance in the \texttt{estimation} spec.
 \item
   \texttt{\$maxiter\$} is replaced with the requested maximum number of
   iterations in the \texttt{estimation} spec.
 \item
   \texttt{\$maxorder\$} is replaced with two numbers separated by a
   blank space: maximum order of regular ARIMA, and maximum order of
   seasonal ARIMA.
 \item
   \texttt{\$x11\_mode\$} is replaced with the requested mode:
   \texttt{'add'} for additive, \texttt{'mult'} for multiplicative,
   \texttt{'pseudoadd'} for pseudo-additive, or \texttt{'logadd'} for
   log-additive;
 \item
   \texttt{\$x12\_save\$} is replaced with the list of the requested
   output series: \texttt{'d10'} for seasonals, \texttt{'d11'} for final
   seasonally adjusted series, \texttt{'d12'} for trend-cycle,
   \texttt{'d13'} for irregular component.
 \end{itemize}
 Two of the placeholders, \texttt{'\$series\_data\$} and
 \texttt{\$x12\_output\$}, are required; if they are not found in the
 spec file, IRIS throws an error.
 
 \subparagraph{Estimates of ARIMA model parameters}
 
 The ARIMA model specification, \texttt{MODEL}, is a struct with three
 fields:
 
 \begin{itemize}
 \item
   \texttt{.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. \texttt{{[}0 1 1{]}}.
 \item
   \texttt{.ar} - a numeric array with the point estimates of the AR
   coefficients (non-seasonal and seasonal).
 \item
   \texttt{.ma} - a numeric array with the point estimates of the MA
   coefficients (non-seasonal and seasonal).
 \end{itemize}
 \paragraph{Example 1}
 
 If you wish to run \texttt{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
 \texttt{x12} do exactly the same:
 
 \begin{verbatim}
 xsa = x12(x);
 xsa = x12(x,Inf);
 xsa = x12(x,get(x,'range'));
 \end{verbatim}
 \paragraph{Example 2}
 
 If you wish to specify some of the options, you have to enter a date
 range or use \texttt{Inf}:
 
 \begin{verbatim}
 xsa = x12(x,Inf,'mode=','add');
 \end{verbatim}


