torchvinecopulib

https://ty-cheng.github.io/torchvinecopulib
Admin
A PyTorch library for fitting and sampling vine copulas with GPU acceleration and vectorized...
Tokens:44,364
Snippets:204
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Visualize Vine Copula Structure

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Constructs a directed graph of the vine copula and renders it using matplotlib. Requires matplotlib and networkx to be installed.

```python
try:
            import matplotlib.pyplot as plt
            import networkx as nx
            import numpy as np
        except ImportError as e:
            raise ImportError(
                "Please install matplotlib and networkx to draw the vine copula."
            ) from e

        G = nx.DiGraph()
        labels: dict = {}
        pos_obs: dict = {}
        pos_bcp: dict = {}

        def add_level(lv: int):
            edges = []
            bicops = []
            downstream = []
            # * lv-0 marginals
            if lv == 0:
                xs = np.linspace(-self.num_dim / 2, self.num_dim / 2, self.num_dim)
                for v, x in enumerate(xs):
                    node = (v, frozenset())
                    labels[node] = str(v)
                    pos_obs[node] = (float(x), 1.0)
            # * traverse around the bcp; sorted!
            for v_l, v_r, *cond in sorted(self.tree_bidep[lv]):
                cond_set = frozenset(cond)
                bcp = (v_l, v_r, cond_set)
                bicops.append(bcp)
                up_l = (v_l, cond_set)
                up_r = (v_r, cond_set)
                down_l = (v_l, cond_set | {v_r})
                down_r = (v_r, cond_set | {v_l})
                downstream.extend([down_l, down_r])
                # * edges: upstream → bicop → downstream
                edges += [
                    (up_l, bcp),
                    (up_r, bcp),
                    (bcp, down_l),
                    (bcp, down_r),
                ]
                # * labels
                labels[down_l] = f"{down_l[0]}|{','.join(map(str, sorted(down_l[1])))}"
                labels[down_r] = f"{down_r[0]}|{','.join(map(str, sorted(down_r[1])))}"
                br = "\n" if lv > 0 else ""
                labels[bcp] = f"{v_l},{v_r};{br}{','.join(map(str, sorted(cond_set)))}"
            # * layout downstream at y = –lv
            if downstream:
                xs = np.linspace(-len(downstream) / 2, len(downstream) / 2, len(downstream))
                for i, node in enumerate(downstream):
                    pos_obs[node] = (float(xs[i]), float(-lv))
            # * layout bicops at y = –lv + 0.5
            if bicops:
                xs = np.linspace(-len(bicops) / 2, len(bicops) / 2, len(bicops))
                for i, node in enumerate(bicops):
                    pos_bcp[node] = (float(xs[i]), float(-lv + 0.5))
            return edges

        # * accumulate over all levels
        all_edges = []
        for lv in range(len(self.tree_bidep)):
            all_edges.extend(add_level(lv))
        G.add_edges_from(all_edges)
        # * layout dictionary
        pos = {**pos_obs, **pos_bcp}
        # * pseudo-obs to highlight
        _, node_source, _ = self.ref_count_hfunc(
            num_dim=self.num_dim,
            struct_obs=self.struct_obs,
            sample_order=sample_order if sample_order is not None else self.sample_order,
        )
        node_source = [(v_s[0], frozenset(v_s[1:])) for v_s in node_source]
        # * draw
        fig, ax = plt.subplots(nrows=1, ncols=1, figsize=fig_size)
        ax.set_title(label=title, fontsize=font_size_vertex + 1)
        # * pseudo-obs (white)
        node_obs = [_ for _ in G.nodes if len(_) == 2 and _ not in node_source]
        nx.draw_networkx_nodes(
            G=G,
            pos=pos,
            nodelist=node_obs,
            ax=ax,
            node_shape="o",
            node_color="white",
            edgecolors="gray",
            linewidths=0.5,
            alpha=0.8,
        )
        # * pseudo-obs (yellow)
        nx.draw_networkx_nodes(
            G=G,
            pos=pos,
            nodelist=node_source,
            ax=ax,
            node_shape="o",
            node_color="yellow",
            edgecolors="gray",
            linewidths=0.5,
            alpha=0.9,
        )
        # * bcp nodes
        node_bcp = [_ for _ in G.nodes if len(_) == 3]
        nx.draw_networkx_nodes(
            G=G,
            pos=pos,
            nodelist=node_bcp,
            ax=ax,
            node_shape="s",
            node_color="white",
            edgecolors="gray",
            linewidths=0.5,
            alpha=0.8,
        )
        nx.draw_networkx_labels(
            G=G,
            pos=pos,
            labels=labels,
            ax=ax,
            font_size=font_size_vertex,
            font_color="black",
        )
        nx.draw_networkx_edges(
            G=G,
            pos=pos,
            ax=ax,
            edge_color="gray",
            style="--",
            width=0.5,
            alpha=0.8,
        )
```

--------------------------------

### GET /plot

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/bicop.html

Generates a visualization of the bivariate copula density.

