Plotting — Visualize Copula Densities and Structures
API reference for rscopulas.plotting: plot_density for contour plots, plot_scatter for pseudo-observations, and plot_vine_structure for vine tree visualization.
The rscopulas.plotting module provides three functions for visualizing fitted copula models. The base rscopulas package does not depend on matplotlib, so these functions are only available after you install the optional viz extra. If you call any plotting function without matplotlib installed, you will get a clear ImportError with installation instructions.
Installation
uv add "rscopulas[viz]"
If you use pip directly:
pip install "rscopulas[viz]"
Import
from rscopulas.plotting import plot_density, plot_scatter, plot_vine_structure
plot_density
Plot a filled contour map of the bivariate copula density over the unit square [0, 1]². This function only supports models with dim == 2.
plot_density(
model,
*,
ax=None,
grid_size=100,
levels=10,
clip_eps=1e-12,
cmap="viridis",
)
A fitted copula model with a dim property equal to 2 and a log_pdf(data, *, clip_eps) method. Any rscopulas model with dim == 2 satisfies this interface.
A matplotlib Axes object to draw on. If None, a new figure and axes are created automatically.
Number of points per axis in the evaluation grid. Larger values produce smoother contours at the cost of more computation.
Number of filled contour levels. The contour overlay uses half this value.
Boundary clipping passed to log_pdf to avoid evaluation at exact 0 or 1.
A matplotlib colormap name for the filled contours.
The axes object, so you can further customize or save the figure.
Example
import numpy as np
from rscopulas import GaussianCopula
from rscopulas.plotting import plot_density
import matplotlib.pyplot as plt
corr = np.array([[1.0, 0.7], [0.7, 1.0]])
model = GaussianCopula.from_params(corr)
ax = plot_density(model, grid_size=80, cmap="plasma")
plt.savefig("gaussian_density.png", dpi=150, bbox_inches="tight")
plt.show()
plot_scatter
Plot pseudo-observations as a scatter plot. You can pass either an existing sample array or a model to draw samples from.
plot_scatter(
*,
sample=None,
model=None,
n=500,
seed=None,
ax=None,
alpha=0.4,
s=12,
dims=(0, 1),
)
You must pass exactly one of sample or model. Passing both or neither raises a ValueError.
A 2-D array of pseudo-observations to plot directly. Mutually exclusive with model.
A fitted copula model with a sample(n, *, seed) method. The function draws n samples from the model before plotting. Mutually exclusive with sample.
Number of samples to draw when model is provided.
Random seed for reproducibility when sampling from model.
Axes to draw on. A new figure is created if None.
Point opacity. Lower values reduce overplotting for large samples.
Marker size in points squared, passed to matplotlib's scatter.
Column indices to plot on the x and y axes. Useful for visualizing a 2-D slice of a higher-dimensional model.
The axes object.
Example
import numpy as np
from rscopulas import ClaytonCopula
from rscopulas.plotting import plot_scatter
model = ClaytonCopula.from_params(dim=2, theta=3.0)
ax = plot_scatter(model=model, n=800, seed=1)
import numpy as np
from rscopulas.plotting import plot_scatter
rng = np.random.default_rng(0)
sample = rng.uniform(0.01, 0.99, size=(600, 4))
# Plot dimensions 1 and 3
ax = plot_scatter(sample=sample, dims=(1, 3), alpha=0.3)
plot_vine_structure
Visualize a fitted vine copula's structure matrix as a heatmap, with an optional annotation sidebar summarizing each tree level's edges and pair-copula families.
plot_vine_structure(vine_model, *, ax=None, annotate=True)
A fitted VineCopula instance. The model must have structure_info and trees attributes.
Axes to draw on. A new figure is created if None.
When True, cell values are printed over the matrix heatmap and a monospace summary of each tree's edges is added to the right of the plot.
The axes object.
Example
import numpy as np
from rscopulas import VineCopula
from rscopulas.plotting import plot_vine_structure
import matplotlib.pyplot as plt
rng = np.random.default_rng(0)
data = rng.uniform(0.01, 0.99, size=(500, 4))
result = VineCopula.fit_r(data, family_set=["gaussian", "clayton", "gumbel"])
vine = result.model
ax = plot_vine_structure(vine, annotate=True)
plt.tight_layout()
plt.savefig("vine_structure.png", dpi=150, bbox_inches="tight")
plt.show()
Missing viz extra
If you import from rscopulas.plotting without matplotlib installed, you will see:
ImportError: matplotlib is required for rscopulas plotting support.
Install it with `uv add 'rscopulas[viz]'` (in a uv project),
or `uv pip install 'rscopulas[viz]'` / `matplotlib`.
The error is raised lazily—only when you call a plotting function, not at import time.