- link.list, earg.list
Some VGAM family functions
(such as normal.vcm)
implement models with
potentially lots of parameter link functions.
These two arguments allow many such links and extra arguments
to be inputted more easily.
One has something like
link.list = list
("(Default)" = "identitylink", x2 = "loglink", x3 = "logofflink")
and
earg.list = list
("(Default)" = list(), x2 = list(), x3 = "list(offset = -1)").
Then any unnamed terms will have the default link with its
corresponding extra argument.
Note: the multilogitlink link is also possible,
and if so, at least two instances of it are necessary.
Then the last term is the baseline/reference group.
- isigma
Optional initial values can often be inputted using an argument
beginning with "i".
For example, "isigma" and "ilocation", or just
"init" if there is one parameter.
A value of NULL means a value is computed internally, i.e.,
a self-starting VGAM family function.
If a failure to converge occurs make use of these types of arguments.
- gsigma
Grid-search initial values can be inputted using an argument
beginning with "g",
e.g., "gsigma", "gshape" and "gscale".
If argument isigma is inputted then that has precedence over
gsigma, etc.
If the grid search is 2-dimensional then it is advisable not to
make the vectors too long as a nested for loop may be used.
Ditto for 3-dimensions etc.
Sometimes a ".mux" is added as a suffix, e.g., gshape.mux;
this means that the grid is created relatively and not absolutely,
e.g., its values are multipled by some single initial estimate of the
parameter in order to create the grid on an absolute scale.
Some family functions have an argument called gprobs.y.
This is fed into the probs
argument of quantile in order to
obtain some values of central tendency of the response,
i.e., some spread of values in the middle.
when imethod = 1 to obtain an initial value for the mean
Some family functions have an argument called iprobs.y, and
if so, then these values can overwrite gprobs.y.
- parallel
A logical, or a simple formula specifying which terms have
equal/unequal
coefficients.
The formula must be simple, i.e.,
additive with simple main effects terms.
Interactions and nesting etc. are not handled.
To handle complex formulas use the constraints argument
(of vglm etc.);
however, there is a lot more setting up involved and things will
not be as convenient.
Here are some examples.
1. parallel = TRUE ~ x2 + x5 means the parallelism assumption
is only applied to \(X_2\), \(X_5\) and the intercept.
2. parallel = TRUE ~ -1
and parallel = TRUE ~ 0
mean the parallelism assumption
is applied to no variables at all.
Similarly,
parallel = FALSE ~ -1 and
parallel = FALSE ~ 0
mean the parallelism assumption
is applied to all the variables including the intercept.
3. parallel = FALSE ~ x2 - 1
and parallel = FALSE ~ x2 + 0
applies the
parallelism constraint to all terms (including the intercept)
except for \(X_2\).
This argument is common in VGAM family functions for categorical
responses, e.g., cumulative, acat,
cratio, sratio.
For the proportional odds model (cumulative) having
parallel constraints applied to each explanatory variable (except for
the intercepts) means the fitted probabilities do not become negative
or greater than 1. However this parallelism or proportional-odds
assumption ought to be checked.
- nsimEIM
Some VGAM family functions use simulation to obtain an
approximate
expected information matrix (EIM).
For those that do, the nsimEIM argument specifies the number
of random variates used per observation; the mean of nsimEIM
random variates is taken.
Thus nsimEIM controls the accuracy and a larger value may be
necessary if the EIMs are not positive-definite.
For intercept-only models (y ~ 1) the value of nsimEIM
can be smaller (since the common value used is also then taken as the
mean over the observations), especially if the number of observations
is large.
Some VGAM family functions provide two algorithms for estimating
the EIM.
If applicable, set nsimEIM = NULL to choose the other algorithm.
- imethod
An integer with value 1 or 2 or 3 or ... which
specifies the initialization method for some parameters or a specific
parameter.
If failure to converge occurs try the next higher value, and
continue until success.
For example, imethod = 1 might be the method of moments,
and imethod = 2 might be another method.
If no value of imethod works then it will be necessary
to use arguments such as isigma.
For many VGAM family functions it is advisable to try
this argument with all possible values to safeguard against
problems such as converging to a local solution.
VGAM family functions with this argument usually correspond
to a model or distribution that is relatively hard to fit successfully,
therefore care is needed to ensure the global solution is obtained.
So using all possible values that this argument supplies is a good idea.
VGAM family functions such genpoisson2 recycle
imethod to be of length 2 corresponding to the 2
parameters. In the future, this feature will be extended to
other family functions to confer more flexibility.
- type.fitted
Character.
Type of fitted value returned by the fitted() methods function.
The first choice is always the default.
The available choices depends on what kind of family function it is.
Using the first few letters of the chosen choice is okay.
See fittedvlm for more details.
The choice "Qlink" refers to quantile-links, which was
introduced in December 2018 in VGAMextra 0.0-2 for
several 1-parameter distributions.
Here, either the
loglink or
logitlink or
identitylink of the quantile is the link function
(and the choice is dependent on the support of the distribution),
and link functions end in "Qlink".
A limited amount of support is provided for such links,
e.g.,
fitted(fit) are the fitted quantiles, which is the same as
predict(fit, type = "response").
However, fitted(fit, percentiles = 77) will not work.
- percentiles
Numeric vector, with values between 0 and 100
(although it is not recommended that exactly 0 or 100 be inputted).
Used only if type.fitted = "quantiles" or
type.fitted = "percentiles", then
this argument specifies the values of these quantiles.
The argument name tries to reinforce that the values
lie between 0 and 100.
See fittedvlm for more details.
- probs.x, probs.y
Numeric, with values in (0, 1).
The probabilites that define quantiles with respect to some vector,
usually an x or y of some sort.
This is used to create two subsets of data corresponding to `low' and
`high' values of x or y.
Each value is separately fed into the probs argument
of quantile.
If the data set size is small then it may be necessary to
increase/decrease slightly the first/second values respectively.
- lss
Logical.
This stands for the ordering: location, scale and shape.
Should the ordering of the parameters be in this order?
Almost all VGAM family functions have this order by default,
but in order to match the arguments of existing R functions, one
might need to set lss = FALSE.
For example, the arguments of weibullR are
scale and shape, whereas rweibull
are shape and scale.
As a temporary measure
(from VGAM 0.9-7 onwards but prior to version 1.0-0),
some family functions such as sinmad have an
lss argument without a default. For these,
setting lss = FALSE will work.
Later, lss = TRUE will be the default.
Be careful for the dpqr-type functions, e.g.,
rsinmad.
- whitespace
Logical.
Should white spaces (" ") be used in the
labelling of the linear/additive predictors?
Setting TRUE usually results in more readability but
it occupies more columns of the output.
- oim
Logical.
Should the observed information matrices (OIMs) be used for
the working weights?
In general, setting oim = TRUE means the Newton-Raphson
algorithm, and oim = FALSE means Fisher-scoring.
The latter uses the EIM, and is usually recommended.
If oim = TRUE then nsimEIM is ignored.
- zero
Either an integer vector, or a vector of character strings.
If an integer, then it specifies which
linear/additive predictor is modelled as intercept-only.
That is, the regression coefficients are
set to zero for all covariates except for the intercept.
If zero is specified then it may be a vector with values
from the set \(\{1,2,\ldots,M\}\).
The value zero = NULL means model all linear/additive
predictors as functions of the explanatory variables.
Here, \(M\) is the number of linear/additive predictors.
Technically, if zero contains the value \(j\) then
the \(j\)th row of every constraint matrix (except for the
intercept) consists of all 0 values.
Some VGAM family functions allow the zero argument to
accept negative values; if so then its absolute value is recycled
over each (usual) response. For example, zero = -2 for the
two-parameter negative binomial distribution would mean,
for each response, the second linear/additive predictor is modelled
as intercepts-only. That is, for all the \(k\) parameters in
negbinomial (this VGAM family function can handle
a matrix of responses).
Suppose zero = zerovec where zerovec is a vector
of negative values. If \(G\) is the usual \(M\) value for
a univariate response then the actual values for argument zero
are all values in
c(abs(zerovec), G + abs(zerovec), 2*G + abs(zerovec), ... )
lying in the integer range \(1\) to \(M\).
For example, setting zero = -c(2, 3) for a matrix response
of 4 columns with zinegbinomial (which
usually has \(G = M = 3\) for a univariate response)
would be equivalent to zero = c(2, 3, 5, 6, 8, 9, 11, 12).
This example has \(M = 12\).
Note that if zerovec contains negative values then their
absolute values should be elements from the set 1:G.
Note: zero may have positive and negative values,
for example, setting zero = c(-2, 3) in the above example
would be equivalent to zero = c(2, 3, 5, 8, 11).
The argument zero also
accepts a character vector (for VGAM 1.0-1 onwards).
Each value is fed into grep with
fixed = TRUE, meaning that wildcards "*" are not useful.
See the example below---all the variants work;
those with LOCAT issue a warning that that value is unmatched.
Importantly, the parameter names
are c("location1", "scale1", "location2", "scale2")
because there are 2 responses.
Yee (2015) described zero for only numerical input.
Allowing character input is particularly important when the
number of parameters cannot be determined without having the actual
data first. For example, with time series data,
an ARMA(\(p\),\(q\)) process
might have parameters \(\theta_1,\ldots,\theta_p\) which should
be intercept-only by default. Then specifying a numerical default
value for zero would be too difficult (there are the drift
and scale parameters too).
However, it is possible with the character representation:
zero = "theta" would achieve this.
In the future, most VGAM family functions might be converted
to the character representation---the advantage being that it
is more readable.
When programming a VGAM family function that allows character
input, the variable predictors.names
must be assigned correctly.
If the constraints argument is used then the
family function's zero argument (if it exists)
needs to be set to
NULL. This avoids what could be a probable contradiction.
Sometimes setting other arguments related to constraint
matrices to FALSE is also a good idea, e.g.,
parallel = FALSE,
exchangeable = FALSE.
- ishrinkage
Shrinkage factor \(s\) used for obtaining initial values.
Numeric, between 0 and 1.
In general, the formula used is something like
\(s \mu + (1-s) y\)
where \(\mu\) is a measure of central tendency such as a weighted
mean or median, and \(y\) is the response vector.
For example, the initial values are slight perturbations of
the mean towards the actual data.
For many types of models this method seems to work well and is often
reasonably robust to outliers in the response.
Often this argument is only used if
the argument imethod is assigned a certain value.
- nointercept
An integer-valued vector specifying which
linear/additive predictors have no intercepts.
Any values must be from the set {1,2,...,\(M\)}.
A value of NULL means no such constraints.
- multiple.responses
Logical.
Some VGAM family functions allow a multivariate or
vector response.
If so, then usually the response is a matrix with columns
corresponding to the individual response variables.
They are all fitted simultaneously.
Arguments such as parallel may then be useful to allow
for relationships between the regressions of each response variable.
If multiple.responses = TRUE then sometimes the response
is interpreted
differently, e.g., posbinomial chooses the first
column of a matrix response as success and combines the other
columns as failure, but when multiple.responses = TRUE
then each column
of the response matrix is the number of successes and the
weights argument is of the same dimension as the
response and contains the number of trials.
- earg.link
This argument should be generally ignored.
- byrow.arg
Logical.
Some VGAM family functions that handle multiple responses
have arguments that allow input to be fed in which affect
all the responses,
e.g., imu for initalizing a mu parameter.
In such cases it is sometime more convenient
to input one value per response by
setting byrow.arg = TRUE; then values are recycled
in order to form a matrix of the appropriate dimension.
This argument matches byrow in matrix;
in fact it is fed into such using matrix(..., byrow = byrow.arg).
This argument has no effect when there is one response.
- bred
Logical.
Some VGAM family functions will allow bias-reduction based
on the work by Kosmidis and Firth.
Sometimes half-stepping is a good idea; set stepsize = 0.5
and monitor convergence by setting trace = TRUE.