gephi plugin developer workshop

Mathieu Bastian<[email protected]>

Mountain View, CaliforniaOctober 2011

Gephi Plugin Developer Workshop


Welcome!

Introduction to Gephi

Why building plug-ins?

Netbeans Platform

Gephi’s Architecture

Plug-ins example

Gephi Toolkit

Live coding



• A project started in 2007

• An Exploratory Network Analysis Tool

• An open-source platform

• Written in Java, Swing, OpenGL

Gephi is…



• A website, a wiki, a bug tracker, a forum and a mailing-list

• A modular and extensible architecture

• A codebase of ~180K lines of code

• Long-term plans and roadmap

• A Manifesto

Gephi has…

http://wiki.gephi.org/index.php/Manifesto



• Performance, Usability and Modularity (and Stability!)

• The platform, easy to use and extend

• Networks. No diagrams or other visualizations.

• Standards and open innovation

Gephi focus on…



• Modular architecture The secret sauce for a sustainable code

• Interoperability Use, improve or create standards

• Integration Be exigent with UI, installation, platforms

• Open and transparent Ideas and features come from the community

• Public good Is and will remain open-source

• Documentation Provide tutorials and rich Javadoc

The Platform’s vision



• Networks are everywhere

Social Networks, Biological Networks, Power grid, Software, Innovation… The complex world produces networks to visualize and analyze.

• Gephi is a generic software for all networks

The variety of networks, data sources and algorithms is huge. Gephi can’t support all of them by default so we need plug-ins.



• It’s easy to build and update

Plug-ins are easy to create and release. Development is integrated in Netbeans IDE. No JAR hell. Easy to release new version through Gephi’s website.

• Hack vs Plug-ins

Plug-ins are an incentive to build sustainable modules and share them. One can always take the source code and hack it to get things done but there is an real advantage to built on top of clean APIs.


Gephi architecture


Netbeans Platform

"The NetBeans Platform is a generic framework for Swing applications. It provides the "plumbing" that, before, every developer had to write themselves”

Description and tutorials

Quick Start

API Index

http://platform.netbeans.org/description.html

http://platform.netbeans.org/tutorials/nbm-quick-start.html

http://bits.netbeans.org/dev/javadoc/index.html


Netbeans Platform

• Gephi is built on top of Netbeans Platform.

• So, development is fully integrated in Netbeans IDE:

• Download Gephi’s sources

• File > Open Project in Netbeans

• Browse existing modules or create new

• Run Gephi. Click on Run!

http://gephi.org/users/download/


Netbeans Platform

In a few words…

• Netbeans Platform provides to Gephi the module system, the window system, the localization system, the preferences system and more…

• Gephi development is integrated within Netbeans IDE.

• A Netbeans Platform application (like Gephi) is basically a suite of modules.

• Each module has a title, a description, a version, an author and hopefully a well defined role in the application.

• Modules expose public APIs and depend on each other (without circular dependencies).


Gephi Architecture


Gephi APIs

• Graph API

• Attributes API

• Import API

• Layout API

• Statistics API

• Filters API

• Ranking API

• Partition API

• Project API

• Preview API

• Export API

• DataLab API

• Dynamic API

• Generator API

• LongTask API

• Visualization API

Read more on the Javadoc

http://gephi.org/docs/api/


Gephi APIs

• Each API has a role and a set of public packages other modules can use

• Consult the Javadoc to see what an API does and browse classes

• While the software evolve, APIs remain backward compatible

• When we do changes on APIs, we wrote changes in the “API Changes” section on the Javadoc front-page

• If you see an undocumented API, contact us or report a bug

http://gephi.org/docs/api/


Gephi SPIs

SPI vs API…

• API: Can be called to do something. For instance a module call the LayoutAPI to run a layout algorithm for 100 iterations.

• SPI: Interface to be implemented. For example a plug-in implements the Layout interface to add a new layout

SPIs is the classical way how features are implemented in Gephi (and Netbeans). You’ll see some packages ending with ‘spi’ in the Javadoc.


Gephi SPIs

• Import SPI

• Layout SPI

• Statistics SPI

• Filters SPI

• Ranking SPI

• Generator SPI

• DataLab SPI

• Partition SPI

• Preview SPI

• Export SPI

• Perspective SPI

• Tools SPI

• Workspace Persistence SPI


Graph API

Hosts the Graph data. A graph is a collection of nodes and edges and could be directed, undirected or mixed.

• Iterate over nodes, edges or add/remove items.

• Get node counts, degrees, neighbors…

