Aaron Andersen

GraphShop Script API Reference

The GraphShop scripting environment has access to all the standard global variables, functions, and object from the ECMAScript specification, such as Math, Array, parseInt(), etc. This corresponds to the typical global scope found in JavaScript, with the exception of the web-specific items such as the document object and the DOM API.

For more information on these build-in objects, as well as the ECMAScript language itself, consult any good book or website on JavaScript (ECAMAScript's most widely used implementation).

window

The global variable window is available in all script contexts and provides a reference to GraphShop's graphical user interface. The window object has several scriptable methods, which are primarily used to work with the list of graphs currently available in the ui.

Array<Graph> graphList()

The list of graphs currently available in the user interface.

Graph getGraph(int)

Get a reference to a graph from the user interface, by index number. Index numbers start at 0 and increment for each new graph added to the ui, and correspond to the order in which the graphs are listed in GraphShop's View menu.

int graphCount()

The total number of graphs currently available in the user interface.

Graph addGraph(Graph)

Add an existing graph from the scripting environment to the user interface.

Graph includeGraph(Graph)

Verify that the given graph is part of the window graph list. Unlike addGraph, this function does nothing if the given graph has already been added.

Graph addNewGraph(String label="")

Create a new graph and immediately add it to the window graph list. A reference to the newly created graph is returned.

Graph

To construct a new graph with a given label, use new Graph(label). The label parameter can be omitted, which will create a graph with an empty label. The graph will be initially null (i.e., with no vertices, edges, or arcs).

Graph clone()

Create and return a new graph identical in structure to this one. Graph and vertex labels will be copied from the original.

void build()

For graphs created using the graph constructor, this does nothing. Derived graphs (i.e., graphs created using one of the graph operation constructors) need to be built using build() before they can be used.

Vertex addVertex(String vertexLabel = "")

Creates a new vertex with the given label (or an empty label if the label parameter is omitted) and adds it to the graph. The newly created vertex is returned so that it can be stored or used if necessary.

void removeVertex(Vertex vertex)

Remove the given vertex from the graph. Any edges or arcs connected to that vertex will be removed from the graph also. The removed objects should then be considered invalid, and any further references to them held by the calling script discarded.

void removeVertices()

Remove all vertices from the graph. This has the effect of clearing out the all the edges and arcs also, resulting in a null or empty graph.

Vertex getVertex(int index)

Returns the vertex with the given index, where vertices in an n-vertex graph are numbered 0 through n-1. The order of the vertices in this system has no defined meaning, and is only guaranteed to be constant for a given vertex as long as no other vertices are added or removed from the graph.  The vertex index is thus not useful as a long-term identifier, but is extremely valuable for iterating over the vertices in a graph and for short-term references within a particular algorithm or script.

Array<Vertex> getVertexSet()

Returns an array containing all the vertices in the graph. For simple iteration over the vertex set it is generally better to use getVertex with vertexCount instead.

int vertexCount()

The number of vertices in the graph, otherwise known as the order of the graph.

Edge addEdge(int vertex1, int vertex2, String edgeLabel = "")

Adds a new edge to the graph, with an optional label, using the indices of the endpoint vertices instead of the vertices themselves. A reference to the newly added edge is returned.

Edge addEdge(Vertex vertex1, Vertex vertex2, String edgeLabel = "")

Adds a new edge to the graph, with an optional label, using a reference to each endpoint verex. A reference to the newly added edge is returned.

void removeEdge(Edge)

Remove the given edge from the graph. To remove an edge by index, call removeEdge(getEdge(index)).

void removeEdges()

Remove all the edges in the graph. If the graph contains no arcs, this results in a graph consisting entirely of isolated vertices.

int edgeMultiplicity(int vertex1, int vertex2)

The number of edges between the given vertices, referenced by index.

int edgeMultiplicity(Vertex vertex1, Vertex vertex2)

The number of edges between the given vertices. This is here as a shortcut for getEdges(vertex1, vertex2).length and for consistency with setEdgeMultiplicity.

void setEdgeMultiplicity(int vertex1, int vertex2, int count)

Let there be count edges between the given vertices, referenced by index.

void setEdgeMultiplicity(Vertex vertex1, Vertex vertex2, int count)

Let there by count edges between the given vertices. This could require adding or deleting edges from the graph depending on how many such edges there were before. If new edges are added, they will be given blank labels.

Edge getEdge(int index)

Get the edge with the given index. Index values range from 0 to edgeCount()-1 and are generally the most convenient way of identifying a particular edge within an algorithm. The index of a given edge has no defined meaning and is likely to change if edges are added to or removed from the graph.

bool hasEdge(int vertex1, int vertex2)

True if there is at least one edge between the given vertices, identified by index.

bool hasEdge(Vertex vertex1, Vertex vertex2)

True if there is at least one edge between the given vertices. This is a shortcut for getEdges(vertex1, vertex2).length > 0, though it is implemented in a way that is likely to be faster than that.

Array<Edge> getEdges(int vertex1, int vertex2)

Returns an array containing all the edges between the given vertices, identified by index.

Array<Edge> getEdges(Vertex vertex1, Vertex vertex2)

Returns an array containing all the edges between the given vertices. If no such edges exist, the result is an empty array.

Array<Edge> getEdgeSet()

Get an array containing all the edges in the graph. For simple iteration over the edgeSet, it is generally better to use getEdge with edgeCount instead.

int edgeCount()

The number of edges in the graph, otherwise known as the size of the graph. If the graph contains both edges and arcs, the actual graph size is edgeCount() + arcCount().

Arc addArc(int tail, int head, String arcLabel = "")

Add a new arc, with an optional label, from vertex tail to vertex head, identified by their indices. A reference to the newly created arc is returned.

Arc addArc(Vertex tail, Vertex head, String arcLabel = "")

Add a new arc, with an optional label, from vertex tail to vertex head. A reference to the newly created arc is returned.

void removeArc(Arc)

Remove the given arc from the graph. To remove an arc by index, call removeArc(getArc(index)).

void removeArcs()

Remove all arcs from the graph. If the graph contained only arcs (i.e., no edges), this results in a graph consisting of isolated vertices.

int arcMultiplicity(int tail, int head)

The number of arcs with the given head and tail vertex, identified by index..

int arcMultiplicity(Vertex tail, Vertex head)

The number of arcs with the given head and tail vertex. This is here as a shortcut for getEdges(vertex1, vertex2).length and for consistency with setEdgeMultiplicity.

void setArcMultiplicity(int tail, int head, int count)

Let there by count arcs going from vertex tail to vertex head, identified by index.

void setArcMultiplicity(Vertex tail, Vertex head, int count)

Let there by count arcs going from vertex tail to vertex head. This may require add or removing arcs from the graph, depending on its current structure. If new arcs are added, they will have empty labels. Arcs going the opposite direction (i.e., from vertex head to vertex tail) are not affected.

Arc getArc(int index)

Get the arc with the given index. Index values range from 0 to arcCount()-1 and are generally the most convenient way of identifying a particular arc within an algorithm. The index of a given arc has no defined meaning and is likely to change if arcs are added to or removed from the graph.

void flipArc(Arc arc)

Flip the direction of the given arc (i.e., set the arc to go from its current head to its current tail, so that the current tail becomes the new head and vice versa).

bool hasArc(int trail, int head)

True if there exists at least one arc from vertex tail to vertex head, identified by index.

bool hasArc(Vertex tail, Vertex head)

True if there exists at least one arc from vertex tail to vertex head. This is a functionally equivalent to getArcs(tail, head) > 0, but is likely to be slightly faster especially in large graphs.

Array<Arc> getArcs(int tail, int head)

Returns an array containing all the arcs going from tail to head, identified by index.

Array<Arc> getArcs(Vertex tail, Vertex head)

Returns an array containing all the arcs from tail to head. If no such arcs exist, an empty array is returned.

Array<Arc> getArcSet()

Returns an array containing all the arcs in the graph. For simple iteration over the arc set, it is generally better to use getArc with arcCount instead.

int arcCount()

The number of arcs in the graph. In the context of a pure digraph, this is often called the size of the graph (though if the graph also contains edges, the true size is arcCount() + edgeCount()).

void clear()

Removes all the edges, arcs, and vertices from the graph. This is functionally equivalent to removeVertices() but is implemented as a single step instead of a series of individual item deletions .

Array<Array<Vertex> > getComponents()

Calculate and return the connected components (often just called the components ) of the graph. The return value is an array of arrays of vertices, where each top-level array represents a component and each component is represented by its member vertices.

String label()

The label of the graph. Graph's created from the user interface are given default labels of the form "Graph n", where n is the window index number of the new graph. Graphs created from scripting default to an empty label.

void setLabel(String newLabel)

Set the graph label to the given string. It is recommended that graph labels be unique to the extent possible, though no system relies on this property so it is not required.

bool isComplete()

True if the graph is either arc complete or edge complete. This fact is rarely useful, but serves as a shortcut for calling isArcComplete() or isEdgeComplete() in situations when the graph is known to be pure (i.e., containing only edges or only arcs).

bool isArcComplete()

True if there is at least one arc between every two vertices. This is still true if there is more than one such arc; if it is desired to know whether the graph contains one and only one arc between every two vertices, further testing to verify that arcCount() = (n*(n-1))/2 (where n = vertexCount()) would be required. (This might be changed in a future release to work in the latter sense by default).

bool isEdgeComplete()

True if there is at least one edge between every two vertices. This is still true if there is more than one such edge; if it is desired to know whether the graph contains one and only one edge between every two vertices, further testing to verify that edgeCount() = (n*(n-1))/2 (where n = vertexCount()) would be required. (This might be changed in a future release to work in the latter sense by default).

bool isCompleteGraph()

True if the graph is both a pure graph (i.e., has no arcs) and edge complete.

bool isCompleteDigraph()

True if the graph is both a pure digraph (i.e., has no edges) and arc complete.

bool isPure()

True if the graph is either a pure graph or a pure digraph.

bool isPureGraph()

True if the graph has no arcs (presumably, this means it has edges, though the null graph also qualifies).

bool isPureDigraph()

True if the graph has no edges (presumably, this means it has arcs, though the null graph also qualifies).

bool isEmpty()

True if the graph has neither edges nor arcs. An empty graph is the collection or zero or more isolated vertices.

bool isNull()

True if the graph has no vertices (and thus no edges or arcs).

bool isTrivial()

True if the graph contains exactly one vertex (and no edges or arc loops). This is often more appropriately called the singleton graph.

Graph getCompetitionGraph()

Returns a static copy of the competition graph of this graph. To create a linked competition graph (i.e., a graph that automatically updates to reflect changes to the structure of this one), use the CompetitionGraph constructor.

See the derived graphs section of the user interface documentation for the definition and explanation of the Competition Graph.

Graph getComplementGraph()

Returns a static copy of the complement graph of this graph. To create a linked compelement graph (i.e., a graph that automatically updates to reflect changes to the structure of this one), use the ComplementGraph constructor.

See the derived graphs section of the user interface documentation for the definition and explanation of the Complement Graph.

Graph getConverseGraph()

Returns a static copy of the converse graph of this graph. To create a linked converse graph (i.e., a graph that automatically updates to reflect changes to the structure of this one), use the ConverseGraph constructor.

See the derived graphs section of the user interface documentation for the definition and explanation of the Converse Graph.

Graph getDominationGraph()

Returns a static copy of the domination graph of this graph. To create a linked domination graph (i.e., a graph that automatically updates to reflect changes to the structure of this one), use the DominationGraph constructor.

See the derived graphs section of the user interface documentation for the definition and explanation of the Domination Graph.

Graph getUnderlyingGraph()

Returns a static copy of the underlying graph of this graph. To create a linked underlying graph (i.e., a graph that automatically updates to reflect changes to the structure of this one), use the UnderlyingGraph constructor.

See the derived graphs section of the user interface documentation for the definition and explanation of the Underlying Graph.

Vertex

To create a new vertex, call addVertex on the graph it should belong to. Vertices cannot be created outside of a graph, nor can a vertex be moved from one graph to another.

Array<Vertex> neighborhood()

Returns an array with references to all the vertices that are neighbors of this one (i.e., all the vertices that are connected to this one by an edge or arc going either direction). If no such vertices exist (i.e., if this is an isolated vertex), the resulting array will be empty.

Array<Vertex> inNeighborhood()

Returns an array with references to all the vertices in this vertex's in neighborhood (i.e., all the vertices for which there is an arc going from that vertex to this one). If no such vertex exists, the resulting array will be empty.

Array<Vertex> outNeighborhood()

Returns an array with references to all the vertices in this vertex's out neighborhood (i.e., al l the vertices for which there is an arc going from this vertex to that one) . If no such vertex exists, the resulting array will be empty.

int index()

The current index of this vertex in the parent graph. This value can change as vertices are added to or deleted from the graph.

String label()

The vertex label, as given to the parent graph's addVertex function or set with setLabel.

void setLabel(String newLabel)

Sets the vertex label to the given string.

Array<Edge> edges()

All the edges connected to this vertex. To add or remove edges from the vertex, use the appropriate edge function on the parent graph object.

Array<Edge> edgesWith(Vertex other)

All the edges between this vertex and the given other. If no such edges exist, the resulting array will be empty.

Array<Arc> arcs()

All the arcs connected to this vertex (going either direction).

Array<Arc> arcsWith(Vertex other)

All the arcs connected to this vertex and the given other (going either direction).

Array<Arc> inArcs()

All the arcs coming into this one (i.e., the arcs for which this vertex is the head).

Array<Arc> arcsFrom(Vertex other)

All the arcs coming from the given other vertex to this one (i.e. , with the other vertex and this one as their tail and head respectively).

Array<Arc> outArcs()

All the arc going out from this one (i.e., the arcs for which this vertex is the tail).

Array<Arc> arcsTo(Vertex other)

All the arcs going from this vertex to the given other (i.e., with this vertex and the other as their tail and head respectively).

Edge

To create a new edge, call addEdge on the graph it should belong to. Edges cannot be created outside of a graph, nor can an edge be moved from one graph to another.

Vertex vertex1()

The vertex connected to the "first" end of this edge.

Vertex vertex2()

The vertex connected to the "second" end of this edge. In reality, the first and second ends of an edge are an unordered pair; the distinction between vertex1 and vertex2 is created soley to allow them to be referenced separately in scripting. Although this distinction implies a sort of direction to an edge, that property is meaningless and should generally not be used as part of any algorithm or script.

int index()

The current index of this edge in the parent graph. This value can change as vertices are added to or deleted from the graph.

String label()

The edge label, as given to the parent graph's addEdge function or set with setLabel.

void setLabel(String newLabel)

Set the edge label to the given string

Arc

To create a new edge, call addEdge on the graph it should belong to. Edges cannot be created outside of a graph, nor can an edge be moved from one graph to another.

Vertex head()

The head or ending vertex of this arc.

Vertex tail()

The tail or starting vertex of this arc. An arc is said to go from its tail to its edge, and is implied by stating that the tail vertex beats the head vertex.

int index()

The current index of this arc in the parent graph. This value can change as vertices are added to or deleted from the graph.

String label()

The arc label, as given to the parent graph's addArc function or set with setLabel.

void setLabel(String newLabel)

Set the edge label to the given string

Derived Graphs

Derived graphs (i.e., graphs created from the various graph operations) can be obtained from an existing graph (including another derived graph) by constructing a new derived graph object (i.e., a new object using the CompetitionGraph, ComplementGraph, ConverseGraph, DominationGraph, or UnderlyingGraph constructors) and passing in the source graph as the sole construction parameter.

Derived graphs have the same features and API as the regular Graph class. Once created, derived graphs are automatically updated to reflect changes made to the structure of the source graph. For this reason, the graph modification function should not be called directly on a derived graph. To get a static copy of a derived graph at any time, use the clone() function.