JMSLTM Numerical Library 5.0.1

com.imsl.stat
Class ARSeasonalFit

java.lang.Object
  extended by com.imsl.stat.ARSeasonalFit
All Implemented Interfaces:
Serializable

public class ARSeasonalFit
extends Object
implements Serializable

Estimates the optimum seasonality parameters for a time series using an autoregressive model, AR(p), to represent the time series.

ARMA time series modeling assumes the time series is stationary. Seasonal trends and cycles violate this assumption, which can lead to inaccurate predictions. However, in many cases the nonstationary series can be transformed into a stationary series by first differencing the series. For example, if the correlation is strong from one period to the next, the series might be differenced by a lag of 1. Instead of fitting a model to the original series Z_t, the model is fitted to the transformed series: W_t = Z_t - Z_{t-1}. Higher order lags or differences are warranted if the series has cycles every 4 or 13 weeks. Class ARSeasonalFit is designed to help identify the optimum differencing for a series with seasonal trends or cycles.

ARSeasonalFit assumes the original series has no missing values, is equally spaced in time and is not centered before computing the optimum differencing. However, by default the transformed series is centered using the mean of that series. Users can change this default using the setCenter method. If setCenter is set to NO_CENTER the series is not centered, if set to CENTER_MEAN the series is centered using the mean of the series, and if set to CENTER_MEDIAN, the series is centered using the median of the series. If setCenter is set to CENTER_MEAN or CENTER_MEDIAN then the differenced series, W_t is centered before determination of minimum AIC and optimum lag.

For every combination of rows in sInitial and dInitial, the series Z_t is converted to the seasonally adjusted series using the following computation

W_t(s,d) = Delta^{d_1}_{s_1}Delta^{d_2}_{s_2}
 cdotsDelta^{d_m}_{s_m}Z_t=prodlimits_{i=1}^{m}sumlimits_{j=0}^{d_i}
 {{d_i}choose{j}}{(-1)}^jB^{jcdot s_i}Z_t

where s := (s_1,ldots,s_m), d := (d_1,ldots,d_m) represent specific rows of arrays sInitial and dInitial respectively, and m is the number of differences, or m=sInitial[0].length.

This transformation of the series Z_t to W_t (s,d) is computed using the Difference class. After this transformation the transformed series

W_t (s,d)

is centered, unless NO_CENTER is specified, and the ARAutoUnivariate class is used to automatically determine the optimum lag for an AR(p) representation for W_t (s,d).

This procedure is repeated for every possible combination of rows in sInitial and dInitial. The series with the minimum AIC is identified as the optimum representation and returned in the methods getAROrder, getOptimumS, getOptimumD, getAIC, and getAR. The transformed series with the minium AIC can be retrieved from the getTransformedTimeSeries method.

See Also:
Example, Serialized Form

Field Summary
static int CENTER_MEAN
          Indicates the transformed series should be centered using the average of the differenced series.
static int CENTER_MEDIAN
          Indicates the transformed series should be centered using the median of the differenced series.
static int NO_CENTER
          Indicates the transformed series should not be centered.
 
Constructor Summary
ARSeasonalFit(int maxlag, int[][] sInitial, double[] z)
          Constructor for ARSeasonalFit.
 
Method Summary
 void compute()
          Computes the minimum AIC and optimum values for s and d based upon the candidates provided in sInitial and dInitial, and computes the values for the transformed series, W_t(s,d).
 double getAIC()
          Returns the final estimate for Akaike's Information Criterion (AIC) at the optimum.
 double[] getAR()
          Returns the final autoregressive parameter estimates at the optimum in the transformed series W_t.
 int getAROrder()
          Returns optimum number of lags, p, for the optimum autoregressive AR(p) model.
 int getCenter()
          Returns the current setting for centering the input time series.
 int[][] getDInitial()
          Returns the candidate values for d to evaluate.
 boolean getExclude()
          Returns the current setting for excluding or replacing the inital values in the transformed series.
 int getMaxlag()
          Returns the maximum lag used to fit the AR(p) model.
 int getNLost()
          Returns the number of values in the initial part of the series lost to differencing.
 int[] getOptimumD()
          Returns the optimum values for d selected among the candidates in dInitial.
 int[] getOptimumS()
          Returns the optimum values for s selected among the candidates in sInitial.
 int[][] getSInitial()
          Returns the the candidate values for s to evaluate.
 double[] getTimeSeries()
          Returns the time series.
 double[] getTransformedTimeSeries()
          Returns the transformed series, W_t(s,d).
 void setCenter(int center)
          Controls centering of the differenced series.
 void setDInitial(int[][] dInitial)
          Sets the candidate values for selecting the optimum seasonal adjustment prior to calling the compute method.
 void setExclude(boolean exclude)
          Controls whether to exclude or replace the inital values in the transformed series.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CENTER_MEAN

