tmapper-py 0.1.0__py3-none-any.whl

tmapper/cknngraph.py

@@ -0,0 +1,73 @@
+"""Port of tmapper_tools/cknngraph.m from the MATLAB toolbox."""
+
+import numpy as np
+import networkx as nx
+from scipy.spatial.distance import cdist
+
+
+def cknngraph(X_or_D, k, delta, *, average=False):
+    """Construct a graph based on continuous k-nearest neighbors (Berry &
+    Sauer, 2019).
+
+    Port of MATLAB's ``cknngraph.m``. Connects points x, y iff::
+
+        D(x, y) < delta * sqrt(D(x, x_k) * D(y, y_k))
+
+    where ``D(~, ~)`` is the distance and ``~_k`` is the k-th nearest
+    neighbor of ``~``.
+
+    Parameters
+    ----------
+    X_or_D : array_like, shape (N, d) or (N, N)
+        Either raw coordinates (N points in d-dim space) or a precomputed
+        (N, N) distance matrix. Auto-detected: treated as a distance
+        matrix only if square *and* symmetric.
+    k : int
+        Used to normalize distance by local point density. Must be a
+        positive integer strictly less than N.
+    delta : float
+        Threshold for linking two nodes (must be a positive real
+        number).
+    average : bool, default False
+        Whether ``x_k`` is the average distance over the first k nearest
+        neighbors (True) or just the k-th nearest neighbor (False).
+
+    Returns
+    -------
+    networkx.Graph
+        Unweighted undirected graph, one node per input point.
+    """
+    X_or_D = np.asarray(X_or_D, dtype=float)
+    if X_or_D.ndim != 2:
+        raise ValueError("X_or_D must be a 2D array.")
+    if not (np.isscalar(k) and float(k) == round(float(k)) and k >= 1):
+        raise ValueError("k must be a positive integer scalar.")
+    k = int(k)
+    if not (np.isscalar(delta) and np.isreal(delta) and delta > 0):
+        raise ValueError("delta must be a positive real scalar.")
+
+    nr, nc = X_or_D.shape
+    if nr != nc or not np.allclose(X_or_D, X_or_D.T):
+        D = cdist(X_or_D, X_or_D)
+    else:
+        D = X_or_D.copy()
+    Nn = D.shape[0]
+
+    if k >= Nn:
+        raise ValueError(f"k must be smaller than the number of points ({Nn}).")
+
+    # -- find nearest neighbors and compute distance
+    D_sorted = np.sort(D, axis=1)
+    if average:
+        Dk = D_sorted[:, 1:1 + k].mean(axis=1)  # col 0 is distance to self
+    else:
+        Dk = D_sorted[:, k]
+
+    # -- normalize D by local density
+    D_norm = D / np.sqrt(np.outer(Dk, Dk))
+
+    # -- construct graph from adjacency matrix
+    A = D_norm < delta
+    np.fill_diagonal(A, False)
+
+    return nx.from_numpy_array(A)

tmapper/cycle_cluster.py

