safeUroot: One-dimensional Root (Zero) Finding - Extra "Safety" for...

In copula: Multivariate Dependence with Copulas

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 x_0, that is, if the function is increasing or decreasing there, Sig can be specified, typically as S := \pm 1, to require S = \mathrm{sign}(f(x_0 + \epsilon)) 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.

See Also

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 documentation built on Sept. 11, 2024, 7:48 p.m.