okstra 0.108.0 → 0.109.0

package/runtime/python/okstra_vendor/networkx/algorithms/bipartite/cluster.py

@@ -0,0 +1,289 @@
+"""Functions for computing clustering of pairs"""
+
+import itertools
+
+import networkx as nx
+
+__all__ = [
+    "clustering",
+    "average_clustering",
+    "latapy_clustering",
+    "robins_alexander_clustering",
+]
+
+
+def cc_dot(nu, nv):
+    return len(nu & nv) / len(nu | nv)
+
+
+def cc_max(nu, nv):
+    return len(nu & nv) / max(len(nu), len(nv))
+
+
+def cc_min(nu, nv):
+    return len(nu & nv) / min(len(nu), len(nv))
+
+
+modes = {"dot": cc_dot, "min": cc_min, "max": cc_max}
+
+
+@nx._dispatchable
+def latapy_clustering(G, nodes=None, mode="dot"):
+    r"""Compute a bipartite clustering coefficient for nodes.
+
+    The bipartite clustering coefficient is a measure of local density
+    of connections defined as [1]_:
+
+    .. math::
+
+       c_u = \frac{\sum_{v \in N(N(u))} c_{uv} }{|N(N(u))|}
+
+    where `N(N(u))` are the second order neighbors of `u` in `G` excluding `u`,
+    and `c_{uv}` is the pairwise clustering coefficient between nodes
+    `u` and `v`.
+
+    The mode selects the function for `c_{uv}` which can be:
+
+    `dot`:
+
+    .. math::
+
+       c_{uv}=\frac{|N(u)\cap N(v)|}{|N(u) \cup N(v)|}
+
+    `min`:
+
+    .. math::
+
+       c_{uv}=\frac{|N(u)\cap N(v)|}{min(|N(u)|,|N(v)|)}
+
+    `max`:
+
+    .. math::
+
+       c_{uv}=\frac{|N(u)\cap N(v)|}{max(|N(u)|,|N(v)|)}
+
+
+    Parameters
+    ----------
+    G : graph
+        A bipartite graph
+
+    nodes : list or iterable (optional)
+        Compute bipartite clustering for these nodes. The default
+        is all nodes in G.
+
+    mode : string
+        The pairwise bipartite clustering method to be used in the computation.
+        It must be "dot", "max", or "min".
+
+    Returns
+    -------
+    clustering : dictionary
+        A dictionary keyed by node with the clustering coefficient value.
+
+
+    Examples
+    --------
+    >>> from networkx.algorithms import bipartite
+    >>> G = nx.path_graph(4)  # path graphs are bipartite
+    >>> c = bipartite.clustering(G)
+    >>> c[0]
+    0.5
+    >>> c = bipartite.clustering(G, mode="min")
+    >>> c[0]
+    1.0
+
+    See Also
+    --------
+    robins_alexander_clustering
+    average_clustering
+    networkx.algorithms.cluster.square_clustering
+
+    References
+    ----------
+    .. [1] Latapy, Matthieu, Clémence Magnien, and Nathalie Del Vecchio (2008).
+       Basic notions for the analysis of large two-mode networks.
+       Social Networks 30(1), 31--48.
+    """
+    if not nx.algorithms.bipartite.is_bipartite(G):
+        raise nx.NetworkXError("Graph is not bipartite")
+
+    try:
+        cc_func = modes[mode]
+    except KeyError as err:
+        raise nx.NetworkXError(
+            "Mode for bipartite clustering must be: dot, min or max"
+        ) from err
+
+    if nodes is None:
+        nodes = G
+    ccs = {}
+    for v in nodes:
+        cc = 0.0
+        nbrs2 = {u for nbr in G[v] for u in G[nbr]} - {v}
+        for u in nbrs2:
+            cc += cc_func(set(G[u]), set(G[v]))
+        if cc > 0.0:  # len(nbrs2)>0
+            cc /= len(nbrs2)
+        ccs[v] = cc
+    return ccs
+
+
+clustering = latapy_clustering
+
+
+@nx._dispatchable(name="bipartite_average_clustering")
+def average_clustering(G, nodes=None, mode="dot"):
+    r"""Compute the average bipartite clustering coefficient.
+
+    A clustering coefficient for the whole graph is the average,
+
+    .. math::
+
+       C = \frac{1}{n}\sum_{v \in G} c_v,
+
+    where `n` is the number of nodes in `G`.
+
+    Similar measures for the two bipartite sets can be defined [1]_
+
+    .. math::
+
+       C_X = \frac{1}{|X|}\sum_{v \in X} c_v,
+
+    where `X` is a bipartite set of `G`.
+
+    Parameters
+    ----------
+    G : graph
+        a bipartite graph
+
+    nodes : list or iterable, optional
+        A container of nodes to use in computing the average.
+        The nodes should be either the entire graph (the default) or one of the
+        bipartite sets.
+
+    mode : string
+        The pairwise bipartite clustering method.
+        It must be "dot", "max", or "min"
+
+    Returns
+    -------
+    clustering : float
+       The average bipartite clustering for the given set of nodes or the
+       entire graph if no nodes are specified.
+
+    Examples
+    --------
+    >>> from networkx.algorithms import bipartite
+    >>> G = nx.star_graph(3)  # star graphs are bipartite
+    >>> bipartite.average_clustering(G)
+    0.75
+    >>> X, Y = bipartite.sets(G)
+    >>> bipartite.average_clustering(G, X)
+    0.0
+    >>> bipartite.average_clustering(G, Y)
+    1.0
+
+    See Also
+    --------
+    clustering
+
+    Notes
+    -----
+    The container of nodes passed to this function must contain all of the nodes
+    in one of the bipartite sets ("top" or "bottom") in order to compute
+    the correct average bipartite clustering coefficients.
+    See :mod:`bipartite documentation <networkx.algorithms.bipartite>`
+    for further details on how bipartite graphs are handled in NetworkX.
+
+
+    References
+    ----------
+    .. [1] Latapy, Matthieu, Clémence Magnien, and Nathalie Del Vecchio (2008).
+        Basic notions for the analysis of large two-mode networks.
+        Social Networks 30(1), 31--48.
+    """
+    if nodes is None:
+        nodes = G
+    ccs = latapy_clustering(G, nodes=nodes, mode=mode)
+    return sum(ccs[v] for v in nodes) / len(nodes)
+
+
+@nx._dispatchable
+def robins_alexander_clustering(G):
+    r"""Compute the bipartite clustering of G.
+
+    Robins and Alexander [1]_ defined bipartite clustering coefficient as
+    four times the number of four cycles `C_4` divided by the number of
+    three paths `L_3` in a bipartite graph:
+
+    .. math::
+
+       CC_4 = \frac{4 * C_4}{L_3}
+
+    Parameters
+    ----------
+    G : graph
+        a bipartite graph
+
+    Returns
+    -------
+    clustering : float
+       The Robins and Alexander bipartite clustering for the input graph.
+
+    Examples
+    --------
+    >>> from networkx.algorithms import bipartite
+    >>> G = nx.davis_southern_women_graph()
+    >>> print(round(bipartite.robins_alexander_clustering(G), 3))
+    0.468
+
+    See Also
+    --------
+    latapy_clustering
+    networkx.algorithms.cluster.square_clustering
+
+    References
+    ----------
+    .. [1] Robins, G. and M. Alexander (2004). Small worlds among interlocking
+           directors: Network structure and distance in bipartite graphs.
+           Computational & Mathematical Organization Theory 10(1), 69–94.
+
+    """
+    if G.order() < 4 or G.size() < 3:
+        return 0
+    L_3 = _threepaths(G)
+    if L_3 == 0:
+        return 0
+    C_4 = _four_cycles(G)
+    return (4.0 * C_4) / L_3
+
+
+def _four_cycles(G):
+    # Also see `square_clustering` which counts squares in a similar way
+    cycles = 0
+    seen = set()
+    G_adj = G._adj
+    for v in G:
+        seen.add(v)
+        v_neighbors = set(G_adj[v])
+        if len(v_neighbors) < 2:
+            # Can't form a square without at least two neighbors
+            continue
+        two_hop_neighbors = set().union(*(G_adj[u] for u in v_neighbors))
+        two_hop_neighbors -= seen
+        for x in two_hop_neighbors:
+            p2 = len(v_neighbors.intersection(G_adj[x]))
+            cycles += p2 * (p2 - 1)
+    return cycles / 4
+
+
+def _threepaths(G):
+    paths = 0
+    for v in G:
+        for u in G[v]:
+            for w in set(G[u]) - {v}:
+                paths += len(set(G[w]) - {v, u})
+    # Divide by two because we count each three path twice
+    # one for each possible starting point
+    return paths / 2

