jupyter widget bindings for the motif library
Project description
Pymotif
A Python package that lets you plot Motif graphs within Jupyter Notebook / Jupyter Lab:
It's that easy to get started!
Features
- Seamless integration into existing Jupyter workflows
- Multiple data import options
- Programmatic graph manipulation
- Easy code sharing and reuse
Installation
You can install using pip
(we recommend using virtual environments):
pip install pymotif
And it should work. In some cases, you may also need to install and enable Jupyter extensions:
# Jupyter Lab
jupyter labextension install @jupyter-widgets/jupyterlab-manager
# For Jupyter Lab <= 2, you may need to install the extension manually
jupyter labextension install @cylynx/pymotif
# For Jupyter Notebook <= 5.2, you may need to enable nbextensions
jupyter nbextension enable --py [--sys-prefix|--user|--system] pymotif
Demo
Demo notebooks can be found in the examples
folder. For a start, check out examples/introduction.ipynb
, which gives a quick overview of the available functionality!
Motif Class
As shown above, using Motif in Jupyter involves importing and instantiating the Motif
class from pymotif
.
Instantiation
from pymotif import Motif
motif = Motif()
motif.plot() # or just 'motif'
Motif()
accepts various instantiation parameters (refer to Motif's __init__
method for updated information):
All parameters are optional.
Only one graph import (json_path, nx_graph, neo4j_graph, or csv_path) can be passed each time.
json_path: str
Path to a local JSON file containing the graph data.
If this is used, all other params will be ignored.
nx_graph: nx.Graph
A networkx graph to be rendered
neo4j_graph: neo4j.graph.Graph
A neo4j graph to be rendered, obtained from the neo4j.Result.graph() method.
Ref: https://neo4j.com/docs/api/python-driver/current/api.html#graph
csv_path: str
Path to a local CSV edgelist file
style: dict
The rendered graph's style. Its format depends on Motif's StyleOptions interface:
https://github.com/cylynx/motif.gl/blob/c79ba6549407979a4ec0214cc6c7c7d0f2a3be41/packages/motif/src/redux/graph/types.ts#L206
title: str
The rendered graph's title
Other params are ignored when using JSON files because the file itself may also contain pre-defined styles, titles, or other settings.
Example Usage
# import a csv file and set a title
motif = Motif(csv_path=<YOUR CSV PATH>, title='my first csv import')
# import a json file. as mentioned above, using json ignores all other params
motif = Motif(json_path=<YOUR JSON PATH>, title='ignored parameter')
# import a networkx graph and arrange it in a grid layout
style = {'layout': {'type': 'grid'}}
motif = Motif(nx_graph=<YOUR NETWORKX GRAPH>, style=style)
Attributes
There is only one class attribute for now:
state: dict
There are 2 possible keys: data, style.
Data is a list of graph data describing what will be rendered in the widget.
Style is a dict describing how the graphs will be rendered.
Follows the TLoadFormat interface defined in Motif's types.ts:
https://github.com/cylynx/motif.gl/blob/master/packages/motif/src/redux/graph/types.ts#L283
Example Usage
m = Motif(<YOUR PARAMS>)
# check graph's initial state
m.state
# stuff happens
...
# sanity check
m.state
This may be useful for debugging your graph objects at various points in time throughout your analysis.
Methods
def add_graph(self, **kwargs):
"""
Adds another graph to an existing Motif widget.
Takes the same parameters as __init__.
If provided, graph settings here will overwrite those set previously (e.g. style).
"""
def set_style(self, style: dict, overwrite=False):
"""
Allows updating the style of an existing widget.
------------
Parameters
------------
style: dict
The rendered graph's style
overwrite=False:
If True, overwrites all existing styles with the passed 'style' param.
If False, merges 'style' param with existing styles
"""
def plot(self):
""" Plots the graphs' current state as a Jupyter widget """
Example Usage
# create a new graph
m = Motif(<YOUR PARAMS>)
# add another previously-saved graph from a JSON file
m.add_graph(json_path=<YOUR JSON PATH>)
# adjust and overwrite the combined graphs' style
m.set_style(style=<YOUR STYLE>, overwrite=True)
# plot the combined graph
m.plot()
Development
This section contains instructions for developing Pymotif locally.
For a more thorough walkthrough check out the official Jupyter widgets guide:
https://ipywidgets.readthedocs.io/en/latest/examples/Widget%20Custom.html
Create a new conda environment with the dependencies
To create the environment, execute the following command:
conda create -n motif -c conda-forge jupyterlab nodejs python
Then activate the environment with:
conda activate motif
Build and install the widget for development
Since the widget contains a Python part, you need to install the package in editable mode:
npm run pymotif:build // In root directory to link it with monorepo setup
python -m pip install -e .
If you are using JupyterLab:
jupyter labextension develop --overwrite .
If you are using the Classic Notebook:
jupyter nbextension install --sys-prefix --symlink --overwrite --py pymotif
jupyter nbextension enable --sys-prefix --py pymotif
To continuously monitor the project for changes and automatically trigger a rebuild, start Jupyter in watch mode:
jupyter lab --watch
And in a separate session, begin watching the source directory for changes:
npm run pymotif // In root directory to link it with monorepo setup
After a change wait for the build to finish and then refresh your browser and the changes should take effect.
If you make a change to the python code then you will need to restart the notebook kernel to have it take effect.
Publishing
- Update the version in package.json
- Relase the
@cylynx/pymotif
packages:
npm login
npm run pymotif:publish
- Bundle the python package:
python setup.py sdist bdist_wheel
- Update the version in
pymotif/_version.py
- If frontend version dependency has changed, update
pymotif/_frontend.py
- Publish the package to PyPI:
pip install twine
twine upload dist/pymotif*
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file pymotif-0.0.6.tar.gz
.
File metadata
- Download URL: pymotif-0.0.6.tar.gz
- Upload date:
- Size: 16.3 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.2 importlib_metadata/3.7.0 pkginfo/1.7.0 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9dde3fecf366848e069ce9e6f5381bf822d39ea2240e17eca9df01b19329b855 |
|
MD5 | 4532a2f0f962441346cbf9567d1c5a0d |
|
BLAKE2b-256 | 4b6616a3bdbd8c69f353a1a5db947e3e91fdfc9dd179e0d5944d41a7e289e8ed |
File details
Details for the file pymotif-0.0.6-py2.py3-none-any.whl
.
File metadata
- Download URL: pymotif-0.0.6-py2.py3-none-any.whl
- Upload date:
- Size: 17.1 MB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.2 importlib_metadata/3.7.0 pkginfo/1.7.0 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.5
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 52a7c8736b1d8e03e4f1ab4402453ea9b70e4026b19120dbcd520e7f4e0b1d79 |
|
MD5 | 112a7f9c78acd9b74bb299f1f22482f9 |
|
BLAKE2b-256 | 99e830d36919062026c2fa3eeb02225236013a3c796822f1f8af5c291c5e1940 |