Package com.imsl.stat

Class ARSeasonalFit

java.lang.Object

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} \cdots\Delta^{d_m}_{s_m}Z_t=\prod\limits_{i=1}^{m}\sum\limits_{j=0}^{d_i} {{d_i}\choose{j}}{(-1)}^jB^{j\cdot 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

Fields

Modifier and Type	Field	Description
static final int	CENTER_MEAN	Indicates the transformed series should be centered using the average of the differenced series.
static final int	CENTER_MEDIAN	Indicates the transformed series should be centered using the median of the differenced series.
static final int	NO_CENTER	Indicates the transformed series should not be centered.

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
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 Details

NO_CENTER

public static final int NO_CENTER

Indicates the transformed series should not be centered.

See Also:

• Constant Field Values

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

Constructor Details

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 Details

compute

public void compute()
             throws ARMA.MatrixSingularException,
ARMA.TooManyCallsException,
ARMA.IncreaseErrRelException,
ARMA.NewInitialGuessException,
ARMA.IllConditionedException,
ARMA.TooManyITNException,
ARMA.TooManyFcnEvalException,
ARMA.TooManyJacobianEvalException,
ARMA.ResidualsTooLargeException,
ARAutoUnivariate.TriangularMatrixSingularException,
ARMAMaxLikelihood.NonInvertibleException,
ARMAMaxLikelihood.NonStationaryException

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.

ARMA.ResidualsTooLargeException - is thrown if the residuals computed in one step of the Least Squares estimation of the ARMA coefficients become too large.

ARMAMaxLikelihood.NonStationaryException - is thrown if the final maximum likelihood estimates for the time series are non-stationary.

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} = -2\ln(L)+ 2p\), where L is the value of the maximum likelihood function evaluated at the parameter estimates.

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\).

getAR

public double[] getAR()
               throws ARMA.MatrixSingularException,
ARMA.TooManyCallsException,
ARMA.IncreaseErrRelException,
ARMA.NewInitialGuessException,
ARMA.IllConditionedException,
ARMA.TooManyITNException,
ARMA.TooManyFcnEvalException,
ARMA.TooManyJacobianEvalException,
ARMA.ResidualsTooLargeException,
ARAutoUnivariate.TriangularMatrixSingularException,
ARMAMaxLikelihood.NonInvertibleException,
ARMAMaxLikelihood.NonStationaryException

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

ARMA.ResidualsTooLargeException - is thrown if the residuals computed in one step of the Least Squares estimation of the ARMA coefficients become too large.

ARMAMaxLikelihood.NonStationaryException - is thrown if the final maximum likelihood estimates for the time series are non-stationary

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.

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.

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

getDInitial

public int[][] getDInitial()

Returns the candidate values for d to evaluate.

Returns:

an int matrix containing the candidate values for d to evaluate

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,
ARMA.ResidualsTooLargeException,
ARAutoUnivariate.TriangularMatrixSingularException,
ARMAMaxLikelihood.NonInvertibleException,
ARMAMaxLikelihood.NonStationaryException

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

ARMA.ResidualsTooLargeException - is thrown if the residuals computed in one step of the Least Squares estimation of the ARMA coefficients become too large.

ARMAMaxLikelihood.NonStationaryException - is thrown if the final maximum likelihood estimates for the time series are non-stationary

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,
ARMA.ResidualsTooLargeException,
ARAutoUnivariate.TriangularMatrixSingularException,
ARMAMaxLikelihood.NonInvertibleException,
ARMAMaxLikelihood.NonStationaryException

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

ARMA.ResidualsTooLargeException - is thrown if the residuals computed in one step of the Least Squares estimation of the ARMA coefficients become too large.

ARMAMaxLikelihood.NonStationaryException - is thrown if the final maximum likelihood estimates for the time series are non-stationary

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,
ARMA.ResidualsTooLargeException,
ARAutoUnivariate.TriangularMatrixSingularException,
ARMAMaxLikelihood.NonInvertibleException,
ARMAMaxLikelihood.NonStationaryException

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

ARMA.ResidualsTooLargeException - is thrown if the residuals computed in one step of the Least Squares estimation of the ARMA coefficients become too large.

ARMAMaxLikelihood.NonStationaryException - is thrown if the final maximum likelihood estimates for the time series are non-stationary

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.

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,
ARMA.ResidualsTooLargeException,
ARAutoUnivariate.TriangularMatrixSingularException,
ARMAMaxLikelihood.NonInvertibleException,
ARMAMaxLikelihood.NonStationaryException

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} \ldots\Delta_{s_m}^{d_m}Z_t-\mu) = a_t\mbox{,}$$ where \(\{Z_t\}\) is the original time series, B is the backward shift operator defined by \(B^kZ_t=Z_{t-k} \mbox{, \,\,with }\,\, k\ge0\), \(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,\,\,\,\,0\le{p}\le\mbox{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

ARMA.ResidualsTooLargeException - is thrown if the residuals computed in one step of the Least Squares estimation of the ARMA coefficients become too large.

ARMAMaxLikelihood.NonStationaryException - is thrown if the final maximum likelihood estimates for the time series are non-stationary

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

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.