public static final int CENTER_MEAN
Indicates the transformed series should be centered using the average of the differenced series.

See Also:
Constant Field Values

CENTER_MEDIAN

public static final int CENTER_MEDIAN
Indicates the transformed series should be centered using the median of the differenced series.

See Also:
Constant Field Values

NO_CENTER

public static final int NO_CENTER
Indicates the transformed series should not be centered.

See Also:
Constant Field Values
Constructor Detail

ARSeasonalFit

public ARSeasonalFit(int maxlag,
                     int[][] sInitial,
                     double[] z)
Constructor for ARSeasonalFit.

Parameters:
maxlag - An int scalar specifying the maximum lag allowed when fitting an AR(p) model.
sInitial - An int matrix where each row represents seasonal differences to evaluate. The number of columns in sInitial represent the number of differences to perform. All values of sInitial must be greater than zero.
z - An input double array containing the time series.
Method Detail

compute

public void compute()
             throws ARMA.MatrixSingularException,
                    ARMA.TooManyCallsException,
                    ARMA.IncreaseErrRelException,
                    ARMA.NewInitialGuessException,
                    ARMA.IllConditionedException,
                    ARMA.TooManyITNException,
                    ARMA.TooManyFcnEvalException,
                    ARMA.TooManyJacobianEvalException,
                    ARAutoUnivariate.TriangularMatrixSingularException,
                    ARMAMaxLikelihood.NonInvertibleException,
                    ARMAMaxLikelihood.NonStationaryException,
                    ARMAMaxLikelihood.InitialMAException
Computes the minimum AIC and optimum values for s and d based upon the candidates provided in sInitial and dInitial, and computes the values for the transformed series, W_t(s,d).

Warnings are printed if a row in sInitial is skipped due to too many observations lost in the differenced series or if problems occurred computing the optimum AIC using the differenced series.

Throws:
ARMA.MatrixSingularException - is thrown if the input matrix is singular
ARMA.TooManyCallsException - is thrown if the number of calls to the function has exceeded the maximum number of iterations times the number of moving average (MA) parameters + 1.
ARMA.IncreaseErrRelException - is thrown if the bound for the relative error is too small
ARMA.NewInitialGuessException - is thrown if the iteration has not made good progress
ARMA.IllConditionedException - is thrown if the problem is ill-conditioned
ARMA.TooManyITNException - is thrown if the maximum number of iterations is exceeded
ARMA.TooManyFcnEvalException - is thrown if the maximum number of function evaluations is exceeded
ARMA.TooManyJacobianEvalException - is thrown if the maximum number of Jacobian evaluations is exceeded
ARMAMaxLikelihood.NonStationaryException - is thrown if the final maximum likelihood estimates for the time series are nonstationary
ARMAMaxLikelihood.NonInvertibleException - is thrown if the final maximum likelihood estimates for the time series are noninvertible
ARMAMaxLikelihood.InitialMAException - is thrown if the initial values provided for the moving average terms using setMA are noninvertible. In this case, ARMAMaxLikelihood terminates and does not compute the time series estimates.
ARAutoUnivariate.TriangularMatrixSingularException - is thrown if the input triangular matrix is singular.

getAIC

public double getAIC()
Returns the final estimate for Akaike's Information Criterion (AIC) at the optimum.

Returns:
a double equal to mbox{AIC} = -2ln(L)+2p, where L is the value of the maximum likelihood function evalutated at the parameter estimates

getAR

public double[] getAR()
               throws ARMA.MatrixSingularException,
                      ARMA.TooManyCallsException,
                      ARMA.IncreaseErrRelException,
                      ARMA.NewInitialGuessException,
                      ARMA.IllConditionedException,
                      ARMA.TooManyITNException,
                      ARMA.TooManyFcnEvalException,
                      ARMA.TooManyJacobianEvalException,
                      ARAutoUnivariate.TriangularMatrixSingularException,
                      ARMAMaxLikelihood.NonInvertibleException,
                      ARMAMaxLikelihood.NonStationaryException,
                      ARMAMaxLikelihood.InitialMAException
Returns the final autoregressive parameter estimates at the optimum in the transformed series W_t.

