Links: Link functions for VGLM/VGAM/etc. families
In VGAM: Vector Generalized Linear and Additive Models
Links R Documentation
Link functions for VGLM/VGAM/etc. families
Description
The VGAM package provides a number of
(parameter) link functions which are described
in general here. Collectively, they offer the
user considerable choice and flexibility for
modelling data.
Usage
TypicalVGAMlink(theta, someParameter = 0, bvalue = NULL, inverse = FALSE,
deriv = 0, short = TRUE, tag = FALSE)
Arguments
theta
Numeric or character.
This is usually \theta (default)
but can sometimes be \eta,
depending on the other arguments.
If theta is character then inverse and
deriv are ignored.
The name theta should always be the
name of the first argument.
someParameter
Some parameter, e.g., an offset.
bvalue
Boundary value, positive if given.
If 0 < theta then
values of theta which are less than
or equal to 0 can be replaced by bvalue
before computing the link function value.
Values of theta which are greater than
or equal to 1 can be
replaced by 1 minus bvalue
before computing the link function value.
The value bvalue = .Machine$double.eps
is sometimes a reasonable value, or something
slightly higher.
inverse
Logical. If TRUE and deriv = 0 then
the inverse link value
\theta is returned, hence the argument
theta is really \eta.
In all other cases, the argument theta is
really \theta.
deriv
Integer.
Either 0, 1, or 2, specifying the order of
the derivative.
Most link functions handle values up to 3 or 4.
Some links can even handle values up to 9 but may
suffer from catastrophic cancellation near the
boundaries,
be inefficient and slow because they are
based on D.
short, tag
Logical.
These are used for labelling the blurb
slot of a vglmff-class object.
These arguments are used only if theta
is character, and gives the formula for the
link in character form. If tag = TRUE
then the result is preceeded by a little
more information.
Details
Almost all VGAM link functions have
something similar to the argument list as
given above. In this help file we have
\eta = g(\theta)
where g is the link function,
\theta is the parameter and
\eta is the linear/additive
predictor. The link g must be strictly
monotonic and twice-differentiable in its
range.
The following is a brief enumeration of all
VGAM link functions.
For parameters lying between 0 and 1 (e.g.,
probabilities):
logitlink,
probitlink,
clogloglink,
cauchitlink,
foldsqrtlink,
logclink.
For positive parameters
(i.e., greater than 0):
loglink,
negloglink,
sqrtlink,
powerlink.
For parameters greater than 1:
logloglink,
loglogloglink (greater than e).
For parameters between -1 and 1:
fisherzlink,
rhobitlink.
For parameters between finite A and B:
extlogitlink,
logofflink (B = \infty).
For unrestricted parameters (i.e., any value):
identitylink,
negidentitylink,
reciprocallink,
negreciprocallink.
Value
Returns one of:
the link function value or its first or second
derivative, the inverse link or its first or
second derivative, or a character description
of the link.
Here are the general details.
If inverse = FALSE and deriv = 0
(default) then the ordinary link function
\eta = g(\theta)
is returned.
If inverse = TRUE and deriv =
0 then the inverse link function value
is returned, hence theta is really
\eta (the only occasion this
happens).
If inverse = FALSE and deriv
= 1 then it is d\eta / d\theta as a function of
\theta. If inverse =
FALSE and deriv = 2 then it is
d^2\eta / d\theta^2
as a function of \theta.
If inverse = TRUE and deriv
= 1 then it is d\theta / d\eta as a function of
\theta. If inverse = TRUE
and deriv = 2 then it is d^2\theta
/ d\eta^2 as a
function of \theta.
It is only when deriv = 1 that
linkfun(theta, deriv = 1, inverse = TRUE)
and
linkfun(theta, deriv = 1, inverse = FALSE)
are reciprocals of each other.
In particular,
linkfun(theta, deriv = 2, inverse = TRUE)
and
linkfun(theta, deriv = 2, inverse = FALSE)
are not reciprocals of each other
in general.
Warning
The output of link functions changed at
VGAM 0.9-9 (date was around
2015-07). Formerly, linkfun(theta,
deriv = 1) is now linkfun(theta,
deriv = 1, inverse = TRUE), or equivalently,
1 / linkfun(theta, deriv = 1, inverse =
TRUE). Also, formerly, linkfun(theta,
deriv = 2) was 1 / linkfun(theta,
deriv = 2, inverse = TRUE). This was a bug.
Altogether, these are big changes and the
user should beware!
In VGAM 1.0-7 (January 2019)
all link function names were made to
end in the characters "link",
e.g.,
loglink replaces loge,
logitlink replaces logit.
For this most of them were renamed.
Upward compatability holds for older link
function names, however, users should adopt
the new names immediately.
Note
VGAM link functions are generally
not compatible with other functions outside
the package. In particular, they won't work
with glm or any other
package for fitting GAMs.
From October 2006 onwards,
all VGAM family functions will only
contain one default value for each link
argument rather than giving a vector
of choices. For example, rather than
binomialff(link = c("logitlink",
"probitlink", "clogloglink", "cauchitlink",
"identitylink"), ...) it is now
binomialff(link = "logitlink", ...).
No checking will be done to see if the user's
choice is reasonable. This means that the
user can write his/her own VGAM link
function and use it within any VGAM
family function. Altogether this provides
greater flexibility. The downside is that
the user must specify the full name of
the link function, by either assigning the
link argument the full name as a character
string, or just the name itself. See the
examples below.
From August 2012 onwards, a major
change in link functions occurred.
Argument esigma (and the like such
as earg) used to be in VGAM
prior to version 0.9-0 (released during the
2nd half of 2012).
The major change is that arguments such as
offset that used to be passed in via
those arguments can done directly through
the link function. For example,
gev(lshape = "logofflink", eshape = list(offset = 0.5))
is replaced by
gev(lshape = logofflink(offset = 0.5)).
The @misc slot no longer
has link and earg components,
but two other components replace
these. Functions such as
dtheta.deta(),
d2theta.deta2(),
d3theta.deta3(),
eta2theta(),
theta2eta()
are modified.
From January 2019 onwards, all link function
names ended in "link". See above
for details.
Author(s)
T. W. Yee
References
McCullagh, P. and Nelder, J. A. (1989).
Generalized Linear Models,
2nd ed. London: Chapman & Hall.
See Also
TypicalVGAMfamilyFunction,
linkfun,
vglm,
vgam,
rrvglm.
cqo,
cao.
Examples
logitlink("a")
logitlink("a", short = FALSE)
logitlink("a", short = FALSE, tag = TRUE)
logofflink(1:5, offset = 1) # Same as log(1:5 + 1)
powerlink(1:5, power = 2) # Same as (1:5)^2
## Not run: # This is old and no longer works:
logofflink(1:5, earg = list(offset = 1))
powerlink(1:5, earg = list(power = 2))
## End(Not run)
fit1 <- vgam(agaaus ~ altitude,
binomialff(link = "clogloglink"), hunua) # best
fit2 <- vgam(agaaus ~ altitude,
binomialff(link = clogloglink ), hunua) # okay
## Not run:
# This no longer works since "clog" is not a valid VGAM link function:
fit3 <- vgam(agaaus ~ altitude,
binomialff(link = "clog"), hunua) # not okay
# No matter what the link, the estimated var-cov matrix is the same
y <- rbeta(n = 1000, shape1 = exp(0), shape2 = exp(1))
fit1 <- vglm(y ~ 1, betaR(lshape1 = "identitylink",
lshape2 = "identitylink"),
trace = TRUE, crit = "coef")
fit2 <- vglm(y ~ 1, betaR(lshape1 = logofflink(offset = 1.1),
lshape2 = logofflink(offset = 1.1)), trace=TRUE)
vcov(fit1, untransform = TRUE)
vcov(fit1, untransform = TRUE) -
vcov(fit2, untransform = TRUE) # Should be all 0s
\dontrun{ # This is old:
fit1@misc$earg # Some 'special' parameters
fit2@misc$earg # Some 'special' parameters are here
}
par(mfrow = c(2, 2))
p <- seq(0.05, 0.95, len = 200) # A rather restricted range
x <- seq(-4, 4, len = 200)
plot(p, logitlink(p), type = "l", col = "blue")
plot(x, logitlink(x, inverse = TRUE), type = "l", col = "blue")
plot(p, logitlink(p, deriv=1), type="l", col="blue") # 1 / (p*(1-p))
plot(p, logitlink(p, deriv=2), type="l", col="blue") # (2*p-1)/(p*(1-p))^2
## End(Not run)
VGAM documentation built on Sept. 18, 2024, 9:09 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Links | R Documentation |
Link functions for VGLM/VGAM/etc. families
Description
The VGAM package provides a number of (parameter) link functions which are described in general here. Collectively, they offer the user considerable choice and flexibility for modelling data.
Usage
TypicalVGAMlink(theta, someParameter = 0, bvalue = NULL, inverse = FALSE,
deriv = 0, short = TRUE, tag = FALSE)
Arguments
theta |
Numeric or character.
This is usually |
someParameter |
Some parameter, e.g., an offset. |
bvalue |
Boundary value, positive if given.
If |
inverse |
Logical. If |
deriv |
Integer.
Either 0, 1, or 2, specifying the order of
the derivative.
Most link functions handle values up to 3 or 4.
Some links can even handle values up to 9 but may
suffer from catastrophic cancellation near the
boundaries,
be inefficient and slow because they are
based on |
short, tag |
Logical.
These are used for labelling the |
Details
Almost all VGAM link functions have
something similar to the argument list as
given above. In this help file we have
\eta = g(\theta)
where g is the link function,
\theta is the parameter and
\eta is the linear/additive
predictor. The link g must be strictly
monotonic and twice-differentiable in its
range.
The following is a brief enumeration of all VGAM link functions.
For parameters lying between 0 and 1 (e.g.,
probabilities):
logitlink,
probitlink,
clogloglink,
cauchitlink,
foldsqrtlink,
logclink.
For positive parameters
(i.e., greater than 0):
loglink,
negloglink,
sqrtlink,
powerlink.
For parameters greater than 1:
logloglink,
loglogloglink (greater than e).
For parameters between -1 and 1:
fisherzlink,
rhobitlink.
For parameters between finite A and B:
extlogitlink,
logofflink (B = \infty).
For unrestricted parameters (i.e., any value):
identitylink,
negidentitylink,
reciprocallink,
negreciprocallink.
Value
Returns one of: the link function value or its first or second derivative, the inverse link or its first or second derivative, or a character description of the link.
Here are the general details.
If inverse = FALSE and deriv = 0
(default) then the ordinary link function
\eta = g(\theta)
is returned.
If inverse = TRUE and deriv =
0 then the inverse link function value
is returned, hence theta is really
\eta (the only occasion this
happens).
If inverse = FALSE and deriv
= 1 then it is d\eta / d\theta as a function of
\theta. If inverse =
FALSE and deriv = 2 then it is
d^2\eta / d\theta^2
as a function of \theta.
If inverse = TRUE and deriv
= 1 then it is d\theta / d\eta as a function of
\theta. If inverse = TRUE
and deriv = 2 then it is d^2\theta
/ d\eta^2 as a
function of \theta.
It is only when deriv = 1 that
linkfun(theta, deriv = 1, inverse = TRUE)
and
linkfun(theta, deriv = 1, inverse = FALSE)
are reciprocals of each other.
In particular,
linkfun(theta, deriv = 2, inverse = TRUE)
and
linkfun(theta, deriv = 2, inverse = FALSE)
are not reciprocals of each other
in general.
Warning
The output of link functions changed at
VGAM 0.9-9 (date was around
2015-07). Formerly, linkfun(theta,
deriv = 1) is now linkfun(theta,
deriv = 1, inverse = TRUE), or equivalently,
1 / linkfun(theta, deriv = 1, inverse =
TRUE). Also, formerly, linkfun(theta,
deriv = 2) was 1 / linkfun(theta,
deriv = 2, inverse = TRUE). This was a bug.
Altogether, these are big changes and the
user should beware!
In VGAM 1.0-7 (January 2019)
all link function names were made to
end in the characters "link",
e.g.,
loglink replaces loge,
logitlink replaces logit.
For this most of them were renamed.
Upward compatability holds for older link
function names, however, users should adopt
the new names immediately.
Note
VGAM link functions are generally
not compatible with other functions outside
the package. In particular, they won't work
with glm or any other
package for fitting GAMs.
From October 2006 onwards,
all VGAM family functions will only
contain one default value for each link
argument rather than giving a vector
of choices. For example, rather than
binomialff(link = c("logitlink",
"probitlink", "clogloglink", "cauchitlink",
"identitylink"), ...) it is now
binomialff(link = "logitlink", ...).
No checking will be done to see if the user's
choice is reasonable. This means that the
user can write his/her own VGAM link
function and use it within any VGAM
family function. Altogether this provides
greater flexibility. The downside is that
the user must specify the full name of
the link function, by either assigning the
link argument the full name as a character
string, or just the name itself. See the
examples below.
From August 2012 onwards, a major
change in link functions occurred.
Argument esigma (and the like such
as earg) used to be in VGAM
prior to version 0.9-0 (released during the
2nd half of 2012).
The major change is that arguments such as
offset that used to be passed in via
those arguments can done directly through
the link function. For example,
gev(lshape = "logofflink", eshape = list(offset = 0.5))
is replaced by
gev(lshape = logofflink(offset = 0.5)).
The @misc slot no longer
has link and earg components,
but two other components replace
these. Functions such as
dtheta.deta(),
d2theta.deta2(),
d3theta.deta3(),
eta2theta(),
theta2eta()
are modified.
From January 2019 onwards, all link function
names ended in "link". See above
for details.
Author(s)
T. W. Yee
References
McCullagh, P. and Nelder, J. A. (1989). Generalized Linear Models, 2nd ed. London: Chapman & Hall.
See Also
TypicalVGAMfamilyFunction,
linkfun,
vglm,
vgam,
rrvglm.
cqo,
cao.
Examples
logitlink("a")
logitlink("a", short = FALSE)
logitlink("a", short = FALSE, tag = TRUE)
logofflink(1:5, offset = 1) # Same as log(1:5 + 1)
powerlink(1:5, power = 2) # Same as (1:5)^2
## Not run: # This is old and no longer works:
logofflink(1:5, earg = list(offset = 1))
powerlink(1:5, earg = list(power = 2))
## End(Not run)
fit1 <- vgam(agaaus ~ altitude,
binomialff(link = "clogloglink"), hunua) # best
fit2 <- vgam(agaaus ~ altitude,
binomialff(link = clogloglink ), hunua) # okay
## Not run:
# This no longer works since "clog" is not a valid VGAM link function:
fit3 <- vgam(agaaus ~ altitude,
binomialff(link = "clog"), hunua) # not okay
# No matter what the link, the estimated var-cov matrix is the same
y <- rbeta(n = 1000, shape1 = exp(0), shape2 = exp(1))
fit1 <- vglm(y ~ 1, betaR(lshape1 = "identitylink",
lshape2 = "identitylink"),
trace = TRUE, crit = "coef")
fit2 <- vglm(y ~ 1, betaR(lshape1 = logofflink(offset = 1.1),
lshape2 = logofflink(offset = 1.1)), trace=TRUE)
vcov(fit1, untransform = TRUE)
vcov(fit1, untransform = TRUE) -
vcov(fit2, untransform = TRUE) # Should be all 0s
\dontrun{ # This is old:
fit1@misc$earg # Some 'special' parameters
fit2@misc$earg # Some 'special' parameters are here
}
par(mfrow = c(2, 2))
p <- seq(0.05, 0.95, len = 200) # A rather restricted range
x <- seq(-4, 4, len = 200)
plot(p, logitlink(p), type = "l", col = "blue")
plot(x, logitlink(x, inverse = TRUE), type = "l", col = "blue")
plot(p, logitlink(p, deriv=1), type="l", col="blue") # 1 / (p*(1-p))
plot(p, logitlink(p, deriv=2), type="l", col="blue") # (2*p-1)/(p*(1-p))^2
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.