vispy 0.15.0__cp313-cp313-macosx_11_0_arm64.whl

vispy/visuals/graphs/layouts/force_directed.py

@@ -0,0 +1,211 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Vispy Development Team. All Rights Reserved.
+# Distributed under the (new) BSD License. See LICENSE.txt for more info.
+"""
+Force-Directed Graph Layout
+===========================
+
+This module contains implementations for a force-directed layout, where the
+graph is modelled like a collection of springs or as a collection of
+particles attracting and repelling each other. The whole graph tries to
+reach a state which requires the minimum energy.
+"""
+
+import numpy as np
+
+try:
+    from scipy.sparse import issparse
+except ImportError:
+    def issparse(*args, **kwargs):
+        return False
+
+from ..util import _straight_line_vertices, _rescale_layout
+
+
+class fruchterman_reingold(object):
+    r"""Fruchterman-Reingold implementation adapted from NetworkX.
+
+    In the Fruchterman-Reingold algorithm, the whole graph is modelled as a
+    collection of particles, it runs a simplified particle simulation to
+    find a nice layout for the graph.
+
+    Parameters
+    ----------
+    optimal : number
+        Optimal distance between nodes. Defaults to :math:`1/\\sqrt{N}` where
+        N is the number of nodes.
+    iterations : int
+        Number of iterations to perform for layout calculation.
+    pos : array
+        Initial positions of the nodes
+
+    Notes
+    -----
+    The algorithm is explained in more detail in the original paper [1]_.
+
+    .. [1] Fruchterman, Thomas MJ, and Edward M. Reingold. "Graph drawing by
+       force-directed placement." Softw., Pract. Exper. 21.11 (1991),
+       1129-1164.
+    """
+
+    def __init__(self, optimal=None, iterations=50, pos=None):
+        self.dim = 2
+        self.optimal = optimal
+        self.iterations = iterations
+        self.num_nodes = None
+        self.pos = pos
+
+    def __call__(self, adjacency_mat, directed=False):
+        """
+        Starts the calculation of the graph layout.
+
+        This is a generator, and after each iteration it yields the new
+        positions for the nodes, together with the vertices for the edges
+        and the arrows.
+
+        There are two solvers here: one specially adapted for SciPy sparse
+        matrices, and the other for larger networks.
+
+        Parameters
+        ----------
+        adjacency_mat : array
+            The graph adjacency matrix.
+        directed : bool
+            Wether the graph is directed or not. If this is True,
+            it will draw arrows for directed edges.
+
+        Yields
+        ------
+        layout : tuple
+            For each iteration of the layout calculation it yields a tuple
+            containing (node_vertices, line_vertices, arrow_vertices). These
+            vertices can be passed to the `MarkersVisual` and `ArrowVisual`.
+        """
+        if adjacency_mat.shape[0] != adjacency_mat.shape[1]:
+            raise ValueError("Adjacency matrix should be square.")
+
+        self.num_nodes = adjacency_mat.shape[0]
+
+        if issparse(adjacency_mat):
+            # Use the sparse solver
+            solver = self._sparse_fruchterman_reingold
+        else:
+            solver = self._fruchterman_reingold
+
+        for result in solver(adjacency_mat, directed):
+            yield result
+
+    def _fruchterman_reingold(self, adjacency_mat, directed=False):
+        if self.optimal is None:
+            self.optimal = 1 / np.sqrt(self.num_nodes)
+
+        if self.pos is None:
+            # Random initial positions
+            pos = np.asarray(
+                np.random.random((self.num_nodes, self.dim)),
+                dtype=np.float32
+            )
+        else:
+            pos = self.pos.astype(np.float32)
+
+        # Yield initial positions
+        line_vertices, arrows = _straight_line_vertices(adjacency_mat, pos,
+                                                        directed)
+        yield pos, line_vertices, arrows
+
+        # The initial "temperature"  is about .1 of domain area (=1x1)
+        # this is the largest step allowed in the dynamics.
+        t = 0.1
+
+        # Simple cooling scheme.
+        # Linearly step down by dt on each iteration so last iteration is
+        # size dt.
+        dt = t / float(self.iterations+1)
+        # The inscrutable (but fast) version
+        # This is still O(V^2)
+        # Could use multilevel methods to speed this up significantly
+        for iteration in range(self.iterations):
+            delta_pos = _calculate_delta_pos(adjacency_mat, pos, t,
+                                             self.optimal)
+            pos += delta_pos
+            _rescale_layout(pos)
+
+            # cool temperature
+            t -= dt
+
+            # Calculate edge vertices and arrows
+            line_vertices, arrows = _straight_line_vertices(adjacency_mat,
+                                                            pos, directed)
+
+            yield pos, line_vertices, arrows
+
+    def _sparse_fruchterman_reingold(self, adjacency_mat, directed=False):
+        # Optimal distance between nodes
+        if self.optimal is None:
+            self.optimal = 1 / np.sqrt(self.num_nodes)
+
+        # Change to list of list format
+        # Also construct the matrix in COO format for easy edge construction
+        adjacency_arr = adjacency_mat.toarray()
+        adjacency_coo = adjacency_mat.tocoo()
+
+        if self.pos is None:
+            # Random initial positions
+            pos = np.asarray(
+                np.random.random((self.num_nodes, self.dim)),
+                dtype=np.float32
+            )
+        else:
+            pos = self.pos.astype(np.float32)
+
+        # Yield initial positions
+        line_vertices, arrows = _straight_line_vertices(adjacency_coo, pos,
+                                                        directed)
+        yield pos, line_vertices, arrows
+
+        # The initial "temperature"  is about .1 of domain area (=1x1)
+        # This is the largest step allowed in the dynamics.
+        t = 0.1
+        # Simple cooling scheme.
+        # Linearly step down by dt on each iteration so last iteration is
+        # size dt.
+        dt = t / float(self.iterations+1)
+        for iteration in range(self.iterations):
+            delta_pos = _calculate_delta_pos(adjacency_arr, pos, t,
+                                             self.optimal)
+            pos += delta_pos
+            _rescale_layout(pos)
+
+            # Cool temperature
+            t -= dt
+
+            # Calculate line vertices
+            line_vertices, arrows = _straight_line_vertices(adjacency_coo,
+                                                            pos, directed)
+
+            yield pos, line_vertices, arrows
+
+
+def _calculate_delta_pos(adjacency_arr, pos, t, optimal):
+    """Helper to calculate the delta position"""
+    # XXX eventually this should be refactored for the sparse case to only
+    # do the necessary pairwise distances
+    delta = pos[:, np.newaxis, :] - pos
+
+    # Distance between points
+    distance2 = (delta*delta).sum(axis=-1)
+    # Enforce minimum distance of 0.01
+    distance2 = np.where(distance2 < 0.0001, 0.0001, distance2)
+    distance = np.sqrt(distance2)
+    # Displacement "force"
+    displacement = np.zeros((len(delta), 2))
+    for ii in range(2):
+        displacement[:, ii] = (
+            delta[:, :, ii] *
+            ((optimal * optimal) / (distance*distance) -
+             (adjacency_arr * distance) / optimal)).sum(axis=1)
+
+    length = np.sqrt((displacement**2).sum(axis=1))
+    length = np.where(length < 0.01, 0.1, length)
+    delta_pos = displacement * t / length[:, np.newaxis]
+    return delta_pos

