toyplot.layout module

Provides layout algorithms.

class toyplot.layout.Buchheim(edges=None, basis=None)

Bases: GraphLayout

Compute a tree layout using the 2002 algorithm of Buchheim, Junger, and Leipert.

Note: this layout currently ignores preexisting vertex coordinates.

graph(vcoordinates, edges)

Compute vertex and edge coordinates for a graph.

Parameters:

• vcoordinates (\(V \times 2\) masked array) – Coordinates for every graph vertex, in vertex order. Where practical, only masked coordinates will have values assigned by the underlying algorithm.

• edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.

Returns:

• vcoordinates (\(V \times 2\) matrix) – Contains coordinates for every graph vertex, in vertex order.

• eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:

  • M - change the current coordinates without drawing (requires one set of coordinates).

  • L - draw a straight line segment (requires one set of coordinates).

  • Q - draw a quadratic Bezier curve (requires two sets of coordinates).

  • C - draw a cubic Bezier curve (requires three sets of coordinates).

• ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.

class toyplot.layout.CurvedEdges(curvature=0.15)

Bases: EdgeLayout

Creates curved edges between graph vertices.

Parameters:

• curvature (number)

• arc (Controls the curvature of each edge's)

• the (as a percentage of)

• curve (distance between the edge's vertices. Use negative values to)

• direction. (edges in the opposite)

edges(vcoordinates, edges)

Return edge coordinates for a graph.

Parameters:

• vcoordinates (\(V \times 2\) matrix) – Contains the coordinates for every graph vertex, in vertex order.

• edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.

Returns:

• eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:

  • M - change the current coordinates without drawing (requires one set of coordinates).

  • L - draw a straight line segment from the current coordinates (requires one set of coordinates).

  • Q - draw a quadratic Bezier curve from the current coordinates (requires two sets of coordinates).

  • C - draw a cubic Bezier curve from the current coordinates (requires three sets of coordinates).

• ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.

class toyplot.layout.Eades(edges=None, c1=2, c2=1, c3=1, c4=0.1, M=100, seed=1234)

Bases: GraphLayout

Compute a force directed graph layout using the 1984 algorithm of Eades.

Parameters:

• edges (toyplot.layout.EdgeLayout instance, optional) – The default will generate straight edges.

• c1 (numbers, optional) – Constants defined in Eades’ original paper.

• c2 (numbers, optional) – Constants defined in Eades’ original paper.

• c3 (numbers, optional) – Constants defined in Eades’ original paper.

• c4 (numbers, optional) – Constants defined in Eades’ original paper.

• M (integer, optional) – Number of iterations to run the spring simulation.

• seed (integer, optional) – Random seed used to initialize vertex coordinates.

graph(vcoordinates, edges)

Compute vertex and edge coordinates for a graph.

Parameters:

• vcoordinates (\(V \times 2\) masked array) – Coordinates for every graph vertex, in vertex order. Where practical, only masked coordinates will have values assigned by the underlying algorithm.

• edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.

Returns:

• vcoordinates (\(V \times 2\) matrix) – Contains coordinates for every graph vertex, in vertex order.

• eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:

  • M - change the current coordinates without drawing (requires one set of coordinates).

  • L - draw a straight line segment (requires one set of coordinates).

  • Q - draw a quadratic Bezier curve (requires two sets of coordinates).

  • C - draw a cubic Bezier curve (requires three sets of coordinates).

• ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.

class toyplot.layout.EdgeLayout

Bases: object

Abstract interface for algorithms that compute graph edge coordinates.

edges(vcoordinates, edges)

Return edge coordinates for a graph.

Parameters:

• vcoordinates (\(V \times 2\) matrix) – Contains the coordinates for every graph vertex, in vertex order.

• edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.

Returns:

• eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:

  • M - change the current coordinates without drawing (requires one set of coordinates).

  • L - draw a straight line segment from the current coordinates (requires one set of coordinates).

  • Q - draw a quadratic Bezier curve from the current coordinates (requires two sets of coordinates).

  • C - draw a cubic Bezier curve from the current coordinates (requires three sets of coordinates).

• ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.

class toyplot.layout.FruchtermanReingold(edges=None, area=1, temperature=0.1, M=50, seed=1234)

Bases: GraphLayout

Compute a force directed graph layout using the 1991 algorithm of Fruchterman and Reingold.

Parameters:

• edges (toyplot.layout.EdgeLayout instance, optional) – The default will generate straight edges.

• area (numbers, optional) – Constants defined in the original paper.

• temperature (numbers, optional) – Constants defined in the original paper.

• M (integer, optional) – Number of iterations to run the spring simulation.

• seed (integer, optional) – Random seed used to initialize vertex coordinates.

graph(vcoordinates, edges)

Compute vertex and edge coordinates for a graph.

Parameters:

• vcoordinates (\(V \times 2\) masked array) – Coordinates for every graph vertex, in vertex order. Where practical, only masked coordinates will have values assigned by the underlying algorithm.

• edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.

Returns:

• vcoordinates (\(V \times 2\) matrix) – Contains coordinates for every graph vertex, in vertex order.

• eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:

  • M - change the current coordinates without drawing (requires one set of coordinates).

  • L - draw a straight line segment (requires one set of coordinates).

  • Q - draw a quadratic Bezier curve (requires two sets of coordinates).

  • C - draw a cubic Bezier curve (requires three sets of coordinates).

• ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.

class toyplot.layout.Graph(vids, vcoordinates, edges, eshapes, ecoordinates)

Bases: object

Stores graph layout information.

Typically used when sharing a layout among more than one graph.

property ecoordinates

Return a matrix of edge coordinates. The number of coordinates is determined by the contents of the eshapes vector.

property ecount

Return the number of edges \(E\) in the graph.

property edges

Return the graph edges as a \(E \times 2\) matrix of source, target indices.

property eshapes

Return a vector of \(E\) string edge shapes.

property vcoordinates

Return graph vertex coordinates as a \(V \times 2\) matrix.

property vcount

Return the number of vertices \(V\) in the graph.

property vids

Return \(V\) graph vertex identifiers.

class toyplot.layout.GraphLayout

Bases: object

Abstract interface for algorithms that compute coordinates for graph vertices and edges.

graph(vcoordinates, edges)

Compute vertex and edge coordinates for a graph.

Parameters:

• vcoordinates (\(V \times 2\) masked array) – Coordinates for every graph vertex, in vertex order. Where practical, only masked coordinates will have values assigned by the underlying algorithm.

• edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.

Returns:

• vcoordinates (\(V \times 2\) matrix) – Contains coordinates for every graph vertex, in vertex order.

• eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:

  • M - change the current coordinates without drawing (requires one set of coordinates).

  • L - draw a straight line segment (requires one set of coordinates).

  • Q - draw a quadratic Bezier curve (requires two sets of coordinates).

  • C - draw a cubic Bezier curve (requires three sets of coordinates).

• ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.

class toyplot.layout.IgnoreVertices(edges=None)

Bases: GraphLayout

Do-nothing graph layout for use when all vertices are already specified.

Parameters:

• edges (toyplot.layout.EdgeLayout instance, optional)

• edges. (The default will generate straight)

graph(vcoordinates, edges)

Compute vertex and edge coordinates for a graph.

Parameters:

• vcoordinates (\(V \times 2\) masked array) – Coordinates for every graph vertex, in vertex order. Where practical, only masked coordinates will have values assigned by the underlying algorithm.

• edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.

Returns:

• vcoordinates (\(V \times 2\) matrix) – Contains coordinates for every graph vertex, in vertex order.

• eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:

  • M - change the current coordinates without drawing (requires one set of coordinates).

  • L - draw a straight line segment (requires one set of coordinates).

  • Q - draw a quadratic Bezier curve (requires two sets of coordinates).

  • C - draw a cubic Bezier curve (requires three sets of coordinates).

• ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.

class toyplot.layout.Random(edges=None, seed=1234)

Bases: GraphLayout

Compute a random graph layout.

Parameters:

• edges (toyplot.layout.EdgeLayout instance, optional) – The default will generate straight edges.

• seed (integer, optional) – Random seed used to generate vertex coordinates.

graph(vcoordinates, edges)

Compute vertex and edge coordinates for a graph.

Parameters:

• vcoordinates (\(V \times 2\) masked array) – Coordinates for every graph vertex, in vertex order. Where practical, only masked coordinates will have values assigned by the underlying algorithm.

• edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.

Returns:

• vcoordinates (\(V \times 2\) matrix) – Contains coordinates for every graph vertex, in vertex order.

• eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:

  • M - change the current coordinates without drawing (requires one set of coordinates).

  • L - draw a straight line segment (requires one set of coordinates).

  • Q - draw a quadratic Bezier curve (requires two sets of coordinates).

  • C - draw a cubic Bezier curve (requires three sets of coordinates).

• ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.

class toyplot.layout.StraightEdges

Bases: EdgeLayout

Creates straight edges between graph vertices.

edges(vcoordinates, edges)

Return edge coordinates for a graph.

Parameters:

• vcoordinates (\(V \times 2\) matrix) – Contains the coordinates for every graph vertex, in vertex order.

• edges (\(E \times 2\) matrix) – Contains the integer vertex indices for every graph edge in edge order. The first and second matrix columns contain the source and target vertices respectively.

Returns:

• eshapes (array of \(E\) strings) – Contains a shape string for each edge, in edge order. The shape string contains drawing codes that define an arbitrary-complexity path for the edge, using a set of current coordinates and a turtle drawing model. The following codes are currently allowed:

  • M - change the current coordinates without drawing (requires one set of coordinates).

  • L - draw a straight line segment from the current coordinates (requires one set of coordinates).

  • Q - draw a quadratic Bezier curve from the current coordinates (requires two sets of coordinates).

  • C - draw a cubic Bezier curve from the current coordinates (requires three sets of coordinates).

• ecoordinates (matrix containing two columns) – Contains coordinates for each of the edge shape strings, in drawing-code order.

toyplot.layout.graph(a, b=None, c=None, olayout=None, layout=None, vcoordinates=None)

Compute a graph layout.

toyplot.layout.region(xmin, xmax, ymin, ymax, bounds=None, rect=None, corner=None, grid=None, margin=None)

Specify a rectangular target region relative to a parent region.

Parameters:

• xmin (number, required) – Minimum X boundary of the parent region, specified in CSS pixel units.

• xmax (number, required) – Maximum X boundary of the parent region, specified in CSS pixel units.

• ymin (number, required) – Minimum Y boundary of the parent region, specified in CSS pixel units.

• ymax (number, required) – Maximum Y boundary of the parent region, specified in CSS pixel units.

• margin (number, string, (number, string) tuple, or tuple containing between one and four numbers, strings, or (number, string) tuples, optional) – Padding around the target region, specified in real-world units. Defaults to CSS pixel units. See Units for details. Follows the same behavior as the CSS margin property.

Returns:

xmin, xmax, ymin, ymax – The boundaries of the target region, specified in CSS pixel units.

Return type:

number