VGAMextra (version 0.0-6)

cm.ARMA: Constraint matrices for vector generalized time series family functions.

Description

Constraint matrices for coefficients of vector genelized time series family functions in VGAMextra.

Usage

cm.ARMA(Model      = ~ 1, 
               Resp       =  1,
               lags.cm    =  2,
               offset     = -2, 
               whichCoeff =  1,
               factorSeq  =  2)

Value

A list of constraint matrices with specific restrictions over the AR(\(p\)), MA(\(q\)) or ARMA (\(p, q\)) coefficients. Each matrix returned is conformable with the VGAM/VGLM framework.

Paragrpah above means that each constraint matrix returned by cm.ARMA() is full-rank with M rows (number of parameters), as required by VGAM. Note that constraint matrices within the VGAM/VGLM framework are M by M identity matrices by default.

Restrictions currently handled by cm.ARMA() are (increasing) arithmetic and geometric progressions.

Arguments

Model

A symbolic description of the model being fitted. Must match that formula specified in the vglm() call.

lags.cm

Vector of POSITIVE integers greater than 1 indicating the order for each response. It must match the orders entered in the vglm call. Its default value is 2, assuming that a TS process of order greater than 1 is being fitted. If lags.cm < 2, then NO constraints are required as only one coefficient (AR, MA or ARMA) is being estimated.

offset

Vector of integers specifying the position of the ARMA coefficient at which constraints initiate FOR each response. If negative, it is recycled and the absolute value is used. The default value is -2, which refers to the fourth position on the vector parameter, right after the drift or mean, the white noise sd, and the first ARMA coefficient.

Particularly, if only one coefficient is being estimated, i.e, an AR or MA process of order-1 is being fitted, then NO restrictions over the (unique) coefficient are needed. Consequently, abs(offset < 2) leads to a message error.

whichCoeff