vispy/visuals/graphs/layouts/networkx_layout.py

@@ -0,0 +1,87 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Vispy Development Team. All Rights Reserved.
+# Distributed under the (new) BSD License. See LICENSE.txt for more info.#!/usr/bin/env python3
+from ..util import _straight_line_vertices, issparse
+import numpy as np
+try:
+    import networkx as nx
+except ModuleNotFoundError:
+    nx = None
+
+
+class NetworkxCoordinates:
+    def __init__(self, graph=None, layout=None, **kwargs):
+        """
+        Converts :graph: into a layout. Can be used in conjunction with networkx layouts or using raw 2D-numpy arrays.
+
+        Parameters
+        ----------
+        graph : a networkx graph.
+        layout : str or dict or iterable-object of float32, optional
+        - When :layout: is s string, a lookup will be performed in the networkx avaiable layouts.
+        - When :layout: is a dict, it will be assumed that it takes the shape (key, value) = (node_id, 2D-coordinate).
+        - When :layout: is numpy array it is assumed it takes the shape (number_of_nodes, 2).
+        kwargs: dict, optional
+        when layout is :str: :kwargs: will act as a setting dictionary for the layout function of networkx
+        """
+        if nx is None:
+            raise ValueError("networkx not found, please install networkx to use its layouts")
+        if isinstance(graph, type(None)):
+            raise ValueError("Requires networkx input")
+        self.graph = graph
+        self.positions = np.zeros((len(graph), 2), dtype=np.float32)
+        # default random positions
+        if isinstance(layout, type(None)):
+            self.positions = np.random.rand(*self.positions.shape)
+
+        # check for networkx
+        elif isinstance(layout, str):
+            if not layout.endswith("_layout"):
+                layout += "_layout"  # append for nx
+            layout_function = getattr(nx, layout)
+            if layout_function:
+                self.positions = np.asarray(
+                    [i for i in dict(layout_function(graph, **kwargs)).values()])
+            else:
+                raise ValueError("Check networkx for layouts")
+        # assume dict from networkx; values are 2-array
+        elif isinstance(layout, dict):
+            self.positions = np.asarray([i for i in layout.values()])
+
+        # assume given values
+        elif isinstance(layout, np.ndarray):
+            assert layout.ndim == 2
+            assert layout.shape[0] == len(graph)
+            self.positions = layout
+        else:
+            raise ValueError("Input not understood")
+
+        # normalize coordinates
+        self.positions = (self.positions - self.positions.min()) / \
+            (self.positions.max() - self.positions.min())
+        self.positions = self.positions.astype(np.float32)
+
+    def __call__(self, adjacency_mat, directed=False):
+        """
+        Parameters
+        ----------
+        adjacency_mat : sparse adjacency matrix.
+        directed : bool, default False
+
+        Returns
+        ---------
+        (node_vertices, line_vertices, arrow_vertices) : tuple
+        Yields the node and line vertices in a tuple. This layout only yields a
+        single time, and has no builtin animation
+        """
+        if issparse(adjacency_mat):
+            adjacency_mat = adjacency_mat.tocoo()
+        line_vertices, arrows = _straight_line_vertices(
+            adjacency_mat, self.positions, directed)
+
+        yield self.positions, line_vertices, arrows
+
+    @property
+    def adj(self):
+        """Convenient storage and holder of the adjacency matrix for the :scene.visuals.Graph: function."""
+        return nx.adjacency_matrix(self.graph)

