torchvinecopulib.bicop package

Module contents

class torchvinecopulib.bicop.Clayton

Bases: BiCopArchimedean

static cdf_0(obs: Tensor, par: tuple[float]) → Tensor

static hfunc1_0(obs: Tensor, par: tuple[float]) → Tensor

first h function, Prob(V1<=v1 | V0=v0)

static hinv1_0(obs: Tensor, par: tuple[float]) → Tensor

inverse of the first h function, Q(p=v1 | V0=v0)

static l_pdf_0(obs: Tensor, par: tuple[float]) → Tensor

static par2tau_0(par: tuple[float]) → float

static tau2par_0(tau: float, **kwargs) → tuple

class torchvinecopulib.bicop.DataBiCop(*, fam: str = 'Independent', negloglik: float = 0.0, num_obs: int = 1, par: tuple = (), rot: int = 0)

Bases: ABC

Dataclass for a bivariate copula.

The default BiCopData is an Independent BiCop.

num_obs = 1 by default, to avoid nan for bic. Can modify num_obs during instantiation, for accurate bic calculation

property aic: float

an instance of the DataBiCop dataclass :return: Akaike information criterion (AIC) :rtype: float

Type:

param self

property bic: float

an instance of the DataBiCop dataclass :return: Bayesian information criterion (BIC) :rtype: float

Type:

param self

cdf(obs: Tensor) → Tensor

Parameters:

• self – an instance of the DataBiCop dataclass

• obs (torch.Tensor) – observation of the bivariate copula, of shape (num_obs, 2)

Returns:

cumulative distribution function (CDF) of shape (num_obs, 1), given the observation

Return type:

torch.Tensor

fam: str

bivariate copula family name

hfunc1(obs: Tensor) → Tensor

Parameters:

• self – an instance of the DataBiCop dataclass

• obs (torch.Tensor) – observation of the bivariate copula, of shape (num_obs, 2)

Returns:

first h function, Prob(V_right<=v_right | V_left=v_left), of shape (num_obs, 1), given the observation

Return type:

torch.Tensor

hfunc2(obs: Tensor) → Tensor

Parameters:

• self – an instance of the DataBiCop dataclass

• obs (torch.Tensor) – observation of the bivariate copula, of shape (num_obs, 2)

Returns:

second h function, Prob(V_left<=v_left | V_right=v_right), of shape (num_obs, 1), given the observation

Return type:

torch.Tensor

hinv1(obs: Tensor) → Tensor

Parameters:

• self – an instance of the DataBiCop dataclass

• obs (torch.Tensor) – observation of the bivariate copula, of shape (num_obs, 2)

Returns:

first h inverse function, Q(V_right=v_right | V_left=v_left), of shape (num_obs, 1), given the observation

Return type:

torch.Tensor

hinv2(obs: Tensor) → Tensor

Parameters:

• self – an instance of the DataBiCop dataclass

• obs (torch.Tensor) – observation of the bivariate copula, of shape (num_obs, 2)

Returns:

second h inverse function, Q(V_left=v_left | V_right=v_right), of shape (num_obs, 1), given the observation

Return type:

torch.Tensor

l_pdf(obs: Tensor) → Tensor

Parameters:

• self – an instance of the DataBiCop dataclass

• obs (torch.Tensor) – observation of the bivariate copula, of shape (num_obs, 2)

Returns:

log probability density function (PDF) of shape (num_obs, 1), given the observation

Return type:

torch.Tensor

negloglik: float

negative log likelihood, recorded during fitting using observations

num_obs: int

number of observations, recorded during fitting using observations

property num_par: int

number of parameters

Parameters:

self – an instance of the DataBiCop dataclass

Returns:

length of the parameter tuple of the bivariate copula dataclass object

Return type:

int

par: tuple

parameters of the bivariate copula

rot: int

(COUNTER-CLOCKWISE) rotation degree of the bivariate copula model, one of (0, 90, 180, 270)

sim(num_sim: int, seed: int = 0, device: str = 'cpu', dtype: dtype = torch.float64, is_sobol: bool = False) → Tensor

