# logffMeanlink: Link functions for the mean of 1-parameter discrete... In VGAMextra: Additions and Extensions of the 'VGAM' Package

## Description

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

## Usage

 ```1 2 3``` ``` logffMlink(theta, bvalue = NULL, alg.roots = c("Newton-Raphson", "bisection"), inverse = FALSE, deriv = 0, short = TRUE, tag = FALSE) ```

## Arguments

 `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 `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, μ, 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 `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

μ = μ(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 `logffMlink` 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 `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, ∞).

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 η and, then, this link function returns a unique vector θ[η] such that

i.e., the inverse image of η. Specifically, the inverse of `logffMlink` cannot be written in closed–form, then the latter is equivalent to search for the roots of the function

logff.func(θ) = logffMlink(θ) - η

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 `logffMlink`. 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.

## 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 η is required, each entry of η (via argument `theta`) must be non-negative so that logff.func(θ; η) = logffMlink(θ) - η 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 `logffMlink` 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.

## Note

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 `logitlink`, in such cases.

## Author(s)

V. Miranda and T. W. Yee

`logff`, `newtonRaphson.basic`, `bisection.basic`, `Links`, `clogloglink`, `logitlink`.
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48``` ```## 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)) ```