fit_copula_to_data
Fit multiple copula families to multi-column data, rank by AIC/SIC/HQIC, and output the best-fitting copula with its tail-dependence type for joint-tail risk assessment.
Instructions
ModelRisk: Fit parametric copulas to a multi-column data range and rank them by goodness of fit — the DEPENDENCE STRUCTURE fitted from data, not merely constructed. Tries Normal, T, Clayton, Frank and Gumbel families (VoseFitObject), scores each with AIC / SIC / HQIC, and reports the winner plus its tail-dependence character (lower = crash-together, upper = boom-together, both = T, none = Normal/Frank) — the joint-tail risk a single correlation coefficient throws away. Runs on a transient scratch sheet that is always deleted; the data is not modified. Pair with fit_all_data_and_wire to insert the fitted copula into the model.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sheet | Yes | Sheet holding the data. | |
| families | No | Copula families to try. Omit for the default 5-family set. | |
| workbook | Yes | Workbook file name, e.g. 'model.xlsx'. | |
| criterion | No | Ranking criterion: 'SIC' (default), 'AIC', or 'HQIC'. | SIC |
| data_range | Yes | A1 range of the multi-column data, e.g. 'A1:C500'. | |
| uncertainty | No | Fit with parameter uncertainty (second-order). Default False. | |
| data_in_rows | No | True if each variable is a ROW, not a column. Default False. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | Interpretation of the winning family's tail behaviour. | |
| skipped | No | Families that could not be fitted, with a reason each. | |
| criterion | Yes | Criterion the ranking is sorted by (AIC / SIC / HQIC). | |
| candidates | Yes | Successfully-fitted copula families, best first. | |
| data_range | Yes | ||
| best_family | No | Top-ranked copula family, or null if every fit failed. | |
| n_variables | Yes | Number of variables (columns) the copula spans. | |
| sample_size | Yes | Number of joint observations (rows). |