Vector of POSITIVE integers strictly less than `abs(offset)', each entry aplies to each response in the vglm(...) call. This argument allows the user to specify the unrestricted coefficient to be considered for constraints. For instance, whichCoeff = 2 means that \(\theta_2\) is the required coefficient to compute the constraint matrices. By default, whichCoeff = -1 which implies that \(\theta_1\) is used for this purpose.

If whichCoeff is greater than or equal to abs(offset), an error message is displayed since constraints must be function of unrestricted parameters.

Resp

The number of responses in the model fitted. Must match the number of responses given in formula in the vglm call.

factorSeq

Vector of POSITIVE integers. Thus far, restrictions handled are geometric sequences and arithmetic progressions. Hence, factorSeq specifies either the initial power or factor at restrictions.

See below for further details.

Warning

Hypotheses above can be tested by properly applying parameter link functions. If the test $$Ho: \theta_k = \theta_1^k,$$ arises, then constraint matrices returned by cm.ARMA() are conformable to the use of loglink.

On the other hand, the following hypothesis $$Ho: \theta_k = k * \theta_1,$$ properly adapts to the link function identitylink. \(k = 2, 3,\ ldots\).

For further details on parameter link functions within VGAM, see CommonVGAMffArguments.

Author

Victor Miranda and T. W. Yee

Details

NOTE: Except for the Model, all arguments of length 1 are recycled when Resp \( \geq 2\).

Time Series family functions in VGAMextra that are derived from AR(p) or MA(q) processes include the drift term (or mean) and the white noise standard deviation as the first two elements in the vector parameter. For an MA(4), for example, it is given by $$(\mu, \sigma_\varepsilon, \phi_1, \phi_2, \phi_3, \phi_4).$$

Thus, constraint matrices on coefficients can be stated from the second coefficient, i.e., from \(\phi_2\). This feature is specified with offset = -2 by default.

In other words, offset indicates the exact position at which parameter restrictions commence. For example, offset = -3 indicates that \(\phi_3\) is the first coefficient over which constraints are applied. Then, in order to successfully utilize this argument, it must be greater than or equal to 2 in absolute value. Otherwise, an error message will be displayed as no single restriction are amenable with \(\phi_1\) only.

Furthermore, if lags.cm = 1, i.e, a AR or MA process of order one is being fitted, then NO constraints are required either, as only one coefficient is directly considered.

Hence, the miminum absolute value for argument offset is 2

As for the factorSeq argument, its defaul value is 2. Let factorSeq = 4, lags.cm = 5, offset = -3, and whichCoeff = 1. The coefficient restrictions if a geometric progression is assumed are

$$ \theta_3 = \theta_1^4, $$ $$ \theta_4 = \theta_1^5, $$ $$ \theta_5 = \theta_1^6, $$

If coefficient restrictions are in arithmetic sequence, constraints are given by

$$ \theta_3 = 4 * \theta_1, $$ $$ \theta_4 = 5 * \theta_1, $$ $$ \theta_5 = 6 * \theta_1, $$

The difference lies on thelink function used: loglink for the first case, and identitylink for the latter.

Note that conditions above are equivalent to test the following two Null Hypotheses: $$Ho: \theta_k = \theta_1^k$$ or $$Ho: \theta_k = j * \theta_1$$ for \(k = 3, 4, 5\).

Simpler hypotheses can be tested by properly setting all arguments in cm.ARMA(). For instance, the default list of constraint matrices returned by cm.ARMA() allows to test $$Ho: \theta_k = \theta_1^j$$ for \(k = 2\), in a TS model of order-2 with one response.

References

Yee, T. W. and Hastie, T. J. (2003) Reduced-rank vector generalized linear models. Statistical Modelling, 3, 15--41.

Yee, T. W. (2008) The VGAM Package. R News, 8, 28--39.

See Also

loglink, rhobitlink, CommonVGAMffArguments.

Examples

#############
# Example 1.
#############
# Constraint matrices for a TS family function (AR or MA) 
# with 6 lagged terms.
# Restriction commences at the third position (theta[3]) powered to
# or multiplied by 4. Intercept-only model.
position   <- -3
numberLags <-  6
myfactor   <-  4
cm.ARMA(offset = position, lags.cm = numberLags, factorSeq = myfactor)

# With one covariate
cm.ARMA(Model =  ~ x2, offset = position, 
        lags.cm = numberLags, factorSeq = myfactor)

# \donttest{
# Or 2 responses...
cm.ARMA(offset = position, lags.cm = numberLags, 
        factorSeq = myfactor, Resp = 2)


# The following call causes an ERROR.
# cm.ARMA(offset = -1, lags.cm = 6, factorSeq = 2)
# }

##############
# Example 2.
##############

# In this example, the use of constraints via 'cm.ARMA()' is
# included in the 'vglm' call. Here, two AR(2) models are fitted
# in the same call (i.e. two responses), where different constraints
# are set, as follows:
# a) list(ar = c(theta1, theta1^2)) and
# b) list(ar = c(theta2, theta2^2 )).

# 2.0 Generate the data.
set.seed(1001)
nn     <- 100
# A single covariate.
covdata <- data.frame(x2 =  runif(nn)) 

theta1 <- 0.40; theta2 <- 0.55
drift  <- c(0.5, 0.75)
sdAR   <- c(sqrt(2.5), sqrt(2.0))

# Generate AR sequences, TS1 and TS2, considering Gaussian white noise

# Save both in a data.frame object: the data.
tsdata  <- 
  data.frame(covdata, # Not used 
             TS1 = arima.sim(nn, 
                             model = list(ar = c(theta1, theta1^2)), 
                             rand.gen = rnorm, 
                             mean = drift[1], sd = sdAR[1]),
             TS2 = arima.sim(nn, 
                             model = list(ar = c(theta2, theta2^2)), 
                             rand.gen = rnorm, 
                             mean = drift[2], sd = sdAR[2]))

# 2.1 Fitting both time series with 'ARXff'... multiple responses case.
fit1 <- vglm(cbind(TS1, TS2) ~ 1, 
             ARXff(order = c(2, 2), type.EIM = "exact"), 
             data = tsdata,  
             trace = TRUE)

Coef(fit1)                
coef(fit1, matrix = TRUE)
summary(fit1)

## Same length for both vectors, i.e. no constraints.
length(Coef(fit1))
length(coef(fit1, matrix = TRUE))




###2.2 Now, fit the same models with suitable constraints via 'cm.ARMA()'
# Most importantly, "loglink" is used as link function to adequately match 
# the relationship between coefficients and constraints. That is:
# theta2 = theta1^2, then log(theta2) = 2 * log(theta1).

fit2 <- vglm(cbind(TS1, TS2) ~ 1, 
             ARXff(order = c(2, 2), type.EIM = "exact", lARcoeff = "loglink"), 
             constraints = cm.ARMA(Model = ~ 1, 
                                   Resp = 2,
                                   lags.cm = c(2, 2),
                                   offset  = -2),
             data = tsdata,  
             trace = TRUE)
Coef(fit2)
coef(fit2, matrix = TRUE)
summary(fit2)

# NOTE, for model 1, Coeff2 = Coeff1^2, then log(Coeff2) = 2 * log(Coeff1)
( mycoef <- coef(fit2, matrix = TRUE)[c(3, 4)] )
2 * mycoef[1] - mycoef[2]    # SHOULD BE ZERO

# Ditto for model 2: 
( mycoef <- coef(fit2, matrix = TRUE)[c(7, 8)] )
2 * mycoef[1] - mycoef[2]    # SHOULD BE ZERO

## Different lengths, due to constraints
length(Coef(fit2))
length(coef(fit2, matrix = TRUE))