logffMeanlink: Link functions for the mean of 1-parameter discrete...
In VGAMextra: Additions and Extensions of the 'VGAM' Package
logffMlink R Documentation
Link functions for the mean of 1–parameter
discrete distributions: The Logarithmic Distribuion.
Description
Computes the logffMlink transformation, including its inverse
and the first two derivatives.
Usage
logffMlink(theta, bvalue = NULL,
alg.roots = c("Newton-Raphson", "bisection")[1],
inverse = FALSE, deriv = 0, short = TRUE, tag = FALSE)
Arguments
theta
Numeric or character. This is \theta by default although could
be \eta depending on other parameters. See below for details.
bvalue
This is a boundary value. See below.
Also refer to Links for additional
details.
alg.roots
Character. The iterative algorithm to find the inverse of this link
function. Default is the first (Newton–Raphson). Optionally, the
bisection method is also available. See below for more details.
inverse, deriv, short, tag
Details at Links
Details
This link function arises as a natural link function for the mean,
\mu, of the logarithmic (or log-series) distribution,
logff. It is defined for any value
of the shape parameter s (i.e. theta in the
VGLM/VGAM context), 0 < s < 1, as the
logarithm of \mu = \mu(s). It can be easily shown that
logffMlink is the difference of two common link functions:
logitlink and
clogloglink.
It is particularly usefull for event–rate data where the expected
number of events can be modelled as
\mu = \mu(s) = \lambda t.
Here \lambda is the standardized mean (or event-rate)
per unit time, t is the timeframe observed,
whereas \mu and s are the mean and the
shape parameter of the logarithmic distribution respectively.
The logarithm is then applied to both sides so
that t can be incorporated in the analysis as an offset.
While logffMlink is not the canonical link function of
the logarithmic distribution, it is certainly part of the
canonical link, given by the composite
\log \circ~(g^{-1}) \circ \log,
where g^{-1} denotes the inverse of
logffMlink.
The domain set of this link function is (0, 1).
Therefore, values of theta (that is s) too close to
0 or to 1 or out of range will result in Inf,
-Inf, NA or NaN. Use argument bvalue
to adequately replace them before computing the link function.
Particularly, if inverse = TRUE and deriv = 0,
then s becomes \eta, and therefore the domain set
turns to (0, \infty).
If theta is a character, then arguments inverse and
deriv are disregarded.
Value
For deriv = 0, the logffMlink transformation of
theta, i.e., logitlink(theta) - clogloglink(theta), if
inverse = FALSE.
When inverse = TRUE the vector entered at theta
becomes \eta and, then, this link function
returns a unique vector \theta_{\eta} such that
{\tt{logffMlink}} (\theta_{\eta}) = \eta,
i.e., the inverse image of \eta.
Specifically, the inverse of logffMlink cannot be written in
closed–form, then the latter is equivalent to search for the roots
of the function
{\tt{logff.func}}(\theta) = {\tt{logffMlink}}(\theta) - \eta
as a function of \theta. To do this, the auxiliary
function logff.func is internally generated.
Then, with the method established at alg.roots,
either Newton–Raphson or bisection, this link function
approximates and returns the inverse image
\theta_{\eta} (of given \eta), which
plays the role of the inverse of logffMlink. In particular,
for \eta = 0 and \eta =Inf, it returns 0
and 1 respectively.
For deriv = 1, d eta / d theta
as a function of theta if inverse = FALSE, else
the reciprocal d theta / d eta.
Similarly, when deriv = 2 the second order derivatives
are correspondingly returned.
Both, first and second derivatives, can be written in closed–form.
Warning
logffMlink is a monotonically
increasing, convex, and strictly positive function in (0, 1) such
that the horizontal axis is an asymptote. Therefore, when the inverse
image of \eta is required, each entry of \eta
(via argument theta) must be non-negative so that
{\tt{logff.func}(\theta; \eta) = \tt{logffMlink}}(\theta) - \eta
is shifted down. This fact allows this function to uniquely
intersect the horizontal axis which guarantees to iteratively find
the corresponding root \theta_{\eta}, i.e., the
inverse image of \eta. Else, NaN will be returned.
See example 3. It is the plot of logffMlink in (0, 1)
for \eta = 1.5.
Besides, the vertical straight line theta = 1 is also
an asymptote. Hence, this link function may grow sharply for
values of theta too close to 1.
See Example 4 for further details.
Note
To find the inverse image \theta_{\eta} of
\eta, either
newtonRaphson.basic
or bisection.basic is
called.
This link function can be used for modelling any parameter lying
between 0.0 and 1.0. Consequently, when there are covariates,
some problems may occur. For example, the method entered
at alg.roots to approximate the inverse image may converge
at a slow rate. Similarly if the sample size is small, less than 20 say.
Try another link function, as
logitlink, in such cases.
Author(s)
V. Miranda and T. W. Yee
See Also
logff,
newtonRaphson.basic,
bisection.basic,
Links,
clogloglink,
logitlink.
Examples
## Example 1 ##
set.seed(0906)
Shapes <- sort(runif(10))
logffMlink(theta = Shapes, deriv = 1) ## d eta/d theta, as function of theta
logldata.inv <-
logffMlink(theta = logffMlink(theta = Shapes), inverse = TRUE) - Shapes
summary(logldata.inv) ## Should be zero
## Example 2 Some probability link funtions ##
s.shapes <- ppoints(100)
par(lwd = 2)
plot(s.shapes, logitlink(s.shapes), xlim = c(-0.1, 1.1), type = "l", col = "limegreen",
ylab = "transformation", las = 1, main = "Some probability link functions")
lines(s.shapes, logffMlink(s.shapes), col = "blue")
lines(s.shapes, probitlink(s.shapes), col = "purple")
lines(s.shapes, clogloglink(s.shapes), col = "chocolate")
lines(s.shapes, cauchitlink(s.shapes), col = "tan")
abline(v = c(0.5, 1), lty = "dashed")
abline(v = 0, h = 0, lty = "dashed")
legend(0.1, 4.5, c("logffMlink","logitlink", "probitlink", "clogloglink",
"cauchitlink"),
col = c("blue", "limegreen", "purple", "chocolate", "tan"), lwd = 1)
par(lwd = 1)
## Example 3. Plot of 'logffMlink()' with eta = 1.5. ##
m.eta1.5 <- logffMlink(theta = s.shapes, deriv = 0) - 1.5
plot(m.eta1.5 ~ s.shapes, type = "l", col = "limegreen",
las = 1, lty = 2, lwd = 3, xlim = c(-0.1, 1.0), ylim = c(-2, 3),
xlab = "shape parameter, s, in (0, 1).",
ylab = "logffMlink(s) - 1.5",
main = "logff.func(s; 1.5) = logffMlink(s) - 1.5, in (0, 1)")
abline(h = 0, v = 0)
abline(v = 1.0, lty = 2)
## Example 4. Special values of theta, inverse = FALSE ##
s.shapes <- c(-Inf, -2, -1, 0.0, 0.25, 0.5, 1, 10, 100, Inf, NaN, NA)
rbind(s.shapes, logffMlink(theta = s.shapes))
VGAMextra documentation built on Nov. 2, 2023, 5:59 p.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.
| logffMlink | R Documentation |
Link functions for the mean of 1–parameter discrete distributions: The Logarithmic Distribuion.
Description
Computes the logffMlink transformation, including its inverse
and the first two derivatives.
Usage
logffMlink(theta, bvalue = NULL,
alg.roots = c("Newton-Raphson", "bisection")[1],
inverse = FALSE, deriv = 0, short = TRUE, tag = FALSE)
Arguments
theta |
Numeric or character. This is |
bvalue |
This is a boundary value. See below.
Also refer to |
alg.roots |
Character. The iterative algorithm to find the inverse of this link function. Default is the first (Newton–Raphson). Optionally, the bisection method is also available. See below for more details. |
inverse, deriv, short, tag |
Details at |
Details
This link function arises as a natural link function for the mean,
\mu, of the logarithmic (or log-series) distribution,
logff. It is defined for any value
of the shape parameter s (i.e. theta in the
VGLM/VGAM context), 0 < s < 1, as the
logarithm of \mu = \mu(s). It can be easily shown that
logffMlink is the difference of two common link functions:
logitlink and
clogloglink.
It is particularly usefull for event–rate data where the expected number of events can be modelled as
\mu = \mu(s) = \lambda t.
Here \lambda is the standardized mean (or event-rate)
per unit time, t is the timeframe observed,
whereas \mu and s are the mean and the
shape parameter of the logarithmic distribution respectively.
The logarithm is then applied to both sides so
that t can be incorporated in the analysis as an offset.
While logffMlink is not the canonical link function of
the logarithmic distribution, it is certainly part of the
canonical link, given by the composite
\log \circ~(g^{-1}) \circ \log,
where g^{-1} denotes the inverse of
logffMlink.
The domain set of this link function is (0, 1).
Therefore, values of theta (that is s) too close to
0 or to 1 or out of range will result in Inf,
-Inf, NA or NaN. Use argument bvalue
to adequately replace them before computing the link function.
Particularly, if inverse = TRUE and deriv = 0,
then s becomes \eta, and therefore the domain set
turns to (0, \infty).
If theta is a character, then arguments inverse and
deriv are disregarded.
Value
For deriv = 0, the logffMlink transformation of
theta, i.e., logitlink(theta) - clogloglink(theta), if
inverse = FALSE.
When inverse = TRUE the vector entered at theta
becomes \eta and, then, this link function
returns a unique vector \theta_{\eta} such that
{\tt{logffMlink}} (\theta_{\eta}) = \eta,
i.e., the inverse image of \eta.
Specifically, the inverse of logffMlink cannot be written in
closed–form, then the latter is equivalent to search for the roots
of the function
{\tt{logff.func}}(\theta) = {\tt{logffMlink}}(\theta) - \eta
as a function of \theta. To do this, the auxiliary
function logff.func is internally generated.
Then, with the method established at alg.roots,
either Newton–Raphson or bisection, this link function
approximates and returns the inverse image
\theta_{\eta} (of given \eta), which
plays the role of the inverse of logffMlink. In particular,
for \eta = 0 and \eta =Inf, it returns 0
and 1 respectively.
For deriv = 1, d eta / d theta
as a function of theta if inverse = FALSE, else
the reciprocal d theta / d eta.
Similarly, when deriv = 2 the second order derivatives
are correspondingly returned.
Both, first and second derivatives, can be written in closed–form.
Warning
logffMlink is a monotonically
increasing, convex, and strictly positive function in (0, 1) such
that the horizontal axis is an asymptote. Therefore, when the inverse
image of \eta is required, each entry of \eta
(via argument theta) must be non-negative so that
{\tt{logff.func}(\theta; \eta) = \tt{logffMlink}}(\theta) - \eta
is shifted down. This fact allows this function to uniquely
intersect the horizontal axis which guarantees to iteratively find
the corresponding root \theta_{\eta}, i.e., the
inverse image of \eta. Else, NaN will be returned.
See example 3. It is the plot of logffMlink in (0, 1)
for \eta = 1.5.
Besides, the vertical straight line theta = 1 is also
an asymptote. Hence, this link function may grow sharply for
values of theta too close to 1.
See Example 4 for further details.
Note
To find the inverse image \theta_{\eta} of
\eta, either
newtonRaphson.basic
or bisection.basic is
called.
This link function can be used for modelling any parameter lying
between 0.0 and 1.0. Consequently, when there are covariates,
some problems may occur. For example, the method entered
at alg.roots to approximate the inverse image may converge
at a slow rate. Similarly if the sample size is small, less than 20 say.
Try another link function, as
logitlink, in such cases.
Author(s)
V. Miranda and T. W. Yee
See Also
logff,
newtonRaphson.basic,
bisection.basic,
Links,
clogloglink,
logitlink.
Examples
## Example 1 ##
set.seed(0906)
Shapes <- sort(runif(10))
logffMlink(theta = Shapes, deriv = 1) ## d eta/d theta, as function of theta
logldata.inv <-
logffMlink(theta = logffMlink(theta = Shapes), inverse = TRUE) - Shapes
summary(logldata.inv) ## Should be zero
## Example 2 Some probability link funtions ##
s.shapes <- ppoints(100)
par(lwd = 2)
plot(s.shapes, logitlink(s.shapes), xlim = c(-0.1, 1.1), type = "l", col = "limegreen",
ylab = "transformation", las = 1, main = "Some probability link functions")
lines(s.shapes, logffMlink(s.shapes), col = "blue")
lines(s.shapes, probitlink(s.shapes), col = "purple")
lines(s.shapes, clogloglink(s.shapes), col = "chocolate")
lines(s.shapes, cauchitlink(s.shapes), col = "tan")
abline(v = c(0.5, 1), lty = "dashed")
abline(v = 0, h = 0, lty = "dashed")
legend(0.1, 4.5, c("logffMlink","logitlink", "probitlink", "clogloglink",
"cauchitlink"),
col = c("blue", "limegreen", "purple", "chocolate", "tan"), lwd = 1)
par(lwd = 1)
## Example 3. Plot of 'logffMlink()' with eta = 1.5. ##
m.eta1.5 <- logffMlink(theta = s.shapes, deriv = 0) - 1.5
plot(m.eta1.5 ~ s.shapes, type = "l", col = "limegreen",
las = 1, lty = 2, lwd = 3, xlim = c(-0.1, 1.0), ylim = c(-2, 3),
xlab = "shape parameter, s, in (0, 1).",
ylab = "logffMlink(s) - 1.5",
main = "logff.func(s; 1.5) = logffMlink(s) - 1.5, in (0, 1)")
abline(h = 0, v = 0)
abline(v = 1.0, lty = 2)
## Example 4. Special values of theta, inverse = FALSE ##
s.shapes <- c(-Inf, -2, -1, 0.0, 0.25, 0.5, 1, 10, 100, Inf, NaN, NA)
rbind(s.shapes, logffMlink(theta = s.shapes))
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.