R: Control Function for rrvglm()

rrvglm.control {VGAM}

R Documentation

Control Function for rrvglm()

Description

Algorithmic constants and parameters for running rrvglm are set using this function. Doubly constrained RR-VGLMs (DRR-VGLMs) are also catered for.

Usage

rrvglm.control(Rank = 1, Algorithm = "alternating",
    Corner = TRUE, Uncorrelated.latvar = FALSE, Wmat = NULL,
    Svd.arg = FALSE,
    Index.corner = head(setdiff(seq(length(str0) + Rank), str0), Rank),
    Ainit = NULL, Alpha = 0.5, Bestof = 1, Cinit = NULL,
    Etamat.colmax = 10, sd.Ainit = 0.02, sd.Cinit = 0.02,
    str0 = NULL, noRRR = ~1, Norrr = NA, noWarning = FALSE,
    trace = FALSE, Use.Init.Poisson.QO = FALSE,
    checkwz = TRUE, Check.rank = TRUE, Check.cm.rank = TRUE,
    wzepsilon = .Machine$double.eps^0.75,
    H.A.alt = list(), H.C = list(), scaleA = FALSE,
    Crow1positive = TRUE, ...)

Arguments

`Rank`	The numerical rank `R` of the model. Must be an element from the set {1,2,...,min(`M`,p2)}. Here, the vector of explanatory variables x is partitioned into (x1,x2), which is of dimension p1+p2. The variables making up x1 are given by the terms in `noRRR` argument, and the rest of the terms comprise x2.
`Algorithm`	Character string indicating what algorithm is to be used. The default is the first one. The choice `"derivative"` has been withdrawn in VGAM 1.1-10.
`Corner`	Logical indicating whether corner constraints are to be used. This is one method for ensuring a unique solution. If `TRUE`, `Index.corner` specifies the `R` rows of the constraint matrices that are use as the corner constraints, i.e., they hold an order-`R` identity matrix.
`Uncorrelated.latvar`	Logical indicating whether uncorrelated latent variables are to be used. This is normalization forces the variance-covariance matrix of the latent variables to be `diag(Rank)`, i.e., unit variance and uncorrelated. This constraint does not lead to a unique solution because it can be rotated. Update during 2023/2024: setting this argument to be `TRUE` might not work anymore.
`Wmat`	Yet to be done.
`Svd.arg`	Logical indicating whether a singular value decomposition of the outer product is to computed. This is another normalization which ensures uniqueness. See the argument `Alpha` below. Update during 2023/2024: setting this argument to be `TRUE` might not work anymore.
`Index.corner`	Specifies the `R` rows of the constraint matrices that are used for the corner constraints, i.e., they hold an order-`R` identity matrix. For certain DRR-VGLMs one does not want to have corner constraints (e.g., `CM.qnorm`) so setting (`scaleA = TRUE` and) `Corner = FALSE` will achieve this. Then arguments such as `Index.corner` and `str0` will be ignored. If there are structural zeros then they should be built into the constraint matrices.
`Alpha`	The exponent in the singular value decomposition that is used in the first part: if the SVD is `U D V^T` then the first and second parts are `U D^{\alpha}` and `D^{1-\alpha} V^T` respectively. A value of 0.5 is ‘symmetrical’. This argument is used only when `Svd.arg=TRUE`. Update during 2023/2024: using this argument might not work anymore.
`Bestof`	Integer. The best of `Bestof` models fitted is returned. This argument helps guard against local solutions by (hopefully) finding the global solution from many fits. The argument works only when the function generates its own initial value for C, i.e., when C is not passed in as initial values.
`Ainit`, `Cinit`	Initial A and C matrices which may speed up convergence. They must be of the correct dimension.
`Etamat.colmax`	Positive integer, no smaller than `Rank`. Controls the amount of memory used by `.Init.Poisson.QO()`. It is the maximum number of columns allowed for the pseudo-response and its weights. In general, the larger the value, the better the initial value. Used only if `Use.Init.Poisson.QO=TRUE`.
`str0`	Integer vector specifying which rows of the estimated constraint matrices (A) are to be all zeros. These are called structural zeros. Must not have any common value with `Index.corner`, and be a subset of the vector `1:M`. The default, `str0 = NULL`, means no structural zero rows at all.
`sd.Ainit`, `sd.Cinit`	Standard deviation of the initial values for the elements of A and C. These are normally distributed with mean zero. This argument is used only if `Use.Init.Poisson.QO = FALSE`.
`noRRR`	Formula giving terms that are not to be included in the reduced-rank regression. That is, `noRRR` specifes which explanatory variables are in the `x_1` vector of `rrvglm`, and the rest go into `x_2`. The `x_1` variables constitute the `\bold{B}_1` matrix in Yee and Hastie (2003). Those `x_2` variables which are subject to the reduced-rank regression correspond to the `\bold{B}_2` matrix. Set `noRRR = NULL` for the reduced-rank regression to be applied to every explanatory variable including the intercept.
`Norrr`	Defunct. Please use `noRRR`. Its use results in an error. The argument may be removed soon.
`trace`	Logical indicating if output should be produced for each iteration.
`Use.Init.Poisson.QO`	Logical indicating whether the `.Init.Poisson.QO()` should be used to obtain initial values for the C. The function uses a new method that can work well if the data are Poisson counts coming from an equal-tolerances QRR-VGLM (CQO). This option is less realistic for RR-VGLMs compared to QRR-VGLMs.
`checkwz`	logical indicating whether the diagonal elements of the working weight matrices should be checked whether they are sufficiently positive, i.e., greater than `wzepsilon`. If not, any values less than `wzepsilon` are replaced with this value.
`noWarning`, `Check.rank`, `Check.cm.rank`	Same as `vglm.control`. Ignored for VGAM 0.9-7 and higher.
`wzepsilon`	Small positive number used to test whether the diagonals of the working weight matrices are sufficiently positive.
`H.A.alt`, `H.C`	Lists. DRR-VGLMs are doubly constrained RR-VGLMs where A has `Rank` constraint matrices (one for each column) in a list called `H.A.alt`, and C has a constraint matrix for each row, i.e., for each explanatory variable making up it. The class `"drrvglm"` may arise for such models. So `H.C` should be a named list of `p_2` constraint matrices, each one for a different row of C, i.e., `p_2` is the number of variables making up the latent variable. Note that if `H.C` has `names` then matching is done with that, and the components of `H.C` are reordered if they are not sorted according to the terms in `formula`. If they are not named, then their order is used, for example, `H.C[[1]]` and `H.C[[2]]` are taken as the constraint matrices for the first two variables of the latent variable(s).
`scaleA`	Logical. Another uniqueness constraint to obtain a unique A and C. If `H.A.alt` and/or `H.C` are inputted then sometimes one wants to preserve the structure in A, e.g., `CM.qnorm`. Here, `A <- scale(A, center = FALSE)` so that only the columns are multiplicatively scaled. Note that the estimates of the elements of A and C are unique, up to their sign. Also note that ideally the attributes `attr(,"scaled:scale")` should be unity upon convergence so that if they differ substantially from that then this suggests some misbehaviour in convergence.
`Crow1positive`	Logical vector of length `Rank` (recycled if necessary): are the elements of the first row of `C` positive? For example, if `Rank` is 4, then specifying `Crow1positive = c(FALSE, TRUE)` will force `C[1,1]` and `C[1,3]` to be negative, and `C[1,2]` and `C[1,4]` to be positive. This argument therefore allows the user to determine the direction of the latent variables since they are unique up to a sign. This argument certainly works for RR-VGLMs but may not be applicable to DRR-VGLMs because the constraint matrices may control their sign.
`...`	Variables in ... are passed into `vglm.control`. If the derivative algorithm is used then ... are also passed into `rrvglm.optim.control`; and if the alternating algorithm is used then ... are also passed into `valt0.control`.

In the above, R is the Rank and M is the number of linear predictors.

Details

VGAM supports three normalizations to ensure a unique solution. Of these, only corner constraints will work with summary of RR-VGLM objects. Update during late-2023/early-2024: with ongoing work implementing the "drrvglm" class, there may be disruption and changes to other normalizations. However, corner constraints should be fully supported and have the greatest priority.

Value

A list with components matching the input names. Some error checking is done, but not much.

Note

The arguments in this function begin with an upper case letter to help avoid interference with those of vglm.control.

In the example below a rank-1 stereotype model (Anderson, 1984) is fitted. However, the intercepts ideally should be sorted and that might now be achieved using CM.symm0, CM.equid, CM.qnorm, etc. Currently the intercepts are completely unconstrained.

Author(s)

Thomas W. Yee

References

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

Examples

## Not run: 
set.seed(111)
pneumo <- transform(pneumo, let = log(exposure.time),
                            x3 = runif(nrow(pneumo)))  # Unrelated
fit <- rrvglm(cbind(normal, mild, severe) ~ let + x3,
              multinomial, pneumo, Rank = 1, Index.corner = 2)
constraints(fit)
vcov(fit)
summary(fit)

## End(Not run)

[Package VGAM version 1.1-10 Index]