• Subscribe to graph events

• Create sub-graphs (views)

• Supports hierarchical graphs (graphs within graphs)

• No parallel edges


Attributes API

Each node/edge can have additional data, called attributes. Attributes can be any primitive type (Integer, Boolean, String, …), lists or dynamic.

• Add/Remove columns

• Columns are identified by an id and a title.

• Push data to nodes/edges specifying the column

Id Label Age Gender

n1 Johm 26 Male

n2 Margaret 46 Female


Import API

Imports data from any support (files, databases. streams). Import is a two-step process: first step adds all data to a container and second step appends the container to the workspace.

• Import data to a new workspace or merge it to an existing

• Verify the content of the container, fill a log/warning/error report

• Automatically merge parallel edges

• Doesn’t support real-time import


Layout API

Provides real-time layout algorithm execution. Layouts do nothing else than modify the X and Y coordinates of nodes.

• Control layout execution


Statistics API

Provides the statistics/metrics algorithm execution framework. Statistics typically use the network data to create results for each node/edge (degree, clustering coefficient, hits, …) or global.

• Synchronous or asynchronous algorithm execution

• Supports progress tracking and cancellation

• Get HTML reports from statistics execution

• Execute dynamic statistics with sliding window support


Filters API

Provides the framework to filter the graph and obtain a filtered sub-graph (a view). A filter can be a simple boolean predicate (age > 30) or a more complex process (k-core). Filters have parameters.

• Execute a filter and obtain the sub-graph

• Create more advanced filter queries with operators (And, Or, Not…)

• Create advanced chained filter queries

• Export the filter result to a new workspace


Ranking API

Ranking uses numerical attribute columns to visually transform elements (nodes, edges). Typically changing the size or color of the element.

• Get all possible rankings for a type of element

• Transform nodes/edges with default transformers

• Define custom interpolations

• Enable auto-transformation. Simply a transformation automatically applied when the graph changes.


Partition API

Partitions are sets of nodes/edges with the same value for a particular column.

• Get the set of values for a particular columns and the collections of items for each value.

• Apply color transformation on the partition

• Transform a partition into a hierarchical graph


Project API

Project API hosts the project and workspace data. Workspaces are data containers which any module can access. If data has to be shared between modules it has to lie in the Workspace. That’s exactly where each model is supposed to be stored.

• Create, open and close projects and workspaces

• Retrieve and switch the current workspace

• Subscribe to the almighty Workspace events


Preview API

Preview is a flexible visual rendering framework with high level of customization. The input is the graph data and a style and the output is a network map ready to be exported to PDF, SVG or PNG.

• Renders the graph to Processing, PDF or SVG with the same visual output

• Customize all sort of things, from fonts to edge thickness or color

• Get a Processing viewer out of the box


Export API

Export’s role is to export graph or preview data to files or streams.

• Export graph data, for instance to a GEXF or GraphML file

• Export preview data, typically to PDF, SVG or PNG files

• For graph, one can choose to export the complete or only visible graph


Data Laboratory API

The Data Laboratory works with spreadsheets and provides a large number of actions to manipulate the graph. All actions available by either right-clicking on nodes/edges or in the toolbar are accessible in the API. For instance the Search/Replace feature.

• Manipulate columns, Import CSV, Merge elements, clear…

• Sophisticated merging strategies (sum, average, join…)

• Graph manipulation (group, delete, duplicate…)

• Search/Replace


Dynamic API

API dedicated to dynamic network states and events. Browsing dynamic networks uses the Timeline component and defines a ‘visible interval’. This API is responsible for holding and modifying that value.

• Retrieve/Set the current visible interval

• Get the current time format (date, double, datetime)

• Create DynamicGraph, a utility class to apply a sliding window on a dynamic graph


Generator API

Generators are algorithms to create networks from a set of properties. This API simply let users execute these algorithms in a thread.

• Execute a generator in a thread

• Provides progress and cancellation


LongTask API

API used by other modules (Statistics, Generator, Import…) to execute long tasks in separate threads with progress, error and cancel support.

• Execute a LongTask in a separate thread with progress, error and cancel support

• Get informed when tasks finishes or returned errors

• Each LongTaskExecutor only supports one task at a time


Visualization API

Still in development. This API will eventually expose all options of the rendering engine and let users customize properties. It will also provide mouse events queues, selected elements lookup and off-screen screenshots.


Now SPIs…

SPIs define how Gephi can be extended. There are simple Java interfaces like Layout, Importer, Filter or Renderer.