@@ -0,0 +1,111 @@
+"""Port of tmapper_tools/CycleCluster.m from the MATLAB toolbox."""
+
+import numpy as np
+from scipy.cluster.hierarchy import linkage, fcluster
+from scipy.spatial.distance import squareform
+
+
+def _classical_mds(dist, n_components=2):
+    """Classical (Torgerson) multidimensional scaling, matching MATLAB's
+    ``cmdscale``. ``dist`` is a square distance matrix."""
+    dist = np.asarray(dist, dtype=float)
+    n = dist.shape[0]
+    J = np.eye(n) - np.ones((n, n)) / n
+    B = -0.5 * J @ (dist ** 2) @ J
+    eigvals, eigvecs = np.linalg.eigh(B)
+    order = np.argsort(eigvals)[::-1]
+    eigvals, eigvecs = eigvals[order], eigvecs[:, order]
+    eigvals = np.clip(eigvals[:n_components], 0, None)
+    return eigvecs[:, :n_components] * np.sqrt(eigvals)
+
+
+def cycle_cluster(allcycles, thres, *, plotmat=True, plotmds=False, plothist=True,
+                   reordermat=True, ax=None, return_ax=False):
+    """Cluster cycles based on the fraction of overlap between them
+    (shared nodes / union of nodes).
+
+    Port of MATLAB's ``CycleCluster.m``.
+
+    Parameters
+    ----------
+    allcycles : sequence of sequence of int
+        ``allcycles[n]`` is the path of one cycle.
+    thres : float
+        Cut-off threshold (0-1) for single-linkage clustering: if
+        overlap > thres, two cycles belong to the same cluster.
+    plotmat : bool, default True
+        Whether to plot the overlap matrix.
+    plotmds : bool, default False
+        Whether to plot a 2D classical-MDS projection of the cycles.
+    plothist : bool, default True
+        Whether to plot the histogram of linkage distances.
+    reordermat : bool, default True
+        Whether to reorder the overlap matrix by cluster assignment.
+    ax : matplotlib.axes.Axes, optional
+        Axes for the overlap-matrix plot (only used if ``plotmat``).
+        A new figure is created if not given.
+    return_ax : bool, default False
+        If True, also return the axes used for the overlap-matrix plot
+        (None if ``plotmat`` is False), so a caller can add further
+        annotations to it (e.g. :func:`cycle_path_decomp`'s cluster-block
+        outlines).
+
+    Returns
+    -------
+    numpy.ndarray
+        1-indexed cluster label for each cycle (matching MATLAB's
+        ``cluster()`` convention).
+    ax : matplotlib.axes.Axes or None
+        Only returned if ``return_ax`` is True.
+    """
+    Nc = len(allcycles)
+
+    if Nc <= 1:
+        cluster_idx = np.ones(Nc, dtype=int)
+        return (cluster_idx, None) if return_ax else cluster_idx
+
+    prct_overlap = np.zeros((Nc, Nc))
+    sets = [set(c) for c in allcycles]
+    for ii in range(Nc):
+        for jj in range(Nc):
+            prct_overlap[ii, jj] = len(sets[ii] & sets[jj]) / len(sets[ii] | sets[jj])
+
+    if plotmds:
+        import matplotlib.pyplot as plt
+        Y = _classical_mds(1 - prct_overlap, 2)
+        plt.figure()
+        plt.scatter(Y[:, 0], Y[:, 1])
+
+    Z = linkage(squareform(1 - prct_overlap, checks=False), method="complete")
+
+    if plothist:
+        import matplotlib.pyplot as plt
+        plt.figure()
+        plt.hist(1 - Z[:, 2], bins=np.linspace(0, 1, 21))
+        ylim = plt.ylim()
+        plt.plot([thres, thres], ylim)
+        plt.xlabel("overlap")
+        plt.ylabel("count")
+
+    cluster_idx = fcluster(Z, t=1 - thres, criterion="distance")
+
+    if plotmat:
+        import matplotlib.pyplot as plt
+        if ax is None:
+            _, ax = plt.subplots()
+        if reordermat:
+            order = np.argsort(cluster_idx, kind="stable")
+            im = ax.imshow(prct_overlap[np.ix_(order, order)], origin="lower", vmin=0, vmax=1)
+            ax.set_xlabel("cycle/path index (reordered)")
+            ax.set_ylabel("cycle/path index (reordered)")
+        else:
+            im = ax.imshow(prct_overlap, origin="lower", vmin=0, vmax=1)
+            ax.set_xlabel("cycle/path index")
+            ax.set_ylabel("cycle/path index")
+        cbar = plt.colorbar(im, ax=ax)
+        cbar.set_label("fraction of overlap")
+        ax.set_aspect("equal")
+    else:
+        ax = None
+
+    return (cluster_idx, ax) if return_ax else cluster_idx

tmapper/cycle_cluster_conn.py

