pystra.dependence.joint.CopulaTransformation

Use it: User guide · Worked example · Theory

class CopulaTransformation(joint_distribution, method='rosenblatt', order=None, factorization='cholesky')

Bases: object

Isoprobabilistic map for an explicit JointDistribution.

method=’rosenblatt’ maps to independent standard normals. method=’nataf’ requires an elliptical copula; Student-t produces a spherical t vector with identity shape, not independent coordinates or unit covariance. Its univariate scale is one; covariance is df/(df-2) times identity when df>2. Gaussian Nataf and canonical Gaussian Rosenblatt coincide.

Order is a permutation of indices, supported by Rosenblatt only. Output coordinates remain indexed by original variables: u[order[k]] is the k-th conditional normal innovation. factorization=’svd’ is supported for Nataf. Jacobians are analytic for elliptical copulas, and use central differences of the inverse map in normal space for other copulas.

Parameters:

• joint_distribution (JointDistribution) – Physical joint law to transform.

• method (str) – Rosenblatt produces independent normals; Nataf retains the elliptical copula’s latent family.

• order (Sequence[int] | ndarray | None) – Conditioning permutation for Rosenblatt; outputs retain original positions.

• factorization (str) – Nataf matrix factor. Rosenblatt requires "cholesky".

Methods

jacobian_u_wrt_x	Return du[i] / dx[j] in original joint marginal order.
jacobian_x_wrt_u	Return dx[i] / du[j] in original joint marginal order.
u_to_x	Map one reference point to physical marginal coordinates.
x_to_u	Map one physical point to this transformation's reference space.

x_to_u(x, marg=None)

Map one physical point to this transformation’s reference space.

Parameters:

• x (ArrayLike) – Finite physical point in original marginal order.

• marg (Sequence[Distribution] | None) – Compatibility argument; the joint distribution supplies the marginals.

Returns:

Reference coordinates in original variable positions. The reference law is identified by standard_space.

Return type:

ndarray

u_to_x(u, marg=None)

Map one reference point to physical marginal coordinates.

Parameters:

• u (ArrayLike) – Finite reference point in original variable positions.

• marg (Sequence[Distribution] | None) – Compatibility argument; the joint distribution supplies the marginals.

Returns:

Physical point in original marginal order.

Return type:

ndarray

jacobian_u_wrt_x(u, x, marg=None)

Return du[i] / dx[j] in original joint marginal order.

u and x are corresponding reference and physical vectors of shape (dimension,). The returned matrix has shape (dimension, dimension): reference coordinates are rows and physical variables are columns. marg is unused and is accepted for the shared transformation interface. Rosenblatt innovations stay indexed by original variables even with a noncanonical order.

Return type:

ndarray

jacobian_x_wrt_u(u, x, marg=None)

Return dx[i] / du[j] in original joint marginal order.

Inputs are corresponding reference/physical points of shape (dimension,). The returned (dimension, dimension) matrix has physical variables in rows and reference coordinates in columns. marg is unused. This is the inverse of jacobian_u_wrt_x() at a nonsingular point, for both Nataf and Rosenblatt mappings.

Return type:

ndarray