```APIDOC
## GET /plot

### Description
Plots the bivariate copula density as either a contour or surface plot.

### Method
GET

### Parameters
#### Query Parameters
- **plot_type** (str) - Optional - Type of plot, either "contour" or "surface". Defaults to "surface".
- **margin_type** (str) - Optional - Type of margin, either "unif" or "norm". Defaults to "unif".
- **xylim** (tuple[float, float]) - Optional - Limits for x and y axes.
- **grid_size** (int) - Optional - Size of the grid for the plot.

### Response
#### Success Response (200)
- **fig** (plt.Figure) - The generated matplotlib figure object.
- **ax** (plt.Axes) - The generated matplotlib axes object.
```

--------------------------------

### Draw Vine Copula Level Graph

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Constructs a NetworkX graph for a specific vine level, visualizing bivariate-copula edges with weights. Requires matplotlib and networkx installed.

```python
try:
    import matplotlib.pyplot as plt
    import networkx as nx
except ImportError as e:
    raise ImportError(
        "Please install matplotlib and networkx to draw the vine copula."
    ) from e
tree = self.tree_bidep[lv]
edge_weight = []
if lv == 0:
    # * level‐0: plain variable indices
    for (u, v, *_), w in tree.items():
        edge_weight.append((u, v, round(w.item(), num_digit)))
elif is_bcp:
    # ! nodes are the parent‐bicop "l,r;s"
    for (u, v, *s), w in tree.items():
        # * parent bicop cond_ed str
        label_u = self.struct_obs[lv][(u, *s)]
        label_v = self.struct_obs[lv][(v, *s)]
        # * append the cond_ing set
        sep = "" if lv == 1 else "\n"
        label_u = f"""{label_u};{sep}{
            ",".join(str(x) for x in sorted(self.struct_bcp[label_u]["cond_ing"]))
        }"""
        label_v = f"""{label_v};{sep}{
            ",".join(str(x) for x in sorted(self.struct_bcp[label_v]["cond_ing"]))
        }"""
        edge_weight.append((label_u, label_v, round(w.item(), num_digit)))
else:
    # ! nodes are pseudo‐obs "v|s"
    for (u, v, *s), w in tree.items():
        s_str = ",".join(str(x) for x in sorted(s))
        label_u = f"{u}|{s_str}"
        label_v = f"{v}|{s_str}"
        edge_weight.append((label_u, label_v, round(w.item(), num_digit)))

# * weighted undirected graph
G = nx.Graph()
G.add_weighted_edges_from(edge_weight)
fig, ax = plt.subplots(figsize=fig_size)
if title is None:
    title = f"Vine level {lv}"
ax.set_title(title, fontsize=font_size_vertex + 1)
pos = nx.planar_layout(G)
nx.draw_networkx_nodes(
    G,
    pos,
    ax=ax,
    node_color="white",
    node_shape="s" if (is_bcp and lv > 0) else "o",
    linewidths=0.5,
    edgecolors="gray",
    alpha=0.8,
)
nx.draw_networkx_labels(G, pos, ax=ax, font_size=font_size_vertex, font_color="black")
# * scale line‐width by weight
widths = [math.log1p(0.5 + 100 * abs(data["weight"])) for _, _, data in G.edges(data=True)]
nx.draw_networkx_edges(G, pos, ax=ax, width=widths, style="--", alpha=0.9)
nx.draw_networkx_edge_labels(
    G,
    pos,
    ax=ax,
    edge_labels=nx.get_edge_attributes(G, "weight"),
    font_size=font_size_edge,
)
ax.set_axis_off()
fig.tight_layout()
plt.draw_if_interactive()

if f_path:
    fig.savefig(f_path, bbox_inches="tight")
    return fig, ax, G, f_path
return fig, ax, G
```

--------------------------------

### Initialize and Fit VineCop Model

Source: https://ty-cheng.github.io/torchvinecopulib/torchvinecopulib.vinecop.html

Demonstrates the basic workflow of initializing a VineCop instance, fitting it to data, and performing sampling and log-likelihood evaluation.

```python
>>> from torchvinecopulib.vinecop import VineCop
>>> vc = VineCop(num_dim=4, is_cop_scale=False, num_step_grid=128)
>>> vc.fit(obs=data_tensor, mtd_vine="rvine", mtd_bidep="chatterjee_xi")
>>> samples = vc.sample(num_sample=500)
>>> log_liks = vc.log_pdf(obs=data_tensor)
```

--------------------------------

### Fit VineCop Model to Multivariate Data

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Initializes the model, processes marginal distributions, and learns the vine structure using either Dissmann's algorithm or a provided matrix.