vispy/visuals/graphs/layouts/random.py

@@ -0,0 +1,52 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Vispy Development Team. All Rights Reserved.
+# Distributed under the (new) BSD License. See LICENSE.txt for more info.
+"""
+Random Graph Layout
+====================
+
+This layout positions the nodes at random
+"""
+
+import numpy as np
+
+from ..util import _straight_line_vertices, issparse
+
+
+def random(adjacency_mat, directed=False, random_state=None):
+    """
+    Place the graph nodes at random places.
+
+    Parameters
+    ----------
+    adjacency_mat : matrix or sparse
+        The graph adjacency matrix
+    directed : bool
+        Whether the graph is directed. If this is True, is will also
+        generate the vertices for arrows, which can be passed to an
+        ArrowVisual.
+    random_state : instance of RandomState | int | None
+        Random state to use. Can be None to use ``np.random``.
+
+    Yields
+    ------
+    (node_vertices, line_vertices, arrow_vertices) : tuple
+        Yields the node and line vertices in a tuple. This layout only yields a
+        single time, and has no builtin animation
+    """
+    if random_state is None:
+        random_state = np.random
+    elif not isinstance(random_state, np.random.RandomState):
+        random_state = np.random.RandomState(random_state)
+
+    if issparse(adjacency_mat):
+        adjacency_mat = adjacency_mat.tocoo()
+
+    # Randomly place nodes, visual coordinate system is between 0 and 1
+    num_nodes = adjacency_mat.shape[0]
+    node_coords = random_state.rand(num_nodes, 2)
+
+    line_vertices, arrows = _straight_line_vertices(adjacency_mat,
+                                                    node_coords, directed)
+
+    yield node_coords, line_vertices, arrows

