# Constraint matrices for vector generalized time series family functions. Constraint matrices for coefficients of vector genelized time series family functions in `VGAMextra`. ```r cm.ARMA(Model = ~ 1, Resp = 1, lags.cm = 2, offset = -2, whichCoeff = 1, factorSeq = 2) ``` ## 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. ## Details NOTE: Except for the `Model`, all arguments of length 1 are recycled when `Resp` $\ge 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).%(\mu, \sigma[e], \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[3] = \theta[1]^4, $$ $$ \theta_4 = \theta_1^5,\theta[4] = \theta[1]^5, $$ $$ \theta_5 = \theta_1^6,\theta[5] = \theta[1]^6, $$ If coefficient restrictions are in **arithmetic sequence**, constraints are given by $$ \theta_3 = 4 * \theta_1,\theta[3] = 4 * \theta[1], $$ $$ \theta_4 = 5 * \theta_1,\theta[4] = 5 * \theta[1], $$ $$ \theta_5 = 6 * \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^kHo: \theta[k] = \theta[1]^k $$ or $$ Ho: \theta_k = j * \theta_1Ho: \theta[k] = k * \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^jH: \theta[k] = \theta[1]^k $$ for $k = 2$, in a TS model of order-2 with one response. ## Returns 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. ## Warning Hypotheses above can be tested by properly applying **parameter link functions**. If the test $$ Ho: \theta_k = \theta_1^k,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,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`. ## 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. ## Author(s) Victor Miranda and T. W. Yee ## Note `cm.ARMA()` can be utilized to compute constraint matrices for many VGLTSM fmaily functions, e.g., `ARXff` and `MAXff` in `VGAMextra`. More improvements such as restrictions on the **drift parameter** and **white noise standard deviation** will be set later. ## See Also `loglink`, `rhobitlink`, `CommonVGAMffArguments`. ## Examples ```r ############# # 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) # 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)) ```

cm.ARMA function