```python
    @torch.no_grad()
    def fit(
        self,
        obs: torch.Tensor,
        is_dissmann: bool = True,
        matrix: torch.Tensor = None,
        first_tree_vertex: tuple = tuple(),
        mtd_vine: str = "rvine",
        mtd_bidep: str = "chatterjee_xi",
        thresh_trunc: None | float = 0.01,
        mtd_kde: str = "tll",
        mtd_tll: str = "constant",
        num_iter_max: int = 17,
        is_tau_est: bool = False,
        num_step_grid_kde1d: int = None,
        **kde_kwargs,
    ) -> None:
        """Fit the VineCop object to multivariate data. Learns both the vine structure (via
        Dissmann’s greedy MST or a provided matrix) and fits all bivariate copulas and 1D marginals
        (if needed).

        Args:
            obs (torch.Tensor): observations of shape (num_obs, num_dim). If ``is_cop_scale=False``, raw data; otherwise assumed already uniform.
            is_dissmann (bool, optional): if True, use Dissmann's algorithm to learn the vine structure. Otherwise, use the provided matrix. Defaults to True.
            matrix (torch.Tensor, optional): matrix representation of the vine structure. Defaults to None.
            first_tree_vertex (tuple, optional): vertices of the first tree (set of conditioning variables). Defaults to ().
            mtd_vine (str, optional): method for vine structure. One of "cvine", "dvine", "rvine". Defaults to "rvine".
            mtd_bidep (str, optional): method for bivariate dependence. One of "chatterjee_xi", "ferreira_tail_dep_coeff", "kendall_tau", "mutual_info". Defaults to "chatterjee_xi".
            thresh_trunc (None | float, optional): threshold for truncating bivariate copulas using p-val from Kendall's tau stats test. Defaults to 0.01.
            mtd_kde (str, optional): method for bicop KDE. One of "fastKDE" or "tll". Defaults to "fastKDE".
            mtd_tll (str, optional): fit method for the transformation local-likelihood (TLL) nonparametric family, one of ("constant", "linear", or "quadratic"). Defaults to "constant".
            num_iter_max (int, optional): num of Sinkhorn/IPF iters for grid normalization, used only when `mtd_kde` is "fastKDE". Defaults to 17.
            is_tau_est (bool, optional): If True, compute and store Kendall’s τ inside BiCop. Defaults to False.
            num_step_grid_kde1d (int, optional): Grid resolution for each marginal KDE. Defaults to None.
            **kde_kwargs: additional keyword arguments for ``kdeCDFPPF1D``.

        Raises:
            ValueError: if `mtd_vine` is not one of "cvine", "dvine", or "rvine".
        """
        self.reset()
        # ! device agnostic
        device, dtype = self.device, self.dtype
        if self.is_cop_scale:
            obs_mvcp = obs.to(device=device, dtype=dtype)
        else:
            for v in range(self.num_dim):
                self.marginals[v] = kdeCDFPPF1D(
                    x=obs[:, v],
                    num_step_grid=num_step_grid_kde1d,
                    **kde_kwargs,
                ).to(device=device, dtype=dtype)
            obs_mvcp = torch.hstack(
                [self.marginals[v].cdf(obs[:, [v]]) for v in range(self.num_dim)]
            ).to(device=device, dtype=dtype)

        self.num_obs.copy_(obs_mvcp.shape[0])
        self.mtd_bidep = mtd_bidep
        is_kendall_tau = mtd_bidep == "kendall_tau"
```

--------------------------------

### GET /draw_lv

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Visualizes a specific level of the vine copula structure.

```APIDOC
## GET /draw_lv

### Description
Visualizes the vine copula structure at a specific level (lv).

### Method
GET

### Endpoint
/draw_lv

### Parameters
#### Query Parameters
- **lv** (int) - Optional - The level of the vine to draw. Defaults to 0.
- **is_bcp** (bool) - Optional - Whether to include bivariate copula information. Defaults to True.
- **title** (str) - Optional - Title for the plot.
- **num_digit** (int) - Optional - Number of digits for labels. Defaults to 2.
- **font_size_vertex** (int) - Optional - Font size for vertices. Defaults to 8.
- **font_size_edge** (int) - Optional - Font size for edges. Defaults to 7.
- **f_path** (Path) - Optional - File path to save the plot.
- **fig_size** (tuple) - Optional - Dimensions of the figure.
```

--------------------------------

### String Representation of KDE Object

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/util.html

Returns a formatted string containing the configuration and parameters of the KDE instance.

```python
header = self.__class__.__name__
params = {
    "num_obs": int(self.num_obs),
    "negloglik": float(self.negloglik.round(decimals=4)),
    "x_min": float(round(self.x_min, 4)),
    "x_max": float(round(self.x_max, 4)),
    "num_step_grid": int(self.num_step_grid),
    "dtype": self.dtype,
    "device": self.device,
}
params_str = pformat(params, sort_dicts=False, underscore_numbers=True)
return f"{header}\n{params_str[1:-1]}\n\n"
```

--------------------------------

### GET /draw_lv

Source: https://ty-cheng.github.io/torchvinecopulib/torchvinecopulib.html

Draws a weighted undirected graph representing a specific level of the vine copula.

```APIDOC
## GET /draw_lv

### Description
Constructs and returns a NetworkX graph of bivariate-copula edges at a specified level of the vine copula.

### Parameters
#### Query Parameters
- **lv** (int) - Optional - Level to draw. Defaults to 0.
- **is_bcp** (bool) - Optional - If True, nodes are parent-bicop; otherwise, nodes are pseudo-obs. Defaults to True.
- **title** (str) - Optional - Title of the plot.
- **num_digit** (int) - Optional - Number of decimal digits for edge weights. 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 - Path to save the figure.
- **fig_size** (tuple) - Optional - Figure size.

### Response
#### Success Response (200)
- **tuple** (tuple) - Figure, axis, graph object, and file path.
```

