Transformations

This module contains functionality for isoprobabilistic transformations in UQpy. The module currently contains the following classes:

  • Nataf: Class to perform the Nataf isoprobabilistic transformations.

  • Correlate: Class to induce correlation to a standard normal vector.

  • Decorrelate: Class to remove correlation from a standard normal vector.

Nataf

Nataf is a class for transforming random variables using the Nataf transformation and calculating the correlation distortion. According to the Nataf transformation theory (1, 2), a n-dimensional dependent random vector \(\textbf{X}=[X_1,...,X_n]\) for which the marginal cumulative distributions \(F_i(x_i)\) and the correlattion matrix \(\textbf{C}_x=[\xi_{ij}]\) are known, can be transformed (component-wise) to standard normal random vector \(\textbf{z}=[Z_1,...,Z_n]\) with correlation matrix \(\textbf{C}_z=[\rho_{ij}]\) through the transformation:

\[Z_{i}=\Phi^{-1}(F_i(X_{i}))\]

where \(\Phi(\cdot)\) is the standard normal cumulative distribution function.

This transformation causes a correlation distortion; the correlation coefficient between the standard normal variables \(Z_i\) and \(Z_j\), denoted \(\rho_{ij}\), is not equal to its counterpart in the parameter space (\(\rho_{ij} \neq \xi_{ij}\)).

If the Gaussian correlation \(\rho_{ij}\) is know, the non-Gaussian correlation \(\xi_{ij}\) can be determined through the following integral equation:

\[\xi_{ij} =\dfrac{1}{\sigma_{X_i}\sigma_{X_j}}\int_{-\infty}^{\infty}\int_{-\infty}^{\infty}\left(X_i-\mu_{X_i}\right)\left(X_j-\mu_{X_j}\right)\phi_2(Z_i,Z_j;\rho_{ij})dZ_idZ_j\]

where \(X_i =F_i^{-1}(\Phi(Z_{i}))\) and \(\phi_2(\cdot)\) is the bivariate standard normal probability density function. The integration is directly evaluated using a quadratic two-dimensional Gauss-Legendre integration. However, in the case where the non-Gaussian correlation is known \(\xi_{ij}\), the integral above cannot be inverted to solve for the Gaussian correlation \(\rho_{ij}\). In such case, iterative methods must be employed such as the Iterative Translation Approximation Method (ITAM) 3, used in UQpy.

The Jacobian of the transformation can be also estimated with the Nataf class as:

\[\mathbf{J_{xz}} = \dfrac{\partial\mathbf{x}}{\partial\mathbf{z}} =\left[\dfrac{\phi(Z_i)}{f_i(X_i)}\right]\mathbf{H}.\]

where \(\textbf{H}\) is the lower diagonal matrix resulting from the Cholesky decomposition of the correlation matrix (\(\mathbf{C_Z}\)).

The Nataf class also allows for the inverse of the Nataf transformation, i.e. transforming a vector of standard normal vector \(\textbf{z}=[Z_1,...,Z_n]\) to random variables with prescribed marginal cumulative distributions and correlation matrix \(\textbf{C}_x=[\rho_{ij}]\) according to:

\[X_{i}=F_i^{-1}(\Phi(Z_{i}))\]

Nataf Class Descriptions

class UQpy.Transformations.Nataf(dist_object, samples_x=None, samples_z=None, jacobian=False, corr_z=None, corr_x=None, beta=None, itam_threshold1=None, itam_threshold2=None, itam_max_iter=None, verbose=False)[source]

Transform random variables using the Nataf or Inverse Nataf transformation

