copulas 0.12.4.dev3__py3-none-any.whl

copulas/bivariate/clayton.py

@@ -0,0 +1,163 @@
+"""Clayton module."""
+
+import numpy as np
+
+from copulas.bivariate.base import Bivariate, CopulaTypes
+from copulas.bivariate.utils import split_matrix
+
+
+class Clayton(Bivariate):
+    """Class for clayton copula model."""
+
+    copula_type = CopulaTypes.CLAYTON
+    theta_interval = [0, float('inf')]
+    invalid_thetas = []
+
+    def generator(self, t):
+        r"""Compute the generator function for Clayton copula family.
+
+        The generator is a function
+        :math:`\psi: [0,1]\times\Theta \rightarrow [0, \infty)`  # noqa: JS101
+
+        that given an Archimedian copula fulfills:
+        .. math:: C(u,v) = \psi^{-1}(\psi(u) + \psi(v))
+
+        Args:
+            t (numpy.ndarray)
+
+        Returns:
+            numpy.ndarray
+
+        """
+        self.check_fit()
+
+        return (1.0 / self.theta) * (np.power(t, -self.theta) - 1)
+
+    def probability_density(self, X):
+        r"""Compute probability density function for given copula family.
+
+        The probability density(PDF) for the Clayton family of copulas correspond to the formula:
+
+        .. math:: c(U,V) = \frac{\partial^2}{\partial v \partial u}C(u,v) =
+            (\theta + 1)(uv)^{-\theta-1}(u^{-\theta} +
+            v^{-\theta} - 1)^{-\frac{2\theta + 1}{\theta}}
+
+        Args:
+            X (numpy.ndarray)
+
+        Returns:
+            numpy.ndarray: Probability density for the input values.
+
+        """
+        self.check_fit()
+
+        U, V = split_matrix(X)
+
+        a = (self.theta + 1) * np.power(U * V, -(self.theta + 1))
+        b = np.power(U, -self.theta) + np.power(V, -self.theta) - 1
+        c = -(2 * self.theta + 1) / self.theta
+        return a * np.power(b, c)
+
+    def cumulative_distribution(self, X):
+        """Compute the cumulative distribution function for the clayton copula.
+
+        The cumulative density(cdf), or distribution function for the Clayton family of copulas
+        correspond to the formula:
+
+        .. math:: C(u,v) = (u^{-θ} + v^{-θ} - 1)^{-1/θ}
+
+        Args:
+            X (numpy.ndarray)
+
+        Returns:
+            numpy.ndarray: cumulative probability.
+
+        """
+        self.check_fit()
+
+        U, V = split_matrix(X)
+
+        if (V == 0).all() or (U == 0).all():
+            return np.zeros(V.shape[0])
+
+        else:
+            cdfs = [
+                np.power(
+                    np.power(U[i], -self.theta) + np.power(V[i], -self.theta) - 1,
+                    -1.0 / self.theta,
+                )
+                if (U[i] > 0 and V[i] > 0)
+                else 0
+                for i in range(len(U))
+            ]
+
+            return np.array(cdfs)
+
+    def percent_point(self, y, V):
+        """Compute the inverse of conditional cumulative distribution :math:`C(u|v)^{-1}`.
+
+        Args:
+            y (numpy.ndarray): Value of :math:`C(u|v)`.
+            v (numpy.ndarray): given value of v.
+        """
+        self.check_fit()
+
+        if self.theta < 0:
+            return V
+
+        else:
+            a = np.power(y, self.theta / (-1 - self.theta))
+            b = np.power(V, self.theta)
+
+            # If b == 0, self.theta tends to inf,
+            # so the next operation tends to 1
+            if (b == 0).all():
+                return np.ones(len(V))
+
+            return np.power((a + b - 1) / b, -1 / self.theta)
+
+    def partial_derivative(self, X):
+        r"""Compute partial derivative of cumulative distribution.
+
+        The partial derivative of the copula(CDF) is the conditional CDF.
+
+        .. math:: F(v|u) = \frac{\partial C(u,v)}{\partial u} =
+            u^{- \theta - 1}(u^{-\theta} + v^{-\theta} - 1)^{-\frac{\theta+1}{\theta}}
+
+        Args:
+            X (np.ndarray)
+            y (float)
+
+        Returns:
+            numpy.ndarray: Derivatives
+
+        """
+        self.check_fit()
+
+        U, V = split_matrix(X)
+
+        A = np.power(V, -self.theta - 1)
+
+        # If theta tends to inf, A tends to inf
+        # And the next partial_derivative tends to 0
+        if (A == np.inf).any():
+            return np.zeros(len(V))
+
+        B = np.power(V, -self.theta) + np.power(U, -self.theta) - 1
+        h = np.power(B, (-1 - self.theta) / self.theta)
+        return A * h
+
+    def compute_theta(self):
+        r"""Compute theta parameter using Kendall's tau.
+
+        On Clayton copula this is
+
+        .. math:: τ = θ/(θ + 2) \implies θ = 2τ/(1-τ)
+        .. math:: θ ∈ (0, ∞)
+
+        On the corner case of :math:`τ = 1`, return infinite.
+        """
+        if self.tau == 1:
+            return np.inf
+
+        return 2 * self.tau / (1 - self.tau)