Returns:
a double array containing the estimates for the autoregressive parameters
Throws:
ARMA.MatrixSingularException - is thrown if the input matrix is singular
ARMA.TooManyCallsException - is thrown if the number of calls to the function has exceeded the maximum number of iterations times the number of moving average (MA) parameters + 1.
ARMA.IncreaseErrRelException - is thrown if the bound for the relative error is too small
ARMA.NewInitialGuessException - is thrown if the iteration has not made good progress
ARMA.IllConditionedException - is thrown if the problem is ill-conditioned
ARMA.TooManyITNException - is thrown if the maximum number of iterations is exceeded
ARMA.TooManyFcnEvalException - is thrown if the maximum number of function evaluations is exceeded
ARMA.TooManyJacobianEvalException - is thrown if the maximum number of Jacobian evaluations is exceeded
ARMAMaxLikelihood.NonStationaryException - is thrown if the final maximum likelihood estimates for the time series are nonstationary
ARMAMaxLikelihood.NonInvertibleException - is thrown if the final maximum likelihood estimates for the time series are noninvertible
ARMAMaxLikelihood.InitialMAException - is thrown if the initial values provided for the moving average terms using setMA are noninvertible. In this case, ARMAMaxLikelihood terminates and does not compute the time series estimates.
ARAutoUnivariate.TriangularMatrixSingularException - is thrown if the input triangular matrix is singular.

getAROrder

public int getAROrder()
Returns optimum number of lags, p, for the optimum autoregressive AR(p) model. This is the value of p for the transformed series, W_t.

Returns:
An int containing the optimum number of lags in the autoregressive model used to fit the transformed series W_t.

getCenter

public int getCenter()
Returns the current setting for centering the input time series.

Returns:
an int containing the setting for center equal to 0, 1, or 2, which implies NO_CENTER, CENTER_MEAN, CENTER_MEDIAN respectively.

getDInitial

public int[][] getDInitial()
Returns the candidate values for d to evaluate.

Returns:
an int matrix containing the candidate values for d to evaluate

getExclude

public boolean getExclude()
Returns the current setting for excluding or replacing the inital values in the transformed series.

If exclude is true, then inital values in the transformed series that cannot be computed are set to missing, NaN. This ensures that the length of the transformed series W_t is equal to the length of the time series, z.length. If exclude is set to false, then inital values in the transformed series W_t that cannot be computed are removed. This makes the length of the transformed series W_t equal to z.length-nLost where nLost is the number of lost values obtained from method getNLost.


getMaxlag

public int getMaxlag()
Returns the maximum lag used to fit the AR(p) model.

Returns:
an int scalar containing the maximum lag allowed when fitting an AR(p) model

getNLost

public int getNLost()
             throws ARMA.MatrixSingularException,
                    ARMA.TooManyCallsException,
                    ARMA.IncreaseErrRelException,
                    ARMA.NewInitialGuessException,
                    ARMA.IllConditionedException,
                    ARMA.TooManyITNException,
                    ARMA.TooManyFcnEvalException,
                    ARMA.TooManyJacobianEvalException,
                    ARAutoUnivariate.TriangularMatrixSingularException,
                    ARMAMaxLikelihood.NonInvertibleException,
                    ARMAMaxLikelihood.NonStationaryException,
                    ARMAMaxLikelihood.InitialMAException
Returns the number of values in the initial part of the series lost to differencing.

Returns:
an int containing the number of values in the initial part of the series lost to differencing. These lost values will be set to missing or dropped in the transformed series, depending upon the setting for exclude.
Throws:
ARMA.MatrixSingularException - is thrown if the input matrix is singular
ARMA.TooManyCallsException - is thrown if the number of calls to the function has exceeded the maximum number of iterations times the number of moving average (MA) parameters + 1.
ARMA.IncreaseErrRelException - is thrown if the bound for the relative error is too small
ARMA.NewInitialGuessException - is thrown if the iteration has not made good progress
ARMA.IllConditionedException - is thrown if the problem is ill-conditioned
ARMA.TooManyITNException - is thrown if the maximum number of iterations is exceeded
ARMA.TooManyFcnEvalException - is thrown if the maximum number of function evaluations is exceeded
ARMA.TooManyJacobianEvalException - is thrown if the maximum number of Jacobian evaluations is exceeded
ARMAMaxLikelihood.NonStationaryException - is thrown if the final maximum likelihood estimates for the time series are nonstationary
ARMAMaxLikelihood.NonInvertibleException - is thrown if the final maximum likelihood estimates for the time series are noninvertible
ARMAMaxLikelihood.InitialMAException - is thrown if the initial values provided for the moving average terms using setMA are noninvertible. In this case, ARMAMaxLikelihood terminates and does not compute the time series estimates.
ARAutoUnivariate.TriangularMatrixSingularException - is thrown if the input triangular matrix is singular.

getOptimumD