Inputs:

  • dist_object ((list of ) Distribution object(s)):

    Probability distribution of each random variable. Must be an object of type DistributionContinuous1D or JointInd.

  • corr_x (ndarray):

    The correlation matrix (\(\mathbf{C_X}\)) of the random vector X .

    Default: The identity matrix.

    If corr_x is specified, the Nataf class invokes the ITAM to compute corr_z.

  • corr_z (ndarray):

    The correlation matrix (\(\mathbf{C_Z}\)) of the standard normal random vector Z .

    Default: The identity matrix.

    If corr_z is specified, the Nataf class computes the correlation distortion integral above to solve for corr_x.

  • itam_threshold1 (float):

    If corr_x is specified, this specifies the threshold value for the error in the ITAM method (see Utilities module) given by:

    \[\epsilon_1 = ||\mathbf{C_X}^{target} - \mathbf{C_X}^{computed}||\]

    Default: 0.001

  • itam_threshold2 (float):

    If corr_x is specified, this specifies the threshold value for the error difference between iterations in the ITAM method (see Utilities module) given by:

    \[\epsilon_1^{i} - \epsilon_1^{i-1}\]

    for iteration \(i\).

    Default: 0.01

  • beta (float):

    A parameter selected to optimize convergence speed and desired accuracy of the ITAM method.

    Default: 1.0

  • samples_x (ndarray):

    Random vector of shape (nsamples, dimension) with prescribed probability distributions.

    If samples_x is provided, the Nataf class transforms them to samples_z.

  • samples_z (ndarray):

    Standard normal random vector of shape (nsamples, dimension)

    If samples_z is provided, the Nataf class transforms them to samples_x.

  • jacobian (‘Boolean’):

    A boolean whether to return the jacobian of the transformation.

    Default: False

  • itam_max_iter (int):

    Maximum number of iterations for the ITAM method.

    Default: 100

  • verbose (Boolean):

    A boolean declaring whether to write text to the terminal.

    Default: False

Attributes:

  • corr_z (ndarray):

    Distorted correlation matrix (\(\mathbf{C_Z}\)) of the standard normal vector Z.

  • corr_x (ndarray):

    Distorted correlation matrix (\(\mathbf{C_X}\)) of the random vector X.

  • H (ndarray):

    The lower triangular matrix resulting from the Cholesky decomposition of the correlation matrix \(\mathbf{C_Z}\).

  • itam_error1 (list)

    List of ITAM errors for each iteration

  • itam_error2 (list)

    List of ITAM difference errors for each iteration

  • samples_x (ndarray):

    Random vector of shape (nsamples, dimension) with prescribed probability distributions.

  • samples_z (ndarray):

    Standard normal random vector of shape (nsamples, dimension)

  • jxz (ndarray):

    The Jacobian of the transformation of shape (dimension, dimension).

  • jzx (ndarray):

    The Jacobian of the transformation of shape (dimension, dimension).

Methods:

static distortion_z2x(dist_object, corr_z, verbose=None)[source]

This is a method to calculate the correlation matrix \(\mathbf{C_x}\) of the random vector \(\mathbf{x}\) given the correlation matrix \(\mathbf{C_z}\) of the standard normal random vector \(\mathbf{z}\).

This method is part of the Nataf class.

Inputs:

  • dist_object ((list of ) Distribution object(s)):

    Probability distribution of each random variable. Must be an object of type DistributionContinuous1D or JointInd.

    dist_object must have an icdf method.

  • corr_z (ndarray):

    The correlation matrix (\(\mathbf{C_z}\)) of the standard normal vector Z .

    Default: The identity matrix.

  • verbose (Boolean):

    A boolean declaring whether to write text to the terminal.

    Default: False

Output/Returns:

  • corr_x (ndarray):

    Distorted correlation matrix (\(\mathbf{C_X}\)) of the random vector X.

static itam(dist_object, corr_x, itam_max_iter=None, beta=None, itam_threshold1=None, itam_threshold2=None, verbose=None)[source]

Calculate the correlation matrix \(\mathbf{C_Z}\) of the standard normal random vector \(\mathbf{Z}\) given the correlation matrix \(\mathbf{C_X}\) of the random vector \(\mathbf{X}\) using the ITAM method 3.

Inputs:

  • dist_object ((list of ) Distribution object(s)):

    Probability distribution of each random variable. Must be an object of type DistributionContinuous1D or JointInd.

    dist_object must have a cdf method.

  • corr_x (ndarray):

    The correlation matrix (\(\mathbf{C_X}\)) of the random vector X .

    Default: The identity matrix.

  • itam_threshold1 (float):

    If corr_x is specified, this specifies the threshold value for the error in the ITAM method (see Utilities module) given by:

    \[\epsilon_1 = ||\mathbf{C_X}^{target} - \mathbf{C_X}^{computed}||\]
  • itam_max_iter (int):

    Maximum number of iterations for the ITAM method.

    Default: 100

  • itam_threshold1 (float):

    A threshold value for the relative difference between the non-Gaussian correlation function and the underlying Gaussian.

    Default: 0.001

  • itam_threshold2 (float):

    If corr_x is specified, this specifies the threshold value for the error difference between iterations in the ITAM method (see Utilities module) given by:

    \[\epsilon_1^{i} - \epsilon_1^{i-1}\]

    for iteration \(i\).

    Default: 0.01

  • beta (float):

    A parameters selected to optimize convergence speed and desired accuracy of the ITAM method (see 2).

    Default: 1.0

  • verbose (Boolean):

    A boolean declaring whether to write text to the terminal.

    Default: False

