---
title: "Bivariate copula models"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Bivariate copula models}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
library(rvinecopulib)
set.seed(201)
```

Bivariate copulas are the building blocks of vine models. rvinecopulib can
construct a known model, fit or select one from data, evaluate its distribution
functions, and summarize its dependence.

## Implemented families

| Type | Family | Identifier | Parameters |
|---|---|---|---:|
| Independence | Independence | `"indep"` | 0 |
| Elliptical | Gaussian | `"gaussian"` | 1 |
| Elliptical | Student t | `"t"` | 2 |
| Archimedean | Clayton | `"clayton"` | 1 |
| Archimedean | Gumbel | `"gumbel"` | 1 |
| Archimedean | Frank | `"frank"` | 1 |
| Archimedean | Joe | `"joe"` | 1 |
| Archimedean | BB1, BB6, BB7, BB8 | lower-case name | 2 |
| Extreme value | Tawn | `"tawn"` | 3 |
| Nonparametric | Transformation kernel | `"tll"` | effective count |

Unambiguous partial names such as `"gauss"` and collection aliases such as
`"par"` are accepted. For reusable code, full names make intent clearer.

## Construct a known model

`bicop_dist()` specifies a family, rotation, parameters, and variable types.

```{r construct}
cop <- bicop_dist(
  family = "clayton",
  rotation = 90,
  parameters = 2
)
cop
```

Rotations are `0`, `90`, `180`, or `270` degrees. They allow asymmetric
Archimedean copulas to represent different corners and negative dependence.
Elliptical, Frank, independence, and nonparametric copulas already cover both
signs without rotations.

## Evaluate and simulate

The density, CDF, and random generator follow R's `d*`, `p*`, and `r*`
conventions.

```{r evaluate}
points <- rbind(c(0.2, 0.7), c(0.8, 0.3))
dbicop(points, cop)
pbicop(points, cop)
rbicop(4, cop)
```

The same functions also accept family, rotation, and parameters directly:

```{r direct}
dbicop(points, "gaussian", 0, 0.6)
```

## Conditional distributions and h-functions

H-functions are the conditional distributions used recursively in vine
copulas. If `cond_var = 1`, the first input variable is conditioned on and the
function returns the conditional CDF of the second. With `inverse = TRUE`, it
returns the corresponding conditional quantile.

```{r h-functions}
h <- hbicop(points, cond_var = 1, family = cop)
h
hbicop(cbind(points[, 1], h), cond_var = 1, family = cop, inverse = TRUE)
```

This round trip recovers the second column up to numerical precision. The same
conditional-distribution operations drive vine recursion and simulation; see
[Conditional simulation and Rosenblatt
transforms](conditional-simulation.html) for the multivariate workflow.

## Dependence measures

`par_to_ktau()` converts family parameters to Kendall's tau, and
`ktau_to_par()` provides the inverse for families where tau determines all
parameters. Model objects expose Kendall's tau through `get_ktau()`.

```{r dependence}
par_to_ktau("clayton", 90, 2)
get_ktau(cop)
blomqvist_beta(cop)
tail_dep(cop)
```

`tail_dep()` reports the four corner tail-dependence coefficients. This is
especially useful for rotated and asymmetric families, where a single
lower/upper pair is not enough to describe the model.

## Fit and select from data

`bicop()` expects two approximately uniform columns. It fits every requested
compatible family and selects the best according to `selcrit`.

```{r selection}
u <- rbicop(300, "gumbel", 180, 2)
fit <- bicop(
  u,
  family_set = c("gaussian", "clayton", "gumbel", "frank"),
  selcrit = "bic"
)
fit
summary(fit)
```

Useful family collections include:

- `"all"`, `"parametric"`, and `"nonparametric"`;
- `"oneparametric"`, `"twoparametric"`, and `"threeparametric"`;
- `"elliptical"`, `"archimedean"`, `"ev"`, and `"bbs"`;
- `"itau"`, the families compatible with Kendall's tau inversion.

Partial matching makes shorter forms such as `"onepar"` and `"par"`
available. Explicit character vectors are preferable when the candidate set is
part of a scientific specification.

Maximum likelihood is the default for parametric families. Set
`par_method = "itau"` for Kendall's tau inversion. The transformation-kernel
model uses `nonpar_method` and `mult` to control the local-likelihood order and
smoothing.

## Observation weights and missing values

Pass one nonnegative weight per row with `weights`. The backend standardizes
weights internally. Missing or zero-weight observations do not contribute to a
pair fit.

```{r weights}
weights <- seq_len(nrow(u))
weighted_fit <- bicop(
  u,
  family_set = c("gaussian", "gumbel"),
  weights = weights
)
weighted_fit
```

## Discrete variables

A discrete copula observation needs both `F(x)` and `F(x-)`. For two discrete
variables, pass four columns: the two CDF values followed by their two left
limits. Redundant left-limit columns for continuous variables may be omitted.

```{r discrete}
counts <- cbind(rpois(80, 2), rpois(80, 3))
u_discrete <- cbind(
  ppois(counts[, 1], 2),
  ppois(counts[, 2], 3),
  ppois(counts[, 1] - 1, 2),
  ppois(counts[, 2] - 1, 3)
)
fit_discrete <- bicop(
  u_discrete,
  var_types = c("d", "d"),
  family_set = "onepar"
)
fit_discrete
```

The [discrete-data guide](discrete-data.html) derives the likelihood
contribution and covers compact layouts, mixed models, and atoms in detail.

## Observation-specific parameters

Evaluation and simulation can use one parameter set per observation without
constructing many model objects. A one-parameter family accepts a vector;
multi-parameter families use a matrix with one row per observation.

```{r vectorized}
rho <- seq(-0.7, 0.7, length.out = nrow(points))
dbicop(points, "gaussian", 0, parameters = rho)
rbicop(length(rho), "gaussian", 0, parameters = rho)
```

This interface is intended for conditional or covariate-dependent copula
models. Parameters are not recycled, and vectorized evaluation is limited to
parametric families.

## Related documentation

- [Vine copula models and structures](vine-copula-models.html) shows how
  bivariate copulas are assembled into a high-dimensional model.
- [Scores, Hessians, and varying parameters](likelihood-inference.html)
  documents likelihood derivatives and parameter ordering.
- The [`bicop()` reference](../reference/bicop.html) lists all fitting
  controls; [`bicop_dist()` and its distribution
  functions](../reference/bicop_dist.html) document construction and
  evaluation.