--------------------------------

### Get Vine Matrix Representation

Source: https://ty-cheng.github.io/torchvinecopulib/torchvinecopulib.vinecop.html

Retrieves the matrix representation of the vine structure. Diagonal elements indicate the sampling order.

```python
_property _matrix _: Tensor_
```

--------------------------------

### Initialize Grid Values

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/bicop.html

Calculates the CDF and h-function grids from the PDF grid using cumulative sums.

```python
self._cdf_grid = ((self._pdf_grid * self.step_grid**2).cumsum(dim=0).cumsum(dim=1)).clamp_(
            0.0, 1.0
        )
        # ! h functions
        self._hfunc_l_grid = (self._pdf_grid * self.step_grid).cumsum(dim=1).clamp_(0.0, 1.0)
        self._hfunc_r_grid = (self._pdf_grid * self.step_grid).cumsum(dim=0).clamp_(0.0, 1.0)
```

--------------------------------

### VineCop Initialization (Internal)

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Internal initialization of the VineCop class, setting up dimensions, scaling, and grid parameters. It also initializes marginals and pairwise bicopulas, and defines the structure for conditional bivariate copulas.

```python
class VineCop(torch.nn.Module):
    def __init__(
        self,
        num_dim: int,
        is_cop_scale: bool = False,
        num_step_grid: int = 128,
    ) -> None:
        """Initialize a VineCop object.

        Args:
            num_dim (int): number of dimensions.
            is_cop_scale (bool, optional): if True, the marginals are assumed in copula scale [0,1]. Otherwise, the marginals are fitted via KDE. Defaults to False.
            num_step_grid (int, optional): Grid resolution (power of 2) passed to each BiCop. Defaults to 128.

        Attributes:
            num_dim (int):
            is_cop_scale (bool):
            num_step_grid (int):
            marginals (torch.nn.ModuleList): list of marginals for each dimension.
            bicops (torch.nn.ModuleDict): dictionary of BiCop
            struct_bcp (dict): BiCop structures on condition-ed/ing sets, independence, parents.
            struct_obs (list): Pseudo-obs structure per vine level.
            tree_bidep (list): Learned edge weights per vine level.
            sample_order (tuple): Sampling order for inverse Rosenblatt transform.
            num_obs (torch.Tensor): number of observations.
        """
        super().__init__()
        self.num_dim = num_dim
        self.is_cop_scale = is_cop_scale
        self.marginals = torch.nn.ModuleList([None] * num_dim)
        self.bicops = torch.nn.ModuleDict()
        self.struct_bcp = {}
        self.struct_obs = [{} for _ in range(num_dim)]
        for i in range(num_dim):
            self.struct_obs[0][(i,)] = ""
        for i, j in combinations(range(num_dim), 2):
            # * num_bicop = num_dim * (num_dim - 1) // 2
            # NOTE i < j by itertools.combinations;
            # ! ModuleDict key must be str
            cond_ed = f"{i},{j}"
            self.bicops[cond_ed] = BiCop(num_step_grid=num_step_grid)
            self.struct_bcp[cond_ed] = dict(
                # * cond_ed, cond_ing (now empty) of a bicop
                cond_ed=(i, j),
                cond_ing=tuple(),
                is_indep=True,
                # ! left parent cond_ed str
                left=None,
                # ! right parent cond_ed str
                right=None,
            )
        self.mtd_bidep = None
        self.tree_bidep = [{} for _ in range(num_dim - 1)]
        self.num_step_grid = num_step_grid
        self.sample_order = tuple(_ for _ in range(num_dim))
        self.register_buffer("num_obs", torch.zeros((), dtype=torch.int))
```

--------------------------------

### Get Optimized Sampling Order

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Schedules an optimized sampling order to minimize h-function calls. This method is essential for efficient vine copula sampling.

```python
@torch.no_grad()
    def _sample_order(self) -> tuple[int, ...]:
        """Schedule an optimized sampling order to minimize h‐function calls.
        
```

--------------------------------

### Initialize and Use BiCop

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/bicop.html

Basic workflow for initializing a BiCop model, fitting it to observations, and performing inference.

```python
>>> from torchvinecopulib.bicop import BiCop
>>> cop = BiCop(num_step_grid=256)
>>> cop.fit(obs)  # obs: Tensor of shape (n,2) in [0,1]²
>>> u = torch.rand(10, 2)
>>> cdf_vals = cop.cdf(u)
>>> samples = cop.sample(1000, is_sobol=True)
```

--------------------------------

### Get Vine Copula Matrix Representation

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Generates the matrix representation of the vine copula. The diagonal elements indicate the sampling order. This is useful for visualizing the structure of the vine.

