R: Integration of One-Dimensional Functions

distrExIntegrate {distrEx} | R Documentation

## Integration of One-Dimensional Functions

### Description

Numerical integration via `integrate`. In case `integrate` fails a Gauss-Legendre quadrature is performed.

### Usage

    distrExIntegrate(f, lower, upper, subdivisions = 100,
                     rel.tol = .Machine$double.eps^0.25,
                     abs.tol = rel.tol, stop.on.error = TRUE,
                     distr, order, ..., diagnostic = FALSE)
    showDiagnostic(x, what, withNonShows = FALSE, ...)
    getDiagnostic(x, what, reorganized=TRUE)
    ## S3 method for class 'DiagnosticClass'
    print(x, what, withNonShows = FALSE, xname, ...)

### Arguments

`f` | an R function taking a numeric first argument and returning a numeric vector of the same length. Returning a non-finite element will generate an error.
`lower` | lower limit of integration. Can be `-Inf`.
`upper` | upper limit of integration. Can be `Inf`.
`subdivisions` | the maximum number of subintervals.
`rel.tol` | relative accuracy requested.
`abs.tol` | absolute accuracy requested.
`stop.on.error` | logical. If `TRUE` (the default) an error stops the function. If false some errors will give a result with a warning in the `message` component.
`distr` | object of class `UnivariateDistribution`.
`order` | order of Gauss-Legendre quadrature.
`diagnostic` | logical; if `TRUE`, the return value obtains an attribute `"diagnostic"` with diagnostic information on the integration, i.e., a list with entries `method` (`"integrate"` or `"GLIntegrate"`), `call`, `result` (the complete return value of the method), `args` (the args with which the method was called), and `time` (the time to compute the integral).
`...` | In case of integrators: additional arguments to be passed to `f`. Remember to use argument names not matching those of `integrate` and `GLIntegrate`! In case of `showDiagnostic`, `print.DiagnosticClass`: additional arguments to be passed on to print methods called for particular items in the diagnostic list.
`x` | the item for which the diagnostic is to be shown.
`what` | a character vector with all the diagnostic items to be selected/shown. If empty or missing all items are selected/shown.
`withNonShows` | internally we distinguish items which are easily printed (first kind) (numeric, logical, character) and more difficult ones (second kind), e.g., calls, functions, lists. The distinction is made according to the list item name. If `withNonShows==TRUE` one also attempts to show the selected items of the second kind, otherwise they are not shown (but returned).
`xname` | an optional name for the diagnostic object to be shown.
`reorganized` | should the diagnostic information be reorganized (using internal function `.reorganizeDiagnosticList`?

### Details

`distrExIntegrate` calls `integrate`. In case `integrate` returns an error a Gauss-Legendre integration is performed using `GLIntegrate`. If `lower` or (and) `upper` are infinite the `GLIntegrateTruncQuantile`, respectively the `1-GLIntegrateTruncQuantile` quantile of `distr` is used instead.

`distrExIntegrate` is called from many places in the distr and robast families of packages. At every such instance, diagnostic information can be collected (setting a corresponding argument `diagnostic` to `TRUE` in the calling function. This diagnostic information is originally stored in a tree like list structure of S3 class `DiagnosticClass` which is then attached as attribute `diagnostic` to the respective object. It can be inspected and accessed through `showDiagnostic` and `getDiagnostic`. More specifically, for any object with attribute `diagnostic`, `showDiagnostic` shows the diagnostic collected during integration, and `getDiagnostic` returns the diagnostic collected during integration. To this end, `print.DiagnosticClass` is an S3 method for `print` for objects of S3 class `DiagnosticClass`.

### Value

The value of `distrExIntegrate` is a numeric approximation of the integral. If argument `diagnostic==TRUE` in `distrExIntegrate`, the return value has an attribute `diagnostic` of S3 class `DiagnosticClass` containing diagnostic information on the integration.

`showDiagnostic`, `getDiagnostic`, `print.DiagnosticClass` all return (invisibly) a list with the selected items, reorganized by internal function `.reorganizeDiagnosticList`, respectively, in case of argument `reorganized==FALSE`, `getDiagnostic` returns (invisibly) the diagnostic information as is.

### Author(s)

Matthias Kohl Matthias.Kohl@stamats.de

### References

Based on QUADPACK routines `dqags` and `dqagi` by R. Piessens and E. deDoncker-Kapenga, available from Netlib.

R. Piessens, E. deDoncker-Kapenga, C. Uberhuber, D. Kahaner (1983) Quadpack: a Subroutine Package for Automatic Integration. Springer Verlag.

W.H. Press, S.A. Teukolsky, W.T. Vetterling, B.P. Flannery (1992) Numerical Recipies in C. The Art of Scientific Computing. Second Edition. Cambridge University Press.

### See Also

`integrate`, `GLIntegrate`, `distrExOptions`

### Examples

    fkt <- function(x){x*dchisq(x+1, df = 1)}
    integrate(fkt, lower = -1, upper = 3)
    GLIntegrate(fkt, lower = -1, upper = 3)
    try(integrate(fkt, lower = -1, upper = 5))
    distrExIntegrate(fkt, lower = -1, upper = 5)

[Package distrEx version 2.8.0 Index]