package/runtime/python/okstra_vendor/networkx/algorithms/bipartite/covering.py

@@ -0,0 +1,57 @@
+"""Functions related to graph covers."""
+
+import networkx as nx
+from networkx.algorithms.bipartite.matching import hopcroft_karp_matching
+from networkx.algorithms.covering import min_edge_cover as _min_edge_cover
+from networkx.utils import not_implemented_for
+
+__all__ = ["min_edge_cover"]
+
+
+@not_implemented_for("directed")
+@not_implemented_for("multigraph")
+@nx._dispatchable(name="bipartite_min_edge_cover")
+def min_edge_cover(G, matching_algorithm=None):
+    """Returns a set of edges which constitutes
+    the minimum edge cover of the graph.
+
+    The smallest edge cover can be found in polynomial time by finding
+    a maximum matching and extending it greedily so that all nodes
+    are covered.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+        An undirected bipartite graph.
+
+    matching_algorithm : function
+        A function that returns a maximum cardinality matching in a
+        given bipartite graph. The function must take one input, the
+        graph ``G``, and return a dictionary mapping each node to its
+        mate. If not specified,
+        :func:`~networkx.algorithms.bipartite.matching.hopcroft_karp_matching`
+        will be used. Other possibilities include
+        :func:`~networkx.algorithms.bipartite.matching.eppstein_matching`,
+
+    Returns
+    -------
+    set
+        A set of the edges in a minimum edge cover of the graph, given as
+        pairs of nodes. It contains both the edges `(u, v)` and `(v, u)`
+        for given nodes `u` and `v` among the edges of minimum edge cover.
+
+    Notes
+    -----
+    An edge cover of a graph is a set of edges such that every node of
+    the graph is incident to at least one edge of the set.
+    A minimum edge cover is an edge covering of smallest cardinality.
+
+    Due to its implementation, the worst-case running time of this algorithm
+    is bounded by the worst-case running time of the function
+    ``matching_algorithm``.
+    """
+    if G.order() == 0:  # Special case for the empty graph
+        return set()
+    if matching_algorithm is None:
+        matching_algorithm = hopcroft_karp_matching
+    return _min_edge_cover(G, matching_algorithm=matching_algorithm)