@@ -0,0 +1,112 @@
+"""Port of tmapper_tools/CycleClusterConn.m from the MATLAB toolbox."""
+
+import numpy as np
+
+
+def cycle_cluster_conn(dg, allcycles, cluster_idx):
+    """Connectivity between M clusters of N cycles.
+
+    Port of MATLAB's ``CycleClusterConn.m``.
+
+    Parameters
+    ----------
+    dg : networkx.DiGraph
+        The directed graph the cycles/paths live on.
+    allcycles : sequence of sequence of int
+        ``allcycles[n]`` is the path of one cycle.
+    cluster_idx : array_like of int
+        Cluster label of each cycle (e.g. from :func:`cycle_cluster`).
+
+    Returns
+    -------
+    cluster_conn : list of list of set
+        ``cluster_conn[i][j]`` (== ``cluster_conn[j][i]``) contains
+        nodes on the boundary between loop-clusters i and j.
+    cluster_conn_dir : list of list of set
+        ``cluster_conn_dir[i][j]`` contains nodes in the boundary of
+        cluster j that receive a link from at least one node of cluster
+        i (excluding shared nodes).
+    clusters_nodes : list of list
+        All nodes in each cluster (first-seen order).
+    clusters_boundary : list of set
+        Boundary nodes of each cluster.
+    clusters_interior : list of list
+        Nodes of each cluster that are not on its boundary.
+    clusters_crtpts : list of list
+        Critical points (nodes with more than one source or target) in
+        each cluster.
+    clusters_intcrtpts : list of list
+        Critical points in each cluster that are not on its boundary.
+    """
+    cluster_idx = np.asarray(cluster_idx)
+    clusters = np.unique(cluster_idx)
+    n_clusters = len(clusters)
+
+    out_degree = dict(dg.out_degree())
+    in_degree = dict(dg.in_degree())
+    crtpts = {n for n in dg.nodes() if out_degree[n] > 1 or in_degree[n] > 1}
+
+    clusters_nodes = [None] * n_clusters
+    clusters_crtpts = [None] * n_clusters
+    clusters_intcrtpts = [None] * n_clusters
+    clusters_inneighbors = [None] * n_clusters
+    clusters_outneighbors = [None] * n_clusters
+    clusters_boundary = [None] * n_clusters
+    clusters_interior = [None] * n_clusters
+
+    for ii, c in enumerate(clusters):
+        cycles_ii = [allcycles[k] for k in range(len(allcycles)) if cluster_idx[k] == c]
+
+        seen, seen_set = [], set()
+        for cyc in cycles_ii:
+            for node in cyc:
+                if node not in seen_set:
+                    seen_set.add(node)
+                    seen.append(node)
+        clusters_nodes[ii] = seen
+
+        crtpts_ii = [n for n in seen if n in crtpts]
+        clusters_crtpts[ii] = crtpts_ii
+
+        innbg, outnbg = set(), set()
+        for cp in crtpts_ii:
+            innbg |= set(dg.predecessors(cp))
+            outnbg |= set(dg.successors(cp))
+        innbg -= seen_set
+        outnbg -= seen_set
+
+        bd = set()
+        for n in innbg:
+            bd |= set(dg.successors(n))
+        for n in outnbg:
+            bd |= set(dg.predecessors(n))
+        bd &= seen_set
+
+        clusters_inneighbors[ii] = innbg
+        clusters_outneighbors[ii] = outnbg
+        clusters_boundary[ii] = bd
+        clusters_interior[ii] = [n for n in seen if n not in bd]
+        clusters_intcrtpts[ii] = [n for n in crtpts_ii if n not in bd]
+
+    cluster_conn = [[None] * n_clusters for _ in range(n_clusters)]
+    cluster_conn_dir = [[None] * n_clusters for _ in range(n_clusters)]
+    cluster_conn_in = [[None] * n_clusters for _ in range(n_clusters)]
+    cluster_conn_out = [[None] * n_clusters for _ in range(n_clusters)]
+
+    for ii in range(n_clusters):
+        for jj in range(n_clusters):
+            cluster_conn[ii][jj] = clusters_boundary[ii] & set(clusters_nodes[jj])
+            cluster_conn_in[ii][jj] = clusters_inneighbors[jj] & set(clusters_nodes[ii])
+            cluster_conn_out[ii][jj] = clusters_outneighbors[ii] & set(clusters_nodes[jj])
+
+    for ii in range(n_clusters):
+        for jj in range(n_clusters):
+            bd = set()
+            for nn in cluster_conn[ii][jj]:
+                preds = set(dg.predecessors(nn))
+                if preds & cluster_conn_in[ii][jj]:
+                    bd.add(nn)
+            cluster_conn_dir[ii][jj] = bd & cluster_conn[ii][jj]
+
+    return (cluster_conn, cluster_conn_dir, clusters_nodes, clusters_boundary,
+            clusters_interior, clusters_crtpts, clusters_intcrtpts)

