Copulas
A library to model multivariate data using copulas.
Last verified:
What is Copulas?
Copulas is a Python library for modeling multivariate distributions and sampling from them using copula functions. Given a table of numerical data, Copulas learns the distribution and generates new synthetic data following the same statistical properties. The library is part of The Synthetic Data Vault Project, a project from DataCebo.
Key features include the ability to model multivariate data by choosing from a variety of univariate distributions and copulas, including Archimedian Copulas, Gaussian Copulas, and Vine Copulas. Users can compare real and synthetic data visually after building their model, with visualizations available as 1D histograms, 2D scatterplots, and 3D scatterplots. The library also provides complete access to the internals of the model, allowing users to access and manipulate learned parameters, set or tune parameters to their choosing.
Copulas is designed for data scientists, machine learning engineers, and researchers who need to generate synthetic tabular data for testing, privacy protection, or data augmentation. It is particularly useful for those working with multivariate numerical datasets who need to preserve statistical properties while generating new data samples. The library integrates with pandas DataFrames and provides built-in demo datasets for quick Start.
The library supports saving and loading fitted models to disk, extracting parameters as dictionaries, and creating identical copula instances from parameter dictionaries. It includes built-in sample datasets like sample_trivariate_xyz and sample_bivariate_age_income for testing and demonstration purposes.
Copulas pricing
Pricing model: Freemium
Copulas is completely free and open source. There is no paid tier or commercial licensing. The library can be installed via pip (pip install copulas) or conda (conda install -c sdv-dev -c conda-forge copulas) at no cost. All features including Gaussian Copulas, Vine Copulas, Archimedian Copulas, visualization tools, and model persistence are included in the free open source version.
Copulas pros
- Open source and free to use
- Supports Gaussian Copulas for multivariate modeling
- Includes Vine Copulas for complex dependencies
- Supports Archimedian Copulas (Clayton, Frank, Gumbel)
- Built-in visualization tools for 1D histograms
- Built-in visualization tools for 2D scatterplots
- Built-in visualization tools for 3D scatterplots
- Easy installation with pip
- Easy installation with conda
- Model save and load functionality
- Extract parameters using to_dict method
- Create instances from parameters using from_dict
- Built-in demo datasets for quick testing
- Returns pandas DataFrame for synthetic data
- Automatic marginal distribution estimation
- Complete access to model internals
- Supports multiple univariate distributions (Beta, Gamma, Gaussian, GaussianKDE, LogLaplace, StudentT, TruncatedGaussian, Uniform)
- Part of the larger SDV ecosystem for synthetic data
Copulas cons
- Primarily focused on numerical data only
- No built-in support for categorical data
- Fitting process can take a lot of time for some copula models
- Requires loading same class when loading saved model
- Documentation lacks comprehensive FAQ section
- No cloud-based or SaaS offering available
- Limited to tabular data (no images or text)
- No automatic hyperparameter tuning built in
Frequently asked questions about Copulas
What is Copulas used for?
Copulas is a Python library for modeling multivariate distributions and sampling from them using copula functions. Given a table of numerical data, you use Copulas to learn the distribution and generate new synthetic data following the same statistical properties.
How do I install Copulas?
The easiest and recommended way to install Copulas is using pip: pip install copulas. It can also be installed using conda: conda install -c sdv-dev -c conda-forge copulas. For development, you can install from source by cloning the repository and running make install-develop.
What types of copulas does the library support?
The Copulas library offers many options including Gaussian Copula (via GaussianMultivariate), Vine Copulas (via VineCopula class), and Archimedian Copulas including Clayton, Frank, and Gumbel copulas.
How do I generate synthetic data with Copulas?
First create a Copula instance like GaussianMultivariate(), then call fit(data) with your data to estimate marginal and joint distributions. Finally, call sample(num_samples) to generate new synthetic data. The returned object is a pandas DataFrame with the same format as your input data.
Can I save and load Copulas models?
Yes. If you have a fitted model, you can save it by calling the save method with a file path argument. You can load a model stored on disk using the load method, passing the path where the model is stored. Note that you need to load it using the same class that was used to save it.
What visualization options are available?
Visualizations are available as 1D histograms (using compare_1d or dist_1d), 2D scatterplots (using compare_2d or scatter_2d), and 3D scatterplots (using compare_3d or scatter_3d). You can compare real and synthetic data side-by-side visually.
What univariate distributions are supported?
The library supports multiple univariate distributions including BetaUnivariate, GammaUnivariate, GaussianUnivariate, GaussianKDE (non-parametric), LogLaplace, StudentTUnivariate, TruncatedGaussian, and UniformUnivariate. You can also use select_univariate to automatically choose the best distribution.
How do I extract model parameters?
Once your copula is fitted, you can extract its parameters using the to_dict method, which returns a dictionary containing all the copula parameters. You can then create a new identical Copula instance using the from_dict method with those parameters.
Does Copulas work with categorical data?
Copulas is designed for numerical data. The library is for modeling multivariate distributions of numerical data and generating synthetic numerical data following the same statistical properties. Categorical data is not directly supported.
Who maintains the Copulas library?
Copulas is part of The Synthetic Data Vault Project, a project from DataCebo. The Synthetic Data Vault Project was first created at MIT's Data to AI Lab in 2016, and DataCebo was created in 2020 with the goal of growing the project. Today, DataCebo is the proud developer of SDV, the largest ecosystem for synthetic data generation and evaluation.