![\u201cCopulas\u201d](\"https://dai.lids.mit.edu/wp-content/uploads/2018/06/Logo_DAI_highres.png\"){kind=logo}
\nAn open source project from Data to AI Lab at MIT.\n\n\nAn open source project from Data to AI Lab at MIT.\n
![\"CDF](\"docs/images/dice_cdf.png\")
\n\nWe can see as the cumulative probability raises by steps of 1/6 at each integer between 1 and 6,\nas those are the only values that can appear.\n\n## Types of distributions\n\nThere are as many different distributions as different random phenomenon, but usually we classify\nthem using this three aspects:\n\n* Continuity: We call a random variable a **continous random variable** if it's `cdf` is\n continuous, that it have no steps. Otherwise, we call it **discrete random variable**.\n In the example of the dice, we have discrete random variable.\n* Dimensionality: When a random variable represents the behavior of a single random phenomenon,\n we call it a **univariate distribution**, analogously we define **bivariate** and\n **multivariate** distributions.\n* Type: Most distribution have a type, defined by its behavior, some of the most common types of\n distributions are: **uniform**, **gaussian**, **exponential**,...\n\n## Copulas\n\nCopulas are multivariate distributions whose marginals are uniform. Using them with distributions\nto model the marginals they allow us to generate **multivariate random variables** for any kind\nof phenomena.\n\n# Quickstart\n\nIn this short tutorial we will guide you through the a series of steps that will help you getting\nstarted with the most basic usage of **Copulas** in order to generate samples from a simple\ndataset.\n\n**NOTE:** To be able to run this demo you will need to install the package from its sources.\n\n## 1. Load the data\n\nThe first step is to load the data we will use to fit **Copulas**. In order to do so, we will\nfirst import the module `pandas` and call its function `read_csv` with the path to our\nexample dataset.\n\nIn this case, we will load the `iris` dataset into a `pandas.DataFrame`.\n\n```python\nimport pandas as pd\ndata = pd.read_csv('data/iris.data.csv')\n```\n\nThis will be return us a dataframe with 4 columns:\n\n```\n 0 1 2\nfeature_01 5.1 4.9 4.7\nfeature_02 3.5 3.0 3.2\nfeature_03 1.4 1.4 1.3\nfeature_04 0.2 0.2 0.2\n```\n\n## 2. Create a Copula instance\n\nThe next step is to import Copulas and create an instance of the desired copulas.\n\nTo do so, we need to import the `copulas.multivariate.GaussianMultivariate` and call it, in order\nto create a GaussianMultivariate instance with the default arguments:\n\n```python\nfrom copulas.multivariate import GaussianMultivariate\ncopula = GaussianMultivariate()\n```\n\n## 3. Fit the model\n\nOnce we have a **Copulas** instance, we can proceed to call its `fit` method passing the `data`\nthat we loaded bfore in order to start the fitting process:\n\n```python\ncopula.fit(data)\n```\n\n## 4. Sample new data\n\nAfter the model has been fitted, we are ready to generate new samples by calling the `sample`\nmethod of the `Copulas` instance passing it the desired amount of samples:\n\n```python\nnum_samples = 1000\nsamples = copula.sample(num_samples)\n```\n\nThis will return a DataFrame with the same number of columns as the original data.\n\n```\n 0 1 2\nfeature_01 7.534814 7.255292 5.723322\nfeature_02 2.723615 2.959855 3.282245\nfeature_03 6.465199 6.896618 2.658393\nfeature_04 2.267646 2.442479 1.109811\n```\n\nThe returned object, `samples`, is a `pandas.DataFrame` containing a table of synthetic data with\nthe same format as the input data and 1000 rows as we requested.\n\n## 5. Load and save a model\n\nFor some copula models the fitting process can take a lot of time, so we probably would like to\navoid having to fit every we want to generate samples. Instead we can fit a model once, save it,\nand load it every time we want to sample new data.\n\nIf we have a fitted model, we can save it by calling it's `save` method, that only takes\nas argument the path where the model will be stored. Similarly, the `load` allows to load\na model stored on disk by passing as argument the path where the model is stored.\n\n```python\nmodel_path = 'mymodel.pkl'\ncopula.save(model_path)\n```\n\nOnce the model is saved, it can be loaded back as a **Copulas** instance by using the `load`\nmethod:\n\n**NOTE**: In order to load a saved model, you need to load it using the same class that was used to save it.\n\n```python\nnew_copula = GaussianMultivariate.load(model_path)\n```\n\nAt this point we could use this model instance to generate more samples.\n\n```python\nnew_samples = new_copula.sample(num_samples)\n```\n\n## 6. Extract and set parameters\n\nIn some cases it's more useful to obtain the parameters from a fitted copula than to save\nand load from disk.\n\nOnce our copula is fitted, we can extract it's parameters using the `to_dict` method:\n\n```python\ncopula_params = copula.to_dict()\n```\n\nThis will return a dictionary containing all the copula parameters:\n\n```\n{'covariance': [[1.006711409395973,\n -0.11010327176239859,\n 0.877604856347186,\n 0.8234432550696282],\n [-0.11010327176239859,\n 1.006711409395972,\n -0.4233383520816992,\n -0.3589370029669185],\n [0.877604856347186,\n -0.4233383520816992,\n 1.006711409395973,\n 0.9692185540781538],\n [0.8234432550696282,\n -0.3589370029669185,\n 0.9692185540781538,\n 1.006711409395974]],\n 'distribs': {'feature_01': {'type': 'copulas.univariate.gaussian.GaussianUnivariate',\n 'fitted': True,\n 'constant_value': None,\n 'mean': 5.843333333333334,\n 'std': 0.8253012917851409},\n 'feature_02': {'type': 'copulas.univariate.gaussian.GaussianUnivariate',\n 'fitted': True,\n 'constant_value': None,\n 'mean': 3.0540000000000003,\n 'std': 0.4321465800705435},\n 'feature_03': {'type': 'copulas.univariate.gaussian.GaussianUnivariate',\n 'fitted': True,\n 'constant_value': None,\n 'mean': 3.758666666666666,\n 'std': 1.7585291834055212},\n 'feature_04': {'type': 'copulas.univariate.gaussian.GaussianUnivariate',\n 'fitted': True,\n 'constant_value': None,\n 'mean': 1.1986666666666668,\n 'std': 0.7606126185881716}},\n 'type': 'copulas.multivariate.gaussian.GaussianMultivariate',\n 'fitted': True,\n 'distribution': 'copulas.univariate.gaussian.GaussianUnivariate'}\n```\n\nOnce we have all the parameters we can create a new identical **Copula** instance by using the method `from_dict`:\n\n```python\nnew_copula = GaussianMultivariate.from_dict(copula_params)\n```\n\nAt this point we could use this model instance to generate more samples.\n\n```python\nnew_samples = new_copula.sample(num_samples)\n```\n\n# What's next?\n\nFor more details about **Copulas** and all its possibilities and features, please check the\n[documentation site](https://dai-lab.github.io/Copulas/).\n\nThere you can learn more about [how to contribute to Copulas](https://dai-lab.github.io/Copulas/contributing.html)\nin order to help us developing new features or cool ideas.\n\n# Credits\n\nCopulas is an open source project from the Data to AI Lab at MIT which has been built and maintained\nover the years by the following team:\n\n* Manuel Alvarez