Statistics and time-series analytics API
Data Structures | Enumerations | Functions
X12-ARIMA Model
Analytics APIs » ARMA-ARIMA Analysis

X-12ARIMA Model and Seasonal ajustments. More...

Data Structures

struct  X12ARIMA_OPTIONS
 Data structure to capture X-12-ARIMA options. More...
 

Enumerations

enum  X11_MODE_TYPE { X11_MODE_MULT = 0 , X11_MODE_ADD = 1 , X11_MODE_PSEUDOADD = 2 , X11_MODE_LOGADD = 3 }
 
enum  X11_SEASONALMA_TYPE {
  X11_SEASONALMA_3x1 = 0 , X11_SEASONALMA_3x3 = 1 , X11_SEASONALMA_3x5 = 2 , X11_SEASONALMA_3x9 = 3 ,
  X11_SEASONALMA_3x15 = 4 , X11_SEASONALMA_STABLE = 5 , X11_SEASONALMA_DEFAULT = 6 , X11_SEASONALMA_MSR =7
}
 

Functions

int __stdcall NDK_X12_ENV_INIT (BOOL bOverride)
 Initialize the filesystem environment on the local machine for the current user.
 
int __stdcall NDK_X12_ENV_CLEANUP (void)
 Finalize the X12A environment and release any resources allocated.
 
int __stdcall NDK_X12_SCEN_INIT (LPCTSTR szScenarioName, LPVOID X12Options, size_t *ulModelHash)
 Initialize the required files for the given scenario/model.
 
int __stdcall NDK_X12_SCEN_READ (LPCTSTR szScenarioName, LPVOID X12Options, size_t *ulModelHash)
 Read the model configuration file (options.ini).
 
int __stdcall NDK_X12_SCEN_CLEAUP (LPCTSTR szScenarioName)
 Finalize the X12A environment and release any resources allocated.
 
int __stdcall NDK_X12_DATA_FILE (LPCTSTR szScenarioName, double *pData, size_t nLen, BOOL monthly, LONG startDate, WORD fileType, size_t *ulDataHash)
 Write the given data into an X12a formatted data file.
 
int __stdcall NDK_X12_READ_DATA_FILE (LPCTSTR szScenarioName, double *pData, size_t nLen, WORD fileType, size_t *ulDataHash)
 Read the scenario data file into the given data into an X12a formatted data file.
 
int __stdcall NDK_X12_SPC_FILE (LPCTSTR szScenarioName, void *pX12Structure, size_t *ulModelHash)
 Create or updates the x12a specification file using the options selected.
 
int __stdcall NDK_X12_RUN_BATCH (LPCTSTR szScenarioName, LPCTSTR szBatchFile, LPWORD status)
 Run a batch file in x12a environment.
 
int __stdcall NDK_X12_RUN_SCENARIO (LPCTSTR szScenarioName, LPWORD status)
 Run a x12a program for the given model or scenrio.
 
int __stdcall NDK_X12_RUN_STAT (LPCTSTR szScenarioName, LPWORD status, LPTSTR szMsg, size_t *nLen)
 Read the status file generated by x12a program.
 
int __stdcall NDK_X12_OUT_FILE (LPCTSTR szScenarioName, WORD retType, LPTSTR szOutFile, size_t *nLen, BOOL OpenFileFlag)
 Return the full path of the output file generated by x12a program.
 
int __stdcall NDK_X12_OUT_SERIES (LPCTSTR szScenarioName, WORD nComponent, double *pData, size_t *nLen)
 Read the output time series (e.g. seasonal adjusted data) generated by x12a program.
 
int __stdcall NDK_X12_FORE_SERIES (LPCTSTR szScenarioName, size_t nStep, WORD retType, double *pData)
 Read the output forecaste series generated by x12a program.
 

Detailed Description

Seasonal adjustment is a statistical method for removing the seasonal component of a time series when analyzing non-seasonal trends. It is normal to report seasonally adjusted data for unemployment rates to reveal the underlying trends in labor markets. Many economic phenomena have seasonal cycles, such as agricultural production and consumer consumption (e.g., greater consumption leading up to Christmas). It is necessary to adjust for this component to understand what underlying trends are in the economy; thus, official statistics are often adjusted to remove seasonal components.

Different statistical research groups have developed different methods of seasonal adjustment, including the United States Census Bureau's X-12-ARIMA, the Bank of Spain's TRAMO/SEATS, and STAMP, developed by a group led by S. J. Koopman. Each group provides software supporting their methods.

NumXL supports the X-12-ARIMA method. X-12-ARIMA is the software produced, distributed, and maintained by the United States Census Bureau.