Simulates random samples from a bivariate copula model.

Parameters:

• num_sim (int) – Number of samples to simulate.

• seed (int, optional) – Random seed for reproducibility. Defaults to 0.

• device (str, optional) – Device to perform the computation (‘cpu’ or ‘cuda’). Defaults to “cpu”.

• dtype (torch.dtype, optional) – Data type of the generated samples. Defaults to torch.float64.

• is_sobol (bool, optional) – If True, uses Sobol sequence for quasi-random number generation. Defaults to False.

Returns:

A tensor of shape (num_sim, 2) containing the simulated samples.

Return type:

torch.Tensor

property tau: float

an instance of the DataBiCop dataclass :return: Kendall’s tau :rtype: float

Type:

param self

class torchvinecopulib.bicop.ENUM_FAM_BICOP(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

an Enum class to store bivariate copula family names and their corresponding class objects

Clayton: BiCopAbstract = <class 'torchvinecopulib.bicop._clayton.Clayton'>

Frank: BiCopAbstract = <class 'torchvinecopulib.bicop._frank.Frank'>

Gaussian: BiCopAbstract = <class 'torchvinecopulib.bicop._gaussian.Gaussian'>

Gumbel: BiCopAbstract = <class 'torchvinecopulib.bicop._gumbel.Gumbel'>

Independent: BiCopAbstract = <class 'torchvinecopulib.bicop._independent.Independent'>

Joe: BiCopAbstract = <class 'torchvinecopulib.bicop._joe.Joe'>

StudentT: BiCopAbstract = <class 'torchvinecopulib.bicop._studentt.StudentT'>

class torchvinecopulib.bicop.Frank

Bases: BiCopArchimedean

static cdf_0(obs: Tensor, par: tuple[float]) → Tensor

static hfunc1_0(obs: Tensor, par: tuple[float]) → Tensor

first h function, Prob(V1<=v1 | V0=v0)

static hinv1_0(obs: Tensor, par: tuple[float]) → Tensor

inverse of the first h function, Q(p=v1 | V0=v0)

classmethod l_pdf_0(obs: Tensor, par: tuple[float]) → Tensor

static par2tau_0(par: tuple) → float

static pdf_0(obs: Tensor, par: tuple[float]) → Tensor

static tau2par(tau: float, **kwargs) → tuple

Convert Kendall’s tau to bicop parameters. rotation ignored, for tau is symmetric.

class torchvinecopulib.bicop.Gaussian

Bases: BiCopElliptical

static cdf_0(obs: Tensor, par: tuple[float]) → Tensor

static hfunc1_0(obs: Tensor, par: tuple[float]) → Tensor

first h function, Prob(V1<=v1 | V0=v0)

static hinv1_0(obs: Tensor, par: tuple[float]) → Tensor

inverse of the first h function, Q(p=v1 | V0=v0)

static l_pdf_0(obs: Tensor, par: tuple[float]) → Tensor

classmethod par2tau_0(par: tuple[float]) → Tensor

classmethod tau2par(tau: float, **kwargs) → Tensor

Convert Kendall’s tau to bicop parameters. rotation ignored, for tau is symmetric.

class torchvinecopulib.bicop.Gumbel

Bases: BiCopArchimedean

static cdf_0(obs: Tensor, par: tuple[float]) → Tensor

static hfunc1_0(obs: Tensor, par: tuple[float]) → Tensor

first h function, Prob(V1<=v1 | V0=v0)

static hinv1_0(obs: Tensor, par: tuple[float]) → Tensor

inverse of the first h function, Q(p=v1 | V0=v0)

classmethod l_pdf_0(obs: Tensor, par: tuple) → Tensor

static par2tau_0(par: tuple) → float

static pdf_0(obs: Tensor, par: tuple[float]) → Tensor

static tau2par(tau: float, **kwargs) → tuple

Convert Kendall’s tau to bicop parameters. rotation ignored, for tau is symmetric.

class torchvinecopulib.bicop.Independent

Bases: BiCopAbstract

static cdf_0(obs: Tensor, **kwargs) → Tensor

static hfunc1_0(obs: Tensor, **kwargs) → Tensor

first h function, Prob(V2<=v2 | V1=v1)

static hinv1_0(obs: Tensor, **kwargs) → Tensor

first h function, Prob(V2<=v2 | V1=v1)

static l_pdf_0(obs: Tensor, **kwargs) → Tensor

static par2tau_0(**kwargs) → float

static pdf_0(obs: Tensor, **kwargs) → Tensor

static sim(num_sim: int, seed: int = 0, device: str = 'cpu', dtype: dtype = torch.float64, **kwargs) → Tensor

static tau2par_0(**kwargs) → tuple

class torchvinecopulib.bicop.Joe

Bases: BiCopArchimedean

static cdf_0(obs: Tensor, par: tuple[float]) → Tensor

static hfunc1_0(obs: Tensor, par: tuple[float]) → Tensor

first h function, Prob(V1<=v1 | V0=v0)

static hinv1_0(obs: Tensor, par: tuple[float]) → Tensor

inverse of the first h function, Q(p=v1 | V0=v0)

classmethod l_pdf_0(obs: Tensor, par: tuple) → Tensor

static par2tau_0(par: tuple) → float

static pdf_0(obs: Tensor, par: tuple[float]) → Tensor

static tau2par(tau: float, **kwargs) → tuple

Convert Kendall’s tau to bicop parameters. rotation ignored, for tau is symmetric.

class torchvinecopulib.bicop.StudentT

Bases: BiCopElliptical

static cdf_0(obs: Tensor, par: tuple[float, float]) → Tensor

static hfunc1_0(obs: Tensor, par: tuple) → Tensor

first h function, Prob(V1<=v1 | V0=v0)

static hinv1_0(obs: Tensor, par: tuple) → Tensor

inverse of the first h function, Q(p=v1 | V0=v0)

static l_pdf_0(obs: Tensor, par: tuple) → Tensor

classmethod par2tau_0(par: tuple) → float

classmethod tau2par(tau: float = None, obs: Tensor = None, mtd_opt: str = 'L-BFGS-B', **kwargs) → tuple

Convert Kendall’s tau to bicop parameters. rotation ignored, for tau is symmetric.

torchvinecopulib.bicop.bcp_from_obs(obs_bcp: Tensor, tau: float | None = None, thresh_trunc: float = 0.05, mtd_fit: str = 'itau', mtd_mle: str = 'L-BFGS-B', mtd_sel: str = 'aic', tpl_fam: tuple[str, ...] = ('Clayton', 'Frank', 'Gaussian', 'Gumbel', 'Independent', 'Joe'), topk: int = 2) → DataBiCop

factory method to make a bivariate copula dataclass object, fitted from observations

Parameters:

• obs_bcp (torch.Tensor) – bivariate copula obs, of shape (num_obs, 2) with values in [0, 1]

• tau (float, optional) – Kendall’s tau of the observations, defaults to None for the function to estimate

• thresh_trunc (float, optional) – threshold of Kendall’s tau independence test, below which we reject independent bicop, defaults to 0.05

• mtd_fit (str, optional) – parameter estimation method, either ‘itau’ (inverse of tau) or ‘mle’ (maximum likelihood estimation); defaults to “itau”

• mtd_mle (str, optional) – optimization method for mle as used by scipy.optimize.minimize, defaults to “COBYLA”

• mtd_sel (str, optional) – model selection criterion, either ‘aic’ or ‘bic’; defaults to “aic”

• tpl_fam (tuple, optional) – tuple of str as candidate family names to fit, could be a subset of (‘Clayton’, ‘Frank’, ‘Gaussian’, ‘Gumbel’, ‘Independent’, ‘Joe’, ‘StudentT’)

• topk (int, optional) – number of best itau fit taken into further mle, used when mtd_fit is ‘mle’; defaults to 2

Raises:

NotImplementedError – when mtd_fit is neither ‘itau’ nor ‘mle’

Returns:

fitted bivariate copula dataclass object

Return type:

DataBiCop