```python
with torch.no_grad():
            mat: list[list[int]] = []
            seen: set[int] = set()
            # * iterate levels reversely; the diag‐variable is sample_order[idx]
            for idx, lv in enumerate(range(self.num_dim - 2, -1, -1)):
                v_diag = int(self.sample_order[idx])
                row: list[int] = [-1] * idx + [v_diag]
                # * look up tree-edges from level lv upwards
                for up in range(lv, -1, -1):
                    for v_l, v_r, *_ in self.tree_bidep[up]:
                        if v_diag in (v_l, v_r) and (v_l not in seen) and (v_r not in seen):
                            # * append the "other" variable
                            row.append(v_l if (v_diag == v_r) else v_r)
                seen.add(v_diag)
                mat.append(row)
            #
            mat.append([-1] * (self.num_dim - 1) + [int(self.sample_order[-1])])
            return torch.tensor(mat, dtype=torch.int, device=self.device)
```

--------------------------------

### Initialize and Fit BiCop Model

Source: https://ty-cheng.github.io/torchvinecopulib/torchvinecopulib.bicop.html

Demonstrates initializing a BiCop model with a specified grid size and fitting it to observational data. Ensure observations are a torch.Tensor of shape (n, 2) in the range [0, 1]².

```python
from torchvinecopulib.bicop import BiCop
cop = BiCop(num_step_grid=256)
cop.fit(obs)  # obs: Tensor of shape (n,2) in [0,1]²
```

--------------------------------

### torchvinecopulib.util Module

Source: https://ty-cheng.github.io/torchvinecopulib/torchvinecopulib.util.html

Overview of the utility module providing tools for dependence measures, KDE, and root-finding.

```APIDOC
## torchvinecopulib.util

### Description
Utility routines for copula-based dependence measures, 1D KDE CDF/PPF, and root-finding via the Interpolate Truncate and Project (ITP) method.
```

--------------------------------

### BiCop Class Initialization

Source: https://ty-cheng.github.io/torchvinecopulib/torchvinecopulib.bicop.html

Initializes a new BiCop instance with a specified grid size.

```APIDOC
## Constructor: BiCop(num_step_grid=128)

### Description
Initializes the bivariate copula model.

### Parameters
- **num_step_grid** (int) - Optional - Number of steps for the grid. Defaults to 128.
```

--------------------------------

### imshow(is_log_pdf, ax, cmap, ...)

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/bicop.html

Displays the (log-)PDF grid as a heatmap.

```APIDOC
## imshow(is_log_pdf, ax, cmap, ...)

### Description
Display the (log-)PDF grid as a heatmap.

### Parameters
#### Request Body
- **is_log_pdf** (bool) - Optional - If True, plot log-PDF. Defaults to False.
- **ax** (plt.Axes) - Optional - Matplotlib Axes object to plot on.
- **cmap** (str) - Optional - Colormap for the plot. Defaults to "inferno".

### Response
#### Success Response (200)
- **figure/axes** (tuple) - The figure and axes objects.
```

--------------------------------

### Build Tree from Matrix (Non-Dissmann Method)

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Constructs a tree structure directly from a matrix, used when the vine copula method is not Dissmann's. It infers edges and calculates weights.

```python
else:
    # * tree structure is inferred from matrix, if not Dissmann
    tree = []
    for idx in range(self.num_dim - lv - 1):
        # ! sorted !
        v_l, v_r = sorted(
            (
                int(matrix[idx][idx]),
                int(matrix[idx][self.num_dim - lv - 1]),
            )
        )
        s = sorted((int(_) for _ in matrix[idx][(self.num_dim - lv) :]))
        tree.append((v_l, v_r, *s))
        # * ensure all pseudo-obs are ready
        for v in (v_l, v_r):
            if dct_obs[lv][(v, *s)] is None:
                _visit_hfunc(lv=lv, v_s=(v, *s))
        w = f_bidep(
            x=dct_obs[lv][v_l, *s],
            y=dct_obs[lv][v_r, *s],
        )
        self.tree_bidep[lv][v_l, v_r, *s] = w[0] if is_kendall_tau else w
```

--------------------------------

### Build Tree from Edge Weights (Dissmann Method)

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Constructs a tree structure from edge weights, used in the Dissmann method for vine copula construction. Supports different vine types (dvine, cvine, rvine).

```python
if is_dissmann:
    # * obs2edge, list possible edges that connect two pseudo obs, calc f_bidep
    # ! proximity condition: only obs sharing 'cond_ing' can have edges
    # * group vertices by their conditioning set
    grp_s = defaultdict(list)
    for v_s in curr_v_s_parent:
        v, *s = v_s
        s = tuple(s)
        grp_s[s].append(v)
    tmp_edge_weight = {}
    for s, lst_v in grp_s.items():
        if len(lst_v) < 2:
            continue
        lst_v.sort()
        # * ensure all pseudo-obs are ready
        for v in lst_v:
            if dct_obs[lv][(v, *s)] is None:
                _visit_hfunc(lv=lv, v_s=(v, *s))
        for v_l, v_r in combinations(lst_v, 2):
            # ! already sorted !
            w = f_bidep(
                x=dct_obs[lv][v_l, *s],
                y=dct_obs[lv][v_r, *s],
            )
            tmp_edge_weight[(v_l, v_r, *s)] = w[0] if is_kendall_tau else w
    if mtd_vine == "dvine":
        # * edge2tree, dvine
        if lv == 0:
            tree = self._mst_from_edge_dvine(edge_weight_lv=tmp_edge_weight)
        else:
            tree = list(tmp_edge_weight)
    elif mtd_vine == "cvine":
        # * edge2tree, cvine
        tree = self._mst_from_edge_cvine(edge_weight_lv=tmp_edge_weight)
    elif mtd_vine == "rvine":
        # * edge2tree, rvine
        tree = self._mst_from_edge_rvine(edge_weight_lv=tmp_edge_weight)
    else:
        raise ValueError("mtd_vine must be one of 'cvine', 'dvine', 'rvine'")
    # * store tree and weights
    self.tree_bidep[lv] = {lr_s: tmp_edge_weight[lr_s] for lr_s in tree}
```