tmapper/cycle_count.py

@@ -0,0 +1,150 @@
+"""Port of tmapper_tools/CycleCount.m from the MATLAB toolbox.
+
+CycleCount.m is itself a third-party algorithm (not original to the
+tmapper toolbox), reproduced here under its original license:
+
+    Authors: P.-L. Giscard, N. Kriege, R. Wilson, Septembre 2016
+
+    Copyright (c) 2017, Pierre-Louis Giscard
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+        * Redistributions of source code must retain the above
+          copyright notice, this list of conditions and the following
+          disclaimer.
+        * Redistributions in binary form must reproduce the above
+          copyright notice, this list of conditions and the following
+          disclaimer in the documentation and/or other materials
+          provided with the distribution.
+        * Neither the name of the University of York nor the names of
+          its contributors may be used to endorse or promote products
+          derived from this software without specific prior written
+          permission.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+    POSSIBILITY OF SUCH DAMAGE.
+"""
+
+import numpy as np
+
+
+def cycle_count(A, L0):
+    """Count all simple cycles of length up to ``L0`` (inclusive) on a
+    graph whose adjacency matrix is ``A``, via the combinatorial-sieve
+    algorithm of Giscard, Kriege & Wilson (2016).
+
+    Parameters
+    ----------
+    A : array_like, shape (N, N)
+        Adjacency matrix of the graph (directed or undirected, weighted
+        or unweighted).
+    L0 : int
+        Maximum length of the simple cycles to count.
+
+    Returns
+    -------
+    numpy.ndarray, shape (L0,)
+        ``primes[i]`` is the number of simple cycles of length ``i + 1``,
+        for ``i`` in ``0..L0-1``.
+    """
+    A = np.asarray(A, dtype=float).copy()
+    L0 = int(L0)
+
+    primes = np.zeros(L0, dtype=complex)
+    primes[0] += np.trace(A)  # self-loops (length-1 cycles)
+    np.fill_diagonal(A, 0)
+    A = _clean_matrix(A)
+
+    directed = not np.array_equal(A, A.T)
+    if directed:
+        A_undir = ((A != 0) | (A.T != 0)).astype(float)
+    else:
+        A_undir = (A != 0).astype(float)
+
+    size = A.shape[0]
+    if L0 > size:
+        L0 = size
+
+    allowed_vert = np.ones(size, dtype=bool)
+    for i in range(size - 1):
+        allowed_vert[i] = False
+        neighbourhood = np.zeros(size)
+        neighbourhood[i] = 1
+        neighbourhood = neighbourhood + A_undir[i, :]
+        primes = _recursive_subgraphs(A, A_undir, L0, [i], allowed_vert, primes, neighbourhood)
+
+    return primes.real
+
+
+def _recursive_subgraphs(A, A_undir, L0, subgraph, allowed_vert, primes, neighbourhood):
+    """Find all connected induced subgraphs of size up to L0 containing
+    ``subgraph``, accumulating their contribution into ``primes``."""
+    allowed_vert = allowed_vert.copy()  # this frame's mutations stay local
+
+    L = len(subgraph)
+    neighbours_number = int(np.count_nonzero(neighbourhood)) - L
+    primes = _prime_count(A, L0, subgraph, neighbours_number, primes)
+
+    if L == L0:
+        return primes
+
+    neighbours = np.flatnonzero(neighbourhood.astype(bool) & allowed_vert)
+    for v in neighbours:
+        new_subgraph = subgraph + [int(v)]
+        allowed_vert[v] = False  # persists across the rest of this loop
+        new_neighbourhood = neighbourhood + A_undir[v, :]
+        primes = _recursive_subgraphs(A, A_undir, L0, new_subgraph, allowed_vert, primes, new_neighbourhood)
+
+    return primes
+
+
+def _prime_count(A, L0, subgraph, neighbours_number, primes):
+    """Combinatorial-sieve contribution of one connected induced subgraph."""
+    subgraph_size = len(subgraph)
+    idx = np.ix_(subgraph, subgraph)
+    x = A[idx]
+
+    xeig = np.linalg.eigvals(x)
+    xS = xeig.astype(complex) ** subgraph_size
+    mk = min(L0, neighbours_number + subgraph_size)
+    binomial_coeff = 1.0
+
+    for k in range(subgraph_size, mk):
+        primes[k - 1] += ((-1) ** k / k) * binomial_coeff * ((-1) ** subgraph_size) * xS.sum()
+        xS = xS * xeig
+        binomial_coeff = binomial_coeff * (subgraph_size - k + neighbours_number) / (1 - subgraph_size + k)
+
+    primes[mk - 1] += ((-1) ** mk / mk) * binomial_coeff * ((-1) ** subgraph_size) * xS.sum()
+    return primes
+
+
+def _matrix_cleaning(A):
+    """Remove sources (no incoming edge) then sinks (no outgoing edge)."""
+    no_incoming = ~A.any(axis=0)
+    A = A[~no_incoming][:, ~no_incoming]
+    no_outgoing = ~A.any(axis=1)
+    A = A[~no_outgoing][:, ~no_outgoing]
+    return A
+
+
+def _clean_matrix(A):
+    """Recursively remove isolated vertices, sinks, and sources until
+    the matrix is invariant under such removal -- i.e. every remaining
+    vertex sustains at least one cycle."""
+    cleaned = A
+    while cleaned.shape[0] != _matrix_cleaning(cleaned).shape[0]:
+        cleaned = _matrix_cleaning(cleaned)
+    return cleaned

