copulas 0.10.1.dev0__py3-none-any.whl

copulas/multivariate/vine.py

@@ -0,0 +1,356 @@
+"""VineCopula module."""
+
+import logging
+import sys
+import warnings
+
+import numpy as np
+import pandas as pd
+
+from copulas import (
+    EPSILON, check_valid_values, get_qualified_name, random_state, store_args,
+    validate_random_state)
+from copulas.bivariate.base import Bivariate, CopulaTypes
+from copulas.multivariate.base import Multivariate
+from copulas.multivariate.tree import Tree, get_tree
+from copulas.univariate.gaussian_kde import GaussianKDE
+
+LOGGER = logging.getLogger(__name__)
+
+
+class VineCopula(Multivariate):
+    """Vine copula model.
+
+    A :math:`vine` is a graphical representation of one factorization of the n-variate probability
+    distribution in terms of :math:`n(n − 1)/2` bivariate copulas by means of the chain rule.
+
+    It consists of a sequence of levels and as many levels as variables. Each level consists of
+    a tree (no isolated nodes and no loops) satisfying that if it has :math:`n` nodes there must
+    be :math:`n − 1` edges.
+
+    Each node in tree :math:`T_1` is a variable and edges are couplings of variables constructed
+    with bivariate copulas.
+
+    Each node in tree :math:`T_{k+1}` is a coupling in :math:`T_{k}`, expressed by the copula
+    of the variables; while edges are couplings between two vertices that must have one variable
+    in common, becoming a conditioning variable in the bivariate copula. Thus, every level has
+    one node less than the former. Once all the trees are drawn, the factorization is the product
+    of all the nodes.
+
+    Args:
+        vine_type (str):
+            type of the vine copula, could be 'center','direct','regular'
+        random_state (int or np.random.RandomState):
+            Random seed or RandomState to use.
+
+
+    Attributes:
+        model (copulas.univariate.Univariate):
+            Distribution to compute univariates.
+        u_matrix (numpy.array):
+            Univariates.
+        n_sample (int):
+            Number of samples.
+        n_var (int):
+            Number of variables.
+        columns (pandas.Series):
+            Names of the variables.
+        tau_mat (numpy.array):
+            Kendall correlation parameters for data.
+        truncated (int):
+            Max level used to build the vine.
+        depth (int):
+            Vine depth.
+        trees (list[Tree]):
+            List of trees used by this vine.
+        ppfs (list[callable]):
+            percent point functions from the univariates used by this vine.
+    """
+
+    @store_args
+    def __init__(self, vine_type, random_state=None):
+        if sys.version_info > (3, 8):
+            warnings.warn(
+                'Vines have not been fully tested on Python >= 3.8 and might '
+                'produce wrong results.'
+            )
+
+        self.random_state = validate_random_state(random_state)
+        self.vine_type = vine_type
+        self.u_matrix = None
+
+        self.model = GaussianKDE
+
+    @classmethod
+    def _deserialize_trees(cls, tree_list):
+        previous = Tree.from_dict(tree_list[0])
+        trees = [previous]
+
+        for tree_dict in tree_list[1:]:
+            tree = Tree.from_dict(tree_dict, previous)
+            trees.append(tree)
+            previous = tree
+
+        return trees
+
+    def to_dict(self):
+        """Return a `dict` with the parameters to replicate this Vine.
+
+        Returns:
+            dict:
+                Parameters of this Vine.
+        """
+        result = {
+            'type': get_qualified_name(self),
+            'vine_type': self.vine_type,
+            'fitted': self.fitted
+        }
+
+        if not self.fitted:
+            return result
+
+        result.update({
+            'n_sample': self.n_sample,
+            'n_var': self.n_var,
+            'depth': self.depth,
+            'truncated': self.truncated,
+            'trees': [tree.to_dict() for tree in self.trees],
+            'tau_mat': self.tau_mat.tolist(),
+            'u_matrix': self.u_matrix.tolist(),
+            'unis': [distribution.to_dict() for distribution in self.unis],
+            'columns': self.columns
+        })
+        return result
+
+    @classmethod
+    def from_dict(cls, vine_dict):
+        """Create a new instance from a parameters dictionary.
+
+        Args:
+            params (dict):
+                Parameters of the Vine, in the same format as the one
+                returned by the ``to_dict`` method.
+
+        Returns:
+            Vine:
+                Instance of the Vine defined on the parameters.
+        """
+        instance = cls(vine_dict['vine_type'])
+        fitted = vine_dict['fitted']
+        if fitted:
+            instance.fitted = fitted
+            instance.n_sample = vine_dict['n_sample']
+            instance.n_var = vine_dict['n_var']
+            instance.truncated = vine_dict['truncated']
+            instance.depth = vine_dict['depth']
+            instance.trees = cls._deserialize_trees(vine_dict['trees'])
+            instance.unis = [GaussianKDE.from_dict(uni) for uni in vine_dict['unis']]
+            instance.ppfs = [uni.percent_point for uni in instance.unis]
+            instance.columns = vine_dict['columns']
+            instance.tau_mat = np.array(vine_dict['tau_mat'])
+            instance.u_matrix = np.array(vine_dict['u_matrix'])
+
+        return instance
+
+    @check_valid_values
+    def fit(self, X, truncated=3):
+        """Fit a vine model to the data.
+
+        1. Transform all the variables by means of their marginals.
+        In other words, compute
+
+        .. math:: u_i = F_i(x_i), i = 1, ..., n
+
+        and compose the matrix :math:`u = u_1, ..., u_n,` where :math:`u_i` are their columns.
+
+        Args:
+            X (numpy.ndarray):
+                Data to be fitted to.
+            truncated (int):
+                Max level to build the vine.
+        """
+        LOGGER.info('Fitting VineCopula("%s")', self.vine_type)
+        self.n_sample, self.n_var = X.shape
+        self.columns = X.columns
+        self.tau_mat = X.corr(method='kendall').to_numpy()
+        self.u_matrix = np.empty([self.n_sample, self.n_var])
+
+        self.truncated = truncated
+        self.depth = self.n_var - 1
+        self.trees = []
+
+        self.unis, self.ppfs = [], []
+        for i, col in enumerate(X):
+            uni = self.model()
+            uni.fit(X[col])
+            self.u_matrix[:, i] = uni.cumulative_distribution(X[col])
+            self.unis.append(uni)
+            self.ppfs.append(uni.percent_point)
+
+        self.train_vine(self.vine_type)
+        self.fitted = True
+
+    def train_vine(self, tree_type):
+        r"""Build the vine.
+
+        1. For the construction of the first tree :math:`T_1`, assign one node to each variable
+           and then couple them by maximizing the measure of association considered.
+           Different vines impose different constraints on this construction. When those are
+           applied different trees are achieved at this level.
+
+        2. Select the copula that best fits to the pair of variables coupled by each edge in
+           :math:`T_1`.
+
+        3. Let :math:`C_{ij}(u_i , u_j )` be the copula for a given edge :math:`(u_i, u_j)`
+           in :math:`T_1`. Then for every edge in :math:`T_1`, compute either
+
+           .. math:: {v^1}_{j|i} = \\frac{\\partial C_{ij}(u_i, u_j)}{\\partial u_j}
+
+           or similarly :math:`{v^1}_{i|j}`, which are conditional cdfs. When finished with
+           all the edges, construct the new matrix with :math:`v^1` that has one less column u.
+
+        4. Set k = 2.
+
+        5. Assign one node of :math:`T_k` to each edge of :math:`T_ {k−1}`. The structure of
+           :math:`T_{k−1}` imposes a set of constraints on which edges of :math:`T_k` are
+           realizable. Hence the next step is to get a linked list of the accesible nodes for
+           every node in :math:`T_k`.
+
+        6. As in step 1, nodes of :math:`T_k` are coupled maximizing the measure of association
+           considered and satisfying the constraints impose by the kind of vine employed plus the
+           set of constraints imposed by tree :math:`T_{k−1}`.
+
+        7. Select the copula that best fit to each edge created in :math:`T_k`.
+
+        8. Recompute matrix :math:`v_k` as in step 4, but taking :math:`T_k` and :math:`vk−1`
+           instead of :math:`T_1` and u.
+
+        9. Set :math:`k = k + 1` and repeat from (5) until all the trees are constructed.
+
+        Args:
+            tree_type (str or TreeTypes):
+                Type of trees to use.
+        """
+        LOGGER.debug('start building tree : 0')
+        # 1
+        tree_1 = get_tree(tree_type)
+        tree_1.fit(0, self.n_var, self.tau_mat, self.u_matrix)
+        self.trees.append(tree_1)
+        LOGGER.debug('finish building tree : 0')
+
+        for k in range(1, min(self.n_var - 1, self.truncated)):
+            # get constraints from previous tree
+            self.trees[k - 1]._get_constraints()
+            tau = self.trees[k - 1].get_tau_matrix()
+            LOGGER.debug(f'start building tree: {k}')
+            tree_k = get_tree(tree_type)
+            tree_k.fit(k, self.n_var - k, tau, self.trees[k - 1])
+            self.trees.append(tree_k)
+            LOGGER.debug(f'finish building tree: {k}')
+
+    def get_likelihood(self, uni_matrix):
+        """Compute likelihood of the vine."""
+        num_tree = len(self.trees)
+        values = np.empty([1, num_tree])
+
+        for i in range(num_tree):
+            value, new_uni_matrix = self.trees[i].get_likelihood(uni_matrix)
+            uni_matrix = new_uni_matrix
+            values[0, i] = value
+
+        return np.sum(values)
+
+    def _sample_row(self):
+        """Generate a single sampled row from vine model.
+
+        Returns:
+            numpy.ndarray
+        """
+        unis = np.random.uniform(0, 1, self.n_var)
+        # randomly select a node to start with
+        first_ind = np.random.randint(0, self.n_var)
+        adj = self.trees[0].get_adjacent_matrix()
+        visited = []
+        explore = [first_ind]
+
+        sampled = np.zeros(self.n_var)
+        itr = 0
+        while explore:
+            current = explore.pop(0)
+            adj_is_one = adj[current, :] == 1
+            neighbors = np.where(adj_is_one)[0].tolist()
+            if itr == 0:
+                new_x = self.ppfs[current](unis[current])
+
+            else:
+                for i in range(itr - 1, -1, -1):
+                    current_ind = -1
+
+                    if i >= self.truncated:
+                        continue
+
+                    current_tree = self.trees[i].edges
+                    # get index of edge to retrieve
+                    for edge in current_tree:
+                        if i == 0:
+                            if (edge.L == current and edge.R == visited[0]) or\
+                               (edge.R == current and edge.L == visited[0]):
+                                current_ind = edge.index
+                                break
+                        else:
+                            if edge.L == current or edge.R == current:
+                                condition = set(edge.D)
+                                condition.add(edge.L)  # noqa: PD005
+                                condition.add(edge.R)  # noqa: PD005
+
+                                visit_set = set(visited)
+                                visit_set.add(current)  # noqa: PD005
+
+                                if condition.issubset(visit_set):
+                                    current_ind = edge.index
+                                break
+
+                    if current_ind != -1:
+                        # the node is not indepedent contional on visited node
+                        copula_type = current_tree[current_ind].name
+                        copula = Bivariate(copula_type=CopulaTypes(copula_type))
+                        copula.theta = current_tree[current_ind].theta
+
+                        U = np.array([unis[visited[0]]])
+                        if i == itr - 1:
+                            tmp = copula.percent_point(np.array([unis[current]]), U)[0]
+                        else:
+                            tmp = copula.percent_point(np.array([tmp]), U)[0]
+
+                        tmp = min(max(tmp, EPSILON), 0.99)
+
+                new_x = self.ppfs[current](np.array([tmp]))
+
+            sampled[current] = new_x
+
+            for s in neighbors:
+                if s not in visited:
+                    explore.insert(0, s)
+
+            itr += 1
+            visited.insert(0, current)
+
+        return sampled
+
+    @random_state
+    def sample(self, num_rows):
+        """Sample new rows.
+
+        Args:
+            num_rows (int):
+                Number of rows to sample
+
+        Returns:
+            pandas.DataFrame:
+                sampled rows.
+        """
+        sampled_values = []
+        for i in range(num_rows):
+            sampled_values.append(self._sample_row())
+
+        return pd.DataFrame(sampled_values, columns=self.columns)