--------------------------------

### Construct R-vine MST

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Builds a general R-vine Maximum Spanning Tree using Kruskal's algorithm with disjoint set union.

```python
    @torch.no_grad()
    def _mst_from_edge_rvine(self, edge_weight_lv: dict) -> None:
        # * edge2tree, rvine (Kruskal's MST, disjoint set/ union find)
        # * lr_s[2:] is cond_ing set
        edge_weight_lv = copy.deepcopy(edge_weight_lv)
        lv = len(next(iter(edge_weight_lv))[2:])
        # ! pseudo obs vertices point to parent bicop vertices (constraint set)
        parent = {}
        for lr_s, cond_ed in self.struct_obs[lv].items():
            parent[lr_s] = (
                frozenset(lr_s + tuple(map(int, cond_ed.split(","))))
                if lv > 0
                else frozenset(lr_s)
            )
        # * bicop vertices point to themselves
        parent.update({r: r for r in parent.values()})
        rank = {r: 0 for r in parent}
        mst = []

        def find(v):
            """
            Path compression.
            """
            if parent[v] != v:
```

--------------------------------

### Sample from VineCop

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Generates samples from the fitted VineCop model. Specify the desired number of samples. The output will be a PyTorch tensor.

```python
samples = vc.sample(num_sample=500)
```

--------------------------------

### VineCop.sample()

Source: https://ty-cheng.github.io/torchvinecopulib/torchvinecopulib.vinecop.html

Samples observations from the VineCop model. Allows for custom sampling orders and pseudo-observations.

```APIDOC
## POST /sample

### Description
Generates samples from the VineCop model.

### Method
POST

### Endpoint
/sample

### Parameters
#### Query Parameters
- **sample_order** (tuple[int, ...] | None) - Optional - Custom sampling order. Defaults to None and uses self.sample_order.
- **dct_v_s_obs** (dict[tuple[int, ...], torch.Tensor] | None) - Optional - Dictionary mapping tuple(idx|conding set) to pseudo-observations. Defaults to None. User-provided pseudo-observations to initialize the sampling process. Notice if is_cop_scale=False, CDF/PPF will only be applied to the top level marginals. Pseudo-obs at deeper levels are assumed to be in copula scale [0,1].

### Response
#### Success Response (200)
- **sampled_observations** (torch.Tensor) - Sampled observations in original scale if `self.is_cop_scale=False`, otherwise in [0,1]^d.

#### Response Example
{
  "sampled_observations": "[tensor data]"
}
```

--------------------------------

### Initialize VineCop

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Initializes a VineCop object. Use this to set up the dimensions, scaling behavior, and grid resolution for bivariate copulas. Marginals are initialized as None and bicops are created for all pairwise combinations.

```python
from torchvinecopulib.vinecop import VineCop

vc = VineCop(num_dim=4, is_cop_scale=False, num_step_grid=128)
```

--------------------------------

### kdeCDFPPF1D Module

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/util.html

A module for 1D KDE CDF/PPF estimation using fastKDE and Simpson's rule.

```APIDOC
## kdeCDFPPF1D

### Description
Fits a kernel density estimate via fastKDE on a grid and precomputes PDF, CDF, and finite-difference slopes for fast interpolation.

### Parameters
#### Arguments
- **x** (torch.Tensor) - Required - Input sample to fit the KDE.
- **num_step_grid** (int) - Optional - Number of grid points (power of 2 plus 1). Defaults to None.
- **x_min** (float) - Optional - Minimum value of the grid. Defaults to x.min() - pad.
- **x_max** (float) - Optional - Maximum value of the grid. Defaults to x.max() + pad.
- **pad** (float) - Optional - Padding to extend beyond min/max. Defaults to 1.0.

### Methods
- **cdf(x: torch.Tensor)**: Compute the CDF of the fitted KDE at x.
```

--------------------------------

### VineCop Initialization

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Initializes a VineCop object with specified dimensions and optional parameters for marginal handling and grid resolution.

```APIDOC
## VineCop Initialization

### Description
Initializes a VineCop object.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **num_dim** (int) - Required - number of dimensions.
- **is_cop_scale** (bool) - Optional - if True, the marginals are assumed in copula scale [0,1]. Otherwise, the marginals are fitted via KDE. Defaults to False.
- **num_step_grid** (int) - Optional - Grid resolution (power of 2) passed to each BiCop. Defaults to 128.

### Request Example
```python
from torchvinecopulib.vinecop import VineCop
vc = VineCop(num_dim=4, is_cop_scale=False, num_step_grid=128)
```

### Response
#### Success Response (200)
None (initialization does not return a value)

#### Response Example
None
```

