A python library for building different types of copulas and using them for sampling.
Project description
An Open Source Project from the Data to AI Lab, at MIT
Overview
- Website: https://sdv.dev
- Documentation: https://sdv.dev/Copulas
- Repository: https://github.com/sdv-dev/Copulas
- License: MIT
- Development Status: Pre-Alpha
Copulas is a Python library for modeling multivariate distributions and sampling from them using copula functions. Given a table containing numerical data, we can use Copulas to learn the distribution and later on generate new synthetic rows following the same statistical properties.
Some of the features provided by this library include:
- A variety of distributions for modeling univariate data.
- Multiple Archimedean copulas for modeling bivariate data.
- Gaussian and Vine copulas for modeling multivariate data.
- Automatic selection of univariate distributions and bivariate copulas.
Supported Distributions
Univariate
- Beta
- Gamma
- Gaussian
- Gaussian KDE
- Log-Laplace
- Student T
- Truncated Gaussian
- Uniform
Archimedean Copulas (Bivariate)
- Clayton
- Frank
- Gumbel
Multivariate
- Gaussian Copula
- D-Vine
- C-Vine
- R-Vine
Install
Requirements
Copulas is part of the SDV project and is automatically installed alongside it. For details about this process please visit the SDV Installation Guide
Optionally, Copulas can also be installed as a standalone library using the following commands:
Using pip
:
pip install copulas
Using conda
:
conda install -c sdv-dev -c conda-forge copulas
For more installation options please visit the Copulas installation Guide
Quickstart
In this short quickstart, we show how to model a multivariate dataset and then generate synthetic data that resembles it.
import warnings
warnings.filterwarnings('ignore')
from copulas.datasets import sample_trivariate_xyz
from copulas.multivariate import GaussianMultivariate
from copulas.visualization import compare_3d
# Load a dataset with 3 columns that are not independent
real_data = sample_trivariate_xyz()
# Fit a gaussian copula to the data
copula = GaussianMultivariate()
copula.fit(real_data)
# Sample synthetic data
synthetic_data = copula.sample(len(real_data))
# Plot the real and the synthetic data to compare
compare_3d(real_data, synthetic_data)
The output will be a figure with two plots, showing what both the real and the synthetic data that you just generated look like:
What's next?
For more details about Copulas and all its possibilities and features, please check the documentation site.
There you can learn more about how to contribute to Copulas in order to help us developing new features or cool ideas.
Credits
Copulas is an open source project from the Data to AI Lab at MIT which has been built and maintained over the years by the following team:
- Manuel Alvarez manuel@pythiac.com
- Carles Sala csala@mit.com
- (Alicia) Yi Sun yis@mit.edu
- José David Pérez jose@pythiac.com
- Kevin Alex Zhang kevz@mit.edu
- Andrew Montanez amontane@mit.edu
- Gabriele Bonomi gbonomib@gmail.com
- Kalyan Veeramachaneni kalyan@csail.mit.edu
- Iván Ramírez rollervan@gmail.com
- Felipe Alex Hofmann fealho@gmail.com
- paulolimac paulolimac@gmail.com
- nazar-ivantsiv nazar.ivantsiv@gmail.com
The Synthetic Data Vault
This repository is part of The Synthetic Data Vault Project
- Website: https://sdv.dev
- Documentation: https://sdv.dev/SDV
History
v0.3.3 - 2020-09-18
General Improvements
- Use
corr
instead ofcov
in the GaussianMultivariate - Issue #195 by @rollervan - Add arguments to GaussianKDE - Issue #181 by @rollervan
New Features
- Log Laplace Distribution - Issue #188 by @rollervan
v0.3.2 - 2020-08-08
General Improvements
New Features
- Add Uniform Univariate - Issue #179 by @rollervan
v0.3.1 - 2020-07-09
General Improvements
- Raise numpy version upper bound to 2 - Issue #178 by @csala
New Features
- Add Student T Univariate - Issue #172 by @gbonomib
Bug Fixes
- Error in Quickstarts : Unknown projection '3d' - Issue #174 by @csala
v0.3.0 - 2020-03-27
Important revamp of the internal implementation of the project, the testing infrastructure and the documentation by Kevin Alex Zhang @k15z, Carles Sala @csala and Kalyan Veeramachaneni @kveerama
Enhancements
- Reimplementation of the existing Univariate distributions.
- Addition of new Beta and Gamma Univariates.
- New Univariate API with automatic selection of the optimal distribution.
- Several improvements and fixes on the Bivariate and Multivariate Copulas implementation.
- New visualization module with simple plotting patterns to visualize probability distributions.
- New datasets module with toy datasets sampling functions.
- New testing infrastructure with end-to-end, numerical and large scale testing.
- Improved tutorials and documentation.
v0.2.5 - 2020-01-17
General Improvements
- Convert import_object to get_instance - Issue #114 by @JDTheRipperPC
v0.2.4 - 2019-12-23
New Features
- Allow creating copula classes directly - Issue #117 by @csala
General Improvements
- Remove
select_copula
fromBivariate
- Issue #118 by @csala - Rename TruncNorm to TruncGaussian and make it non standard - Issue #102 by @csala @JDTheRipperPC
Bugs fixed
- Error on Frank and Gumble sampling - Issue #112 by @csala
v0.2.3 - 2019-09-17
New Features
- Add support to Python 3.7 - Issue #53 by @JDTheRipperPC
General Improvements
- Document RELEASE workflow - Issue #105 by @JDTheRipperPC
- Improve serialization of univariate distributions - Issue #99 by @ManuelAlvarezC and @JDTheRipperPC
Bugs fixed
- The method 'select_copula' of Bivariate return wrong CopulaType - Issue #101 by @JDTheRipperPC
v0.2.2 - 2019-07-31
New Features
truncnorm
distribution and a generic wrapper forscipy.rv_continous
distributions - Issue #27 by @amontanez, @csala and @ManuelAlvarezCIndependence
bivariate copulas - Issue #46 by @aliciasun, @csala and @ManuelAlvarezC- Option to select seed on random number generator - Issue #63 by @echo66 and @ManuelAlvarezC
- Option on Vine copulas to select number of rows to sample - Issue #77 by @ManuelAlvarezC
- Make copulas accept both scalars and arrays as arguments - Issues #85 and #90 by @ManuelAlvarezC
General Improvements
- Ability to properly handle constant data - Issues #57 and #82 by @csala and @ManuelAlvarezC
- Tests for analytics properties of copulas - Issue #61 by @ManuelAlvarezC
- Improved documentation - Issue #96 by @ManuelAlvarezC
Bugs fixed
- Fix bug on Vine copulas, that made it crash during the bivariate copula selection - Issue #64 by @echo66 and @ManuelAlvarezC
v0.2.1 - Vine serialization
- Add serialization to Vine copulas.
- Add
distribution
as argument for the Gaussian Copula. - Improve Bivariate Copulas code structure to remove code duplication.
- Fix bug in Vine Copulas sampling: 'Edge' object has no attribute 'index'
- Improve code documentation.
- Improve code style and linting tools configuration.
v0.2.0 - Unified API
- New API for stats methods.
- Standarize input and output to
numpy.ndarray
. - Increase unittest coverage to 90%.
- Add methods to load/save copulas.
- Improve Gaussian copula sampling accuracy.
v0.1.1 - Minor Improvements
- Different Copula types separated in subclasses
- Extensive Unit Testing
- More pythonic names in the public API.
- Stop using third party elements that will be deprected soon.
- Add methods to sample new data on bivariate copulas.
- New KDE Univariate copula
- Improved examples with additional demo data.
v0.1.0 - First Release
- First release on PyPI.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for copulas-0.4.0.dev0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3105d2e56d69afeca8da3453dde4457986e1d6c7f727ac1ed8f0dbc45f247e91 |
|
MD5 | 14023cb7fc10a5b862295fe518ad74ef |
|
BLAKE2b-256 | b34c484e38b086102806bde3ab5bad63434e44261a8f93824b7d1745fcca79de |