copulas/optimize/__init__.py

@@ -0,0 +1,153 @@
+"""Copulas optimization functions."""
+
+import numpy as np
+
+
+def bisect(f, xmin, xmax, tol=1e-8, maxiter=50):
+    """Bisection method for finding roots.
+
+    This method implements a simple vectorized routine for identifying
+    the root (of a monotonically increasing function) given a bracketing
+    interval.
+
+    Arguments:
+        f (Callable):
+            A function which takes as input a vector x and returns a
+            vector with the same number of dimensions.
+        xmin (np.ndarray):
+            The minimum value for x such that f(x) <= 0.
+        xmax (np.ndarray):
+            The maximum value for x such that f(x) >= 0.
+
+    Returns:
+        numpy.ndarray:
+            The value of x such that f(x) is close to 0.
+    """
+    assert (f(xmin) <= 0.0).all()
+    assert (f(xmax) >= 0.0).all()
+
+    for _ in range(maxiter):
+        guess = (xmin + xmax) / 2.0
+        fguess = f(guess)
+        xmin[fguess <= 0] = guess[fguess <= 0]
+        xmax[fguess >= 0] = guess[fguess >= 0]
+        if (xmax - xmin).max() < tol:
+            break
+
+    return (xmin + xmax) / 2.0
+
+
+def chandrupatla(f, xmin, xmax, eps_m=None, eps_a=None, maxiter=50):
+    """Chandrupatla's algorithm.
+
+    This is adapted from [1] which implements Chandrupatla's algorithm [2]
+    which starts from a bracketing interval and, conditionally, swaps between
+    bisection and inverse quadratic interpolation.
+
+    [1] https://github.com/scipy/scipy/issues/7242#issuecomment-290548427
+    [2] https://books.google.com/books?id=cC-8BAAAQBAJ&pg=PA95
+
+    Arguments:
+        f (Callable):
+            A function which takes as input a vector x and returns a
+            vector with the same number of dimensions.
+        xmin (np.ndarray):
+            The minimum value for x such that f(x) <= 0.
+        xmax (np.ndarray):
+            The maximum value for x such that f(x) >= 0.
+
+    Returns:
+        numpy.ndarray:
+            The value of x such that f(x) is close to 0.
+    """
+    # Initialization
+    a = xmax
+    b = xmin
+    fa = f(a)
+    fb = f(b)
+
+    # Make sure we know the size of the result
+    shape = np.shape(fa)
+    assert shape == np.shape(fb)
+
+    fc = fa
+    c = a
+
+    # Make sure we are bracketing a root in each case
+    assert (np.sign(fa) * np.sign(fb) <= 0).all()
+    t = 0.5
+    # Initialize an array of False,
+    # determines whether we should do inverse quadratic interpolation
+    iqi = np.zeros(shape, dtype=bool)
+
+    # jms: some guesses for default values of the eps_m and eps_a settings
+    # based on machine precision... not sure exactly what to do here
+    eps = np.finfo(float).eps
+    if eps_m is None:
+        eps_m = eps
+    if eps_a is None:
+        eps_a = 2 * eps
+
+    iterations = 0
+    terminate = False
+
+    while maxiter > 0:
+        maxiter -= 1
+        # use t to linearly interpolate between a and b,
+        # and evaluate this function as our newest estimate xt
+        xt = np.clip(a + t * (b - a), xmin, xmax)
+        ft = f(xt)
+
+        # update our history of the last few points so that
+        # - a is the newest estimate (we're going to update it from xt)
+        # - c and b get the preceding two estimates
+        # - a and b maintain opposite signs for f(a) and f(b)
+        samesign = np.sign(ft) == np.sign(fa)
+        c = np.choose(samesign, [b, a])
+        b = np.choose(samesign, [a, b])
+        fc = np.choose(samesign, [fb, fa])
+        fb = np.choose(samesign, [fa, fb])
+        a = xt
+        fa = ft
+
+        # set xm so that f(xm) is the minimum magnitude of f(a) and f(b)
+        fa_is_smaller = np.abs(fa) < np.abs(fb)
+        xm = np.choose(fa_is_smaller, [b, a])
+        fm = np.choose(fa_is_smaller, [fb, fa])
+
+        tol = 2 * eps_m * np.abs(xm) + eps_a
+        tlim = tol / np.abs(b - c)
+        terminate = np.logical_or(terminate, np.logical_or(fm == 0, tlim > 0.5))
+
+        if np.all(terminate):
+            break
+        iterations += 1 - terminate
+
+        # Figure out values xi and phi
+        # to determine which method we should use next
+        xi = (a - b) / (c - b)
+        phi = (fa - fb) / (fc - fb)
+        iqi = np.logical_and(phi**2 < xi, (1 - phi)**2 < 1 - xi)
+
+        if not shape:
+            # scalar case
+            if iqi:
+                # inverse quadratic interpolation
+                eq1 = fa / (fb - fa) * fc / (fb - fc)
+                eq2 = (c - a) / (b - a) * fa / (fc - fa) * fb / (fc - fb)
+                t = eq1 + eq2
+            else:
+                # bisection
+                t = 0.5
+        else:
+            # array case
+            t = np.full(shape, 0.5)
+            a2, b2, c2, fa2, fb2, fc2 = a[iqi], b[iqi], c[iqi], fa[iqi], fb[iqi], fc[iqi]
+            t[iqi] = fa2 / (fb2 - fa2) * fc2 / (fb2 - fc2) + (c2 - a2) / \
+                (b2 - a2) * fa2 / (fc2 - fa2) * fb2 / (fc2 - fb2)
+
+        # limit to the range (tlim, 1-tlim)
+        t = np.minimum(1 - tlim, np.maximum(tlim, t))
+
+    # done!
+    return xm

copulas/univariate/__init__.py

@@ -0,0 +1,25 @@
+"""Univariate copulas module."""
+
+from copulas.univariate.base import BoundedType, ParametricType, Univariate
+from copulas.univariate.beta import BetaUnivariate
+from copulas.univariate.gamma import GammaUnivariate
+from copulas.univariate.gaussian import GaussianUnivariate
+from copulas.univariate.gaussian_kde import GaussianKDE
+from copulas.univariate.log_laplace import LogLaplace
+from copulas.univariate.student_t import StudentTUnivariate
+from copulas.univariate.truncated_gaussian import TruncatedGaussian
+from copulas.univariate.uniform import UniformUnivariate
+
+__all__ = (
+    'BetaUnivariate',
+    'GammaUnivariate',
+    'GaussianKDE',
+    'GaussianUnivariate',
+    'TruncatedGaussian',
+    'StudentTUnivariate',
+    'Univariate',
+    'ParametricType',
+    'BoundedType',
+    'UniformUnivariate',
+    'LogLaplace'
+)