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

safeUroot {copula} | R Documentation

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

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

[Package copula version 1.0-1 Index]