Copulas

Common errors

• AttributeError: module 'copulas' has no attribute 'GaussianCopula'

  cause Attempting to import a specific copula model (e.g., `GaussianCopula` or `GaussianMultivariate`) directly from the top-level `copulas` package.
  fix Import multivariate and bivariate copula models from their specific submodules. For example, use `from copulas.multivariate import GaussianMultivariate` instead.

• ValueError: Input data must be numerical

  cause The `copulas` library expects numerical input data. This error occurs when a DataFrame or array containing non-numerical (e.g., string, object, or boolean) columns is passed to a copula model.
  fix Preprocess your data to ensure all columns intended for modeling are numerical. This may involve one-hot encoding categorical features, label encoding, or converting mixed-type columns. Remove or handle missing values appropriately.

• RuntimeError: The number of features in the data is X, but the copula expects Y.

  cause Mismatch in dimensionality between the input data and the copula model, often when a previously fitted model (or one with a predefined structure) is used with new data of a different number of columns.
  fix Ensure the input data (e.g., `pandas.DataFrame` or `numpy.ndarray`) has the same number of columns (features) as the copula model was originally fitted with, or explicitly define the model for the new dimensionality.

Warnings

• gotcha The Gaussian copula, a common choice, assumes an elliptical dependence structure and exhibits zero tail dependence. Applying it to data with strong non-linear or asymmetric tail dependencies (e.g., financial returns during market crashes) can significantly underestimate joint extreme events.
  Fix: Carefully select the copula family based on the data's inherent dependence structure. Consider Archimedian or t-copulas for tail dependence, or Vine copulas for complex, high-dimensional structures. Refer to the official documentation and statistical literature for guidance on model selection.
• gotcha The `copulas` library primarily expects numerical and stationary data. Direct application to raw categorical data or non-stationary time series (e.g., raw stock prices instead of returns) can lead to unreliable models and synthetic data quality issues.
  Fix: Preprocess data to ensure all columns are numerical (e.g., one-hot encoding for categorical variables). For time series, consider transforming data (e.g., differencing, log returns) to achieve stationarity before fitting the copula.
• breaking The library is part of the SDV (Synthetic Data Vault) ecosystem and has undergone API changes. Older versions (e.g., prior to `v0.2.0`) had different API for statistics methods, input/output formats, and less robust implementations, potentially breaking code written for newer versions.
  Fix: Always check the release notes and migration guides when upgrading. For new projects, use the latest stable version. Ensure your Python environment meets the `requires_python` specification (`<3.15,>=3.9`).
• gotcha Choosing the appropriate copula (e.g., Archimedian, Gaussian, Vine) and univariate distributions for high-dimensional or complex datasets is crucial and non-trivial. An inappropriate model choice may fail to capture the underlying data structure accurately, leading to synthetic data that does not truly resemble the real data.
  Fix: Experiment with different copula families and univariate distributions. Use visualization tools (like `copulas.visualization.compare_3d`) and statistical metrics to evaluate the similarity between real and synthetic data. Consult documentation on advanced model selection and evaluation techniques.

Install

• pip install copulas PyPI
• conda install -c conda-forge copulas Conda-forge

Imports

• sample_trivariate_xyz

  from copulas.datasets import sample_trivariate_xyz

• GaussianMultivariate
  wrong:

  from copulas import GaussianMultivariate

  correct:

  from copulas.multivariate import GaussianMultivariate

  Specific copula models are typically found in `copulas.multivariate` or `copulas.bivariate` submodules, not directly under the top-level package.
• compare_3d

  from copulas.visualization import compare_3d

Quickstart

This quickstart demonstrates how to load a sample dataset, fit a Gaussian Multivariate Copula model to it, and then generate new synthetic data that statistically resembles the original. It also includes an optional visualization step to compare the real and synthetic data.

import pandas as pd
from copulas.datasets import sample_trivariate_xyz
from copulas.multivariate import GaussianMultivariate
import warnings

# Suppress FutureWarnings from certain dependencies for cleaner output
warnings.filterwarnings('ignore', category=FutureWarning)

# 1. Load a demo dataset (or your own pandas DataFrame)
real_data = sample_trivariate_xyz()
print("Original Data Head:\n", real_data.head())

# 2. Initialize and fit a multivariate copula model
copula = GaussianMultivariate()
copula.fit(real_data)
print("\nCopula model fitted successfully.")

# 3. Generate new synthetic data points
synthetic_data = copula.sample(len(real_data))
print("\nSynthetic Data Head:\n", synthetic_data.head())

# Optional: To visualize, uncomment the following lines and ensure a graphical environment
# from copulas.visualization import compare_3d
# compare_3d(real_data, synthetic_data, figsize=(10, 5))
# print("\nComparison plot generated (if running in a graphical environment).")