vispy/visuals/graphs/tests/__init__.py

@@ -0,0 +1 @@
+__author__ = 'lucas'

vispy/visuals/graphs/tests/test_layouts.py

@@ -0,0 +1,139 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Vispy Development Team. All Rights Reserved.
+# Distributed under the (new) BSD License. See LICENSE.txt for more info.
+
+import numpy as np
+from numpy.testing import assert_allclose, assert_equal
+
+from vispy.visuals.graphs.layouts import get_layout
+from vispy.testing import (run_tests_if_main, assert_raises)
+
+
+adjacency_mat = np.array([
+    [0, 1, 0, 0, 0, 0, 0, 0, 0, 0],
+    [1, 0, 0, 0, 1, 0, 1, 1, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 1, 0],
+    [0, 1, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 1, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 1, 0, 0, 0, 0, 0, 0, 0, 0],
+    [0, 0, 0, 1, 0, 0, 0, 0, 0, 1],
+    [0, 0, 0, 0, 0, 0, 0, 0, 1, 0]
+])
+
+
+def test_get_layout():
+    from vispy.visuals.graphs.layouts.random import random
+
+    # Simple retrieval
+    assert_equal(random, get_layout('random'))
+
+    # Pass arguments
+    fruchterman_reingold = get_layout('force_directed', iterations=100)
+    assert_equal(fruchterman_reingold.iterations, 100)
+
+    # Check if layout exists
+    assert_raises(KeyError, get_layout, 'fdgdfgs_non_existent')
+
+
+def test_random_layout():
+    layout = get_layout('random')
+
+    expected_pos = np.array([
+        [0.22270932715095826, 0.7728936927702302],
+        [0.6298054094517744, 0.21851589821484974],
+        [0.75002099889163, 0.5592076821676369],
+        [0.1786754307911973, 0.6442165368790972],
+        [0.5979199081208609, 0.615159318836822],
+        [0.46328431255222746, 0.3582897386994869],
+        [0.9595461883180398, 0.2350580044144016],
+        [0.094482942129406, 0.20584398882694932],
+        [0.5758593091748346, 0.8158957494444451],
+        [0.5908647616961652, 0.1584550825482285]
+    ])
+
+    expected_vertices = np.array([
+        [0.22270932715095826, 0.7728936927702302],
+        [0.6298054094517744, 0.21851589821484974],
+        [0.6298054094517744, 0.21851589821484974],
+        [0.22270932715095826, 0.7728936927702302],
+        [0.6298054094517744, 0.21851589821484974],
+        [0.5979199081208609, 0.615159318836822],
+        [0.6298054094517744, 0.21851589821484974],
+        [0.9595461883180398, 0.2350580044144016],
+        [0.6298054094517744, 0.21851589821484974],
+        [0.094482942129406, 0.20584398882694932],
+        [0.1786754307911973, 0.6442165368790972],
+        [0.5758593091748346, 0.8158957494444451],
+        [0.5979199081208609, 0.615159318836822],
+        [0.6298054094517744, 0.21851589821484974],
+        [0.9595461883180398, 0.2350580044144016],
+        [0.6298054094517744, 0.21851589821484974],
+        [0.094482942129406, 0.20584398882694932],
+        [0.6298054094517744, 0.21851589821484974],
+        [0.5758593091748346, 0.8158957494444451],
+        [0.1786754307911973, 0.6442165368790972],
+        [0.5758593091748346, 0.8158957494444451],
+        [0.5908647616961652, 0.1584550825482285],
+        [0.5908647616961652, 0.1584550825482285],
+        [0.5758593091748346, 0.8158957494444451]
+    ])
+
+    pos, line_vertices, arrows = next(layout(adjacency_mat,
+                                             random_state=0xDEADBEEF))
+
+    assert_allclose(pos, expected_pos, atol=1e-7)
+    assert_allclose(line_vertices, expected_vertices, atol=1e-7)
+
+
+def test_circular_layout():
+    layout = get_layout('circular')
+
+    expected_pos = np.array([
+        [1.0, 0.5],
+        [0.9045084714889526, 0.7938926219940186],
+        [0.6545084714889526, 0.9755282402038574],
+        [0.3454914689064026, 0.9755282402038574],
+        [0.09549146890640259, 0.7938926219940186],
+        [0.0, 0.4999999701976776],
+        [0.09549152851104736, 0.20610731840133667],
+        [0.3454914689064026, 0.024471759796142578],
+        [0.6545085906982422, 0.024471759796142578],
+        [0.9045084714889526, 0.20610734820365906]
+    ])
+
+    expected_vertices = np.array([
+        [1.0, 0.5],
+        [0.9045084714889526, 0.7938926219940186],
+        [0.9045084714889526, 0.7938926219940186],
+        [1.0, 0.5],
+        [0.9045084714889526, 0.7938926219940186],
+        [0.09549146890640259, 0.7938926219940186],
+        [0.9045084714889526, 0.7938926219940186],
+        [0.09549152851104736, 0.20610731840133667],
+        [0.9045084714889526, 0.7938926219940186],
+        [0.3454914689064026, 0.024471759796142578],
+        [0.3454914689064026, 0.9755282402038574],
+        [0.6545085906982422, 0.024471759796142578],
+        [0.09549146890640259, 0.7938926219940186],
+        [0.9045084714889526, 0.7938926219940186],
+        [0.09549152851104736, 0.20610731840133667],
+        [0.9045084714889526, 0.7938926219940186],
+        [0.3454914689064026, 0.024471759796142578],
+        [0.9045084714889526, 0.7938926219940186],
+        [0.6545085906982422, 0.024471759796142578],
+        [0.3454914689064026, 0.9755282402038574],
+        [0.6545085906982422, 0.024471759796142578],
+        [0.9045084714889526, 0.20610734820365906],
+        [0.9045084714889526, 0.20610734820365906],
+        [0.6545085906982422, 0.024471759796142578]
+    ])
+
+    pos, line_vertices, arrows = next(layout(adjacency_mat))
+
+    assert_allclose(pos, expected_pos, atol=1e-4)
+    assert_allclose(line_vertices, expected_vertices, atol=1e-4)
+
+
+run_tests_if_main()