When you implement a new SPI interface add a @ServiceProvider annotation to the class and that’s all you need to do to register your new implementation:

http://gephi.org/docs/api/index.html?org/gephi/layout/spi/Layout.html

http://gephi.org/docs/api/index.html?org/gephi/io/importer/spi/Importer.html

http://gephi.org/docs/api/index.html?org/gephi/filters/spi/Filter.html

http://gephi.org/docs/api/index.html?org/gephi/preview/spi/Renderer.html


Import SPI

Extend the range of file formats or databases supported. An importer is reading a data source and pushing data to the import container.

• Add new file formats

• Add new types of databases

• Add new spigot (API, Socket, Stream…)

• Define custom import UI. The UI could be a single settings JPanel or a wizard.

How to write an Import

How to write a Spigot with Wizard

http://wiki.gephi.org/index.php/HowTo_write_an_import

http://wiki.gephi.org/index.php/HowTo_write_a_Spigot_with_Wizard

http://wiki.gephi.org/index.php/HowTo_write_a_Spigot_with_Wizard


Layout SPI

Add new layout algorithms. A layout algorithm reads the graph and modify X and Y coordinates.

• Add new layout algorithm

• Define the layout properties

How to write a layout

http://wiki.gephi.org/index.php/HowTo_write_a_layout


Statistics SPI

Add new statistics algorithms. Statistics write result data for each node/edge and write HTML reports.

• Add new statistics algorithm

• Create a settings UI panel

• Supports standard and dynamic statistics

How to write a metric

http://wiki.gephi.org/index.php/HowTo_write_a_metric


Filters SPI

Filters are routines that remove nodes/edges from the graph given some parameters. Filters are built by “Builders” which act like factories. A filter builder can for instance build a filter for each attribute column. It’s called a category builder in that case.

• Create new filters and define parameters

• Create a settings UI which modify the parameters

• Create filter builders

How to write a filter

http://wiki.gephi.org/index.php/HowTo_write_a_filter


Ranking SPI

Ranking has a new SPI to create custom transformers. A transformer is transforming the node visual attributes given the list of values normalized between 0 and 1.

• Create new transformers

• Create the transformer UI, a custom JPanel


Generator SPI

Simple SPI for adding new generators. Generator implements the LongTask interface to support progress and cancellation.

• Create new generators

• Provide a settings UI

How to write a graph generator

http://gephi.org/docs/api/index.html?org/gephi/utils/longtask/spi/LongTask.html

http://wiki.gephi.org/index.php/HowTo_write_a_graph_generator

http://wiki.gephi.org/index.php/HowTo_write_a_graph_generator


DataLab SPI

The Data Laboratory actions can be extended, whether it’s a contextual or general action.

• Create new node/edge context menu actions to manipulate one or multiple selected nodes/edges.

• Create a general action that will show up in the Toolbar

• Create a new action for manipulating attribute columns

• Create new merge strategies

How to extend Data Laboratory features

http://wiki.gephi.org/index.php/HowTo_extend_data_laboratory_features

http://wiki.gephi.org/index.php/HowTo_extend_data_laboratory_features


Partition SPI

The partition SPI allows to create new transformers. However this SPI is not stable yet and will be rewritten in a near future.

• Create new transformers

• Provide a settings UI


Preview SPI

Preview is a highly customizable module. Item builders built items from the graph data and renderers render these items to targets (Processing, SVG and PDF).

• Create new item builders or replace default implementations

• Create new renderers or replace default implementations

• Add new properties

• Add custom UI which will be displayed in an extra tab

How to write a preview renderer

http://wiki.gephi.org/index.php/HowTo_write_a_preview_renderer

http://wiki.gephi.org/index.php/HowTo_write_a_preview_renderer


Export SPI

There is three types of exports: Graph, Vector and custom.

• Support new graph format extension

• Support new type of vector-based file

• Create settings UI

• Create new type of custom export (ex: stream)

How to write an export

http://wiki.gephi.org/index.php/HowTo_write_an_export


Perspective SPI

Perspectives are a set of panels. Typically “Overview”, “Data Laboratory” and “Preview” are perspectives.

• Create new perspectives

• Set which panels belong to a perspective

Register a perspective

http://wiki.gephi.org/index.php/HowTo_add_a_module_panel%23Register_in_a_Perspective


Tools SPI

Tools are actions users can take on the graph and are presented in the toolbar at the left of the graph window. Tools register to graph events (Mouse click, drag, press, Node click, …) and take action.

• Create new tools

