R: Estimation of Multivariate Models Defined via Copulas

fitMvdc {copula} | R Documentation

## Estimation of Multivariate Models Defined via Copulas

### Description

Fitting copula-based multivariate distributions (`"mvdc"`) to multivariate data, estimating both the marginal and the copula parameters.

If you assume non parametric margins, in other words, take the empirical distributions for all margins, you can use `fitCopula(*, pobs(x))` instead.

### Usage

    loglikMvdc(param, x, mvdc)
    fitMvdc(data, mvdc, start, optim.control = list(), method = "BFGS",
            lower = -Inf, upper = Inf,
            estimate.variance = fit$convergence == 0, hideWarnings = TRUE)

    ## S3 method for class 'fittedMV'
    coef(object, SE = FALSE, orig = TRUE, ...)
    ## S3 method for class 'fittedMV'
    logLik(object, ...)
    ## S3 method for class 'fittedMV'
    vcov(object, orig = TRUE, ...)

### Arguments

`param` | a vector of parameter values. When specifying parameters for `mvdc` objects, the parameters must be ordered with the marginals first and the copula parameters last. When the `mvdc` object has `marginsIdentical = TRUE`, only the parameters of one marginal must be specified.
`x` | a data matrix.
`mvdc` | a `"mvdc"` object.
`data` | a data matrix.
`start` | a vector of starting value for `"param"`. See `"param"` above for ordering of this vector.
`optim.control` | a list of controls to be passed to `optim`.
`method` | the method for `optim`.
`lower, upper` | bounds on each parameter, passed to `optim`, typically “box constraints” for `method = "L-BFGS-B"`.
`estimate.variance` | logical; if true (as by default, if the optimization converges), the asymptotic variance is estimated.
`hideWarnings` | logical indicating if warning messages from likelihood maximization, e.g., from evaluating at invalid parameter values, should be suppressed (via `suppressWarnings`).
`object` | an R object of class `"fitMvdc"`.
`SE` | for the `coef` method, a logical indicating if standard errors should be returned in addition to the estimated parameters (in a `matrix`). This is equivalent, but more efficient than, e.g., `coef(summary(object))`.
`orig` | `logical`, relevant currently only for `mixCopula` fits with free weights. `orig` indicates if the weights should be shown in original scale (`orig=TRUE`) or in the transformed log- aka lambda-space.
`...` | potentially further arguments to methods.

### Value

The return value `loglikMvdc()` is the log likelihood evaluated for the given value of `param`.

The return value of `fitMvdc()` is an object of class `"fitMvdc"` (see there), containing slots (among others!):

`estimate` | the estimate of the parameters.
`var.est` | large-sample (i.e., asymptotic) variance estimate of the parameter estimator (filled with `NA` if `estimate.variance = FALSE`).
`mvdc` | the fitted multivariate distribution, see `mvdc`.

The `summary()` method for `"fitMvdc"` objects returns a S3 “class” `"summary.fitMvdc"`, simply a list with components `method`, `loglik`, and `convergence`, all three from corresponding slots of the `"fitMvdc"` objects, and

`coefficients` | a matrix of estimated coefficients, standard errors, t values and p-values.

### Note

User-defined marginal distributions can be used as long as the `"{dpq}"` functions are defined. See `vignette("AR_Clayton", package="copula")`.

When covariates are available for marginal distributions or for the copula, one can construct the loglikelihood function and feed it to `"optim"` to estimate all the parameters.

Finally, note that some of the fitting functions generate error messages because invalid parameter values are tried during the optimization process (see `optim`). This should be rarer since 2013, notably for likelihood based methods (as the likelihood is now rather set to `-Inf` than giving an error).

Previously, `loglikMvdc()` had an argument `hideWarnings`; nowadays, do use `suppressWarnings(..)` if you are sure you do not want to see them.

### See Also

`mvdc` and `mvdc`; further, `Copula`, `fitCopula`, `gofCopula`.

For fitting univariate marginals, `fitdistr()`.

### Examples

    G3 <- gumbelCopula(3, dim=2)
    gMvd2  <- mvdc(G3, c("exp","exp"),
                   param = list(list(rate=2), list(rate=4)))
    ## with identical margins:
    gMvd.I <- mvdc(G3, "exp",
                   param = list(rate=3), marginsIdentical=TRUE)

    (Xtras <- copula:::doExtras()) # determine whether examples will be extra (long)
    n <- if(Xtras) 10000 else 200 # sample size (realistic vs short for example)

    set.seed(11)
    x <- rMvdc(n, gMvd2)
    ## Default:     hideWarnings = FALSE .. i.e. show warnings here
    fit2 <- fitMvdc(x, gMvd2, start = c(1,1, 2))
    fit2
    confint(fit2)
    summary(fit2) # slightly more
    ## The estimated, asymptotic var-cov matrix [was used for confint()]:
    vcov(fit2)

    ## with even more output for the "identical margin" case:
    fitI <- fitMvdc(x, gMvd.I, start = c(3, 2),
                    optim.control=list(trace= TRUE, REPORT= 2))
    summary(fitI)
    coef(fitI, SE = TRUE)
    stopifnot(is.matrix(coef(fitI, SE = TRUE)),
              is.matrix(print( confint(fitI) )) )

    ## a wrong starting value can already be *the* problem:
    f2 <- try(fitMvdc(x, gMvd.I, start = c(1, 1),
               optim.control=list(trace= TRUE, REPORT= 2)))
    ##--> Error in optim( ... ) : non-finite finite-difference value [2]

    ##==> "Solution" :  Using a more robust (but slower) optim() method:
    fI.2 <- fitMvdc(x, gMvd.I, start = c(1, 1), method = "Nelder",
                    optim.control=list(trace= TRUE))
    fI.2

[Package copula version 1.0-1 Index]