KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #ai-agent #developer-tools #claude-code #codex #deepseek-harness #ai-agents #react #mcp #rust

pycop

★ 119 Open GitHub ↗

Python library for multivariate dependence modeling with Copulas

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

[![PyPi version](https://badgen.net/pypi/v/pycop/)](https://pypi.org/project/pycop)
[![Downloads](https://pepy.tech/badge/pycop)](https://pepy.tech/project/pycop)
[![License](https://img.shields.io/pypi/l/pycop)](https://img.shields.io/pypi/l/pycop)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7030034.svg)](https://doi.org/10.5281/zenodo.7030034)

# How to cite

If you use pycop in a scientific publication
```
@article{nicolas2022pycop,
  title={pycop: a Python package for dependence modeling with copulas},
  author={Nicolas, Maxime LD},
  journal={Zenodo Software Package},
  volume={70},
  pages={7030034},
  year={2022}
}
```

# Overview

Pycop is the most complete tool for modeling multivariate dependence with Python. The package provides methods such as estimation, random sample generation, and graphical representation for commonly used copula functions. The package supports the use of mixture models defined as convex combinations of copulas. Other methods based on the empirical copula such as the non-parametric Tail Dependence Coefficient are given.

Some of the features covered:
* Elliptical copulas (Gaussian & Student) and common Archimedean Copulas functions
* Mixture model of multiple copula functions (up to 3 copula functions)
* Multivariate random sample generation
* Empirical copula method
* Parametric and Non-parametric Tail Dependence Coefficient (TDC)

### Available copula function

# Usage

Install pycop using pip
```
pip install pycop
```

# Examples
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://githubtocolab.com/maximenc/pycop/blob/master/examples/example_estim.ipynb)
[Estimations on msci returns](https://github.com/maximenc/pycop/blob/master/examples/example_estim.ipynb)

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://githubtocolab.com/maximenc/pycop/blob/master/examples/example_plot.ipynb)
[Graphical Representations](https://github.com/maximenc/pycop/blob/master/examples/example_plot.ipynb)

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://githubtocolab.com/maximenc/pycop/blob/master/examples/example_simu.ipynb)
[Simulations](https://github.com/maximenc/pycop/blob/master/examples/example_simu.ipynb)

# Table of Contents

- [Graphical Representation](#Graphical-Representation)
  - [3d plot](#3d-plot)
  - [Contour plot](#Contour-plot)
  - [Mixture plot](#Mixture-plot)
- [Simulation](#Simulation)
  - [Gaussian](#Gaussian)
  - [Student](#Student)
  - [Archimedean](#Archimedean)
  - [High dimension](#High-dimension)
  - [Mixture simulation](#Mixture-simulation)
- [Estimation](#Estimation)
  - [Canonical Maximum Likelihood Estimation](#Canonical-Maximum-Likelihood-Estimation)
- [Tail Dependence Coefficient](#Tail-Dependence-Coefficient)
  - [Theoretical TDC](#Theoretical-TDC)
  - [Non-parametric TDC](#Non-parametric-TDC)
  - [Optimal Empirical TDC](#Optimal-Empirical-TDC)

# Graphical Representation

We first create a copula object by specifying the copula familly

```python
from pycop import archimedean
cop = archimedean(family="clayton")
```

Plot the cdf and pdf of the copula.

## 3d plot

```python
cop = archimedean(family="gumbel")

cop.plot_cdf([2], plot_type="3d", Nsplit=100 )
cop.plot_pdf([2], plot_type="3d", Nsplit=100, cmap="cividis" )
```

## Contour plot

plot the contour

```python
cop = archimedean(family="plackett")

cop.plot_cdf([2], plot_type="contour", Nsplit=100 )
cop.plot_pdf([2], plot_type="contour", Nsplit=100, )
```

It is also possible to add specific marginals

```python
cop = archimedean.archimedean(family="clayton")

from scipy.stats import norm

marginals = [
    {
        "distribution": norm, "loc" : 0, "scale" : 0.8,
    },
    {
        "distribution": norm, "loc" : 0, "scale": 0.6,
    }]

cop.plot_mpdf([2], marginals, plot_type="3d",Nsplit=100,
            rstride=1, cstride=1,
            antialiased=True,
            cmap="cividis",
            edgecolor='black',
            linewidth=0.1,
            zorder=1,
            alpha=1)

lvls = [0.02, 0.05, 0.1, 0.2, 0.3]

cop.plot_mpdf([2], marginals, plot_type="contour", Nsplit=100,  levels=lvls)
```

## Mixture plot

mixture of 2 copulas

```python
from pycop import mixture

cop = mixture(["clayton", "gumbel"])
cop.plot_pdf([0.2, 2, 2], plot_type="contour", Nsplit=40, levels=[0.1,0.4,0.8,1.3,1.6] )
# plot with defined marginals
cop.plot_mpdf([0.2, 2, 2], marginals, plot_type="contour", Nsplit=50)
```

 <img src="https://github.com/maximenc/pycop/raw/master/docs/images/plot/2c_mixture_contour_pdf.svg" width="45%" />
 <img src="https://github.com/maximenc/pycop/raw/master/docs/images/plot/2c_mixture_contour_mpdf.svg" width="45%" />

```python

cop = mixture(["clayton", "gaussian", "gumbel"])
cop.plot_pdf([1/3, 1/3, 1/3, 2, 0.5, 4], plot_type="contour", Nsplit=40, levels=[0.1,0.4,0.8,1.3,1.6] )
cop.plot_mpdf([1/3, 1/3, 1/3, 2, 0.5, 2], marginals, plot_type="contour", Nsplit=50)
```

 <img src="https://github.com/maximenc/pycop/raw/master/docs/images/plot/3c_mixture_contour_pdf.svg" width="45%" />
 <img src="https://github.com/maximenc/pycop/raw/master/docs/images/plot/3c_mixture_contour_mpdf.svg" width="45%" />

# Simulation

## Gaussian

```python
from scipy.stats import norm
from pycop import simulation

n = 2 # dimension
m = 1000 # sample size

corrMatrix = np.array([[1, 0.8], [0.8, 1]])
u1, u2 = simulation.simu_gaussian(n, m, corrMatrix)
```
Adding gaussian marginals, (using distribution.ppf from scipy.statsto transform uniform margin to the desired distribution)

```python
u1 = norm.ppf(u1)
u2 = norm.ppf(u2)
```

## Student
```python
u1, u2 = simulation.simu_tstudent(n, m, corrMatrix, nu=1)

```

## Archimedean

List of archimedean cop available

```python
u1, u2 = simulation.simu_archimedean("gumbel", n, m, theta=2)
u1, u2 = 1 - u1, 1 - u2
```

Rotated

```python
u1, u2 = 1 - u1, 1 - u2
```

## High dimension

```python

n = 3       # Dimension
m = 1000    # Sample size

corrMatrix = np.array([[1, 0.9, 0], [0.9, 1, 0], [0, 0, 1]])
u = simulation.simu_gaussian(n, m, corrMatrix)
u = norm.ppf(u)
```

 <img src="https://github.com/maximenc/pycop/raw/master/docs/images/simu/gaussian_simu_n3.svg" width="45%" />

```python
u = simulation.simu_archimedean("clayton", n, m, theta=2)
u = norm.ppf(u)
```

## Mixture simulation

Simulation from a mixture of 2 copulas

```python
n = 3
m = 2000

combination = [
    {"type": "clayton", "weight": 1/3, "theta": 2},
    {"type": "gumbel", "weight": 1/3, "theta": 3}
]

u = simulation.simu_mixture(n, m, combination)
u = norm.ppf(u)
```

 <img src="https://github.com/maximenc/pycop/raw/master/docs/images/simu/2c_mixture_simu.svg" width="45%" />

Simulation from a mixture of 3 copulas
```python
corrMatrix = np.array([[1, 0.8, 0], [0.8, 1, 0], [0, 0, 1]])

combination = [
    {"type": "clayton", "weight": 1/3, "theta": 2},
    {"type": "student", "weight": 1/3, "corrMatrix": corrMatrix, "nu":2},
    {"type": "gumbel", "weight": 1/3, "theta":3}
]

u = simulation.simu_mixture(n, m, combination)
u = norm.ppf(u)
```

# Estimation

Estimation available :
CMLE

## Canonical Maximum Likelihood Estimation (CMLE)

Import a sample with pandas

```python
import pandas as pd
import numpy as np

df = pd.read_csv("data/msci.csv")
df.index = pd.to_datetime(df["Date"], format="%m/%d/%Y")
df = df.drop(["Date"], axis=1)

for col in df.columns.values:
    df[col] = np.log(df[col]) - np.log(df[col].shift(1))

df = df.dropna()
```

```python
from pycop import estimation, archimedean

cop = archimedean("clayton")
data = df[["US","UK"]].T.values
param, cmle = estimation.fit_cmle(cop, data)

```
clayton  estim:  0.8025977727691012

# Tail Dependence coefficient

## Theoretical TDC

```python
from pycop import archimedean

cop = archimedean("clayton")

cop.LTDC(theta=0.5)
cop.UTDC(theta=0.5)
```

For a mixture copula, the copula with lower tail dependence comes first, and the one with upper tail dependence is last.

```python
from pycop import mixture

cop = mixture(["clayton", "gaussian", "gumbel"])

LTDC = cop.LTDC(weight = 0.2, theta = 0.5) 
UTDC = cop.UTDC(weight = 0.2, theta = 1.5) 
```

## Non-parametric TDC
Create an empirical copula object
```python
from pycop import empirical

cop = empirical(df[["US","UK"]].T.values)
```
Compute the non-parametric Upper TDC (UTDC) or the Lower TDC (LTDC) for a given threshold:

```python
cop.LTDC(0.01) # i/n = 1%
cop.UTDC(0.99) # i/n = 99%
```

## Optimal Empirical TDC
Returns the optimal non-parametric TDC based on the heuristic plateau-finding algorithm from Frahm et al (2005) "Estimating the tail-dependence coefficient: properties and pitfalls"

```python
cop.optimal_tdc("upper")
cop.optimal_tdc("lower")
```

pycop

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README