Behind the scenes, NumXL translates the user’s options into native X-12-ARIMA scripts, runs the program, and avails the outputs (e.g., seasonally adjusted trend, seasonal factor, irregulars, forecast) through a set of worksheet functions. Nevertheless, the user can view/access the generated input and output files using the NumXL wizard.

Deprecated
Starting with version 1.67 (MARTHA), NumXL supports the latest U.S. Census X13ARIMA-SEATS seasonal adjustment software. The U.S. Census does not maintain the X12ARIMA seasonal adjustment software, and NumXL includes this model to help our customers migrate existing X12 models to the X13 equivalents.
regARIMA Model
The X-12-ARIMA software comes with extensive time series modeling and model selection capabilities for linear regression models with ARIMA errors (regARIMA models).

The ARIMA models, as discussed by Box and Jenkins (1976), are frequently used for seasonal time series. A general multiplicative seasonal ARIMA model for a time series $z_t$ can be written:

\[\phi(L)\Phi(L^s)(1-L)^d (1-L^s)^D\times z_t = \theta(L)\Theta(L^s)a_t \]

Where:

Remarks
  1. The time series is homogeneous or equally spaced.
  2. The time series may include missing values (e.g. NaN) at either end.
  3. It is common to replace \(z_t\) by deviations from the mean:

    \[z_t-\mu\]

    Where:

    \[\mu=E[z_t] \]

  4. \((1-L)^d(1-L^s)^D\) operator yields a stationary time series.

A natural extension for the ARIMA model results from using a time-varying mean function modeled via linear regression effects.

\[ y_t=\sum_{i=1}^N{\beta_i x_{i,t}}+z_t \]

Where:

As a result, the general regARIMA model supported by the X-12-ARIMA program is:

\[\phi(L)\Phi(L^s)(1-L)^d (1-L^s)^D\times (y_t-\sum_{i=1}^N{\beta_i x_{i,t}}) = \theta(L)\Theta(L^s)a_t \]

Related Links
References

Enumeration Type Documentation

◆ X11_MODE_TYPE

enum X11_MODE_TYPE

X11 Modes

See also
Enumerator
X11_MODE_MULT 

multiplicative

X11_MODE_ADD 

additive

X11_MODE_PSEUDOADD 

pseudo-additive

X11_MODE_LOGADD 

log-additive

◆ X11_SEASONALMA_TYPE

enum X11_SEASONALMA_TYPE

X13 seasonal MA types

See also
Enumerator
X11_SEASONALMA_3x1 

3x1 CMA

X11_SEASONALMA_3x3 

3x3 CMA

X11_SEASONALMA_3x5 

3x5 CMA

X11_SEASONALMA_3x9 

3x9 CMA

X11_SEASONALMA_3x15 

3x15 CMA

X11_SEASONALMA_STABLE 

Stable CMA.

X11_SEASONALMA_DEFAULT 

3x3 MA and 3x5

X11_SEASONALMA_MSR 

X-11-ARIMA88.

Function Documentation

◆ NDK_X12_DATA_FILE()

int __stdcall NDK_X12_DATA_FILE ( LPCTSTR szScenarioName,
double * pData,
size_t nLen,
BOOL monthly,
LONG startDate,
WORD fileType,
size_t * ulDataHash )

Write the given data into an X12a formatted data file

Parameters
[in]szScenarioName(Required) The scenario name, must be unique
[in]pData(Required) A univariate time series data (a one dimensional array).
[in]nLen(Required) the number of observations in pData.
[in]monthly(Required) A boolean flag for whether the data is monthly/quartelry sampled.
[in]startDate(Required) The serial date number of the 1st observation in the series.
[in]fileType(Required) A reserved argument for future releases. must be set to 1.
[in,out]ulDataHash(Optional) A pointer to a variable that holds the current CRC hash of the data file (tab delimated).
Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_INVALID_ARGfailed (see remarks)
NDK_LOW_LICENSE_ARG_LIMITfailed (see remarks)
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
  2. This function removes temporary files and folders used by the X12 models during its runtime.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also

◆ NDK_X12_ENV_CLEANUP()

int __stdcall NDK_X12_ENV_CLEANUP ( void )

Finalize the X12A environment and release any resources allocated

Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
  2. This function removes temporary files and folders used by the X12 models during its runtime.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also

◆ NDK_X12_ENV_INIT()

int __stdcall NDK_X12_ENV_INIT ( BOOL bOverride)

Initialize the filesystem environment on the local machine for the current user

Parameters
[in]bOverride(Required) A boolean flag to wipe our existing files and copy new ones.
Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
  2. This function creates a subfolder under the current user local profile for X12ARIMA models, and copy all the scripts needed to run the x12a program.
  3. The NDK_Init function calls this function as part of its initialization, so there is no need to call it it, unless you wish to change the folder/location of the x12 models during runtime.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also