--------------------------------

### BiCop.imshow

Source: https://ty-cheng.github.io/torchvinecopulib/torchvinecopulib.bicop.html

Display the (log-)PDF grid as a heatmap.

```APIDOC
## BiCop.imshow

### Description
Display the (log-)PDF grid as a heatmap.

### Method
Not specified (likely a method of a BiCop object)

### Endpoint
Not applicable (Python function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **figure** (plt.Figure) - The figure object.
- **axes** (plt.Axes) - The axes object.

#### Response Example
```json
{
  "figure": "plt.Figure",
  "axes": "plt.Axes"
}
```

### Parameters
- **is_log_pdf** (bool) - Optional. If True, plot log-PDF. Defaults to False.
- **ax** (plt.Axes) - Optional. Matplotlib Axes object to plot on. If None, a new figure and axes are created. Defaults to None.
- **cmap** (str) - Optional. Colormap for the plot. Defaults to "inferno".
- **xlabel** (str) - Optional. X-axis label. Defaults to r"$u_{left}$".
- **ylabel** (str) - Optional. Y-axis label. Defaults to r"$u_{right}$".
- **title** (str) - Optional. Plot title. Defaults to "Estimated bivariate copula density".
- **colorbartitle** (str) - Optional. Colorbar title. Defaults to "Density".
- **imshow_kwargs** (dict) - Additional keyword arguments for imshow.
```

--------------------------------

### Package Structure Overview

Source: https://ty-cheng.github.io/torchvinecopulib/_sources/torchvinecopulib.rst.txt

Overview of the torchvinecopulib package hierarchy and module structure.

```APIDOC
## Package Structure

### Description
The torchvinecopulib package is organized into three primary subpackages for handling different aspects of vine copula modeling.

### Subpackages
- **torchvinecopulib.bicop**: Contains implementations for bivariate copula models.
- **torchvinecopulib.util**: Contains utility functions and helper modules.
- **torchvinecopulib.vinecop**: Contains implementations for vine copula models.

### Module Contents
- **torchvinecopulib**: The main module providing core functionality and inheritance support for the library.
```

--------------------------------

### sample(num_sample, seed, is_sobol)

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/bicop.html

Generates samples from the copula using the inverse Rosenblatt transform.

```APIDOC
## sample(num_sample, seed, is_sobol)

### Description
Sample from the copula by inverse Rosenblatt transform. Uses Sobol sequence if is_sobol=True, otherwise uniform RNG.

### Parameters
#### Request Body
- **num_sample** (int) - Optional - Number of samples to generate. Defaults to 100.
- **seed** (int) - Optional - Random seed for reproducibility. Defaults to 42.
- **is_sobol** (bool) - Optional - If True, use Sobol sampling. Defaults to False.

### Response
#### Success Response (200)
- **samples** (torch.Tensor) - Generated samples, shape (num_sample, 2).
```

--------------------------------

### Draw Samples from Fitted Vine Copula

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Generates joint samples from a fitted vine copula using inverse Rosenblatt transformations. Supports quasi-random sampling with Sobol engine and custom initialization with pseudo-observations.

```python
raise NotImplementedError
```