public int[] getOptimumD()
                  throws ARMA.MatrixSingularException,
                         ARMA.TooManyCallsException,
                         ARMA.IncreaseErrRelException,
                         ARMA.NewInitialGuessException,
                         ARMA.IllConditionedException,
                         ARMA.TooManyITNException,
                         ARMA.TooManyFcnEvalException,
                         ARMA.TooManyJacobianEvalException,
                         ARAutoUnivariate.TriangularMatrixSingularException,
                         ARMAMaxLikelihood.NonInvertibleException,
                         ARMAMaxLikelihood.NonStationaryException,
                         ARMAMaxLikelihood.InitialMAException
Returns the optimum values for d selected among the candidates in dInitial.

Returns:
an int array of length dInitial[0].length containing the optimum values for d selected among the candidates in dInitial
Throws:
ARMA.MatrixSingularException - is thrown if the input matrix is singular
ARMA.TooManyCallsException - is thrown if the number of calls to the function has exceeded the maximum number of iterations times the number of moving average (MA) parameters + 1.
ARMA.IncreaseErrRelException - is thrown if the bound for the relative error is too small
ARMA.NewInitialGuessException - is thrown if the iteration has not made good progress
ARMA.IllConditionedException - is thrown if the problem is ill-conditioned
ARMA.TooManyITNException - is thrown if the maximum number of iterations is exceeded
ARMA.TooManyFcnEvalException - is thrown if the maximum number of function evaluations is exceeded
ARMA.TooManyJacobianEvalException - is thrown if the maximum number of Jacobian evaluations is exceeded
ARMAMaxLikelihood.NonStationaryException - is thrown if the final maximum likelihood estimates for the time series are nonstationary
ARMAMaxLikelihood.NonInvertibleException - is thrown if the final maximum likelihood estimates for the time series are noninvertible
ARMAMaxLikelihood.InitialMAException - is thrown if the initial values provided for the moving average terms using setMA are noninvertible. In this case, ARMAMaxLikelihood terminates and does not compute the time series estimates.
ARAutoUnivariate.TriangularMatrixSingularException - is thrown if the input triangular matrix is singular.

getOptimumS

public int[] getOptimumS()
                  throws ARMA.MatrixSingularException,
                         ARMA.TooManyCallsException,
                         ARMA.IncreaseErrRelException,
                         ARMA.NewInitialGuessException,
                         ARMA.IllConditionedException,
                         ARMA.TooManyITNException,
                         ARMA.TooManyFcnEvalException,
                         ARMA.TooManyJacobianEvalException,
                         ARAutoUnivariate.TriangularMatrixSingularException,
                         ARMAMaxLikelihood.NonInvertibleException,
                         ARMAMaxLikelihood.NonStationaryException,
                         ARMAMaxLikelihood.InitialMAException
Returns the optimum values for s selected among the candidates in sInitial.

Returns:
an int array of length sInitial[0].length containing the optimum values for s selected among the candidates in sInitial
Throws:
ARMA.MatrixSingularException - is thrown if the input matrix is singular
ARMA.TooManyCallsException - is thrown if the number of calls to the function has exceeded the maximum number of iterations times the number of moving average (MA) parameters + 1.
ARMA.IncreaseErrRelException - is thrown if the bound for the relative error is too small
ARMA.NewInitialGuessException - is thrown if the iteration has not made good progress
ARMA.IllConditionedException - is thrown if the problem is ill-conditioned
ARMA.TooManyITNException - is thrown if the maximum number of iterations is exceeded
ARMA.TooManyFcnEvalException - is thrown if the maximum number of function evaluations is exceeded
ARMA.TooManyJacobianEvalException - is thrown if the maximum number of Jacobian evaluations is exceeded
ARMAMaxLikelihood.NonStationaryException - is thrown if the final maximum likelihood estimates for the time series are nonstationary
ARMAMaxLikelihood.NonInvertibleException - is thrown if the final maximum likelihood estimates for the time series are noninvertible
ARMAMaxLikelihood.InitialMAException - is thrown if the initial values provided for the moving average terms using setMA are noninvertible. In this case, ARMAMaxLikelihood terminates and does not compute the time series estimates.
ARAutoUnivariate.TriangularMatrixSingularException - is thrown if the input triangular matrix is singular.

getSInitial

public int[][] getSInitial()
Returns the the candidate values for s to evaluate.

Returns:
an int matrix containing the candidate values for s to evaluate

getTimeSeries

public double[] getTimeSeries()
Returns the time series.

Returns:
a double array containing the time series values

getTransformedTimeSeries

