logffMlink | R Documentation |

Computes the `logffMlink`

transformation, including its inverse
and the first two derivatives.

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

`theta` |
Numeric or character. This is |

`bvalue` |
This is a boundary value. See below.
Also refer to |

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

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.

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.

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

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.

V. Miranda and T. W. Yee

`logff`

,
`newtonRaphson.basic`

,
`bisection.basic`

,
`Links`

,
`clogloglink`

,
`logitlink`

.

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

VGAMextra documentation built on Nov. 2, 2023, 5:59 p.m.

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.