copulas/bivariate/frank.py

@@ -0,0 +1,170 @@
+"""Frank module."""
+
+import sys
+
+import numpy as np
+import scipy.integrate as integrate
+from scipy.optimize import least_squares
+
+from copulas.bivariate.base import Bivariate, CopulaTypes
+from copulas.bivariate.utils import split_matrix
+from copulas.utils import EPSILON
+
+MIN_FLOAT_LOG = np.log(sys.float_info.min)
+MAX_FLOAT_LOG = np.log(sys.float_info.max)
+
+
+class Frank(Bivariate):
+    """Class for Frank copula model."""
+
+    copula_type = CopulaTypes.FRANK
+    theta_interval = [-float('inf'), float('inf')]
+    invalid_thetas = [0]
+
+    def generator(self, t):
+        """Return the generator function."""
+        a = (np.exp(-self.theta * t) - 1) / (np.exp(-self.theta) - 1)
+        return -np.log(a)
+
+    def _g(self, z):
+        r"""Assist in solving the Frank copula.
+
+        This functions encapsulates :math:`g(z) = e^{-\theta z} - 1` used on Frank copulas.
+
+        Argument:
+            z: np.ndarray
+
+        Returns:
+            np.ndarray
+
+        """
+        return np.exp(-self.theta * z) - 1
+
+    def probability_density(self, X):
+        r"""Compute probability density function for given copula family.
+
+        The probability density(PDF) for the Frank family of copulas correspond to the formula:
+
+        .. math:: c(U,V) = \frac{\partial^2 C(u,v)}{\partial v \partial u} =
+             \frac{-\theta g(1)(1 + g(u + v))}{(g(u) g(v) + g(1)) ^ 2}
+
+        Where the g function is defined by:
+
+        .. math:: g(x) = e^{-\theta x} - 1
+
+        Args:
+            X: `np.ndarray`
+
+        Returns:
+            np.array: probability density
+
+        """
+        self.check_fit()
+
+        U, V = split_matrix(X)
+
+        if self.theta == 0:
+            return U * V
+
+        else:
+            num = (-self.theta * self._g(1)) * (1 + self._g(U + V))
+            aux = self._g(U) * self._g(V) + self._g(1)
+            den = np.power(aux, 2)
+            return num / den
+
+    def cumulative_distribution(self, X):
+        r"""Compute the cumulative distribution function for the Frank copula.
+
+        The cumulative density(cdf), or distribution function for the Frank family of copulas
+        correspond to the formula:
+
+        .. math:: C(u,v) =  −\frac{\ln({\frac{1 + g(u) g(v)}{g(1)}})}{\theta}
+
+
+        Args:
+            X: `np.ndarray`
+
+        Returns:
+            np.array: cumulative distribution
+
+        """
+        self.check_fit()
+
+        U, V = split_matrix(X)
+
+        num = (np.exp(-self.theta * U) - 1) * (np.exp(-self.theta * V) - 1)
+        den = np.exp(-self.theta) - 1
+
+        return -1.0 / self.theta * np.log(1 + num / den)
+
+    def percent_point(self, y, V):
+        """Compute the inverse of conditional cumulative distribution :math:`C(u|v)^{-1}`.
+
+        Args:
+            y: `np.ndarray` value of :math:`C(u|v)`.
+            v: `np.ndarray` given value of v.
+        """
+        self.check_fit()
+
+        if self.theta == 0:
+            return V
+
+        else:
+            return super().percent_point(y, V)
+
+    def partial_derivative(self, X):
+        r"""Compute partial derivative of cumulative distribution.
+
+        The partial derivative of the copula(CDF) is the conditional CDF.
+
+        .. math:: F(v|u) = \frac{\partial}{\partial u}C(u,v) =
+            \frac{g(u)g(v) + g(v)}{g(u)g(v) + g(1)}
+
+        Args:
+            X (np.ndarray)
+            y (float)
+
+        Returns:
+            np.ndarray
+
+        """
+        self.check_fit()
+
+        U, V = split_matrix(X)
+
+        if self.theta == 0:
+            return V
+
+        else:
+            num = self._g(U) * self._g(V) + self._g(U)
+            den = self._g(U) * self._g(V) + self._g(1)
+            return num / den
+
+    def compute_theta(self):
+        r"""Compute theta parameter using Kendall's tau.
+
+        On Frank copula, the relationship between tau and theta is defined by:
+
+        .. math:: \tau = 1 − \frac{4}{\theta} + \frac{4}{\theta^2}\int_0^\theta \!
+            \frac{t}{e^t -1} \mathrm{d}t.
+
+        In order to solve it, we can simplify it as
+
+        .. math:: 0 = 1 + \frac{4}{\theta}(D_1(\theta) - 1) - \tau
+
+        where the function D is the Debye function of first order, defined as:
+
+        .. math:: D_1(x) = \frac{1}{x}\int_0^x\frac{t}{e^t -1} \mathrm{d}t.
+
+        """
+        result = least_squares(self._tau_to_theta, 1, bounds=(MIN_FLOAT_LOG, MAX_FLOAT_LOG))
+        return result.x[0]
+
+    def _tau_to_theta(self, alpha):
+        """Relationship between tau and theta as a solvable equation."""
+
+        def debye(t):
+            return t / (np.exp(t) - 1)
+
+        debye_value = integrate.quad(debye, EPSILON, alpha.item())[0] / alpha
+        return 4 * (debye_value - 1) / alpha + 1 - self.tau