vispy/visuals/graphs/tests/test_networkx_layout.py

@@ -0,0 +1,47 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Vispy Development Team. All Rights Reserved.
+# Distributed under the (new) BSD License. See LICENSE.txt for more info.
+from vispy import testing
+from vispy.visuals.graphs.layouts import get_layout
+from vispy.visuals.graphs.layouts.networkx_layout import NetworkxCoordinates
+import numpy as np
+
+# conditional import
+try:
+    import networkx as nx
+except ModuleNotFoundError:
+    nx = None
+
+
+def test_networkx_layout_with_graph():
+    """Testing the various inputs to the networkx layout."""
+    settings = dict(name="networkx_layout")
+    if nx is None:
+        return testing.SkipTest("'networkx' required")
+
+    # empty input
+    # testing.assert_raises(ValueError("Requires networkx input"), get_layout(**settings))
+
+    # define graph
+    graph = nx.complete_graph(5)
+    # define positions
+    layout = np.random.rand(5, 2)
+    settings['graph'] = graph
+    settings['layout'] = layout
+
+    # test numpy array input
+    testing.assert_true(isinstance(
+        get_layout(**settings), NetworkxCoordinates))
+    # testing string input
+    settings['layout'] = 'circular'
+    testing.assert_true(isinstance(
+        get_layout(**settings), NetworkxCoordinates))
+    # testing dict input
+    settings['layout'] = nx.circular_layout(graph)
+    testing.assert_true(isinstance(
+        get_layout(**settings), NetworkxCoordinates))
+
+
+def test_networkx_layout_no_networkx():
+    settings = dict(name="networkx_layout")
+    testing.assert_raises(ValueError, get_layout, **settings)

