copula: safeUroot – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

safeUroot

One-dimensional Root (Zero) Finding - Extra "Safety" for Convenience

Description

safeUroot() as a “safe” version of uniroot() searches for a root (that is, zero) of the function f with respect to its first argument.

“Safe” means searching for the correct interval = c(lower,upper) if sign(f(x)) does not satisfy the requirements at the interval end points; see the ‘Details’ section.

Usage

safeUroot(f, interval, ...,
       lower = min(interval), upper = max(interval),
       f.lower = f(lower, ...), f.upper = f(upper, ...),
       Sig = NULL, check.conv = FALSE,
       tol = .Machine$double.eps^0.25, maxiter = 1000, trace = 0)

Arguments

`f`	function
`interval`	interval
`...`	additional named or unnamed arguments to be passed to `f`
`lower, upper`	lower and upper endpoint of search interval
`f.lower, f.upper`	function value at `lower` or `upper` endpoint, respectively.
`Sig`	desired sign of `f(upper)`, or `NULL`.
`check.conv`	logical indicating whether a convergence warning of the underlying `uniroot` should be caught as an error.
`tol`	the desired accuracy, that is, convergence tolerance.
`maxiter`	maximal number of iterations
`trace`	number determining tracing

Details

If it is known how f changes sign at the root x0, that is, if the function is increasing or decreasing there, Sig can be specified, typically as S:= +/- 1, to require S = sign(f(x0 + eps)) at the solution. In that case, the search interval [l,u] must be such that S * f(l) <= 0 and S * f(u) >= 0.

Otherwise, by default, when Sig=NULL, the search interval [l,u] must satisfy f(l) * f(u) <= 0.

In both cases, when the requirement is not satisfied, safeUroot() tries to enlarge the interval until the requirement is satisfied.

Value

A list with four components, root, f.root, iter and estim.prec; see uniroot.

Examples

f1 <- function(x) (121 - x^2)/(x^2+1)
f2 <- function(x) exp(-x)*(x - 12)

try(uniroot(f1, c(0,10)))
try(uniroot(f2, c(0,2)))
##--> error: f() .. end points not of opposite sign

## where as safeUroot() simply first enlarges the search interval:
safeUroot(f1, c(0,10),trace=1)
safeUroot(f2, c(0,2), trace=2)

## no way to find a zero of a positive function:
try( safeUroot(exp, c(0,2), trace=TRUE) )

## Convergence checking :
safeUroot(sinc, c(0,5), maxiter=4) #-> "just" a warning
try( # an error, now with  check.conv=TRUE
  safeUroot(sinc, c(0,5), maxiter=4, check.conv=TRUE) )

copula

Multivariate Dependence with Copulas

v1.0-1

GPL (>= 3) | file LICENCE

Authors

Marius Hofert [aut] (<https://orcid.org/0000-0001-8009-4665>), Ivan Kojadinovic [aut] (<https://orcid.org/0000-0002-2903-1543>), Martin Maechler [aut, cre] (<https://orcid.org/0000-0002-8685-9910>), Jun Yan [aut] (<https://orcid.org/0000-0003-4401-7296>), Johanna G. Nešlehová [ctb] (evTestK(), <https://orcid.org/0000-0001-9634-4796>), Rebecca Morger [ctb] (fitCopula.ml(): code for free mixCopula weight parameters)

Initial release

2020-12-07