torchvinecopulib.vinecop package¶

Module contents¶

class torchvinecopulib.vinecop.DataVineCop(*, dct_bcp: dict, dct_tree: dict, tpl_sim: tuple, mtd_bidep: str)[source]¶

Bases: ABC

Dataclass for a vine copula model

property aic: float¶

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

Type:: param self

property bic: float¶

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

Type:: param self

cdf(obs_mvcp: Tensor, num_sim: int = 50000, seed: int = 0) → Tensor[source]¶

cumulative distribution function (CDF) of the multivariate copula given observations, by Monte Carlo.

Parameters:

self – an instance of the DataVineCop dataclass
obs_mvcp (torch.Tensor) – observations of the multivariate copula, of shape (num_obs, num_dim)
num_sim (int, optional) – number of simulations, defaults to 50000
seed (int, optional) – random seed for torch.manual_seed(), defaults to 0

Returns:

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

Return type:

torch.Tensor

dct_bcp: dict¶

DataBiCop}}

Type:: bivariate copulas, stored as {level
Type:: {(vertex_left, vertex_right, frozenset_cond)

dct_tree: dict¶: bivariate dependency measures of edges in trees, stored as {level: {(vertex_left, vertex_right, frozenset_cond): bidep}}

draw_dag(tpl_first_vs: tuple = (), tpl_sim: tuple = (), title: str = 'Vine Copula, Obs and BiCop', font_size_vertex: int = 8, f_path: Path = None, fig_size: tuple = None) → tuple[source]¶

draw the directed acyclic graph (DAG) of the vine copula, with pseudo observations and bicops as nodes. The source nodes in simulation workflow are highlighted in yellow.

Parameters:

tpl_first_vs (tuple, optional) – tuple of vertices (explicitly arranged in conditioned - conditioning set) that are taken as already simulated at the beginning of a simulation workflow, affecting the color of nodes, defaults to tuple()
tpl_sim (tuple, optional) – tuple of vertices in a full simulation workflow, gives flexibility to experienced users, defaults to tuple()
font_size_vertex (int, optional) – font size for vertex labels, defaults to 8
f_path (Path, optional) – file path to save the figure, defaults to None for no saving
fig_size (tuple, optional) – figure size, defaults to None

Returns:

_description_

Return type:

tuple

draw_lv(lv: int = 0, is_bcp: bool = True, num_digit: int = 2, font_size_vertex: int = 8, font_size_edge: int = 7, f_path: Path = None, fig_size: tuple = None) → tuple[source]¶

draw the vine structure at a given level. Each edge corresponds to a fitted bicop. Each node is a bicop of prev lv (is_bcp=True) or pseudo-obs of the given lv (is_bcp=False).

Parameters:

lv (int, optional) – level, defaults to 0
is_bcp (bool, optional) – draw the minimum spanning tree (of prev lv bicops) or pseudo observations, defaults to True
num_digit (int, optional) – number of digits to round for the weights on edges, defaults to 2
font_size_vertex (int, optional) – font size for vertex labels, defaults to 8
font_size_edge (int, optional) – font size for edge labels, defaults to 7
f_path (Path, optional) – file path to save the figure, defaults to None for no saving
fig_size (tuple, optional) – figure size, defaults to None

Returns:

fig, ax, (and file path if the figure is saved)

Return type:

tuple

l_pdf(obs_mvcp: Tensor) → Tensor[source]¶

log probability density function (PDF) of the multivariate copula

Parameters:

self – an instance of the DataVineCop dataclass
obs_mvcp (torch.Tensor) – observation of the multivariate copula, of shape (num_obs, num_dim)

Returns:

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

Return type:

torch.Tensor

property matrix: array¶

upper triangular, in row-major order (each row has a bicop as: vertex_left,…,vertex_right;set_cond)

Returns:: structure matrix
Return type:: np.array
Type:: structure matrix

mtd_bidep: str¶: method to calculate bivariate dependence

property negloglik: float¶

nll, as sum of negative log likelihoods of all bivariate copulas

Returns:: negative log likelihood
Return type:: float

property num_dim: int¶: number of dimensions

property num_obs: int¶: number of observations

property num_par: int¶: number of parameters

rosenblatt_transform(obs_mvcp: Tensor, tpl_sim: tuple = ()) → dict[source]¶

Rosenblatt transformation, from the multivariate copula (with dependence) to the uniform multivariate copula (independent), using constructed vine copula

Parameters:

obs_mvcp (torch.Tensor) – observation of the multivariate copula, of shape (num_obs, num_dim)
tpl_sim (tuple, optional) – tuple of vertices (read from right to left) in a full simulation workflow, gives flexibility to experienced users, defaults to tuple()

Returns:

ideally independent uniform multivariate copula, of shape (num_obs, num_dim)

Return type:

dict

sim(num_sim: int = 1, dct_first_vs: dict | None = None, tpl_sim: tuple = (), seed: int = 0, device: str = 'cpu', dtype: dtype = torch.float64, is_sobol: bool = False) → Tensor[source]¶

full simulation/ quantile-regression/ conditional-simulation using the vine copula. modified from depth-first search (DFS) on binary tree. Sequentially for each beginning vertex in the tpl_sim (from right to left, as from shallower lv to deeper lv in the DAG), walk upward by calling hinv until the top vertex (whose cond set is empty) is reached. (Recursively) call hfunc for the other upper vertex if necessary.

Parameters:

num_sim (int) – Number of samples to simulate, ignored when dct_first_vs is not empty, defaults to 1.
dct_first_vs (dict, optional) – dict of {(vertex,cond_set): torch.Tensor(size=(n,1))} in quantile regression/ conditional simulation, where vertices are taken as given already; defaults to None
tpl_sim (tuple, optional) – tuple of vertices (read from right to left) in a full simulation workflow, gives flexibility to experienced users, defaults to tuple()
seed (int, optional) – random seed for torch.manual_seed(), ignored when is_sobol==True, defaults to 0.
device (str, optional) – device for torch.rand(), defaults to “cpu”
dtype (torch.dtype, optional) – Data type for the simulated samples, defaults to torch.float64
is_sobol (bool, optional) – use Sobol sequence for simulation, defaults to False.

Returns:

simulated observations of the vine copula, of shape (num_sim, num_dim)

Return type:

torch.Tensor

tpl_sim: tuple¶: the source vertices (pseudo-obs) of simulation paths, read from right to left; some vertices can be given as simulated at the beginning of each simulation workflow

vcp_to_json(f_path: Path = './vcp.json') → Path[source]¶

save to a json file

Parameters:

self – an instance of the DataVineCop dataclass
f_path (Path, optional) – file path to save the json file, defaults to ‘./vcp.json’

Returns:

file path where the json file is saved

Return type:

Path

vcp_to_pth(f_path: Path = PosixPath('vcp.pth')) → Path[source]¶

save to a pth file

Parameters:

self – an instance of the DataVineCop dataclass
f_path (Path, optional) – file path to save the pth file, defaults to Path(‘./vcp.pth’)

Returns:

file path where the pth file is saved

Return type:

Path

torchvinecopulib.vinecop.vcp_from_json(f_path: Path = PosixPath('vcp.json')) → DataVineCop[source]¶

load a DataVineCop from a json file

Parameters:: f_path (Path, optional) – path to the json file, defaults to Path(“./vcp.json”)
Returns:: a DataVineCop object
Return type:: DataVineCop

torchvinecopulib.vinecop.vcp_from_obs(obs_mvcp: Tensor, is_Dissmann: bool = True, matrix: ndarray | None = None, tpl_first: tuple[int] = (), mtd_vine: str = 'rvine', mtd_bidep: str = 'chatterjee_xi', 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) → DataVineCop[source]¶

Construct a vine copula model from multivariate observations, with structure prescribed by either Dissmann’s (MST per level) method or a given matrix. May prioritize some vertices to be first (shallower) in the quantile-regression/conditional-simulation workflow.

Parameters:

obs_mvcp (torch.Tensor) – multivariate observations, of shape (num_obs, num_dim)
is_Dissmann (bool, optional) – whether to use Dissmann’s method or follow a given matrix, defaults to True; Dissmann, J., Brechmann, E. C., Czado, C., & Kurowicka, D. (2013). Selecting and estimating regular vine copulae and application to financial returns. Computational Statistics & Data Analysis, 59, 52-69.
matrix (np.ndarray | None, optional) – a matrix of vine copula structure, of shape (num_dim, num_dim), used when is_Dissmann is False, defaults to None
tpl_first (tuple[int], optional) – tuple of vertices to be prioritized (kept shallower) in the cond sim workflow. if empty then no priority is set, defaults to tuple()
mtd_vine (str, optional) – one of ‘cvine’, ‘dvine’, ‘rvine’, defaults to “rvine”
mtd_bidep (str, optional) – method to calculate bivariate dependence, one of “kendall_tau”, “mutual_info”, “ferreira_tail_dep_coeff”, “chatterjee_xi”, “wasserstein_dist_ind”, defaults to “chatterjee_xi”
thresh_trunc (float, optional) – threshold of Kendall’s tau independence test, below which we reject independent bicop, defaults to 0.1
mtd_fit (str, optional) – method to fit bivariate copula, 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) – bivariate copula model selection criterion, either ‘aic’ or ‘bic’; defaults to “aic”
tpl_fam (tuple[str, ...], optional) – tuple of str as candidate family names to fit bicop, could be a subset of (‘Clayton’, ‘Frank’, ‘Gaussian’, ‘Gumbel’, ‘Independent’, ‘Joe’, ‘StudentT’), defaults to ( “Clayton”, “Frank”, “Gaussian”, “Gumbel”, “Independent”, “Joe”)
topk (int, optional) – number of best “itau” fit taken into further “mle”, used when mtd_fit is “mle”; defaults to 2

Raises:

ValueError – when mtd_vine is not one of ‘cvine’, ‘dvine’, ‘rvine’

Returns:

a constructed DataVineCop object

Return type:

DataVineCop

torchvinecopulib.vinecop.vcp_from_pth(f_path: Path = PosixPath('vcp.pth')) → DataVineCop[source]¶

load a DataVineCop from a pth file

Parameters:: f_path (Path, optional) – path to the pth file, defaults to Path(“./vcp.pth”)
Returns:: a DataVineCop object
Return type:: DataVineCop

torchvinecopulib.vinecop.vcp_from_sim(num_dim: int, seed: int) → DataVineCop[source]¶

Simulate a DataVineCop object. It constructs the vine copula by generating correlation matrices, fitting bivariate copulas, and building the vine structure through a series of steps.

Parameters:

num_dim (int) – The number of dimensions for the vine copula.
seed (int) – The random seed for reproducibility.

Returns:

An object representing the simulated vine copula.

Return type:

DataVineCop