Introduction

Graphine is intended to be easy to learn and use whether you are a complete noob to graphs or are a graph
theoretician. For the noob I suggest that before we go any further you first read this wiki article so that
you get a basic understanding of what graphs, nodes and edges are.

Getting Started

Downloading and installing Graphine is really simple, and is documented
on the main Documentation page.

To make sure your installation went according to plan, navigate to the directory
you downloaded graphine to and do the following:

username@hostname:~/graphine$ cd graph
username@hostname:~/graphine/graph$ ./test.py CorrectnessTest

If all goes well you should see a series of dots, some output, and OK.
If it doesn’t, let us know and we’ll try to help you out.

Of course, all the code examples provided here are in the package you just downloaded, under “examples”.

Using Graphine

Now that you’re familiar with graphs and have Graphine installed, let’s dive in.

First we must import Graph which contains everything we need to build, modify and use graphs

from graph.base import Graph

next we must create an instance of Graph

g = Graph()

Now that we have graph g we can build our graph by creating nodes and connecting them with edges.
Let’s start by adding two nodes to g, note that when you create a node or edge you can pass an attribute name and
assign it.

node1 = g.add_node(color="red")
node2 = g.add_node(color="blue")

Since we have two nodes let’s connect them with an edge.

edge1 = g.add_edge(node1, node2)

Let’s take what we've learned here and build a family tree.

Example: Family Tree

This will be an interactive example so that hopefully you’ll get a better understanding of how Graphine works.

Start your python 3 interpreter from the Graphine examples directory and follow me

   >>> from graph.base import Graph
   >>> from familyTree import buildFamilyTree

This will import the following:

#! /usr/bin/env python3

from graph.base import Graph  

def buildFamilyTree(g):  
    '''Accepts a graph object and builds a family tree'''  
    g.add_node("Grandpa")  
    g.add_node("Grandma")  
    g.add_edge("Grandpa","Grandma",relation="married to")  
    g.add_node("Uncle Tom")  
    g.add_node("Aunt Betty")  
    g.add_edge("Grandpa","Uncle Tom", relation="parent/child")  
    g.add_edge("Grandma","Uncle Tom", relation="parent/child")  
    g.add_edge("Uncle Tom","Aunt Betty",relation="married to")  
    g.add_node("Cousin Bob")  
    g.add_edge("Uncle Tom","Cousin Bob",relation="parent/child")  
    g.add_edge("Aunt Betty","Cousin Bob",relation="parent/child")  
    g.add_node("Mom")  
    g.add_edge("Grandpa","Mom",relation="parent/child")  
    g.add_edge("Grandma","Mom",relation="parent/child")  
    g.add_node("Dad")  
    g.add_edge("Mom","Dad", relation="married to")  
    g.add_node("Me")  
    g.add_edge("Dad","Me",relation="parent/child")  
    g.add_edge("Mom","Me",relation="parent/child")

buildFamilyTree uses the add_node and add_edge functions we've already covered. The only thing we haven’t
seen before now is that we gave the edges another attribute called relation. The capability to add edge and node
attributes by simply passing them as arguments makes Graphine easy and intuitive to use. Additionally we could've added
any type of attribute from blood type to IQ.

Let’s build the Graph:

   >>> g = Graph()
   >>> buildFamilyTree(g)

Let’s see what we can do with this new graph, let’s get all the children our Grandpa had.

   >>> for edge in g.search_edges(relation="parent/child", start="Grandpa"):
   ...     print(edge.end)  
   ...   
   Node(name=Mom)  
   Node(name=Uncle Tom)

Pretty cool huh? search_edges searches all the edges in graph g and returns a list of edges that have a relation attribute
that is equal to “parent/child” and where the starting node is “Grandpa”. The start node of an edge is the first node used in
add_edge and the end node is the second node used. I recommend you play with this example and see if you can get all
the married nodes then all the single nodes.

Conclusion

We have not even scratched the surface of Graphine’s abilities and power but hopefully you are now capable of building and
using simple graphs. Also check out GraphineForPythonistas for a more advanced tutorial. If you have any questions,
concerns or suggestions check out our [Google Group][http://groups.google.com/graphine-developers] or email me at CIO at OpenMigration dot net.

BeginningGraphine