Distributions¶
This module contains functionality for all probability distributions supported in UQpy
.
The Distributions
module is used to define probability distribution objects. These objects possess various
methods that allow the user to: compute the probability density/mass function pdf/pmf
, the cumulative
distribution function cdf
, the logarithm of the pdf/pmf log_pdf/log_pmf
, return the moments moments
, draw
independent samples rvs
and compute the maximum likelihood estimate of the parameters from data mle
.
The module contains the following parent classes - probability distributions are defined via sub-classing those parent classes:
Distribution
: Parent class to all distributions.DistributionContinuous1D
: Parent class to 1-dimensional continuous probability distributions.DistributionDiscrete1D
: Parent class to 1-dimensional discrete probability distributions.DistributionND
: Parent class to multivariate probability distributions.Copula
: Parent class to copula to model dependency between marginals.
Note that the various classes of the Distributions
module are written to be consistent with distribuitons in the
scipy.stats
package 1, to the extent possible while maintaining an extensible, object oriented architecture that is
convenient for operating with the other UQpy
modules. All existing distributions and their methods in UQpy
are restructured from the scipy.stats
package.
Parent Distribution Class¶
-
class
UQpy.Distributions.
Distribution
(order_params=None, **kwargs)[source]¶ A parent class to all
Distribution
classes.All distributions possess a number of methods to perform basic probabilistic operations. For most of the predefined distributions in
UQpy
these methods are inherited from thescipy.stats
package. These include standard operations such as computing probability density/mass functions, cumulative distribution functions and their inverse, drawing random samples, computing moments and parameter fitting. However, for user-defined distributions, any desired method can be constructed into the child class structure.For bookkeeping purposes, all
Distribution
objects possessesget_params
andupdate_params
methods. These are described in more detail below.Any
Distribution
further inherits from one of the following classes:DistributionContinuous1D
: Parent class to 1-dimensional continuous probability distributions.DistributionDiscrete1D
: Parent class to 1-dimensional discrete probability distributions.DistributionND
: Parent class to multivariate probability distributions.
Attributes:
- order_params (list):
Ordered list of parameter names, useful when parameter values are stored in vectors and must be passed to the
update_params
method.
- params (dict):
Parameters of the distribution. Note: this attribute is not defined for certain
Distribution
objects such as those of typeJointInd
orJointCopula
. The user is advised to use theget_params
method to access the parameters.
Methods:
- cdf (x)
Evaluate the cumulative distribution function.
Input:
- x (ndarray):
Point(s) at which to evaluate the cdf, must be of shape (npoints, dimension).
Output/Returns:
- (ndarray):
Evaluated cdf values, ndarray of shape (npoints,).
- pdf (x)
Evaluate the probability density function of a continuous or multivariate mixed continuous-discrete distribution.
Input:
- x (ndarray):
Point(s) at which to evaluate the pdf, must be of shape (npoints, dimension).
Output/Returns:
- (ndarray):
Evaluated pdf values, ndarray of shape (npoints,).
- pmf (x)
Evaluate the probability mass function of a discrete distribution.
Input:
- x (ndarray):
Point(s) at which to evaluate the pmf, must be of shape (npoints, dimension).
Output/Returns:
- (ndarray):
Evaluated pmf values, ndarray of shape (npoints,).
- log_pdf (x)
Evaluate the logarithm of the probability density function of a continuous or multivariate mixed continuous-discrete distribution.
Input:
- x (ndarray):
Point(s) at which to evaluate the log_pdf, must be of shape (npoints, dimension).
Output/Returns:
- (ndarray):
Evaluated log-pdf values, ndarray of shape (npoints,).
- log_pmf (x)
Evaluate the logarithm of the probability mass function of a discrete distribution.
Input:
- x (ndarray):
Point(s) at which to evaluate the log_pmf, must be of shape (npoints, dimension).
Output/Returns:
- (ndarray):
Evaluated log-pmf values, ndarray of shape (npoints,).
- icdf (x)
Evaluate the inverse cumulative distribution function for univariate distributions.
Input:
- x (ndarray):
Point(s) at which to evaluate the icdf, must be of shape (npoints, dimension).
Output/Returns:
- (ndarray):
Evaluated icdf values, ndarray of shape (npoints,).
- rvs (nsamples=1, random_state=None)
Sample independent identically distributed (iid) realizations.
Inputs:
- nsamples (int):
Number of iid samples to be drawn. Default is 1.
- random_state (None or int or
numpy.random.RandomState
object): Random seed used to initialize the pseudo-random number generator. Default is None.
If an integer is provided, this sets the seed for an object of
numpy.random.RandomState
. Otherwise, the object itself can be passed directly.
- random_state (None or int or
Output/Returns:
- (ndarray):
Generated iid samples, ndarray of shape (npoints, dimension).
- moments (moments2return=’mvsk’)
Computes the mean ‘number_of_variables’, variance/covariance (‘v’), skewness (‘s’) and/or kurtosis (‘k’) of the distribution.
For a univariate distribution, mean, variance, skewness and kurtosis are returned. For a multivariate distribution, the mean vector, covariance and vectors of marginal skewness and marginal kurtosis are returned.
Inputs:
- moments2return (str):
Indicates which moments are to be returned (mean, variance, skewness and/or kurtosis). Default is ‘mvsk’.
Output/Returns:
- (tuple):
mean
: mean,var
: variance/covariance,skew
: skewness,kurt
: kurtosis.
- fit (data)
Compute the maximum-likelihood parameters from iid data.
Computes the mle analytically if possible. For univariate continuous distributions, it leverages the fit method of the scipy.stats package.
Input:
- data (ndarray):
Data array, must be of shape (npoints, dimension).
Output/Returns:
- (dict):
Maximum-likelihood parameter estimates.
-
get_params
()[source]¶ Return the parameters of a
Distributions
object.To update the parameters of a
JointInd
or aJointCopula
distribution, each parameter is assigned a unique string identifier as key_index - where key is the parameter name and index the index of the marginal (e.g., location parameter of the 2nd marginal is identified as loc_1).Output/Returns:
- (dict):
Parameters of the distribution.
-
update_params
(**kwargs)[source]¶ Update the parameters of a
Distributions
object.To update the parameters of a
JointInd
or aJointCopula
distribution, each parameter is assigned a unique string identifier as key_index - where key is the parameter name and index the index of the marginal (e.g., location parameter of the 2nd marginal is identified as loc_1).Input:
- keyword arguments:
Parameters to be updated, designated by their respective keywords.
1D Continuous Distributions¶
In UQpy
, univariate continuous distributions inherit from the DistributionContinuous1D
class:
-
class
UQpy.Distributions.
DistributionContinuous1D
(**kwargs)[source]¶ Parent class for univariate continuous probability distributions.
List of 1D Continuous Distributions¶
The following is a list of all 1D continuous distributions currently available in UQpy
.
-
class
UQpy.Distributions.
Beta
(a, b, loc=0.0, scale=1.0)[source]¶ Beta distribution having probability density function
\[f(x|a,b) = \dfrac{\Gamma(a+b)x^{a-1}(1-x)^{b-1}}{\Gamma(a)\Gamma(b)}\]for \(0\le x\ge 0\), \(a>0, b>0\). Here \(\Gamma(a)\) refers to the Gamma function.
In this standard form (loc=0, scale=1), the distribution is defined over the interval (0, 1). Use loc and scale to shift the distribution to interval (loc, loc + scale). Specifically, this is equivalent to computing \(f(y|a,b)\) where \(y=(x-loc)/scale\).
Inputs:
- a (float):
first shape parameter
- b (float):
second shape parameter
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
Beta
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
-
class
UQpy.Distributions.
Cauchy
(loc=0.0, scale=1.0)[source]¶ Cauchy distribution having probability density function
\[f(x) = \dfrac{1}{\pi(1+x^2)}\]In this standard form (loc=0, scale=1). Use loc and scale to shift and scale the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=(x-loc)/scale\).
Inputs:
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
Cauchy
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
-
class
UQpy.Distributions.
ChiSquare
(df, loc=0.0, scale=1)[source]¶ Chi-square distribution having probability density:
\[f(x|k) = \dfrac{1}{2^{k/2}\Gamma(k/2)}x^{k/2-1}\exp{(-x/2)}\]for \(x\ge 0\), \(k>0\). Here \(\Gamma(\cdot)\) refers to the Gamma function.
In this standard form (loc=0, scale=1). Use loc and scale to shift and scale the distribution. Specifically, this is equivalent to computing \(f(y|k)\) where \(y=(x-loc)/scale\).
Inputs:
- df (float):
shape parameter (degrees of freedom) (given by k in the equation above)
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
ChiSquare
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
Exponential
(loc=0.0, scale=1.0)[source]¶ Exponential distribution having probability density function:
\[f(x) = \exp(-x)\]In this standard form (loc=0, scale=1). Use loc and scale to shift and scale the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=(x-loc)/scale\).
A common parameterization for Exponential is in terms of the rate parameter \(\lambda\), which corresponds to using \(scale = 1 / \lambda\).
Inputs:
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
Exponential
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
Gamma
(a, loc=0.0, scale=1.0)[source]¶ Gamma distribution having probability density function:
\[f(x|a) = \dfrac{x^{a-1}\exp(-x)}{\Gamma(a)}\]for \(x\ge 0\), \(a>0\). Here \(\Gamma(a)\) refers to the Gamma function.
In this standard form (loc=0, scale=1). Use loc and scale to shift and scale the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=(x-loc)/scale\).
Inputs:
- a (float):
shape parameter
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
Gamma
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
GenExtreme
(c, loc=0.0, scale=1.0)[source]¶ Generalized Extreme Value distribution having probability density function:
\[`f(x|c) = \exp(-(1-cx)^{1/c})(1-cx)^{1/c-1}`\]for \(x\le 1/c, c>0\).
For c=0
\[f(x) = \exp(\exp(-x))\exp(-x)\]In this standard form (loc=0, scale=1). Use loc and scale to shift and scale the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=(x-loc)/scale\).
Inputs:
- c (float):
shape parameter
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
GenExtreme
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
InvGauss
(mu, loc=0.0, scale=1.0)[source]¶ Inverse Gaussian distribution having probability density function
\[f(x|\mu) = \dfrac{1}{2\pi x^3}\exp{(-\dfrac{(x\mu)^2}{2x\mu^2})}\]for \(x>0\).
cdf
method returns NaN for \(\mu<0.0028\).Inputs:
- mu (float):
shape parameter, \(\mu\)
- loc (float):
location parameter
- scale (float):
scale parameter
In this standard form (loc=0, scale=1). Use loc and scale to shift and scale the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=(x-loc)/scale\).
The following methods are available for
InvGauss
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
Laplace
(loc=0, scale=1)[source]¶ Laplace distribution having probability density function
\[f(x) = \dfrac{1}{2}\exp{-|x|}\]In this standard form (loc=0, scale=1). Use loc and scale to shift and scale the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=(x-loc)/scale\).
Inputs:
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
Laplace
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
Levy
(loc=0, scale=1)[source]¶ Levy distribution having probability density function
\[f(x) = \dfrac{1}{\sqrt{2\pi x^3}}\exp(-\dfrac{1}{2x})\]for \(x\ge 0\).
In this standard form (loc=0, scale=1). Use loc and scale to shift and scale the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=(x-loc)/scale\).
Inputs:
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
Levy
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
Logistic
(loc=0, scale=1)[source]¶ Logistic distribution having probability density function
\[f(x) = \dfrac{\exp(-x)}{(1+\exp(-x))^2}\]In this standard form (loc=0, scale=1). Use loc and scale to shift and scale the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=(x-loc)/scale\).
Inputs:
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
Logistic
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
Lognormal
(s, loc=0.0, scale=1.0)[source]¶ Lognormal distribution having probability density function
\[f(x|s) = \dfrac{1}{sx\sqrt{2\pi}}\exp(-\dfrac{\log^2(x)}{2s^2})\]for \(x>0, s>0\).
A common parametrization for a lognormal random variable Y is in terms of the mean, mu, and standard deviation, sigma, of the gaussian random variable X such that exp(X) = Y. This parametrization corresponds to setting s = sigma and scale = exp(mu).
Inputs:
- s (float):
shape parameter
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
Lognormal
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
Maxwell
(loc=0, scale=1)[source]¶ Maxwell-Boltzmann distribution having probability density function
\[f(x) = \sqrt{2/\pi}x^2\exp(-x^2/2)\]for \(x\ge0\).
In this standard form (loc=0, scale=1). Use loc and scale to shift and scale the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=(x-loc)/scale\).
Inputs:
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
Maxwell
: *cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
Normal
(loc=0.0, scale=1.0)[source]¶ Normal distribution having probability density function
\[f(x) = \dfrac{\exp(-x^2/2)}{\sqrt{2\pi}}\]In this standard form (loc=0, scale=1). Use loc and scale to shift and scale the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=(x-loc)/scale\).
Inputs:
- loc (float):
mean
- scale (float):
standard deviation
The following methods are available for
Normal
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
Pareto
(b, loc=0.0, scale=1.0)[source]¶ Pareto distribution having probability density function
\[f(x|b) = \dfrac{b}{x^{b+1}}\]for \(x\ge 1, b>0\).
In this standard form (loc=0, scale=1). Use loc and scale to shift and scale the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=(x-loc)/scale\).
Inputs:
- b (float):
shape parameter
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
Pareto
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
Rayleigh
(loc=0, scale=1)[source]¶ Rayleigh distribution having probability density function
\[f(x) = x\exp(-x^2/2)\]for \(x\ge 0\).
In this standard form (loc=0, scale=1). Use loc and scale to shift and scale the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=(x-loc)/scale\).
Inputs:
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
Rayleigh
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
TruncNorm
(a, b, loc=0, scale=1.0)[source]¶ Truncated normal distribution
The standard form of this distribution (i.e, loc=0., scale=1) is a standard normal truncated to the range [a, b]. Note that a and b are defined over the domain of the standard normal.
Inputs:
- a (float):
shape parameter
- b (float):
shape parameter
- loc (float):
location parameter
- scale (float):
scale parameter
The following methods are available for
TruncNorm
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
-
class
UQpy.Distributions.
Uniform
(loc=0.0, scale=1.0)[source]¶ Uniform distribution having probability density function
\[f(x|a, b) = \dfrac{1}{b-a}\]where \(a=loc\) and \(b=loc+scale\)
Inputs:
- loc (float):
lower bound
- scale (float):
range
The following methods are available for
Uniform
:cdf
,pdf
,log_pdf
,icdf
,rvs
,moments
,fit
.
1D Discrete Distributions¶
In UQpy
, univariate discrete distributions inherit from the DistributionDiscrete1D
class:
-
class
UQpy.Distributions.
DistributionDiscrete1D
(**kwargs)[source]¶ Parent class for univariate discrete distributions.
List of 1D Discrete Distributions¶
The following is a list of all 1D continuous distributions currently available in UQpy
.
-
class
UQpy.Distributions.
Binomial
(n, p, loc=0.0)[source]¶ Binomial distribution having probability mass function:
\[f(x) = {number_of_dimensions \choose x} p^x(1-p)^{number_of_dimensions-x}\]for \(x\inumber_of_dimensions\{0, 1, 2, ..., number_of_dimensions\}\).
In this standard form (loc=0). Use loc to shift the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=x-loc\).
Inputs:
- number_of_dimensions (int):
number of trials, integer >= 0
- p (float):
success probability for each trial, real number in [0, 1]
- loc (float):
location parameter
The following methods are available for
Binomial
:cdf
,pmf
,log_pmf
,icdf
,rvs, moments
.
-
class
UQpy.Distributions.
Poisson
(mu, loc=0.0)[source]¶ Poisson distribution having probability mass function:
\[f(x) = \exp{(-\mu)}\dfrac{\mu^k}{k!}\]for \(x\ge 0\).
In this standard form (loc=0). Use loc to shift the distribution. Specifically, this is equivalent to computing \(f(y)\) where \(y=x-loc\).
Inputs:
- mu (float):
shape parameter
- loc (float):
location parameter
The following methods are available for
Poisson
:cdf
,pmf
,log_pmf
,icdf
,rvs
,moments
.
Multivariate Distributions¶
In UQpy
, multivariate distributions inherit from the DistributionND
class:
-
class
UQpy.Distributions.
DistributionND
(**kwargs)[source]¶ Parent class for multivariate probability distributions.
UQpy
has some inbuilt multivariate distributions, which are directly child classes of DistributionND
. Additionally, joint distributions can be built from their marginals through the use of the JointInd
and JointCopula
classes described below.
List of Multivariate Distributions¶
-
class
UQpy.Distributions.
Multinomial
(n, p)[source]¶ Multinomial distribution having probability mass function
\[f(x) = \dfrac{number_of_dimensions!}{x_1!\dots x_k!}p_1^{x_1}\dots p_k^{x_k}\]for \(x=\{x_1,\dots,x_k\}\) where each \(x_i\) is a non-negative integer and \(\sum_i x_i = number_of_dimensions\).
Inputs:
- number_of_dimensions (int):
number of trials
- p (array_like):
probability of a trial falling into each category; should sum to 1
The following methods are available for
Multinomial
:pmf
,log_pmf
,rvs
,moments
.
-
class
UQpy.Distributions.
MVNormal
(mean, cov=1.0)[source]¶ Multivariate normal distribution having probability density function
\[f(x) = \dfrac{1}{\sqrt{(2\pi)^k\det\Sigma}}\exp{-\dfrac{1}{2}(x-\mu)^T\Sigma^{-1}(x-\mu)}\]where \(\mu\) is the mean vector, \(\Sigma\) is the covariance matrix, and \(k\) is the dimension of x.
Inputs:
- mean (ndarray):
mean vector, ndarray of shape (dimension, )
- cov (float or ndarray):
covariance, float or ndarray of shape (dimension, ) or (dimension, dimension). Default is 1.
The following methods are available for
MVNormal
:pdf
,log_pdf
,rvs
,fit
,moments
.
Joint from independent marginals¶
-
class
UQpy.Distributions.
JointInd
(marginals)[source]¶ Define a joint distribution from its independent marginals.
JointInd
is a child class ofDistributionND
.Inputs:
- marginals (list):
list of
DistributionContinuous1D
orDistributionDiscrete1D
objects that define the marginals.
Such a multivariate distribution possesses the following methods, on condition that all its univariate marginals also possess them:
pdf
,log_pdf
,cdf
,rvs
,fit
,moments
.
The parameters of the distribution are only stored as attributes of the marginal objects. However, the get_params and update_params method can still be used for the joint. Note that, for this purpose, each parameter of the joint is assigned a unique string identifier as key_index - where key is the parameter name and index the index of the marginal (e.g., location parameter of the 2nd marginal is identified as loc_1).
Joint from marginals and copula¶
-
class
UQpy.Distributions.
JointCopula
(marginals, copula)[source]¶ Define a joint distribution from a list of marginals and a copula to introduce dependency.
JointCopula
is a child class ofDistributionND
.Inputs:
- marginals (list):
list of
DistributionContinuous1D
orDistributionDiscrete1D
objects that define the marginals
- copula (object):
object of class
Copula
A
JointCopula
distribution may possess acdf
,pdf
andlog_pdf
methods if the copula allows for it (i.e., if the copula possesses the necessaryevaluate_cdf
andevaluate_pdf
methods).The parameters of the distribution are only stored as attributes of the marginals/copula objects. However, the
get_params
andupdate_params
methods can still be used for the joint. Note that each parameter of the joint is assigned a unique string identifier as key_index - where key is the parameter name and index the index of the marginal (e.g., location parameter of the 2nd marginal is identified as loc_1); and key_c for copula parameters.
Copula¶
-
class
UQpy.Distributions.
Copula
(order_params=None, **kwargs)[source]¶ Define a copula for a multivariate distribution whose dependence structure is defined with a copula.
This class is used in support of the
JointCopula
distribution class.Attributes:
- params (dict):
Parameters of the copula.
- order_params (list):
List of parameter names
Methods:
- evaluate_cdf (unif)
Compute the copula cdf \(C(u_1, u_2, ..., u_d)\) for a d-variate uniform distribution.
For a generic multivariate distribution with marginal cdfs \(F_1, ..., F_d\) the joint cdf is computed as:
\(F(x_1, ..., x_d) = C(u_1, u_2, ..., u_d)\)
where \(u_i = F_i(x_i)\) is uniformly distributed. This computation is performed in the
JointCopula.cdf
method.Input:
- unif (ndarray):
Points (uniformly distributed) at which to evaluate the copula cdf, must be of shape (npoints, dimension).
Output/Returns:
- (tuple):
Values of the cdf, ndarray of shape (npoints, ).
- evaluate_pdf (unif)
Compute the copula pdf \(c(u_1, u_2, ..., u_d)\) for a d-variate uniform distribution.
For a generic multivariate distribution with marginals pdfs \(f_1, ..., f_d\) and marginals cdfs \(F_1, ..., F_d\), the joint pdf is computed as:
\(f(x_1, ..., x_d) = c(u_1, u_2, ..., u_d) f_1(x_1) ... f_d(x_d)\)
where \(u_i = F_i(x_i)\) is uniformly distributed. This computation is performed in the
JointCopula.pdf
method.Input:
- unif (ndarray):
Points (uniformly distributed) at which to evaluate the copula pdf, must be of shape (npoints, dimension).
Output/Returns:
- (tuple):
Values of the copula pdf term, ndarray of shape (npoints, ).
-
check_marginals
(marginals)[source]¶ Perform some checks on the marginals, raise errors if necessary.
As an example, Archimedian copula are only defined for bi-variate continuous distributions, thus this method checks that marginals is of length 2 and continuous, and raise an error if that is not the case.
Input:
- unif (ndarray):
Points (uniformly distributed) at which to evaluate the copula pdf, must be of shape
(npoints, dimension)
.
Output/Returns:
No outputs, this code raises errors if necessary.
List of Copulas¶
-
class
UQpy.Distributions.
Gumbel
(theta)[source]¶ Gumbel copula having cumulative distribution function
\[F(u_1, u_2) = \exp(-(-\log(u_1))^{\Theta} + (-\log(u_2))^{\Theta})^{1/{\Theta}}\]where \(u_1 = F_1(x_1), u_2 = F_2(x_2)\) are uniformly distributed on the interval [0, 1].
Input:
- theta (float):
Parameter of the Gumbel copula, real number in \([1, +\infty)\).
This copula possesses the following methods:
evaluate_cdf
,evaluate_pdf
andcheck_copula
(
check_copula
checks that marginals consist of solely 2 continuous univariate distributions).
-
class
UQpy.Distributions.
Clayton
(theta)[source]¶ Clayton copula having cumulative distribution function
\[F(u_1, u_2) = \max(u_1^{-\Theta} + u_2^{-\Theta} - 1, 0)^{-1/{\Theta}}\]where \(u_1 = F_1(x_1), u_2 = F_2(x_2)\) are uniformly distributed on the interval [0, 1].
Input:
- theta (float):
Parameter of the copula, real number in [-1, +oo){0}.
This copula possesses the following methods:
evaluate_cdf
andcheck_copula
(
check_copula
checks that marginals consist of solely 2 continuous univariate distributions).
-
class
UQpy.Distributions.
Frank
(theta)[source]¶ Frank copula having cumulative distribution function
\(F(u_1, u_2) = -\dfrac{1}{\Theta} \log(1+\dfrac{(\exp(-\Theta u_1)-1)(\exp(-\Theta u_2)-1)}{\exp(-\Theta)-1})\)
where \(u_1 = F_1(x_1), u_2 = F_2(x_2)\) are uniformly distributed on the interval [0, 1].
Input:
- theta (float):
Parameter of the copula, real number in correlation_function{0}.
This copula possesses the following methods:
evaluate_cdf
andcheck_copula
(
check_copula
checks that marginals consist of solely 2 continuous univariate distributions).
User-defined Distributions and Copulas¶
Defining custom distributions in UQpy
can be done by sub-classing the appropriate parent class. The subclasses must possess the desired methods, per the parent Distribution
class.
Custom copulas can be similarly defined by subclassing the Copula
class and defining the appropriate methods.