vispy/visuals/graphs/util.py

@@ -0,0 +1,120 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Vispy Development Team. All Rights Reserved.
+# Distributed under the (new) BSD License. See LICENSE.txt for more info.
+"""
+Graph utilities
+===============
+
+A module containing several graph utility functions.
+"""
+
+import numpy as np
+
+try:
+    from scipy.sparse import issparse
+    from scipy import sparse
+except ImportError:
+    def issparse(*args, **kwargs):
+        return False
+
+
+def _get_edges(adjacency_mat):
+    func = _sparse_get_edges if issparse(adjacency_mat) else _ndarray_get_edges
+    return func(adjacency_mat)
+
+
+def _sparse_get_edges(adjacency_mat):
+    return np.concatenate((adjacency_mat.row[:, np.newaxis],
+                           adjacency_mat.col[:, np.newaxis]), axis=-1)
+
+
+def _ndarray_get_edges(adjacency_mat):
+    # Get indices of all non zero values
+    i, j = np.where(adjacency_mat)
+
+    return np.concatenate((i[:, np.newaxis], j[:, np.newaxis]), axis=-1)
+
+
+def _get_directed_edges(adjacency_mat):
+    func = _sparse_get_edges if issparse(adjacency_mat) else _ndarray_get_edges
+
+    if issparse(adjacency_mat):
+        triu = sparse.triu
+        tril = sparse.tril
+    else:
+        triu = np.triu
+        tril = np.tril
+
+    upper = triu(adjacency_mat)
+    lower = tril(adjacency_mat)
+
+    return np.concatenate((func(upper), func(lower)))
+
+
+def _straight_line_vertices(adjacency_mat, node_coords, directed=False):
+    """
+    Generate the vertices for straight lines between nodes.
+
+    If it is a directed graph, it also generates the vertices which can be
+    passed to an :class:`ArrowVisual`.
+
+    Parameters
+    ----------
+    adjacency_mat : array
+        The adjacency matrix of the graph
+    node_coords : array
+        The current coordinates of all nodes in the graph
+    directed : bool
+        Wether the graph is directed. If this is true it will also generate
+        the vertices for arrows which can be passed to :class:`ArrowVisual`.
+
+    Returns
+    -------
+    vertices : tuple
+        Returns a tuple containing containing (`line_vertices`,
+        `arrow_vertices`)
+    """
+    if not issparse(adjacency_mat):
+        adjacency_mat = np.asarray(adjacency_mat, float)
+
+    if (adjacency_mat.ndim != 2 or adjacency_mat.shape[0] !=
+            adjacency_mat.shape[1]):
+        raise ValueError("Adjacency matrix should be square.")
+
+    arrow_vertices = np.array([])
+
+    edges = _get_edges(adjacency_mat)
+    line_vertices = node_coords[edges.ravel()]
+
+    if directed:
+        arrows = np.array(list(_get_directed_edges(adjacency_mat)))
+        arrow_vertices = node_coords[arrows.ravel()]
+        arrow_vertices = arrow_vertices.reshape((len(arrow_vertices)//2, 4))
+
+    return line_vertices, arrow_vertices
+
+
+def _rescale_layout(pos, scale=1):
+    """
+    Normalize the given coordinate list to the range [0, `scale`].
+
+    Parameters
+    ----------
+    pos : array
+        Coordinate list
+    scale : number
+        The upperbound value for the coordinates range
+
+    Returns
+    -------
+    pos : array
+        The rescaled (normalized) coordinates in the range [0, `scale`].
+
+    Notes
+    -----
+    Changes `pos` in place.
+    """
+    pos -= pos.min(axis=0)
+    pos *= scale / pos.max()
+
+    return pos