◆ NDK_X12_FORE_SERIES()

int __stdcall NDK_X12_FORE_SERIES ( LPCTSTR szScenarioName,
size_t nStep,
WORD retType,
double * pData )

Read the output forecaste series generated by x12a program

Parameters
[in]szScenarioName(Required) The scenario name or the model unique identifier.
[in]nStep(Required) The forecast horizon.
[in]retType(Required) the desired output of the X12a output:
Value Output Type
1 Mean
2 Lower limit value of the conficent interval
3 Upper limit value of the confidence interval
[out]pData(Required) A pointer to a variable to hold the output value.
Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_INVALID_ARGfailed (see remarks)
NDK_LOW_LICENSE_ARG_LIMITfailed (see remarks)
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
  2. This function removes temporary files and folders used by the X12 models during its runtime.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also

◆ NDK_X12_OUT_FILE()

int __stdcall NDK_X12_OUT_FILE ( LPCTSTR szScenarioName,
WORD retType,
LPTSTR szOutFile,
size_t * nLen,
BOOL OpenFileFlag )

Return the full path of the output file generated by x12a program

Parameters
[in]szScenarioName(Required) The scenario name or the model unique identifier.
[in]retType(Required) A pointer to a variable that holds the status after running the batch file.
Value Output Type
0 The X12 specification file (*.spc)
1 The X12 log file
2 The output file
3 The error file
[out]szOutFile(Required) A pointer to a buffer to hold the file full path.
[in,out]nLen(Required) A pointer to a variable that holds the length of the szOutFile. Upon return, this argument stores the actual number of characters used.
[in]OpenFileFlag(Required) a switch to instruct the functiona whether it should open the file using system default editor (e.g.,notepad)
Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_INVALID_ARGfailed (see remarks)
NDK_LOW_LICENSE_ARG_LIMITfailed (see remarks)
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
  2. This function removes temporary files and folders used by the X12 models during its runtime.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also

◆ NDK_X12_OUT_SERIES()

int __stdcall NDK_X12_OUT_SERIES ( LPCTSTR szScenarioName,
WORD nComponent,
double * pData,
size_t * nLen )

Read the output time series (e.g. seasonal adjusted data) generated by x12a program

Parameters
[in]szScenarioName(Required) The scenario name or the model unique identifier.
[in]nComponent(Required) the desired output of the X12a output:
Value Output Type
1 Final seasonal factors (d11)
2 Final trend-cycle (d12)
3 Final irregular component (d13)
4 Final seasonal factors (d10)
5 Combined holiday and trading day factors (d18)
6 Combined seasonal and trading day factors (d16)
[out]pData(Required) A pointer to a buffer to hold the output time series data (a one dimensional array).
[in,out]nLen(Required) A pointer to a variable that holds the size of the szOutFile. Upon return, this argument stores the actual number of elements copied/used.
Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_INVALID_ARGfailed (see remarks)
NDK_LOW_LICENSE_ARG_LIMITfailed (see remarks)
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also

◆ NDK_X12_READ_DATA_FILE()

int __stdcall NDK_X12_READ_DATA_FILE ( LPCTSTR szScenarioName,
double * pData,
size_t nLen,
WORD fileType,
size_t * ulDataHash )

Read the scenario data file into the given data into an X12a formatted data file.

Parameters
[in]szScenarioName(Required) The scenario name, must be unique
[out]pData(Required) A pointer to a buffer to hold the univariate time series data (a one dimensional array).
[in]nLen(Required) the number of observations in pData.
[in]fileType(Required) A reserved argument for future releases. must be set to 1
[out]ulDataHash(Optional) A pointer to a variable that holds the current CRC hash of the data file (tab delimated).
Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_INVALID_ARGfailed (see remarks)
NDK_LOW_LICENSE_ARG_LIMITfailed (see remarks)
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
  2. This function removes temporary files and folders used by the X12 models during its runtime.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also

◆ NDK_X12_RUN_BATCH()

int __stdcall NDK_X12_RUN_BATCH ( LPCTSTR szScenarioName,
LPCTSTR szBatchFile,
LPWORD status )

Run a batch file in x12a environment.

Parameters
[in]szScenarioName(Required) The scenario name or the model unique identifier.
[in]szBatchFile(Required) The batch file name to run
[out]status(Required) A pointer to a variable that holds the status after running the batch file.
Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_INVALID_ARGfailed (see remarks)
NDK_LOW_LICENSE_ARG_LIMITfailed (see remarks)
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
  2. This function removes temporary files and folders used by the X12 models during its runtime.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also

