logffMlink {VGAMextra}

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))