Python Quickstart: Install and Fit Your First Copula

Rscopulas is available on PyPI and requires Python 3.10 or later. This guide walks you through installation, preparing your data as pseudo-observations, fitting a copula model, reading the fit diagnostics, and drawing samples.

Install

1. Add rscopulas to your project

   The recommended way to install rscopulas is with uv inside a uv project. This updates your lockfile and keeps your environment reproducible.

   uv add rscopulas
   

   pip install rscopulas
   

   Info

   Python 3.10 or later is required.

2. Install the optional viz extra (optional)

   If you want density plots, scatter plots, and vine structure graphs, add the viz extra. It pulls in matplotlib>=3.8.

   uv add "rscopulas[viz]"
   

   pip install "rscopulas[viz]"
   

Prepare pseudo-observations

Rscopulas does not fit marginal distributions. You must supply data that is already in pseudo-observation form — a NumPy float64 array with every entry strictly inside (0, 1).

Fit a Gaussian copula

Once your data is in pseudo-observation form, pass it to GaussianCopula.fit. The returned FitResult gives you the fitted model and a FitDiagnostics object.

import numpy as np
from rscopulas import GaussianCopula

data = np.array([[0.12, 0.18], [0.21, 0.25], [0.82, 0.79]], dtype=np.float64)
fit = GaussianCopula.fit(data)
print("AIC:", fit.diagnostics.aic)
print("sample:\n", fit.model.sample(4, seed=7))

fit.diagnostics contains:

• loglik — log-likelihood at the optimum
• aic — Akaike information criterion
• bic — Bayesian information criterion
• converged — whether the optimizer converged
• n_iter — number of optimizer iterations

Sample from a copula without fitting

You can also construct a copula directly from parameters and sample from it without fitting to data. This is useful for simulation studies or when you already know the dependence parameters.

from rscopulas import GumbelCopula

model = GumbelCopula.from_params(2, 2.1)
samples = model.sample(5, seed=11)
print("family:", model.family)
print("samples:\n", samples)
print("log_pdf:\n", model.log_pdf(samples))

from_params takes the dimension as the first argument and the copula parameter(s) as subsequent arguments. The seed keyword on sample makes results reproducible.

Available models

Rscopulas exposes the following model classes in its top-level namespace:

Next steps