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, ...)
    ## S3 method for class 'fittedMV'
    logLik(object, ...)
    ## S3 method for class 'fittedMV'
    vcov(object, ...)

### 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.
`hideWarnings` | logical indicating if warning messages from likelihood maximization, e.g., from evaluating at invalid parameter values, should be suppressed (via `suppressWarnings`).
`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.
`object` | an R object of class `"fitMvdc"`.
`...` | 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

    gumbel.cop <- gumbelCopula(3, dim=2)
    gMvd2 <- mvdc(gumbel.cop, c("exp","exp"),
                  list(list(rate=2), list(rate=4)))
    set.seed(11)
    x <- rMvdc(10000, gMvd2)
    ## with identical margins:
    gMvd.I <- mvdc(gumbel.cop, "exp", param = list(rate=3), marginsIdentical=TRUE)
    if(copula:::doExtras()) { ## these are typically not run with CRAN checking:
     ## Takes about 25 sec. [2012-07]:
     fit2 <- fitMvdc(x, gMvd2, start = c(1,1, 2),
                     hideWarnings=FALSE) ## <- show warnings here
     print(fit2)
     ## The (estimated, asymptotic) var-cov matrix:
     print( vcov(fit2) )

     fitI <- fitMvdc(x, gMvd.I, start = c(3, 2),
                     optim.control=list(trace= TRUE, REPORT= 2))
     print(coef(summary(fitI)))
     print(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))

     ## The (estimated, asymptotic) var-cov matrix:
     print( vcov(fit2) )
     str(sfI <- summary(fitI))
     stopifnot(is.matrix(coef(sfI)))

    }

[Package copula version 0.999-15 Index]