INPUT MODULE: MARGINALS AND VINE COPULA¶

This example showcases how to define a probabilistic input model in three dimension or higher with a vine copula dependence structure.

Package imports¶

In [1]:
from uqpylab import sessions
import numpy as np

Parameters¶

Start a remote UQCloud session¶

In [2]:
# Start the session
mySession = sessions.cloud()
# (Optional) Get a convenient handle to the command line interface
uq = mySession.cli
# Reset the session
mySession.reset()

 uqpylab.sessions :: INFO     :: A new session (872662f01472423a8680db0dac8fac7c) started.
 uqpylab.sessions :: INFO     :: Reset successful.

Probabilistic input model¶

The probabilistic input model consists of three variables:

  • $X_1 \sim \mathcal{N}(0,1)$
  • $X_2 \sim \mathcal{B}(1,3)$
  • $X_3 \sim \mathcal{G}(1,3)$

Specify the marginals of these variables:

In [3]:
InputOpts = {
    'Marginals': [
        {
            'Type': 'Gaussian',
            'Parameters': [0,1],
        },
        {
            'Type': 'Beta',
            'Parameters': [1,3]
        },
        {
            'Type': 'Gumbel',
            'Parameters': [1,3]
        }
    ]
}

The variables are coupled by a Canonical Vine (CVine). A vine in dimension $M$ requires the specification of $M \cdot (M-1)/2$ pair copulas (here, there are three pair copulas):

In [4]:
InputOpts['Copula'] = {
    'Type': 'CVine',
    'Families': ['Gumbel', 'Gaussian', 'Frank'],
    'Parameters': [1.5, -.4, .3],
    'Rotations': [180, 0, 270],
    'Structure': [1, 2, 3]
}

Create an INPUT object based on the specified marginals and copula:

In [5]:
myInput = uq.createInput(InputOpts)

Print and visualize the output¶

Print a summary of the input model:

In [6]:
uq.print(myInput)

==============================================================
Input object name: Input 1
Dimension(M): 3

Marginals:

Index | Name | Type     |  Parameters             | Moments              
--------------------------------------------------------------------------
1     | X1   | Gaussian |  0.000e+00, 1.000e+00   | 0.000e+00, 1.000e+00
2     | X2   | Beta     |  1.000e+00, 3.000e+00   | 2.500e-01, 1.936e-01
3     | X3   | Gumbel   |  1.000e+00, 3.000e+00   | 2.732e+00, 3.848e+00


Copula:

Type: CVine
Dimension: 3
Variables coupled: [1 2 3]
Structure: [1;2;3]
Truncation: 3 (none)
Pair copulas:
     Index | Pair Copula | Family       | Rot | Parameters
       1   | C_1,2       | Gumbel       | 180 | 1.5000e+00
       2   | C_1,3       | Gaussian     |   0 | -4.0000e-01
       3   | C_2,3|1     | Frank        | 270 | 3.0000e-01

==============================================================

Display a visualization of the input model:

In [7]:
fig = uq.display(myInput)
fig.show()

How to assign the pair copulas in the vine?¶

The pair copulas composing the vine can be a difficult beast to tame.

Some (the first $M-1$ ones, for an input of dimension $M$) are unconditional pair copulas, the rest are conditional on other variables. But which variables do they couple? It all depends on the vine type and structure!

If unsure, call the function uq_CopulaSummary: when fed with a vine copula type and a vine copula structure, it prints a report of the meaning of the pair copulas of that vine:

In [8]:
print(uq.CopulaSummary('CVine',[1,2,3]))

Type: CVine
Dimension: 3
Structure: [1;2;3]

Pair copulas:
 Index | Pair Copula 
==================================
   1   | C_1,2        
   2   | C_1,3        
   3   | C_2,3|1

The same function, when fed with an actual copula, prints the same copula information as provided by uq_print:

In [9]:
print(uq.CopulaSummary(myInput['Copula']))

Type: CVine
Dimension: 3
Variables coupled: [1;2;3]
Structure: [1;2;3]
Truncation: 3 (none)
Pair copulas:
     Index | Pair Copula | Family       | Rot | Parameters
       1   | C_1,2       | Gumbel       | 180 | 1.5000e+00
       2   | C_1,3       | Gaussian     |   0 | -4.0000e-01
       3   | C_2,3|1     | Frank        | 270 | 3.0000e-01

Furthermore, a visual representation of the pair copulas composition in a vine can be obtained using the uq_drawVineCopula function:

In [10]:
uq.display(myInput, show_vine=True)

Vine truncation¶

Sometimes, due to lack of information, specifying conditional pair copulas in a vine may be hard or impossible. In these case, it may be reasonable to assume conditional independence from a certain conditioning order. This is called truncation of a vine.

For instance, truncating a vine at the 1st level means that only the unconditional pair copulas are retained, and the rest are set to the independence copula:

In [11]:
InputOpts['Copula']['Truncation'] = 1

Create an INPUT object based on the truncated vine copula:

In [12]:
myInput_Truncated = uq.createInput(InputOpts)

Print a summary of the input with truncated vine:

In [13]:
uq.print(myInput_Truncated)

==============================================================
Input object name: Input 2
Dimension(M): 3

Marginals:

Index | Name | Type     |  Parameters             | Moments              
--------------------------------------------------------------------------
1     | X1   | Gaussian |  0.000e+00, 1.000e+00   | 0.000e+00, 1.000e+00
2     | X2   | Beta     |  1.000e+00, 3.000e+00   | 2.500e-01, 1.936e-01
3     | X3   | Gumbel   |  1.000e+00, 3.000e+00   | 2.732e+00, 3.848e+00


Copula:

Type: CVine
Dimension: 3
Variables coupled: [1 2 3]
Structure: [1;2;3]
Truncation: 1
Pair copulas:
     Index | Pair Copula | Family       | Rot | Parameters
       1   | C_1,2       | Gumbel       | 180 | 1.5000e+00
       2   | C_1,3       | Gaussian     |   0 | -4.0000e-01
       3   | C_2,3|1     | Independent  |   0 | 

==============================================================

Display a visualization of the input model with truncated vine:

In [14]:
fig = uq.display(myInput_Truncated)
fig.show()

Terminate the remote UQCloud session¶

In [15]:
mySession.quit()

 uqpylab.sessions :: INFO     :: Session 872662f01472423a8680db0dac8fac7c terminated.
Out[15]:
True