# Selection of a C- or D- vine copula model for conditional sampling This function fits either a C- or a D- vine model to a d-dimensional dataset of uniform variables. The fit of the pair-copula families is performed sequentially through the function `RVineCopSelect` of the package `VineCopula`. The vine structure is selected among a group of C- and a D- vines which satisfy the requirement discussed in **Bevacqua et al. (2017)**. This group is composed by all C- and D- vines from which the conditioning variables would be sampled as first when following the algorithms from **Aas et al. (2009)**. Alternatively, if the vine matrix describing the vine structure is given to the function, the fit of the pair-copulas is directly performed skipping the vine structure selection procedure. ```r CDVineCondFit(data, Nx, treecrit = "AIC", type = "CVine-DVine", selectioncrit = "AIC", familyset = NA, indeptest = FALSE, level = 0.05, se = FALSE, rotations = TRUE, method = "mle", Matrix = FALSE) ``` ## Arguments - `data`: An `N x d` data matrix (with uniform margins). The data of the conditioning variable(s) have to occupy the last column(s) of this matrix. - `Nx`: Number of conditioning variables. - `treecrit`: Character indicating the criteria used to select the vine. All possible vines are fitted trough the function `RVineCopSelect` of the package `VineCopula`. Then the vines are ranked with respect the Akaike information criterion (`treecrit = "AIC"`, default) or Bayesian information criterion (`treecrit = "BIC"`). This need the estimation and model selection for all the pairs of all the possible vines, therefore could require long time in case of large datasets, i.e. large `N x d`. - `type`: Type of vine to be fitted: C-Vine: "CVine" or 1; D-Vine: "DVine" or 2; Both C and D-Vine: "CVine-DVine" or "1-2" (default). - `selectioncrit`: Character indicating the criterion for pair-copula selection. Possible choices are `"AIC"` (default) and `"BIC"`. - `familyset`: "Integer vector of pair-copula families to select from. The vector has to include at least one pair-copula family that allows for positive and one that allows for negative dependence. Not listed copula families might be included to better handle limit cases. If `familyset = NA` (default), selection among all possible families is performed. If a vector of negative numbers is provided, selection among all but `abs(familyset)` is performed. Coding of bivariate copula families: `0` = independence copula `1` = Gaussian copula `2` = Student t copula (t-copula) `3` = Clayton copula `4` = Gumbel copula `5` = Frank copula `6` = Joe copula `7` = BB1 copula `8` = BB6 copula `9` = BB7 copula `10` = BB8 copula `13` = rotated Clayton copula (180 degrees; ``survival Clayton'') `14` = rotated Gumbel copula (180 degrees; ``survival Gumbel'') `16` = rotated Joe copula (180 degrees; ``survival Joe'') `17` = rotated BB1 copula (180 degrees; ``survival BB1'') `18` = rotated BB6 copula (180 degrees; ``survival BB6'') `19` = rotated BB7 copula (180 degrees; ``survival BB7'') `20` = rotated BB8 copula (180 degrees; ``survival BB8'') `23` = rotated Clayton copula (90 degrees) `24` = rotated Gumbel copula (90 degrees) `26` = rotated Joe copula (90 degrees) `27` = rotated BB1 copula (90 degrees) `28` = rotated BB6 copula (90 degrees) `29` = rotated BB7 copula (90 degrees) `30` = rotated BB8 copula (90 degrees) `33` = rotated Clayton copula (270 degrees) `34` = rotated Gumbel copula (270 degrees) `36` = rotated Joe copula (270 degrees) `37` = rotated BB1 copula (270 degrees) `38` = rotated BB6 copula (270 degrees) `39` = rotated BB7 copula (270 degrees) `40` = rotated BB8 copula (270 degrees) `104` = Tawn type 1 copula `114` = rotated Tawn type 1 copula (180 degrees) `124` = rotated Tawn type 1 copula (90 degrees) `134` = rotated Tawn type 1 copula (270 degrees) `204` = Tawn type 2 copula `214` = rotated Tawn type 2 copula (180 degrees) `224` = rotated Tawn type 2 copula (90 degrees) `234` = rotated Tawn type 2 copula (270 degrees) - `indeptest`: Logical; whether a hypothesis test for the independence of `u1` and `u2` is performed before bivariate copula selection (default: `indeptest = FALSE`; see `BiCopIndTest`). The independence copula is chosen for a (conditional) pair if the null hypothesis of independence cannot be rejected. - `level`: numeric; significance level of the independence test (default: `level = 0.05`). - `se`: Logical; whether standard errors are estimated (default: `se = FALSE`). - `rotations`: logical; if `TRUE`, all rotations of the families in `familyset` are included. - `method`: indicates the estimation method: either maximum likelihood estimation (`method = "mle"`; default) or inversion of Kendall's tau (`method = "itau"`). For `method = "itau"` only one parameter families and the Student t copula can be used (`family = 1,2,3,4,5,6,13,14,16,23,24,26,33,34` or `36`). For the t-copula, `par2` is found by a crude profile likelihood optimization over the interval (2, 10]." (VineCopula Documentation, version 2.1.1, pp. 73-75) - `Matrix`: `d x d` matrix that defines the vine structure. If `Matrix` is not given, the routine finds the best vine structure according to `selectioncrit`. If `Matrix` is given, the fit is performed only if the structure respects the necessary conditions for the conditional sampling (if the conditions are not respected, an error message is returned). ## Returns An `RVineMatrix` object describing the selected copula model (for further details about `RVineMatrix` objects see the documentation file of the `VineCopula` package). The selected families are stored in `$family`, and the sequentially estimated parameters in `$par` and `$par2`. The fit of the model is performed via the function `RVineCopSelect` of the package `VineCopula`. "The object `RVineMatrix` includes the following information about the fit: - **`se, se2`**: standard errors for the parameter estimates (if `se = TRUE`; note that these are only approximate since they do not account for the sequential nature of the estimation, - **`nobs`**: number of observations, - **`logLik, pair.logLik`**: log likelihood (overall and pairwise) - **`AIC, pair.AIC`**: Aikaike's Informaton Criterion (overall and pairwise), - **`BIC, pair.BIC`**: Bayesian's Informaton Criterion (overall and pairwise), - **`emptau`**: matrix of empirical values of Kendall's tau, - **`p.value.indeptest`**: matrix of p-values of the independence test. ## Note For a comprehensive summary of the vine copula model, use `summary(object)`; to see all its contents, use `str(object)`". (VineCopula Documentation, version 2.1.1, pp. 103) ## Examples ```r # Example 1 # Read data data(dataset) data <- dataset$data[1:100,1:5] # Define the variables Y and X. X are the conditioning variables, # which have to be positioned in the last columns of the data.frame colnames(data) <- c("Y1","Y2","X3","X4","X5") ## Not run: # Select and fit a C- vine copula model, requiring that the RVM <- CDVineCondFit(data,Nx=3,treecrit="BIC",type="CVine",selectioncrit="AIC") summary(RVM) RVM$Matrix ## End(Not run) # Example 2 # Read data data(dataset) data <- dataset$data[1:80,1:5] # Define the variables Y and X. X are the conditioning variables, # which have to be positioned in the last columns of the data.frame colnames(data) <- c("Y1","Y2","X3","X4","X5") # Define a VineMatrix which can be used for conditional sampling ListVines <- CDVineCondListMatrices(data,Nx=3) Matrix=ListVines$DVine[[1]] Matrix ## Not run: # Fit copula families for the defined vine: RVM <- CDVineCondFit(data,Nx=3,Matrix=Matrix) summary(RVM) RVM$Matrix RVM$family # check identical(RVM$Matrix,Matrix) # Fit copula families for the defined vine, given a group of families to select from: RVM <- CDVineCondFit(data,Nx=3,Matrix=Matrix,familyset=c(1,2,3,14)) summary(RVM) RVM$Matrix RVM$family # Try to fit copula families for a vine which is not among those # that allow for conditional sampling: Matrix Matrix[which(Matrix==4)]=40 Matrix[which(Matrix==2)]=20 Matrix[which(Matrix==40)]=2 Matrix[which(Matrix==20)]=4 Matrix RVM <- CDVineCondFit(data,Nx=3,Matrix=Matrix) RVM ## End(Not run) ``` ## Author(s) Emanuele Bevacqua ## References Bevacqua, E., Maraun, D., Hobaek Haff, I., Widmann, M., and Vrac, M.: Multivariate statistical modelling of compound events via pair-copula constructions: analysis of floods in Ravenna (Italy), Hydrol. Earth Syst. Sci., 21, 2701-2723, https://doi.org/10.5194/hess-21-2701-2017, 2017. [[link]](https://www.researchgate.net/publication/317414374_Multivariate_statistical_modelling_of_compound_events_via_pair-copula_constructions_Analysis_of_floods_in_Ravenna_Italy) [[link]](https://www.hydrol-earth-syst-sci.net/21/2701/2017/hess-21-2701-2017.html) Aas, K., Czado, C., Frigessi, A. and Bakken, H.: Pair-copula constructions of multiple dependence, Insurance: Mathematics and Economics, 44(2), 182-198, , 2009. [[link]](http://www.sciencedirect.com/science/article/pii/S0167668707000194) Ulf Schepsmeier, Jakob Stoeber, Eike Christian Brechmann, Benedikt Graeler, Thomas Nagler and Tobias Erhardt (2017). VineCopula: Statistical Inference of Vine Copulas. R package version 2.1.1. [[link]](https://CRAN.R-project.org/package=VineCopula) ## See Also `CDVineCondSim`, `CDVineCondRank`

CDVineCondFit function