Introduction

Before we start, you should install motif and the jupyter widget

!pip install pymotif

A brief introduction to Pymotif's functionality. Start by importing it:

In [1]:
from pymotif import Motif

1. Data Import

Pymotif offers a variety of data import options:

JSON Data

If you download your graph data from the Motif UI (floppy disk button right above 'Data Sources'), it will be saved as a JSON file. This makes it easy to share your graph with someone else - you just have to send the file to them and they can import it like this:

In [2]:
# path to local dataset
json_path = 'data/sample.json'

motif_json = Motif(json_path=json_path)
motif_json.plot()
Reading JSON file, all other params will be ignored...

Note the message that appears: Reading JSON file, all other params will be ignored..., which means the json_path parameter overwrites any other parameter passed to the Motif() object.

NetworkX Graphs

If you have NetworkX or NetworkX-compatible graph data, it can be imported into Motif. In this example, we convert a .gml file into a NetworkX graph, then plot it in Motif:

In [3]:
import networkx as nx

# path to local dataset
gml = 'data/karate.gml'

# read using networkx
nx_graph = nx.read_gml(gml)
In [4]:
motif_nx = Motif(nx_graph=nx_graph, title='NetworkX')
motif_nx.plot()

Neo4j Data

If you have data stored in a Neo4j database, it can also be plotted in Motif (change the placeholders to your own connection data):

In [ ]:
import neo4j

neo4j_uri = 'bolt://3.238.89.105:7687'
neo4j_auth = ('neo4j', 'surveyors-beat-weed')
neo4j_driver = neo4j.GraphDatabase.driver(uri=neo4j_uri, auth=neo4j_auth)
neo4j_query = 'MATCH p=()-[r:ACTED_IN]->() RETURN p LIMIT 25'

# get query results and create a Motif object from it
neo4j_results = neo4j_driver.session().run(neo4j_query)
motif_neo4j = Motif(neo4j_graph=neo4j_results.graph(), title='Neo4j')

motif_neo4j.plot()

See neo4j_demo.ipynb for more examples.

CSV Edgelists

Plot graphs stored in CSV edgelists:

In [5]:
# path to local dataset
csv_path = 'data/edgelist.csv'

motif_csv = Motif(csv_path=csv_path, title='CSV')
motif_csv.plot()

2. Save Data And Style

You might have noticed a button at the bottom of each Motif widget. It will be useful when interacting with the graph via the UI. We'll import a graph, make a small change via the UI, then save it:

In [6]:
motif_saved_style = Motif(json_path=json_path)
motif_saved_style
Reading JSON file, all other params will be ignored...

In the graph above, change the layout with these steps:

  • Click on the 'Styles' icon on the left panel
  • Under Layout, change the selection from Concentric to Radial

The nodes and edges should now be arranged differently.

Save the current style by clicking on the SAVE DATA AND STYLE button, then plot the graph again in the following cell:

In [7]:
motif_saved_style

Note how the style persists and the graph is still in a radial layout!


3. Set Style With Code

We can also set styles via code. Let's change the graph above back to a Concentric layout:

In [ ]:
style = {'layout': {'type': 'concentric'}}
motif_saved_style.set_style(style)

motif_saved_style

You can also apply the current styling of one graph to another. An example:

In [ ]:
nice_graph = Motif()

# do styling here via UI / code
# ...

# extract the styles from graph
nice_style = nice_graph.state['style']

# apply style to another graph
# ugly_graph = Motif(...)
ugly_graph.set_style(nice_style)

4. Add Graphs

You can add new graphs to existing Motif objects. We'll create a graph with the same JSON data as above, then add the CSV data into it:

In [8]:
# create initial graph with just json data
motif_json_and_csv = Motif(json_path=json_path)

# add csv data to it
motif_json_and_csv.add_graph(csv_path=csv_path)

motif_json_and_csv
Reading JSON file, all other params will be ignored...

Hopefully the graphs you combine turn out more meaningful than this!


5. Plotting

You've already done a lot of this - just know that for now, a graph can be plotted with or without using the .plot() method:

In [ ]:
m = Motif()

# this
m

# is the same as this
m.plot()

6. State

To find out the underlying state of a Motif object at a point in time, access the .state instance attribute. It will show its graph data (i.e. the nodes and edges) and style:

In [ ]:
# should be empty since nothing was defined above
m.state

7. Export

Save widget state to share the notebook or export it to html.

For Jupyter Lab: Settings -> Save Widget State Automatically For Jupyter Notebook: Widgets -> Save Notebook Widget State

To convert to html:

jupyter nbconvert --to html [file].ipynb