public double[] getTransformedTimeSeries()
                                  throws ARMA.MatrixSingularException,
                                         ARMA.TooManyCallsException,
                                         ARMA.IncreaseErrRelException,
                                         ARMA.NewInitialGuessException,
                                         ARMA.IllConditionedException,
                                         ARMA.TooManyITNException,
                                         ARMA.TooManyFcnEvalException,
                                         ARMA.TooManyJacobianEvalException,
                                         ARAutoUnivariate.TriangularMatrixSingularException,
                                         ARMAMaxLikelihood.NonInvertibleException,
                                         ARMAMaxLikelihood.NonStationaryException,
                                         ARMAMaxLikelihood.InitialMAException
Returns the transformed series, W_t(s,d).

W_t(s,d) is an array of length z.length or z.length-nLost containing the optimum seasonally adjusted, autoregressive series, where nLost is the first lost observations in this series that are dropped due to differencing. If the missing values are not dropped the first nLost values of W_t will be set (Double.NaN). The getNLost method can be used to obtain nLost.

The seasonal adjustment is done by selecting optimum values for d_1,ldots,d_m, s_1,ldots,s_m (m is number of differences or sIinitial[0].length) and p in the AR model:

phi_p(B)(Delta_{s_1}^{d_1}Delta_{s_2}^{d_2}
 ldotsDelta_{s_m}^{d_m}Z_t-mu) = a_tmbox{,}

where {Z_t} is the original time series, B is the backward shift operator defined by B^kZ_t=Z_{t-k} mbox{, ,,with },, kge0, a_t is Gaussian white noise with E[a_t]=0 and mbox{Var}[a_t]= 
 sigma^2, phi_p(B)= 1-phi_1B - phi_2B^2 - cdots - phi_pB^p,,,,,
 0le{p}lembox{maxlag}, Delta_s^d=(1-B^s)^d, with s gt 0, 
 d ge 0, and mu is a centering parameter for the differenced series.

Returns:
a double array of length z.length or z.length-nLost, depending upon the setting for setExclude
Throws:
ARMA.MatrixSingularException - is thrown if the input matrix is singular
ARMA.TooManyCallsException - is thrown if the number of calls to the function has exceeded the maximum number of iterations times the number of moving average (MA) parameters + 1.
ARMA.IncreaseErrRelException - is thrown if the bound for the relative error is too small
ARMA.NewInitialGuessException - is thrown if the iteration has not made good progress
ARMA.IllConditionedException - is thrown if the problem is ill-conditioned
ARMA.TooManyITNException - is thrown if the maximum number of iterations is exceeded
ARMA.TooManyFcnEvalException - is thrown if the maximum number of function evaluations is exceeded
ARMA.TooManyJacobianEvalException - is thrown if the maximum number of Jacobian evaluations is exceeded
ARMAMaxLikelihood.NonStationaryException - is thrown if the final maximum likelihood estimates for the time series are nonstationary
ARMAMaxLikelihood.NonInvertibleException - is thrown if the final maximum likelihood estimates for the time series are noninvertible
ARMAMaxLikelihood.InitialMAException - is thrown if the initial values provided for the moving average terms using setMA are noninvertible. In this case, ARMAMaxLikelihood terminates and does not compute the time series estimates.
ARAutoUnivariate.TriangularMatrixSingularException - is thrown if the input triangular matrix is singular.

setCenter

public void setCenter(int center)
Controls centering of the differenced series.

Parameters:
center - an int scalar value equal NO_CENTER, CENTER_MEAN, or CENTER_MEDIAN . By default, center=CENTER_MEAN

setDInitial

public void setDInitial(int[][] dInitial)
Sets the candidate values for selecting the optimum seasonal adjustment prior to calling the compute method.

Parameters:
dInitial - an int array of candidate values for d to evaluate. All values must be non-negative. dInitial must have the same number of differences (columns) as sInitial. By default, dInitial is initialized to all ones.

setExclude

public void setExclude(boolean exclude)
Controls whether to exclude or replace the inital values in the transformed series.

If exclude is true, then inital values in the transformed series that cannot be computed are set to missing, NaN. This ensures that the length of the transformed series W_t is equal to the length of the time series, z.length. If exclude is set to false, then inital values in the transformed series W_t that cannot be computed are removed. This makes the length of the transformed series W_t equal to z.length-nLost where nLost is the number of lost values obtained from method getNLost.

Parameters:
exclude - a boolean value that controls whether values in W_t that cannot be calculated are dropped or set to missing. Missing values are set to Double.NaN. By default, exclude=true

JMSLTM Numerical Library 5.0.1

Copyright © 1970-2008 Visual Numerics, Inc.
Built July 8 2008.