Output/Returns:

  • corr_z (ndarray):

    Distorted correlation matrix (\(\mathbf{C_Z}\)) of the standard normal vector Z.

  • itam_error1 (list)

    List of ITAM errors for each iteration

  • itam_error2 (list)

    List of ITAM difference errors for each iteration

run(samples_x=None, samples_z=None, jacobian=False)[source]

Execute the Nataf transformation or its inverse.

If samples_x is provided, the run method performs the Nataf transformation. If samples_z is provided, the run method performs the inverse Nataf transformation.

** Input:**

  • samples_x or samples_z (ndarray):

    Random vector X with prescribed probability distributions or standard normal random vector Z of shape``(nsamples, dimension)``.

  • jacobian (Boolean):

    The jacobian of the transformation of shape (dimension, dimension).

    Default: False

rvs(nsamples)[source]

Generate realizations from the joint pdf of the random vector X.

Inputs:

  • nsamples (int):

    Number of samples to generate.

Outputs:

  • samples_x (ndarray):

    Random vector in the parameter space of shape (nsamples, dimension).

Correlate

Correlate is a class to induce correlation to an uncorrelated standard normal vector \(\textbf{u}=[U_1,...,U_n]\), given the correlation matrix \(\textbf{C}_z=[\rho_{ij}]\). The correlated standard normal vector \(\textbf{z}=[Z_1,...,Z_n]\) can be calculated as:

\[\mathbf{z}^\intercal = \mathbf{H}\mathbf{u}^\intercal\]

where \(\mathbf{H}\) is the lower triangular matrix resulting from the Cholesky decomposition of the correlation matrix, i.e. \(\mathbf{C_z}=\mathbf{H}\mathbf{H}^\intercal\).

Correlate Class Descriptions

class UQpy.Transformations.Correlate(samples_u, corr_z)[source]

A class to induce correlation to standard normal random variables.

Inputs:

  • samples_u (ndarray):

    Uncorrelated standard normal vector of shape (nsamples, dimension).

  • corr_z (ndarray):

    The correlation matrix (\(\mathbf{C_Z}\)) of the standard normal random vector Z .

Attributes:

  • samples_z (ndarray):

    Correlated standard normal vector of shape (nsamples, dimension).

  • H (ndarray):

    The lower diagonal matrix resulting from the Cholesky decomposition of the correlation matrix (\(\mathbf{C_Z}\)).

Decorrelate

Decorrelate is a class to remove correlation from an correlated standard normal vector \(\textbf{z}=[Z_1,...,Z_n]\) with correlation matrix \(\textbf{C}_z=[\rho_{ij}]\). The uncorrelated standard normal vector \(\textbf{u}=[U_1,...,U_n]\) can be calculated as:

\[\textbf{u}^\intercal = \mathbf{H}^{-1} \mathbf{z}^\intercal\]

Decorrelate Class Descriptions

class UQpy.Transformations.Decorrelate(samples_z, corr_z)[source]

A class to remove correlation from correlated standard normal random variables.

Inputs:

  • samples_z (ndarray):

    Correlated standard normal vector of shape (nsamples, dimension).

  • corr_z (ndarray):

    The correlation matrix (\(\mathbf{C_Z}\)) of the standard normal random vector Z .

Attributes:

  • samples_u (ndarray):

    Uncorrelated standard normal vector of shape (nsamples, dimension).

  • H (ndarray):

    The lower diagonal matrix resulting from the Cholesky decomposition of the correlation matrix (\(\mathbf{C_Z}\)).

References:

1

A. Nataf, Determination des distributions dont les marges sont donnees, C. R. Acad. Sci. vol. 225, pp. 42-43, Paris, 1962.

2(1,2)

R. Lebrun and A. Dutfoy, An innovating analysis of the Nataf transformation from the copula viewpoint, Prob. Eng. Mech., vol. 24, pp. 312-320, 2009.

3(1,2)

Kim, H. and Shields, M.D. (2015). “Modeling strongly non-Gaussian non-stationary stochastic processes using the Iterative Translation Approximation Method and Karhunen-Loeve Expansion,” Computers and Structures. 161: 31-42.