# ``igraph`.`formula``

module documentation
(source)

Implementation of `igraph.Graph.Formula()`.

You should use this module directly only if you have a very strong reason to do so. In almost all cases, you are better off with calling `igraph.Graph.Formula()`.

Function | `construct_graph_from_formula` | Graph.Formula(formula = None, attr = "name", simplify = True)
Function | `generate_edges` | Parses an edge specification from the head of the given formula part and yields the following:

def construct_graph_from_formula(cls, formula=None, attr='name', simplify=True): (source)

Graph.Formula(formula = None, attr = "name", simplify = True)

Generates a graph from a graph formula

A graph formula is a simple string representation of a graph. It is very handy for creating small graphs quickly. The string consists of vertex names separated by edge operators. An edge operator is a sequence of dashes (`-`) that may or may not start with an arrowhead (`<` at the beginning of the sequence or `>` at the end of the sequence). The edge operators can be arbitrarily long, i.e., you may use as many dashes to draw them as you like. This makes a total of four different edge operators:

- `-----` makes an undirected edge
- `<----` makes a directed edge pointing from the vertex on the right hand side of the operator to the vertex on the left hand side
- `---->` is the opposite of `<----`
- `<--->` creates a mutual directed edge pair between the two vertices

If you only use the undirected edge operator (`-----`), the graph will be undirected. Otherwise it will be directed. Vertex names used in the formula will be assigned to the `name` vertex attribute of the graph.

Some simple examples:

    >>> from igraph import Graph
    >>> print(Graph.Formula())          # empty graph
    IGRAPH UN-- 0 0 --
    + attr: name (v)
    >>> g = Graph.Formula("A-B")        # undirected graph
    >>> g.vs["name"]
    ['A', 'B']
    >>> print(g)
    IGRAPH UN-- 2 1 --
    + attr: name (v)
    + edges (vertex names):
    A--B
    >>> g.get_edgelist()
    [(0, 1)]
    >>> g2 = Graph.Formula("A-----------B")
    >>> g2.isomorphic(g)
    True
    >>> g = Graph.Formula("A  --->  B") # directed graph
    >>> g.vs["name"]
    ['A', 'B']
    >>> print(g)
    IGRAPH DN-- 2 1 --
    + attr: name (v)
    + edges (vertex names):
    A->B

If you have many disconnected componnets, you can separate them with commas. You can also specify isolated vertices:

    >>> g = Graph.Formula("A--B, C--D, E--F, G--H, I, J, K")
    >>> print(", ".join(g.vs["name"]))
    A, B, C, D, E, F, G, H, I, J, K
    >>> g.connected_components().membership
    [0, 0, 1, 1, 2, 2, 3, 3, 4, 5, 6]

The colon (`:`) operator can be used to specify vertex sets. If an edge operator connects two vertex sets, then every vertex from the first vertex set will be connected to every vertex in the second set:

    >>> g = Graph.Formula("A:B:C:D --- E:F:G")
    >>> g.isomorphic(Graph.Full_Bipartite(4, 3))
    True

Note that you have to quote vertex names if they include spaces or special characters:

    >>> g = Graph.Formula('"this is" +- "a silly" -+ "graph here"')
    >>> g.vs["name"]
    ['this is', 'a silly', 'graph here']

Parameters
cls | Undocumented
formula | the formula itself
attr | name of the vertex attribute where the vertex names will be stored
simplify | whether to simplify the constructed graph

Returns
the constructed graph:

def generate_edges(formula): (source)

Parses an edge specification from the head of the given formula part and yields the following:

- startpoint(s) of the edge by vertex names
- endpoint(s) of the edge by names or an empty list if the vertices are isolated
- a pair of bools to denote whether we had arrowheads at the start and end vertices