package/runtime/python/okstra_vendor/networkx/algorithms/bipartite/edgelist.py

@@ -0,0 +1,360 @@
+"""
+********************
+Bipartite Edge Lists
+********************
+Read and write NetworkX graphs as bipartite edge lists.
+
+Format
+------
+You can read or write three formats of edge lists with these functions.
+
+Node pairs with no data::
+
+ 1 2
+
+Python dictionary as data::
+
+ 1 2 {'weight':7, 'color':'green'}
+
+Arbitrary data::
+
+ 1 2 7 green
+
+For each edge (u, v) the node u is assigned to part 0 and the node v to part 1.
+"""
+
+__all__ = ["generate_edgelist", "write_edgelist", "parse_edgelist", "read_edgelist"]
+
+import networkx as nx
+from networkx.utils import not_implemented_for, open_file
+
+
+@open_file(1, mode="wb")
+def write_edgelist(G, path, comments="#", delimiter=" ", data=True, encoding="utf-8"):
+    """Write a bipartite graph as a list of edges.
+
+    Parameters
+    ----------
+    G : Graph
+       A NetworkX bipartite graph
+    path : file or string
+       File or filename to write. If a file is provided, it must be
+       opened in 'wb' mode. Filenames ending in .gz or .bz2 will be compressed.
+    comments : string, optional
+       The character used to indicate the start of a comment
+    delimiter : string, optional
+       The string used to separate values.  The default is whitespace.
+    data : bool or list, optional
+       If False write no edge data.
+       If True write a string representation of the edge data dictionary..
+       If a list (or other iterable) is provided, write the  keys specified
+       in the list.
+    encoding: string, optional
+       Specify which encoding to use when writing file.
+
+    Examples
+    --------
+    >>> G = nx.path_graph(4)
+    >>> G.add_nodes_from([0, 2], bipartite=0)
+    >>> G.add_nodes_from([1, 3], bipartite=1)
+    >>> nx.write_edgelist(G, "test.edgelist")
+    >>> fh = open("test.edgelist_open", "wb")
+    >>> nx.write_edgelist(G, fh)
+    >>> nx.write_edgelist(G, "test.edgelist.gz")
+    >>> nx.write_edgelist(G, "test.edgelist_nodata.gz", data=False)
+
+    >>> G = nx.Graph()
+    >>> G.add_edge(1, 2, weight=7, color="red")
+    >>> nx.write_edgelist(G, "test.edgelist_bigger_nodata", data=False)
+    >>> nx.write_edgelist(G, "test.edgelist_color", data=["color"])
+    >>> nx.write_edgelist(G, "test.edgelist_color_weight", data=["color", "weight"])
+
+    See Also
+    --------
+    write_edgelist
+    generate_edgelist
+    """
+    for line in generate_edgelist(G, delimiter, data):
+        line += "\n"
+        path.write(line.encode(encoding))
+
+
+@not_implemented_for("directed")
+def generate_edgelist(G, delimiter=" ", data=True):
+    """Generate a single line of the bipartite graph G in edge list format.
+
+    Parameters
+    ----------
+    G : NetworkX graph
+       The graph is assumed to have node attribute `part` set to 0,1 representing
+       the two graph parts
+
+    delimiter : string, optional
+       Separator for node labels
+
+    data : bool or list of keys
+       If False generate no edge data.  If True use a dictionary
+       representation of edge data.  If a list of keys use a list of data
+       values corresponding to the keys.
+
+    Returns
+    -------
+    lines : string
+        Lines of data in adjlist format.
+
+    Examples
+    --------
+    >>> from networkx.algorithms import bipartite
+    >>> G = nx.path_graph(4)
+    >>> G.add_nodes_from([0, 2], bipartite=0)
+    >>> G.add_nodes_from([1, 3], bipartite=1)
+    >>> G[1][2]["weight"] = 3
+    >>> G[2][3]["capacity"] = 12
+    >>> for line in bipartite.generate_edgelist(G, data=False):
+    ...     print(line)
+    0 1
+    2 1
+    2 3
+
+    >>> for line in bipartite.generate_edgelist(G):
+    ...     print(line)
+    0 1 {}
+    2 1 {'weight': 3}
+    2 3 {'capacity': 12}
+
+    >>> for line in bipartite.generate_edgelist(G, data=["weight"]):
+    ...     print(line)
+    0 1
+    2 1 3
+    2 3
+    """
+    try:
+        part0 = [n for n, d in G.nodes.items() if d["bipartite"] == 0]
+    except BaseException as err:
+        raise AttributeError("Missing node attribute `bipartite`") from err
+    if data is True or data is False:
+        for n in part0:
+            for edge in G.edges(n, data=data):
+                yield delimiter.join(map(str, edge))
+    else:
+        for n in part0:
+            for u, v, d in G.edges(n, data=True):
+                edge = [u, v]
+                try:
+                    edge.extend(d[k] for k in data)
+                except KeyError:
+                    pass  # missing data for this edge, should warn?
+                yield delimiter.join(map(str, edge))
+
+
+@nx._dispatchable(name="bipartite_parse_edgelist", graphs=None, returns_graph=True)
+def parse_edgelist(
+    lines, comments="#", delimiter=None, create_using=None, nodetype=None, data=True
+):
+    """Parse lines of an edge list representation of a bipartite graph.
+
+    Parameters
+    ----------
+    lines : list or iterator of strings
+        Input data in edgelist format
+    comments : string, optional
+       Marker for comment lines
+    delimiter : string, optional
+       Separator for node labels
+    create_using: NetworkX graph container, optional
+       Use given NetworkX graph for holding nodes or edges.
+    nodetype : Python type, optional
+       Convert nodes to this type.
+    data : bool or list of (label,type) tuples
+       If False generate no edge data or if True use a dictionary
+       representation of edge data or a list tuples specifying dictionary
+       key names and types for edge data.
+
+    Returns
+    -------
+    G: NetworkX Graph
+        The bipartite graph corresponding to lines
+
+    Examples
+    --------
+    Edgelist with no data:
+
+    >>> from networkx.algorithms import bipartite
+    >>> lines = ["1 2", "2 3", "3 4"]
+    >>> G = bipartite.parse_edgelist(lines, nodetype=int)
+    >>> sorted(G.nodes())
+    [1, 2, 3, 4]
+    >>> sorted(G.nodes(data=True))
+    [(1, {'bipartite': 0}), (2, {'bipartite': 0}), (3, {'bipartite': 0}), (4, {'bipartite': 1})]
+    >>> sorted(G.edges())
+    [(1, 2), (2, 3), (3, 4)]
+
+    Edgelist with data in Python dictionary representation:
+
+    >>> lines = ["1 2 {'weight':3}", "2 3 {'weight':27}", "3 4 {'weight':3.0}"]
+    >>> G = bipartite.parse_edgelist(lines, nodetype=int)
+    >>> sorted(G.nodes())
+    [1, 2, 3, 4]
+    >>> sorted(G.edges(data=True))
+    [(1, 2, {'weight': 3}), (2, 3, {'weight': 27}), (3, 4, {'weight': 3.0})]
+
+    Edgelist with data in a list:
+
+    >>> lines = ["1 2 3", "2 3 27", "3 4 3.0"]
+    >>> G = bipartite.parse_edgelist(lines, nodetype=int, data=(("weight", float),))
+    >>> sorted(G.nodes())
+    [1, 2, 3, 4]
+    >>> sorted(G.edges(data=True))
+    [(1, 2, {'weight': 3.0}), (2, 3, {'weight': 27.0}), (3, 4, {'weight': 3.0})]
+
+    See Also
+    --------
+    """
+    from ast import literal_eval
+
+    G = nx.empty_graph(0, create_using)
+    for line in lines:
+        p = line.find(comments)
+        if p >= 0:
+            line = line[:p]
+        if not len(line):
+            continue
+        # split line, should have 2 or more
+        s = line.rstrip("\n").split(delimiter)
+        if len(s) < 2:
+            continue
+        u = s.pop(0)
+        v = s.pop(0)
+        d = s
+        if nodetype is not None:
+            try:
+                u = nodetype(u)
+                v = nodetype(v)
+            except BaseException as err:
+                raise TypeError(
+                    f"Failed to convert nodes {u},{v} to type {nodetype}."
+                ) from err
+
+        if len(d) == 0 or data is False:
+            # no data or data type specified
+            edgedata = {}
+        elif data is True:
+            # no edge types specified
+            try:  # try to evaluate as dictionary
+                edgedata = dict(literal_eval(" ".join(d)))
+            except BaseException as err:
+                raise TypeError(
+                    f"Failed to convert edge data ({d}) to dictionary."
+                ) from err
+        else:
+            # convert edge data to dictionary with specified keys and type
+            if len(d) != len(data):
+                raise IndexError(
+                    f"Edge data {d} and data_keys {data} are not the same length"
+                )
+            edgedata = {}
+            for (edge_key, edge_type), edge_value in zip(data, d):
+                try:
+                    edge_value = edge_type(edge_value)
+                except BaseException as err:
+                    raise TypeError(
+                        f"Failed to convert {edge_key} data "
+                        f"{edge_value} to type {edge_type}."
+                    ) from err
+                edgedata.update({edge_key: edge_value})
+        G.add_node(u, bipartite=0)
+        G.add_node(v, bipartite=1)
+        G.add_edge(u, v, **edgedata)
+    return G
+
+
+@open_file(0, mode="rb")
+@nx._dispatchable(name="bipartite_read_edgelist", graphs=None, returns_graph=True)
+def read_edgelist(
+    path,
+    comments="#",
+    delimiter=None,
+    create_using=None,
+    nodetype=None,
+    data=True,
+    edgetype=None,
+    encoding="utf-8",
+):
+    """Read a bipartite graph from a list of edges.
+
+    Parameters
+    ----------
+    path : file or string
+       File or filename to read. If a file is provided, it must be
+       opened in 'rb' mode.
+       Filenames ending in .gz or .bz2 will be decompressed.
+    comments : string, optional
+       The character used to indicate the start of a comment.
+    delimiter : string, optional
+       The string used to separate values.  The default is whitespace.
+    create_using : Graph container, optional,
+       Use specified container to build graph.  The default is networkx.Graph,
+       an undirected graph.
+    nodetype : int, float, str, Python type, optional
+       Convert node data from strings to specified type
+    data : bool or list of (label,type) tuples
+       Tuples specifying dictionary key names and types for edge data
+    edgetype : int, float, str, Python type, optional OBSOLETE
+       Convert edge data from strings to specified type and use as 'weight'
+    encoding: string, optional
+       Specify which encoding to use when reading file.
+
+    Returns
+    -------
+    G : graph
+       A networkx Graph or other type specified with create_using
+
+    Examples
+    --------
+    >>> from networkx.algorithms import bipartite
+    >>> G = nx.path_graph(4)
+    >>> G.add_nodes_from([0, 2], bipartite=0)
+    >>> G.add_nodes_from([1, 3], bipartite=1)
+    >>> bipartite.write_edgelist(G, "test.edgelist")
+    >>> G = bipartite.read_edgelist("test.edgelist")
+
+    >>> fh = open("test.edgelist", "rb")
+    >>> G = bipartite.read_edgelist(fh)
+    >>> fh.close()
+
+    >>> G = bipartite.read_edgelist("test.edgelist", nodetype=int)
+
+    Edgelist with data in a list:
+
+    >>> textline = "1 2 3"
+    >>> fh = open("test.edgelist", "w")
+    >>> d = fh.write(textline)
+    >>> fh.close()
+    >>> G = bipartite.read_edgelist(
+    ...     "test.edgelist", nodetype=int, data=(("weight", float),)
+    ... )
+    >>> list(G)
+    [1, 2]
+    >>> list(G.edges(data=True))
+    [(1, 2, {'weight': 3.0})]
+
+    See parse_edgelist() for more examples of formatting.
+
+    See Also
+    --------
+    parse_edgelist
+
+    Notes
+    -----
+    Since nodes must be hashable, the function nodetype must return hashable
+    types (e.g. int, float, str, frozenset - or tuples of those, etc.)
+    """
+    lines = (line.decode(encoding) for line in path)
+    return parse_edgelist(
+        lines,
+        comments=comments,
+        delimiter=delimiter,
+        create_using=create_using,
+        nodetype=nodetype,
+        data=data,
+    )