copulas/bivariate/gumbel.py

@@ -0,0 +1,144 @@
+"""Gumbel module."""
+
+import numpy as np
+
+from copulas.bivariate.base import Bivariate, CopulaTypes
+from copulas.bivariate.utils import split_matrix
+
+
+class Gumbel(Bivariate):
+    """Class for clayton copula model."""
+
+    copula_type = CopulaTypes.GUMBEL
+    theta_interval = [1, float('inf')]
+    invalid_thetas = []
+
+    def generator(self, t):
+        """Return the generator function."""
+        return np.power(-np.log(t), self.theta)
+
+    def probability_density(self, X):
+        r"""Compute probability density function for given copula family.
+
+        The probability density(PDF) for the Gumbel family of copulas correspond to the formula:
+
+        .. math::
+
+            \begin{align}
+                c(U,V)
+                    &= \frac{\partial^2 C(u,v)}{\partial v \partial u}
+                    &= \frac{C(u,v)}{uv} \frac{((-\ln u)^{\theta}  # noqa: JS101
+                    + (-\ln v)^{\theta})^{\frac{2}  # noqa: JS101
+                {\theta} - 2 }}{(\ln u \ln v)^{1 - \theta}}  # noqa: JS101
+                ( 1 + (\theta-1) \big((-\ln u)^\theta
+                + (-\ln v)^\theta\big)^{-1/\theta})
+            \end{align}
+
+        Args:
+            X (numpy.ndarray)
+
+        Returns:
+            numpy.ndarray
+
+        """
+        self.check_fit()
+
+        U, V = split_matrix(X)
+
+        if self.theta == 1:
+            return U * V
+
+        else:
+            a = np.power(U * V, -1)
+            tmp = np.power(-np.log(U), self.theta) + np.power(-np.log(V), self.theta)
+            b = np.power(tmp, -2 + 2.0 / self.theta)
+            c = np.power(np.log(U) * np.log(V), self.theta - 1)
+            d = 1 + (self.theta - 1) * np.power(tmp, -1.0 / self.theta)
+            return self.cumulative_distribution(X) * a * b * c * d
+
+    def cumulative_distribution(self, X):
+        r"""Compute the cumulative distribution function for the Gumbel copula.
+
+        The cumulative density(cdf), or distribution function for the Gumbel family of copulas
+        correspond to the formula:
+
+        .. math:: C(u,v) = e^{-((-\ln u)^{\theta} + (-\ln v)^{\theta})^{\frac{1}{\theta}}}
+
+        Args:
+            X (np.ndarray)
+
+        Returns:
+            np.ndarray: cumulative probability for the given datapoints, cdf(X).
+
+        """
+        self.check_fit()
+
+        U, V = split_matrix(X)
+
+        if self.theta == 1:
+            return U * V
+
+        else:
+            h = np.power(-np.log(U), self.theta) + np.power(-np.log(V), self.theta)
+            h = -np.power(h, 1.0 / self.theta)
+            cdfs = np.exp(h)
+            return cdfs
+
+    def percent_point(self, y, V):
+        """Compute the inverse of conditional cumulative distribution :math:`C(u|v)^{-1}`.
+
+        Args:
+            y (np.ndarray): value of :math:`C(u|v)`.
+            v (np.ndarray): given value of v.
+
+        """
+        self.check_fit()
+
+        if self.theta == 1:
+            return y
+
+        else:
+            return super().percent_point(y, V)
+
+    def partial_derivative(self, X):
+        r"""Compute partial derivative of cumulative distribution.
+
+        The partial derivative of the copula(CDF) is the conditional CDF.
+
+        .. math:: F(v|u) = \frac{\partial C(u,v)}{\partial u} =
+            C(u,v)\frac{((-\ln u)^{\theta} + (-\ln v)^{\theta})^{\frac{1}{\theta} - 1}}
+            {\theta(- \ln u)^{1 -\theta}}
+
+        Args:
+            X (np.ndarray)
+            y (float)
+
+        Returns:
+            numpy.ndarray
+
+        """
+        self.check_fit()
+
+        U, V = split_matrix(X)
+
+        if self.theta == 1:
+            return V
+
+        else:
+            t1 = np.power(-np.log(U), self.theta)
+            t2 = np.power(-np.log(V), self.theta)
+            p1 = self.cumulative_distribution(X)
+            p2 = np.power(t1 + t2, -1 + 1.0 / self.theta)
+            p3 = np.power(-np.log(V), self.theta - 1)
+            return p1 * p2 * p3 / V
+
+    def compute_theta(self):
+        r"""Compute theta parameter using Kendall's tau.
+
+        On Gumbel copula :math:`\tau` is defined as :math:`τ = \frac{θ−1}{θ}`
+        that we solve as :math:`θ = \frac{1}{1-τ}`
+        """
+        if self.tau == 1:
+            raise ValueError("Tau value can't be 1")
+
+        return 1 / (1 - self.tau)

