Learn R Programming

VGAMextra (version 0.0-2)

logffMeanlink: Link functions for the mean of 1--parameter discrete distributions: The Logarithmic Distribuion.

Description

Computes the logffMeanlink transformation, including its inverse and the first two derivatives.

Usage


    logffMeanlink(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

Value

For deriv = 0, the logffMeanlink 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{logffMeanlink}} (\theta_{\eta}) = \eta,$$ i.e., the inverse image of \(\eta\). Specifically, the inverse of logffMeanlink cannot be written in closed--form, then the latter is equivalent to search for the roots of the function $$ {\tt{logff.func}}(\theta) = {\tt{logffMeanlink}}(\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 logffMeanlink. 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

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 \(\eta\) is required, each entry of \(\eta\) (via argument theta) must be non-negative so that \({\tt{logff.func}(\theta; \eta) = \tt{logffMeanlink}}(\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 logffMeanlink 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.

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 logffMeanlink 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 logffMeanlink 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 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, \infty)\).

If theta is a character, then arguments inverse and deriv are disregarded.

See Also

logff, newtonRaphson.basic, bisection.basic, Links, clogloglink, logitlink.

Examples

Run this code
# NOT RUN {
## 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)
# }
# NOT RUN {
<!-- % -->
# }
# NOT RUN {
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, 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("logffMeanlink","logitlink", "probitlink", "clogloglink",
"cauchitlink"),
       col = c("blue", "limegreen", "purple", "chocolate", "tan"), lwd = 1)
par(lwd = 1) 
# }
# NOT RUN {
<!-- % -->
# }
# NOT RUN {
## Example 3. Plot of 'logffMeanlink()' with eta = 1.5.  ##
m.eta1.5 <- logffMeanlink(theta = s.shapes, deriv = 0) - 1.5
# }
# NOT RUN {
<!-- % -->
# }
# NOT RUN {
 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)
 
# }
# NOT RUN {
<!-- % -->
# }
# NOT RUN {
## 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))
# }

Run the code above in your browser using DataLab