tmapper/cycle_count2p.py

@@ -0,0 +1,72 @@
+"""Port of tmapper_tools/CycleCount2p.m and reorgCycles.m from the
+MATLAB toolbox."""
+
+import numpy as np
+import networkx as nx
+
+
+def cycle_count2p(A, *, simple=True):
+    """Estimate the number of cycles of different lengths by finding the
+    smallest cycle passing through every pair of vertices.
+
+    Port of MATLAB's ``CycleCount2p.m``. Only counts unique cycles, and
+    by default only unique simple cycles (no repeated nodes other than
+    the start/end).
+
+    Parameters
+    ----------
+    A : array_like, shape (N, N)
+        Adjacency matrix for a simple directed graph.
+    simple : bool, default True
+        Whether to only count simple cycles.
+
+    Returns
+    -------
+    cyc_count : numpy.ndarray
+        Number of cycles per unique length (shortest to longest).
+    cyc_len : numpy.ndarray
+        The unique cycle lengths themselves (shortest to longest).
+    cyc_path : list of numpy.ndarray
+        ``cyc_path[m]`` is an (Nm, Lm) array of the Nm cycles of length
+        ``cyc_len[m]``.
+    all_cycles : list of list
+        Every cycle's path, flattened into a single list.
+    """
+    g = nx.from_numpy_array(np.asarray(A), create_using=nx.DiGraph)
+    n = g.number_of_nodes()
+
+    all_closed = []
+    for s in range(n):
+        for t in range(s + 1, n):
+            if not (nx.has_path(g, s, t) and nx.has_path(g, t, s)):
+                continue
+            spf = nx.shortest_path(g, s, t)  # forward path
+            spb = nx.shortest_path(g, t, s)  # backward path
+            cycle = spf + spb[1:-1]
+            if not simple or len(set(cycle)) == len(cycle):
+                root_idx = cycle.index(min(cycle))
+                all_closed.append(cycle[root_idx:] + cycle[:root_idx])  # start at smallest node
+
+    cyc_length = np.array([len(c) for c in all_closed], dtype=int)
+    cyc_len = np.unique(cyc_length) if cyc_length.size else np.array([], dtype=int)
+
+    cyc_path = []
+    cyc_count = []
+    for L in cyc_len:
+        rows = sorted({tuple(c) for c, l in zip(all_closed, cyc_length) if l == L})
+        cyc_path.append(np.array(rows, dtype=int))
+        cyc_count.append(len(rows))
+    cyc_count = np.array(cyc_count, dtype=int)
+
+    all_cycles = [list(row) for block in cyc_path for row in block]
+
+    return cyc_count, cyc_len, cyc_path, all_cycles
+
+
+def reorg_cycles(cyc_path):
+    """Unpack the ``cyc_path`` output of :func:`cycle_count2p` into a flat
+    list where each element is a single cycle's path.
+
+    Port of MATLAB's ``reorgCycles.m``.
+    """
+    return [list(row) for block in cyc_path for row in np.asarray(block)]

