Applied vignette · copulas · JDistlib 0.7.0+

Model claim severity and occurrence together

Claim severity is continuous while occurrence is binary. A mixed copula model preserves both margins and adds dependence without pretending the binary outcome has a density.

Copula feature · available from 0.7.0

1 · Separate the questions

Specify margins before dependence

Assume a standardized continuous severity score is approximately normal and an indicator records whether a second claim occurs, with probability 0.35. These marginal assumptions should be checked independently. We then ask whether larger severity and repeat occurrence tend to coincide.

2 · Build a candidate · 0.7.0+

Declare continuous and discrete coordinates

import jdistlib.Binomial;
import jdistlib.ClaytonCopula;
import jdistlib.CopulaMarginal;
import jdistlib.MixedCopulaDistribution;
import jdistlib.Normal;

CopulaMarginal[] margins = {
    CopulaMarginal.continuous(new Normal()),
    CopulaMarginal.discrete(new Binomial(1, 0.35))
};

MixedCopulaDistribution candidate =
    new MixedCopulaDistribution(
        new ClaytonCopula(2, 1.2), margins);

Clayton is a scientific hypothesis: it emphasizes association in the lower tail. It is not a neutral default, so we will compare it with other families.

3 · Evaluate and simulate · 0.7.0+

Use the correct mixed measure

CopulaMeasureResult value = candidate.measure(
    new double[] {0.3, 1.0});
if (!value.isSuccess()) {
    throw new ArithmeticException(value.message());
}
double logMeasure = value.logValue;

double[][] simulated = candidate.random(500, 20260826L);

At {0.3, 1.0}, the result is density in the severity coordinate and mass at occurrence = 1. Simulation is often the clearest way to turn the fitted joint law into downstream risk summaries.

4 · Fit competing families · 0.7.0+

Automatic selection narrows, but does not end, the analysis

CopulaSelectionResult result = CopulaSelector.selectMixed(
    observedRows,
    margins,
    null,
    new CopulaFitOptions(),
    CopulaSelectionCriterion.BIC,
    CopulaFamily.INDEPENDENCE,
    CopulaFamily.GAUSSIAN,
    CopulaFamily.CLAYTON,
    CopulaFamily.FRANK);

CopulaFitResult fitted = result.getSelected();
System.out.println(fitted.getFamily());
System.out.println(fitted.getLogLikelihood());

The mixed transform uses the marginal jump intervals rather than assigning arbitrary continuous ranks to a binary variable. BIC penalizes additional parameters, but it cannot determine whether the supplied margins or candidate family set are scientifically suitable.

5 · Report the model honestly

Include what the data cannot identify

Report candidates

List every family considered, the criterion, sample size, selected parameters, and runners-up.

Inspect sensitivity

Repeat the comparison under credible marginal models and with alternative distributional-transform handling.

Respect discreteness

A binary margin provides limited information about copula shape. Close scores may signal practical non-identifiability.

Validate consequences

Compare simulated joint tail summaries with held-out or domain benchmarks, not only in-sample likelihood.

Next · 0.7.0+

Expand dimensions only when needed

For three or more outcomes, the vine overview and the complete copula guide explain C-vines, D-vines, sequential fitting, and numerical probability estimates.