Rscopulas Python Package Overview and Imports

The rscopulas Python package is a thin, type-safe wrapper around a compiled Rust extension. The public surface—models, data classes, and error types—lives in rscopulas and is re-exported from rscopulas.__init__. The compiled Rust extension that powers all numerical work is rscopulas._rscopulas. You interact with rscopulas._rscopulas indirectly through the Python classes; you rarely need to import it directly.

Package structure

rscopulas

The public Python package. Import models, data classes, and errors from here.

rscopulas._rscopulas

The compiled Rust extension. All compute-intensive operations run here. You interact with it indirectly through the public classes.

Imports

All public names are available from the top-level rscopulas package.

from rscopulas import (
    GaussianCopula, StudentTCopula,
    ClaytonCopula, FrankCopula, GumbelCopula,
    VineCopula, HierarchicalArchimedeanCopula, PairCopula,
    FitResult, FitDiagnostics,
    InvalidInputError, ModelFitError,
)

Public exports

Copula models

Class	Description
`GaussianCopula`	Elliptical copula with Gaussian correlation structure
`StudentTCopula`	Elliptical copula with Student-t tails
`ClaytonCopula`	Archimedean copula with lower-tail dependence
`FrankCopula`	Archimedean copula with symmetric dependence
`GumbelCopula`	Archimedean copula with upper-tail dependence
`VineCopula`	Pair-copula construction in C-, D-, or R-vine structure
`HierarchicalArchimedeanCopula`	Nested Archimedean copula with hierarchical structure
`PairCopula`	Bivariate copula used as a building block in vine models

Data and result types

Class	Description
`FitResult`	Generic dataclass holding the fitted model and diagnostics
`FitDiagnostics`	Log-likelihood, AIC, BIC, convergence status, and iteration count
`VineEdgeInfo`	Data for a single edge in a vine tree
`VineStructureInfo`	Vine kind, structure matrix, and truncation level
`VineTreeInfo`	All edges at a given tree level

Error types

Exception	Description
`RscopulasError`	Base class for all library errors
`InvalidInputError`	Raised when input data fails validation (wrong shape, out-of-range values, etc.)
`NonPrefixConditioningError`	Subclass of `InvalidInputError`. Raised by `VineCopula.sample_conditional` when the known columns do not form a diagonal prefix of `variable_order`.
`ModelFitError`	Raised when the fitting algorithm fails to find a valid solution
`NumericalError`	Raised when a numerical operation produces an invalid result
`BackendError`	Raised for internal Rust backend failures
`InternalError`	Raised when an internal Rust panic is caught at the Python boundary

Data requirements

All copula models expect pseudo-observations as input: values that lie strictly in the open interval (0, 1). Passing raw observations, probabilities outside that range, or exact 0 and 1 will raise an InvalidInputError.

Warning

Values equal to 0 or 1 are not valid inputs. Use the clip_eps parameter on fit and log_pdf to clip data away from the boundary during numerical evaluation.

dtype

numpy.float64required

All input arrays must have dtype=numpy.float64. Integer or other floating-point dtypes will be cast automatically by most constructors, but passing the correct dtype avoids an extra allocation.

Response

shape

(n_samples, n_dims)required

Input arrays must be two-dimensional. Rows are observations; columns are variables.

Response

range

(0, 1) exclusiverequired

Every value must satisfy 0 < x < 1. Use clip_eps to clip values at the boundary rather than passing exact boundary values.

Response

Common workflow

The standard pattern is to call Model.fit(data), inspect the FitResult, and then use the fitted model to compute log-densities or draw samples.

import numpy as np
from rscopulas import GaussianCopula

# Pseudo-observations: shape (n, d), dtype float64, values in (0, 1)
rng = np.random.default_rng(0)
data = rng.uniform(0.01, 0.99, size=(500, 3))

# Fit
result = GaussianCopula.fit(data)

# Inspect diagnostics
print("AIC:", result.diagnostics.aic)
print("converged:", result.diagnostics.converged)

# Use the fitted model
model = result.model
log_densities = model.log_pdf(data)
new_samples = model.sample(200, seed=42)