tmapper/cycle_cutter.py

@@ -0,0 +1,47 @@
+"""Port of tmapper_tools/CycleCutter.m from the MATLAB toolbox."""
+
+import numpy as np
+
+
+def cycle_cutter(cyc, node_name):
+    """Cut a cycle into multiple paths at given nodes.
+
+    Port of MATLAB's ``CycleCutter.m``.
+
+    Parameters
+    ----------
+    cyc : sequence
+        A single cycle's path (node names, usually integers).
+    node_name : sequence or scalar
+        Names of nodes that are the cutting points of the cycle. Names
+        not contained in the cycle are ignored.
+
+    Returns
+    -------
+    list of list
+        Each element is a path from one cutting point to the next.
+        Wraps around: if there are ``M`` cutting points, this list has
+        ``M`` elements, and the last one wraps from the last cutting
+        point, through the end of ``cyc``, back through the start, up to
+        (and including) the first cutting point.
+    """
+    cyc = list(cyc)
+
+    if np.isscalar(node_name):
+        node_set = {node_name}
+    else:
+        node_set = set(node_name)
+
+    node_idx = [i for i, v in enumerate(cyc) if v in node_set]
+    if not node_idx:
+        return [cyc]
+
+    n_path = len(node_idx)
+    nodepath = [None] * n_path
+
+    for n in range(n_path - 1):
+        nodepath[n] = cyc[node_idx[n]: node_idx[n + 1] + 1]
+
+    nodepath[n_path - 1] = cyc[node_idx[-1]:] + cyc[:node_idx[0] + 1]
+
+    return nodepath

tmapper/cycle_overlap.py

@@ -0,0 +1,71 @@
+"""Port of tmapper_tools/CyclePathOverlap.m from the MATLAB toolbox."""
+
+import numpy as np
+
+
+def cycle_path_overlap(c, *, cycle=True, overlap_type="edge", grpvar=None):
+    """Calculate the overlap between cycles or paths.
+
+    Port of MATLAB's ``CyclePathOverlap.m``.
+
+    Parameters
+    ----------
+    c : sequence of sequence of int
+        ``c[n]`` is a path of node indices.
+    cycle : bool, default True
+        Whether the paths in ``c`` are cycles (adds a wraparound edge
+        from the last node back to the first when ``overlap_type``
+        is 'edge').
+    overlap_type : {'edge', 'node'}, default 'edge'
+        Whether to calculate overlap between edges or between nodes.
+    grpvar : array_like of int, optional
+        A grouping variable for the paths. By default, each path is its
+        own group.
+
+    Returns
+    -------
+    CO : numpy.ndarray, shape (P, P)
+        Percent overlap between every pair of groups (1 on the
+        diagonal).
+    grpnames : numpy.ndarray
+        The unique group labels, in the same order as ``CO``'s rows.
+    """
+    if overlap_type == "edge":
+        def as_items(x):
+            x = list(x)
+            edges = list(zip(x, x[1:] + [x[0]]))
+            if not cycle:
+                edges = edges[:-1]  # drop the wraparound edge
+            return edges
+    elif overlap_type == "node":
+        def as_items(x):
+            return list(x)
+    else:
+        raise ValueError(f"Unknown type: {overlap_type!r}")
+
+    c_repr = [as_items(x) for x in c]
+
+    Nc = len(c_repr)
+    if grpvar is None:
+        grpvar = np.arange(Nc)
+    grpvar = np.asarray(grpvar)
+    grpnames = np.unique(grpvar)
+    Ngrp = len(grpnames)
+
+    groups = []
+    for name in grpnames:
+        items = set()
+        for idx in np.flatnonzero(grpvar == name):
+            items |= set(c_repr[idx])
+        groups.append(items)
+
+    CO = np.full((Ngrp, Ngrp), np.nan)
+    for ii in range(Ngrp):
+        for jj in range(ii):
+            inter = len(groups[ii] & groups[jj])
+            union = len(groups[ii] | groups[jj])
+            CO[ii, jj] = inter / union
+            CO[jj, ii] = CO[ii, jj]
+    np.fill_diagonal(CO, 1)
+
+    return CO, grpnames