VGAMextra (version 0.0-6)

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

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.

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

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.

Author

V. Miranda and T. W. Yee

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.

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)

# \donttest{
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

# \donttest{
 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))