Overview

The AlgorithmX API provides a selection-based interface for creating interactive network visualizations. At the root of each visualization is a Canvas, which can be created either through a HTTP Server (canvas()), or a Jupyter widget (jupyter_canvas()).

The purpose of the library is to provide a way to manipulate the graphics representing a network, through a series of events which are sent to the client. As such, it does not keep track of any state (except for callbacks). In order to store and analyze the network, you can combine this with another library, such as NetworkX.

Using Selections

Every selection corresponds to one or more graphical objects in the network. If a selection is created with objects that do not exist in the network yet, these can be added by calling add(). Selections will provide a range of methods for setting custom attributes, configuring animations, and interacting with event queues.

Below is an example showing how selections can be created, added, modified and removed:

# Add a big red node
canvas.node('A').add(color='red', size=30)

# Add a label to the node
canvas.node('A').label(1).add(text='My Label')

# Pause for half a second
canvas.pause(0.5)

# Modify the color of the node
canvas.node('A').color('blue')

# Temporarily make the node 1.25 times as big
canvas.node('A').highlight().size('1.25x')

# Add a few more modes
canvas.nodes([1, 2, 3]).add()

# Add an edge
canvas.edge((2, 3)).add()

# Remove the first node
canvas.node('A').remove()

Attributes can also be configured using the attrs() method:

# Configure the attributes of a label
canvas.node(1).label(2).attrs(
    text='Hello',
    color='red'
    size=45,
    font='Courier'
)

Functional Arguments

All selection methods can take functions as arguments, allowing attributes to be configured differently depending on each element’s data and index within the selection.

# Conditionally set color using id
canvas.nodes(['A', 'B']).color(lambda n: 'red' if n == 'A' else 'blue')

# Conditionally set color using index
colors = ['red', 'blue']
canvas.nodes(['A', 'B']).color(lambda _, i: colors[i])

# Conditionally set color using data binding
canvas.nodes(['A', 'B']).data(colors).color(lambda c: c)
api.types.ElementFn = typing.Union[typing.Callable[[typing.Any], ~T], typing.Callable[[typing.Any, int], ~T]]

A function taking a selected element’s data and index as input.

This is typically provided as an argument in a selection method, allowing attributes to be configured differently for each element.

Parameters

  • ElementFn.data – The data associated with the element. * If the data() method was used previously in the method chain, it will determine the type of data used. * If the selection has no associated data, it will fall back on its parent’s data (as is the case for LabelSelection). * Otherwise, the information used to construct the selection will serve as its data (such as node ID values and edge tuples).

  • ElementFn.index – (Optional) The index of the element in the selection, beginning at 0, determined by its position in the list initially used to construct the selection.

api.types.ElementArg = typing.Union[typing.Callable[[typing.Any], ~T], typing.Callable[[typing.Any, int], ~T], ~T]

Allows an argument to be provided either directly, or as a function of each element’s data (see ElementFn and data()).

Expressions

Most numerical attributes can also be specified as linear expressions, often allowing for easier configuration. Expressions use variables corresponding to other attributes; for example, a label could be positioned relative to its parent node without needing to know the node’s size, and would be re-positioned accordingly when the node’s size changes.

# Position a label in the top-left corner of a node
canvas.node('A').label().align('top-left').pos(('-x+5', 'y-5'))

# Pin a node to the canvas using a relative position
canvas.node('A').fixed(True).pos(('-0.5cx', '-0.5cy'))

# Change the size of a node relative to its current size
canvas.node('C').size(('1.25x', '1.25y'))
api.types.NumAttr = typing.Union[int, float, str, typing.Mapping]

A numerical attribute, which can also provided as a linear expression.

Expressions can be provided as an { m, x, c } dictionary, or as expression string such as “-2x+8”. Both m and c are constants, while x is a variable corresponding to some other attribute. Below is a list of valid variables and the context in which they can be used:

  • “cx”: Half the width of the canvas.

  • “cy”: Half the height of the canvas.

  • nodes

    • “x”: Half the width of the node.

    • “y”: Half the height of the node.

    • labels

      • “r”: Distance from the center of the node to its boundary given the angle attribute of the label.