Description Usage Arguments Details Value Warning Note Author(s) See Also Examples

Computes the `logffMlink`

transformation, including its inverse
and the first two derivatives.

1 2 3 |

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

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

*
logffMlink(θ[η]) = η, *

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.

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

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.

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

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.