```python
@torch.no_grad()
def sample(
    self,
    num_sample: int = 1000,
    seed: int = 42,
    is_sobol: bool = False,
    sample_order: tuple[int, ...] | None = None,
    dct_v_s_obs: dict[tuple[int, ...], torch.Tensor] | None = None,
) -> torch.Tensor:
    """Draw random samples from the fitted vine copula via inverse Rosenblatt.

    Generates ``num_sample`` joint samples in original or copula scale by
    (1) sampling independent uniforms for each “source” pseudo-obs,
    (2) recursively applying h-functions and their inverses following the
    vine structure, and (3) optionally transforming back through 1D marginal PPFs.

    Args:
        num_sample (int, optional): number of samples to draw. Defaults to 1000.
        seed (int, optional): random seed for RNG or Sobol engine. Defaults to 42.
        is_sobol (bool, optional): if True, use Sobol engine for quasi-random sampling. Defaults to False.
        sample_order (tuple[int, ...] | None, optional): custom sampling order. Defaults to None and uses `self.sample_order`.
        dct_v_s_obs (dict[tuple[int, ...], torch.Tensor] | None, optional):
            dict mapping tuple(idx|conding set)->pseudo-obs. Defaults to None. User-provided pseudo-obs to initialize
            the sampling process. Notice if `is_cop_scale=False`, CDF/PPF will only be applied to the top level marginals.
            Pseudo-obs at deeper levels are assumed to be in copula scale [0,1].

    Returns:
        torch.Tensor: sampled observations in original scale if ``self.is_cop_scale=False``, otherwise in [0,1]^d.
    """

    def _ref_count_decrement(v_s) -> None:
        ref_count[v_s] -= 1
        if ref_count[v_s] < 1 and (len(v_s) > 1):
            del dct_obs[v_s]

    def _visit(lv: int, v_s: tuple, is_hinv: bool):
        v_down, *s_down = v_s
        s_down = tuple(s_down)
        # * locate the bicop at upper level that connects the three vertices
        cond_ed = self.struct_obs[lv][v_s]
        bcp: BiCop = self.bicops[cond_ed]
        v_l, v_r = self.struct_bcp[cond_ed]["cond_ed"]
        s_up = self.struct_bcp[cond_ed]["cond_ing"]
        is_down_right = v_down == v_r
        # * check missing parents, call hfunc from even upper to visit
        if is_hinv:
            frontier = [(v_l if is_down_right else v_r, *s_up)]
        else:
            frontier = [(v_l, *s_up), (v_r, *s_up)]
        for v_s in frontier:
            if v_s not in dct_obs:
                _visit(lv=lv - 1, v_s=v_s, is_hinv=False)
        # * update pseudo-obs
        v_s_next = (v_down, *s_up)
        if is_hinv:
            if bcp.is_indep:
                dct_obs[v_s_next] = dct_obs[v_down, *s_down]
            elif is_down_right:
                dct_obs[v_s_next] = bcp.hinv_l(
                    torch.hstack(
                        [
                            dct_obs[v_l, *s_up],
                            dct_obs[v_r, *s_down],
                        ]
                    )
                )
            else:
                dct_obs[v_s_next] = bcp.hinv_r(
                    torch.hstack(
                        [
                            dct_obs[v_l, *s_down],
                            dct_obs[v_r, *s_up],
                        ]
                    )
                )
        else:
            if bcp.is_indep:
                dct_obs[v_down, *s_down] = dct_obs[v_down, *s_up]
            else:
                dct_obs[v_down, *s_down] = (bcp.hfunc_l if is_down_right else bcp.hfunc_r)(
                    torch.hstack(
                        [
                            dct_obs[v_l, *s_up],
                            dct_obs[v_r, *s_up],
                        ]
                    )
                )
        # * garbage collection check
        for v_s in [(v_l, *s_up), (v_r, *s_up), (v_down, *s_down)]:
            _ref_count_decrement(v_s=v_s)
        if is_hinv:
            return v_s_next

    # ! device agnostic
    device, dtype = self.device, self.dtype
    torch.manual_seed(seed=seed)
    # ! start with any user‐provided pseudo obs
    dct_obs = dict()
    if dct_v_s_obs:
        for v_s, vec in dct_v_s_obs.items():
            v, *s = v_s
            # ! sorted !
            v_s = (v, *sorted(s))
            # NOTE: if top lv then marginal cdf, else nothing happen (quantile regression for experienced users)
            if not s:

```

--------------------------------

### BiCop Initialization

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/bicop.html

Initializes the bivariate copula (BiCop) class. By default, it creates an independent bicop. The `num_step_grid` parameter controls the resolution of precomputed grids.

```APIDOC
## BiCop Initialization

### Description
Initializes the bivariate copula (BiCop) class. By default an independent bicop.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **num_step_grid** (int, optional) - number of steps per dimension for the precomputed grids (must be a power of 2). Defaults to 128.

### Request Example
```python
from torchvinecopulib.bicop import BiCop
cop = BiCop(num_step_grid=256)
```

### Response
None
```

--------------------------------

### Construct D-vine MST

Source: https://ty-cheng.github.io/torchvinecopulib/_modules/torchvinecopulib/vinecop.html

Builds a Maximum Spanning Tree restricted to a D-vine structure using a greedy approach with degree constraints.

```python
    @torch.no_grad()
    def _mst_from_edge_dvine(self, edge_weight_lv: dict) -> None:
        # * edge2tree, dvine (MST, restricted to dvine)
        # * TSP with precedence constraints (clustered TSP), only called at lv-0
        # ! all s have to be empty for level‑0 D‑vine
        edge_list = [((v_l, v_r), -abs(w)) for (v_l, v_r, *s), w in edge_weight_lv.items()]
        edge_list.sort(key=lambda x: x[1])
        parent = list(range(self.num_dim))
        degree = [0] * self.num_dim

        def find(v):
            while parent[v] != v:
                parent[v] = parent[parent[v]]
                v = parent[v]
            return v

        def union(x, y):
            rx, ry = find(x), find(y)
            if rx != ry:
                parent[ry] = rx
                return True
            return False

        def grow(edge_list, target):
            for (v_l, v_r), _ in edge_list:
                if len(path) >= target:
                    break
                if degree[v_l] < 2 and degree[v_r] < 2 and union(v_l, v_r):
                    path.append((v_l, v_r))
                    degree[v_l] += 1
                    degree[v_r] += 1

        path: list[tuple[int, int]] = []
        cand_v = list(self.first_tree_vertex)
        if len(cand_v) > 1:
            cand_e = [e for e in edge_list if e[0][0] in cand_v and e[0][1] in cand_v]
            grow(edge_list=cand_e, target=len(cand_v) - 1)
        grow(edge_list=edge_list, target=self.num_dim - 1)
        # * canonicalize ordering
        return [(min(v_l, v_r), max(v_l, v_r)) for v_l, v_r in path]
```
Tokens:
Raw