logffMeanlink {VGAMextra} | R Documentation |
Computes the logffMeanlink
transformation, including its inverse
and the first two derivatives.
logffMeanlink(theta, bvalue = NULL, alg.roots = c("Newton-Raphson", "bisection")[1], inverse = FALSE, deriv = 0, short = TRUE, tag = FALSE)
theta |
Numeric or character. This is θ by default although could be η depending on other parameters. See below for details. |
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 |
This link function arises as a natural link function for the mean,
μ, 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 μ = μ(s). It can be easily shown that
logffMeanlink
is the difference of two common link functions:
logit
and
cloglog
.
It is particularly usefull for event–rate data where the expected number of events can be modelled as
μ = μ(s) = λ t.
Here λ is the standardized mean (or event-rate) per unit time, t is the timeframe observed, whereas μ 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 logffMeanlink
is not the canonical link function of
the logarithmic distribution, it is certainly part of the
canonical link, given by the composite
log o (g^(-1)) o log,
where g^(-1) denotes the inverse of
logffMeanlink
.
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, ∞).
If theta
is a character, then arguments inverse
and
deriv
are disregarded.
For deriv = 0
, the logffMeanlink
transformation of
theta
, i.e., logit(theta) - cloglog(theta)
, if
inverse = FALSE
.
When inverse = TRUE
the vector entered at theta
becomes η and, then, this link function
returns a unique vector θ[η] such that
logffMeanlink(θ[η]) = η,
i.e., the inverse image of η.
Specifically, the inverse of logffMeanlink
cannot be written in
closed–form, then the latter is equivalent to search for the roots
of the function
logff.func(θ) = logffMeanlink(θ) - η
as a function of θ. 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
θ[η] (of given η), which
plays the role of the inverse of logffMeanlink
. In particular,
for η = 0 and η =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.
logffMeanlink
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 η is required, each entry of η
(via argument theta
) must be non-negative so that
logff.func(θ; η) = logffMeanlink(θ) - η
is shifted down. This fact allows this function to uniquely
intersect the horizontal axis which guarantees to iteratively find
the corresponding root θ[η], i.e., the
inverse image of η. Else, NaN
will be returned.
See example 3. It is the plot of logffMeanlink
in (0, 1)
for η = 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.
To find the inverse image θ[η] of
η, 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 logit
, in such
cases.
V. Miranda and T. W. Yee
logff
,
newtonRaphson.basic
,
bisection.basic
,
Links
,
cloglog
,
logit
.
## Example 1 ## set.seed(0906) Shapes <- sort(runif(10)) logffMeanlink(theta = Shapes, deriv = 1) ## d eta/d theta, as function of theta logldata.inv <- logffMeanlink(theta = logffMeanlink(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, logit(s.shapes), xlim = c(-0.1, 1.1), type = "l", col = "limegreen", ylab = "transformation", las = 1, main = "Some probability link functions") lines(s.shapes, logffMeanlink(s.shapes), col = "blue") lines(s.shapes, probit(s.shapes), col = "purple") lines(s.shapes, cloglog(s.shapes), col = "chocolate") lines(s.shapes, cauchit(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("logffMeanlink","logit", "probit", "cloglog", "cauchit"), col = c("blue", "limegreen", "purple", "chocolate", "tan"), lwd = 1) par(lwd = 1) ## Example 3. Plot of 'logffMeanlink()' with eta = 1.5. ## m.eta1.5 <- logffMeanlink(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 = "logffMeanlink(s) - 1.5", main = "logff.func(s; 1.5) = logffMeanlink(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, logffMeanlink(theta = s.shapes))