◆ NDK_X12_RUN_SCENARIO()

int __stdcall NDK_X12_RUN_SCENARIO ( LPCTSTR szScenarioName,
LPWORD status )

Run a x12a program for the given model or scenrio.

Parameters
[in]szScenarioName(Required) The scenario name or the model unique identifier.
[out]status(Required) A pointer to a variable that holds the status after running the batch file.
Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_INVALID_ARGfailed (see remarks)
NDK_LOW_LICENSE_ARG_LIMITfailed (see remarks)
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
  2. This function removes temporary files and folders used by the X12 models during its runtime.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also

◆ NDK_X12_RUN_STAT()

int __stdcall NDK_X12_RUN_STAT ( LPCTSTR szScenarioName,
LPWORD status,
LPTSTR szMsg,
size_t * nLen )

Read the status file generated by x12a program.

Parameters
[in]szScenarioName(Required) The scenario name or the model unique identifier.
[out]status(Required) A pointer to a variable that holds the status after running the batch file.
[out]szMsg(Required) A pointer to a buffer that will hold the status message.
[in,out]nLen(Required) A pointer to a variable that holds the size of buffer in szMsg. Upon return, the variable will holds the number of characters copied to szMsg.
Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_INVALID_ARGfailed (see remarks)
NDK_LOW_LICENSE_ARG_LIMITfailed (see remarks)
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
  2. This function removes temporary files and folders used by the X12 models during its runtime.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also

◆ NDK_X12_SCEN_CLEAUP()

int __stdcall NDK_X12_SCEN_CLEAUP ( LPCTSTR szScenarioName)

Finalize the given scenario/model and free allocated resources

Parameters
[in]szScenarioName(Required) The scenario name, must be unique
Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_INVALID_ARGfailed (see remarks)
NDK_LOW_LICENSE_ARG_LIMITfailed (see remarks)
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
  2. This function removes temporary files and folders used by the X12 models during its runtime.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also

◆ NDK_X12_SCEN_INIT()

int __stdcall NDK_X12_SCEN_INIT ( LPCTSTR szScenarioName,
LPVOID X12Options,
size_t * ulModelHash )

Initialize the required files for the given scenario/model

Parameters
[in]szScenarioName(Required) The scenario name, must be unique
[in]X12Options(Required) A pointer to an instance of X12ARIMA_OPTIONS structure with all X12 model options.
[in,out]ulModelHash(Required) A pointer to a variable that holds the current CRC hash of the models's options.ini file.
Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_INVALID_ARGfailed (see remarks)
NDK_LOW_LICENSE_ARG_LIMITfailed (see remarks)
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
  2. This function creates the model file, or if the files exists, it examines their hash against given one to mark the model as clean or dirty.
  3. The function returns the CRC hash of the options.ini file.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also

◆ NDK_X12_SCEN_READ()

int __stdcall NDK_X12_SCEN_READ ( LPCTSTR szScenarioName,
LPVOID X12Options,
size_t * ulModelHash )

Read the model configuration file

Parameters
[in]szScenarioName(Required) The scenario name, must be unique
[out]X12Options(Required) A pointer to an instance of X12ARIMA_OPTIONS structure with all X12 model options.
[out]ulModelHash(Required) A pointer to a variable that holds the current CRC hash of the models's options.ini file.
Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_INVALID_ARGfailed (see remarks)
NDK_LOW_LICENSE_ARG_LIMITfailed (see remarks)
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
  2. This function reads the options.ini file (if exists), and initializes the structure elements in X12Options.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also

◆ NDK_X12_SPC_FILE()

int __stdcall NDK_X12_SPC_FILE ( LPCTSTR szScenarioName,
void * pX12Structure,
size_t * ulModelHash )

Create or updates the x12a specification file using the options selected

Parameters
[in]szScenarioName(Required) The scenario name, must be unique
[in]pX12Structure(Required) A pointer to an instance of X12ARIMA_OPTIONS structure with all X12 model options.
[in,out]ulModelHash(Required) A pointer to a variable that holds the current CRC hash of the models's options.ini file.
Returns
status code of the function call: zero = success, positive = success with a warning, and negative = error occurred.
Return values
NDK_SUCCESSsuccess
NDK_INVALID_ARGfailed (see remarks)
NDK_LOW_LICENSE_ARG_LIMITfailed (see remarks)
NDK_FAILEDfailed
Remarks
  1. The underlying model is described here.
  2. This function removes temporary files and folders used by the X12 models during its runtime.
Requirements
Requirement Value
Target Platform Windows
Header SFSDK.h (include Windows.h)
Library SFSDK.lib
DLL SFSDK.dll
SFLUC.dll
SFLOG.dll
Since
v1.63
See also