• Create property toolbar to configure the tool


Workspace Persistence SPI

Modules can implement the WorkspacePersistenceProvider interface to save/load data into .gephi project files. When the project is saved every implementation is asked to write XML data and an identifier. When the project file is opened the system find identifiers and give the XML to parse to the implementation.

• Add new data to the project file

http://gephi.org/docs/api/index.html?org/gephi/project/spi/WorkspacePersistenceProvider.html


Create a Plug-in (5 minutes)

What a plug-in really is…

A plug-in is nothing else than a Netbeans module packaged in a single file with a NBM extension. It’s basically a JAR with additional meta-data.

There is no differences between Gephi’s core modules and plug-ins. There are all Netbeans modules. In a sense Gephi is just a suite of plug-ins which work together and depend on each other.

To create a new module…

Once Gephi project is open, right click on “Modules” > “Add new…”



Right click on your module > Properties…

• Manage dependencies

Dependencies are explicit between modules. You control which other modules your module depends on. You also control which packages are publicly visible for other modules.

Your module will use APIs set by other modules and/or define its own APIs which others can use.

My Module

Depends on



Right click in your module > Properties…

• Module branding

Each module has a name, a description, a license, a version and an author.

When you update your module, increase the specification version number.



Right click on your module > Create NBM…

It creates a single file you can distribute and share.

Gephi’s website let you upload your NBM file out of the box. You can also update your plug-in with a new version.

For multi-modules plug-ins, it also accepts a zip package of several NBMs.


Plugin examples – Circular Layout

Adds a new Layout. Standard use of the Layout SPI.


Plugin examples – Complex Generators

Adds new Generators with UI. Standard use of the Generator SPI.


Plugin examples – Social Network Analysis

Adds new statistics. Standard use of the Statistics SPI.


Plugin examples – Linkfluence Plugin

Adds new context and global actions in the Data Laboratory. The plug-in has been developed by the Linkfluence company and open-sourced.


Plugin examples – HTTP Graph

Streams the HTTP graph while the user is browsing the web. Implemented as a Generator. It’s a non standard use of the Generator SPI but it works.


Plugin examples – Script console

Adds a Python console as a new component. Doesn’t use a SPI but the plugin uses various APIs.


Plugin examples – Seadragon plugin

Exports the graph from Preview to a zoomable web interface. Extends the Export SPI and uses the Preview API.


Plugin distribution and update

• Plug-ins are available and can be published at http://gephi.org/plugins

• Subscribe to the gephi-plugins mailing-list.

• Plug-ins are also available directly from Gephi’s Plugin Center (Tools > Plugins).

• Like any other module, plug-ins are updated when a new version is available.

http://gephi.org/plugins

http://gephi.org/plugins

http://gephi.org/mailman/listinfo/gephi-plugins


Gephi Toolkit

The Gephi Toolkit packages essential modules in a standard Java library. The toolkit is just a single JAR that anyone could reuse in new Java applications, for example:

• Headless Gephi from an input graph file (DOT, GML, GEXF, …) to the resulting PDF, with a list of settings.

• Servlet Use Gephi toolkit to create graph snippets PNG images automatically in a servlet.

The Toolkit is release separately from Gephi and can be download at http:/gephi.org/toolkit

http://gephi.org/toolkit/


Gephi Toolkit

• The Toolkit is basically Gephi without the user interface modules

• One can find documentation and tutorials on the wiki: Toolkit Portal

• It has a separate Javadoc, as SPI’s implementations are also included

• Plug-ins can also be used in the Toolkit. Consult the wiki

• It’s easy to use from JRuby or Jython

http://wiki.gephi.org/index.php/Toolkit_portal

http://gephi.org/docs/toolkit/

http://wiki.gephi.org/index.php/How_to_use_Gephi_plug-ins_with_the_Gephi_Toolkit


Thank you! Questions?


Book recommendations

Also checkout How to Design a Good API and Why it Matters (Joshua Bloch)

http://lcsd05.cs.tamu.edu/slides/keynote.pdf

http://www.amazon.com/Practical-API-Design-Confessions-Framework/dp/1430209739/ref=sr_1_1?ie=UTF8&qid=1317857740&sr=8-1

http://www.amazon.com/Effective-Java-2nd-Joshua-Bloch/dp/0321356683/ref=pd_bxgy_b_img_b

http://www.amazon.com/Java-Concurrency-Practice-Brian-Goetz/dp/0321349601/ref=pd_bxgy_b_img_c

gephi plugin developer workshop

Technology