zetaffMeanlink {VGAMextra} | R Documentation |
Computes the zetaffMeanlink
transformation, including its inverse
and the first two derivatives.
zetaffMeanlink(theta, bvalue = NULL, alg.roots = c("Newton-Raphson", "bisection")[1], inverse = FALSE, deriv = 0, short = TRUE, tag = FALSE)
theta |
Numeric or character. This is theta by default, although it can be eta sometimes, depending on the other parameters. See below for further details. |
bvalue |
Details at |
alg.roots |
Character. The iterative method to find the inverse of this link function. Default is Newton–Raphson. Optionally, the bisection method is also available. |
inverse, deriv, short, tag |
Details at |
This is a link function for the zeta distribution,
zetaff
, which emerges by applying
the logarithm transformation to its mean. Specifically,
assume Y follows a zeta distribution with shape parameter
s (this is theta
in the VGLM/VGAM framework).
Then, the mean of Y is
μ = zeta(s) / zeta(s + 1),
provided s > 1, where zeta is the Riemann's zeta
function computed by zeta
. The notation
adopted here conforms with zetaff
in terms of the density of the zeta distribution.
The zetaffMeanlink
transformation is then given by
η = zetaffMeanlink(s) = log (zeta(s) / zeta(s + 1)).
It is particularly useful when modelling event–rate data where the expected number of events, μ, can be modelled as
μ = λ t.
Specifically, λ is a standardized mean per unit–time, and t is the observed timeframe.
The domain set for s, i.e. theta, is
(1, ∞). Hence, either large values of
s, or those too close to 1 from the right, or out of
range will result in Inf
, -Inf
, NA
or
NaN
. Use argument bvalue
to adequately replace
them before computing the link function.
WARNING: While in zetaff
the parameter
s lies in (0, ∞),
zetaffMeanlink
will be real when s > 1. Consequently,
for any VGLM fitted via zetaff
using this
link function, numerical problems will take place if any
s value lies between 0.0 and 1.0 at any iteration. Use
optional link functions like loge
.
When inverse = TRUE
and deriv = 0
,
s changes into eta, and therefore the domain set
(only in this case) turns into (0, ∞).
See below for further details.
If theta
is a character, arguments inverse
and
deriv
are disregarded.
For deriv = 0
, the zetaffMeanlink
transformation of
theta
, if inverse = FALSE
. When inverse = TRUE
,
theta
becomes η, and then the inverse of zetaffMeanlink
is required. However, it cannot be written in closed–form. Instead,
the inverse image of η, say θ[η],
is returned. That is, a unique vector θ[η]
such that
zetaffMeanlink(θ[η]) = η.
This process is equivalent to find the root,
θ[η], of the function
zetaffMeanlink(θ) - η,
which is internally carried out via the method entered
at alg.roots
. Options available are
“Newton-Raphson
” and “bisection
”.
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 returned accordingly.
The first two derivatives of the Riemman's zeta function
are computed by zeta
.
Besides, the zetaffMeanlink
function as well as its derivatives
are graphically delimited for specific asymptotes.
Consequently, the mathematical limit of this link function is
returned for special values of theta
, e.g.
for theta
= ∞. See example 2 below.
Where the inverse image of η, θ[η],
is required, values entered at theta
(becoming η) must
be non-negative. The reason is that the zetaffMeanlink
transformation is decreasing but strictly positive in (1, ∞)
asymptotically approaching to the horizontal axis. In this way, the
shifted–down zetaffMeanlink
function
zetaff.func(θ | η) = zetaffMeanlink(θ) - η
uniquely intersects the horizontal axis and hence the inverse image
computed by “Newton-Raphson
” or “bisection
”
will be a real
number.
Overall, this link function is useful to model any parameter
lying in (1, ∞), specially if the theoretical mean
can be written as μ = λ t, as stated above.
As a result, some problems may arise if there are covariates.
Try another link function if any issue, such
as loglog
.
V. Miranda and T. W. Yee
zetaff
,
newtonRaphson.basic
,
bisection.basic
,
zeta
,
loge
,
Links
.
## Example 1 ## Shapes <- 1:10 + 0.1 zetaffMeanlink(theta = Shapes, deriv = 1) ## d eta/d theta, as function of theta zetafflk.inv <- zetaffMeanlink(theta = zetaffMeanlink(theta = Shapes), inverse = TRUE) - Shapes summary(zetafflk.inv) ## Should be zero ## Example 2. Special values of theta, inverse = FALSE ## Shapes <- c(-Inf, -1, 0.5, 1, 1.5, 10, 100, Inf, NaN, NA) print(rbind(Shapes, zetaffMeanlink = zetaffMeanlink(theta = Shapes), inv.zfflink = zetaffMeanlink(theta = Shapes, inverse = TRUE)), digits = 3) ## Example 3. Plot of 'zetaffMeanlink()' and its first two derivatives ## ## inverse = FALSE, deriv = 0, 1, 2 ## Shapes <- seq(1, 20, by = 0.01)[-1] y.shapes <- zetaffMeanlink(theta = Shapes, deriv = 0) der.1 <- zetaffMeanlink(theta = Shapes, deriv = 1) der.2 <- zetaffMeanlink(theta = Shapes, deriv = 2) plot(y.shapes ~ Shapes, col = "black", main = "log(mu), mu = E[Y], Y ~ Zeta(s).", ylim = c(-5, 10), xlim = c(-0.1, 5), lty = 1, type = "l", lwd = 3) abline(v = 1.0, col = "orange", lty = 2, lwd = 3) abline(v = 0, h = 0, col = "gray50", lty = "dashed") lines(Shapes, der.1, col = "blue", lty = 5) lines(Shapes, der.2, col = "chocolate", lty = 4) legend(2, 7, legend = c("zetaffMeanlink", "deriv = 1", "deriv = 2"), col = c("black", "blue", "chocolate"), lty = c(1, 5, 4), lwd = c(3, 1, 1))