Transforms probabilities into log-odds: \(\log(p / (1 - p))\).
This is the equivalent of stats::qlogis() and returns identical values for
numeric input, except that it carries derivatives. Exact differentiation
(deriv_method = "exact") propagates a tangent alongside each value through
the arithmetic and Math group generics. logit() is written as
log(prob / (1 - prob)), so those group generic methods carry a tangent
through it; qlogis() hands its argument to compiled code without
dispatching, and errors on a tangent-carrying argument. Use logit()
inside estimating equations and inside transforms passed to delta_method(),
and qlogis() for ordinary numeric work.
Exact differentiation
deriv_method = "exact" is forward-mode automatic differentiation: it
replaces each value with an object carrying both the value and its
derivative. deli supports those objects through S3 methods: the Ops,
Math, and Summary group generics, plus non-group methods such as [,
%*%, t(), c(), and mean(). standard_normal_cdf(),
standard_normal_pdf(), deli_polygamma(), and deli_digamma() recognize a
tangent-carrying argument themselves and apply their own analytic rule.
Support within the group generics is partial; see
vignette("getting-started") for the operations deli differentiates.
plogis(), qlogis(), pnorm(), dnorm(), and psigamma() take none of
these paths. Each hands its argument straight to compiled code through
.Call() or .Internal() without dispatching, so the tangent reaches C code
that requires a plain number. deli catches the resulting failure and raises
its own error, naming the function that stopped the computation and the deli
function to write in its place. The same applies to every other distribution
function in stats, such as qnorm(), which is named in the error even
though deli exports no counterpart for it.
Each deli utility below returns the same values as its base R counterpart for numeric input. What separates them is whether the counterpart survives exact mode:
| deli function | base R counterpart | base R under deriv_method = "exact" |
inverse_logit() | stats::plogis() | errors |
logit() | stats::qlogis() | errors |
standard_normal_cdf() | stats::pnorm() | errors |
standard_normal_pdf() | stats::dnorm() | errors |
deli_polygamma() | base::psigamma() | errors |
deli_digamma() | base::digamma() | works |
identity_transform() | base::identity() | works |
For the first five rows, use the deli function inside estimating equations
and inside transforms passed to delta_method(), and the base R function
everywhere else: simulating data, post-fit display, plain numeric work. For
the last two rows the base R function is usable everywhere, because
digamma() is a Math group member with a tangent rule and identity()
passes its argument through untouched.
The polygamma row is the one place where the arguments do not line up.
deli_polygamma(n, x) takes the derivative order first and
psigamma(x, deriv = n) takes it second, so a positional substitution
between the two computes a different quantity and raises no error.
See also
stats::qlogis(), the base R equivalent for ordinary numeric work,
and inverse_logit(), which inverts this transformation.
Examples
logit(0.5)
#> [1] 0
logit(c(0.1, 0.5, 0.9))
#> [1] -2.197225 0.000000 2.197225
# The same values as the base R counterpart
all.equal(logit(c(0.1, 0.5, 0.9)), qlogis(c(0.1, 0.5, 0.9)))
#> [1] TRUE
# The proportion of cars with a manual transmission
m <- m_estimate(
stacked_equations = function(theta) ee_mean(theta, y = mtcars$am),
init = 0.5
)
# Variance of the log-odds of that proportion. Writing `qlogis(theta[1])`
# here instead would error, because exact differentiation hands the
# transform a tangent-carrying argument.
delta_method(
m,
transform = function(theta) logit(theta[1]),
deriv_method = "exact"
)
#> [,1]
#> [1,] 0.1295546