copulas/bivariate/independence.py

@@ -0,0 +1,81 @@
+"""Independence module."""
+
+import numpy as np
+
+from copulas.bivariate.base import Bivariate, CopulaTypes
+from copulas.bivariate.utils import split_matrix
+
+
+class Independence(Bivariate):
+    """This class represent the copula for two independent variables."""
+
+    copula_type = CopulaTypes.INDEPENDENCE
+
+    def fit(self, X):
+        """Fit the copula to the given data.
+
+        Args:
+            X (numpy.array): Probabilites in a matrix shaped (n, 2)
+
+        Returns:
+            None
+
+        """
+
+    def generator(self, t):
+        """Compute the generator function for the Copula.
+
+        The generator function is a function f(t), such that an archimedian copula can be
+        defined as
+
+        C(u1, ..., uN) = f(f^-1(u1), ..., f^-1(uN)).
+
+        Args:
+            t(numpy.array)
+
+        Returns:
+            np.array
+
+        """
+        return np.log(t)
+
+    def probability_density(self, X):
+        """Compute the probability density for the independence copula."""
+        return np.all((0.0 <= X) & (X <= 1.0), axis=1).astype(float)
+
+    def cumulative_distribution(self, X):
+        """Compute the cumulative distribution of the independence bivariate copula is the product.
+
+        Args:
+            X(numpy.array): Matrix of shape (n,2), whose values are in [0, 1]
+
+        Returns:
+            numpy.array: Cumulative distribution values of given input.
+
+        """
+        U, V = split_matrix(X)
+        return U * V
+
+    def partial_derivative(self, X):
+        """Compute the conditional probability of one event conditiones to the other.
+
+        In the case of the independence copula, due to C(u,v) = u*v, we have that
+        F(u|v) = dC/du = v.
+
+        Args:
+            X()
+
+        """
+        _, V = split_matrix(X)
+        return V
+
+    def percent_point(self, y, V):
+        """Compute the inverse of conditional cumulative distribution :math:`F(u|v)^-1`.
+
+        Args:
+            y: `np.ndarray` value of :math:`F(u|v)`.
+            v: `np.ndarray` given value of v.
+
+        """
+        self.check_fit()
+        return y

copulas/bivariate/utils.py

@@ -0,0 +1,19 @@
+"""Utilities for bivariate copulas."""
+
+import numpy as np
+
+
+def split_matrix(X):
+    """Split an (n,2) numpy.array into two vectors.
+
+    Args:
+        X(numpy.array): Matrix of shape (n,2)
+
+    Returns:
+        tuple[numpy.array]: Both of shape (n,)
+
+    """
+    if len(X):
+        return X[:, 0], X[:, 1]
+
+    return np.array([]), np.array([])