toyplot.layout module¶
Provides layout algorithms.

class
toyplot.layout.
Buchheim
(edges=None, basis=None)[source]¶ Bases:
toyplot.layout.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)[source]¶ 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 arbitrarycomplexity
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 drawingcode order.


class
toyplot.layout.
CurvedEdges
(curvature=0.15)[source]¶ Bases:
toyplot.layout.EdgeLayout
Creates curved edges between graph vertices.
Parameters: curvature (number) – Controls the curvature of each edge’s arc, as a percentage of the distance between the edge’s vertices. Use negative values to curve edges in the opposite direction. 
edges
(vcoordinates, edges)[source]¶ 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 arbitrarycomplexity
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 drawingcode order.


class
toyplot.layout.
Eades
(edges=None, c1=2, c2=1, c3=1, c4=0.1, M=100, seed=1234)[source]¶ Bases:
toyplot.layout.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, c2, c3, 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)[source]¶ 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 arbitrarycomplexity
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 drawingcode order.
 edges (

class
toyplot.layout.
EdgeLayout
[source]¶ Bases:
object
Abstract interface for algorithms that compute graph edge coordinates.

edges
(vcoordinates, edges)[source]¶ 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 arbitrarycomplexity
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 drawingcode order.


class
toyplot.layout.
FruchtermanReingold
(edges=None, area=1, temperature=0.1, M=50, seed=1234)[source]¶ Bases:
toyplot.layout.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, 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)[source]¶ 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 arbitrarycomplexity
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 drawingcode order.
 edges (

class
toyplot.layout.
Graph
(vids, vcoordinates, edges, eshapes, ecoordinates)[source]¶ Bases:
object
Stores graph layout information.
Typically used when sharing a layout among more than one graph.

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

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

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

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

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

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

vids
¶ Return \(V\) graph vertex identifiers.


class
toyplot.layout.
GraphLayout
[source]¶ Bases:
object
Abstract interface for algorithms that compute coordinates for graph vertices and edges.

graph
(vcoordinates, edges)[source]¶ 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 arbitrarycomplexity
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 drawingcode order.


class
toyplot.layout.
IgnoreVertices
(edges=None)[source]¶ Bases:
toyplot.layout.GraphLayout
Donothing graph layout for use when all vertices are already specified.
Parameters: edges ( toyplot.layout.EdgeLayout
instance, optional) – The default will generate straight edges.
graph
(vcoordinates, edges)[source]¶ 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 arbitrarycomplexity
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 drawingcode order.


class
toyplot.layout.
Random
(edges=None, seed=1234)[source]¶ Bases:
toyplot.layout.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)[source]¶ 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 arbitrarycomplexity
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 drawingcode order.
 edges (

class
toyplot.layout.
StraightEdges
[source]¶ Bases:
toyplot.layout.EdgeLayout
Creates straight edges between graph vertices.

edges
(vcoordinates, edges)[source]¶ 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 arbitrarycomplexity
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 drawingcode order.


toyplot.layout.
graph
(a, b=None, c=None, olayout=None, layout=None, vcoordinates=None)[source]¶ Compute a graph layout.

toyplot.layout.
region
(xmin, xmax, ymin, ymax, bounds=None, rect=None, corner=None, grid=None, margin=None)[source]¶ 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 fournumbers
, strings, or (number
, string) tuples, optional) – Padding around the target region, specified in realworld 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:  xmin (