Skip to main content

Copula

copula_core::traits

Trait Copula 

Source 
pub trait Copula {
    // Required methods
    fn cdf(&self, u: &[f64]) -> Result<f64>;
    fn pdf(&self, u: &[f64]) -> Result<f64>;
    fn sample<R: Rng + ?Sized>(
        &self,
        n: usize,
        rng: &mut R,
    ) -> Result<DMatrix<f64>>;
    fn dimension(&self) -> usize;

    // Provided methods
    fn conditional_cdf(&self, u: &[f64], given: &[usize]) -> Result<f64> { ... }
    fn tail_dependence(&self) -> Result<(f64, f64)> { ... }
    fn kendall_tau(&self) -> Result<f64> { ... }
    fn spearman_rho(&self) -> Result<f64> { ... }
    fn has_closed_form(&self) -> (bool, bool) { ... }
    fn family_name(&self) -> &'static str { ... }
}
Expand description

Core trait that all copulas must implement.

This trait defines the essential operations that any copula must support: evaluating the cumulative distribution function (CDF), probability density function (PDF), generating random samples, and providing dimension information.

§Mathematical Background

A copula C: [0, 1]ⁿ → [0, 1] is a multivariate distribution function whose univariate margins are uniform on [0, 1]. For any n-dimensional copula:

  1. Grounding: C(u₁, …, uᵢ₋₁, 0, uᵢ₊₁, …, uₙ) = 0
  2. Marginality: C(1, …, 1, uᵢ, 1, …, 1) = uᵢ
  3. 2-increasing: For all rectangles in [0, 1]ⁿ, the C-volume is non-negative

§Examples

use copula_core::{Copula, ClaytonCopula};

let copula = ClaytonCopula::new(2.0)?;

// Evaluate CDF
let cdf = copula.cdf(&[0.5, 0.7])?;

// Evaluate PDF  
let pdf = copula.pdf(&[0.5, 0.7])?;

// Generate samples
let mut rng = rand::rng();
let samples = copula.sample(100, &mut rng)?;

Required Methods§

Source

fn cdf(&self, u: &[f64]) -> Result<f64>

Evaluate the copula cumulative distribution function (CDF) at point u.

For a bivariate copula, this computes C(u₁, u₂) = P(U₁ ≤ u₁, U₂ ≤ u₂) where U₁, U₂ are uniform random variables with the copula dependence structure.

§Arguments
  • u - Point at which to evaluate the CDF. All values must be in [0, 1].
§Returns

The CDF value C(u), which is in [0, 1].

§Errors

Returns CopulaError::InvalidRange if any value in u is outside [0, 1]. Returns CopulaError::DimensionMismatch if the length of u doesn’t match the copula’s dimension.

Source

fn pdf(&self, u: &[f64]) -> Result<f64>

Evaluate the copula probability density function (PDF) at point u.

For a bivariate copula, this computes c(u₁, u₂) = ∂²C(u₁, u₂)/(∂u₁∂u₂).

§Arguments
  • u - Point at which to evaluate the PDF. All values must be in [0, 1].
§Returns

The PDF value c(u), which is non-negative.

§Errors

Returns CopulaError::InvalidRange if any value in u is outside [0, 1]. Returns CopulaError::DimensionMismatch if the length of u doesn’t match the copula’s dimension.

Source

fn sample<R: Rng + ?Sized>(&self, n: usize, rng: &mut R) -> Result<DMatrix<f64>>

Generate random samples from the copula.

§Arguments
  • n - Number of samples to generate
  • rng - Random number generator
§Returns

An n × d matrix where each row is a sample from the copula and d is the dimension.

§Errors

Returns CopulaError::NumericalError if sampling fails due to numerical issues.

Source

fn dimension(&self) -> usize

Get the dimension of the copula.

§Returns

The number of variables (dimension) of the copula.

Provided Methods§

Source

fn conditional_cdf(&self, u: &[f64], given: &[usize]) -> Result<f64>

Compute the conditional copula CDF given some variables.

This computes C(u₁, …, uₙ | uⱼ for j ∈ given), which is needed for vine copula constructions and conditional sampling.

§Arguments
  • u - Point at which to evaluate the conditional CDF
  • given - Indices of variables to condition on
§Returns

The conditional CDF value.

§Errors

Returns CopulaError::NotImplemented if the copula doesn’t support conditional evaluation.

Source

fn tail_dependence(&self) -> Result<(f64, f64)>

Compute the tail dependence coefficients.

For a bivariate copula, the tail dependence coefficients are:

  • Lower tail: λₗ = lim_{t→0⁺} C(t,t)/t
  • Upper tail: λᵤ = lim_{t→1⁻} (1-2t+C(t,t))/(1-t)
§Returns

A tuple (λₗ, λᵤ) of lower and upper tail dependence coefficients, each in [0, 1]. A value of 0 indicates no tail dependence.

§Errors

Returns CopulaError::NotImplemented if tail dependence computation is not available for this copula family.

Source

fn kendall_tau(&self) -> Result<f64>

Compute Kendall’s tau for this copula.

Kendall’s tau is a measure of rank correlation that can be computed analytically for many copula families.

§Returns

Kendall’s tau coefficient in [-1, 1].

§Errors

Returns CopulaError::NotImplemented if analytical computation is not available. In this case, users should estimate it from samples.

Source

fn spearman_rho(&self) -> Result<f64>

Compute Spearman’s rho for this copula.

Spearman’s rho is another measure of rank correlation.

§Returns

Spearman’s rho coefficient in [-1, 1].

§Errors

Returns CopulaError::NotImplemented if analytical computation is not available.

Source

fn has_closed_form(&self) -> (bool, bool)

Check if the copula has analytical forms for CDF and PDF.

Some copulas may only have closed-form expressions for certain operations.

Source

fn family_name(&self) -> &'static str

Get a string identifier for the copula family.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§