Gephi Plugin Developer Workshop


Published on

Gephi Plugin Devleoper Workshop, October 6, 2011 in Mountain View, California.

Presentation of Gephi's architecture and the different types of plugins that can be written with examples. Details about Gephi's API, code examples and best practices are presented. The Gephi Toolkit is also covered.

Published in: Technology, Education

Gephi Plugin Developer Workshop

  1. 1. GephiPlugin Developer Workshop<br />Mathieu Bastian<br /><><br />Mountain View, California<br />October 2011<br />
  2. 2. Welcome!<br /><ul><li> Introduction to Gephi
  3. 3. Why building plug-ins?
  4. 4. Netbeans Platform
  5. 5. Gephi’s Architecture
  6. 6. Plug-ins example
  7. 7. Gephi Toolkit
  8. 8. Live coding</li></ul>GephiPlugin Developer Workshop<br />
  9. 9. Introduction to Gephi<br />Gephi is…<br /><ul><li> A project started in 2007
  10. 10. An Exploratory Network Analysis Tool
  11. 11. An open-source platform
  12. 12. Written in Java, Swing, OpenGL</li></ul>GephiPlugin Developer Workshop<br />
  13. 13. Introduction to Gephi<br />Gephi has…<br /><ul><li> A website, a wiki, a bug tracker, a forum and a mailing-list
  14. 14. A modular and extensible architecture
  15. 15. A codebase of ~180K lines of code
  16. 16. Long-term plans and roadmap
  17. 17. A Manifesto</li></ul>GephiPlugin Developer Workshop<br />
  18. 18. Introduction to Gephi<br />Gephi focus on…<br /><ul><li> Performance, Usability and Modularity (and Stability!)
  19. 19. The platform, easy to use and extend
  20. 20. Networks. No diagrams or other visualizations.
  21. 21. Standards and open innovation</li></ul>GephiPlugin Developer Workshop<br />
  22. 22. Introduction to Gephi<br />The Platform’s vision<br /><ul><li> Modular architecture The secret sauce for a sustainable code
  23. 23. Interoperability Use, improve or create standards
  24. 24. Integration Be exigent with UI, installation, platforms
  25. 25. Open and transparent Ideas and features come from the community
  26. 26. Public good Is and will remain open-source
  27. 27. Documentation Provide tutorials and rich Javadoc</li></ul>GephiPlugin Developer Workshop<br />
  28. 28. Why building plug-ins?<br /><ul><li> Networks are everywhere</li></ul>Social Networks, Biological Networks, Power grid, Software, Innovation… The complex world produces networks to visualize and analyze.<br /><ul><li>Gephi is a generic software for all networks</li></ul>The variety of networks, data sources and algorithms is huge. Gephi can’t support all of them by default so we need plug-ins.<br />GephiPlugin Developer Workshop<br />
  29. 29. Why building plug-ins?<br /><ul><li> It’s easy to build and update</li></ul>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.<br /><ul><li> Hack vs Plug-ins</li></ul>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.<br />GephiPlugin Developer Workshop<br />
  30. 30. Gephi architecture<br />GephiPlugin Developer Workshop<br />
  31. 31. Netbeans Platform<br />"The NetBeans Platform is a generic framework for Swing applications. It provides the "plumbing" that, before, every developer had to write themselves”<br />Quick Start<br />Description and tutorials<br />API Index<br />GephiPlugin Developer Workshop<br />
  32. 32. Netbeans Platform<br /><ul><li>Gephi is built on top of Netbeans Platform.
  33. 33. So, development is fully integrated in Netbeans IDE:
  34. 34. Download Gephi’ssources
  35. 35. File > Open Project in Netbeans
  36. 36. Browse existing modules or create new
  37. 37. Run Gephi. Click on Run!</li></ul>GephiPlugin Developer Workshop<br />
  38. 38. Netbeans Platform<br />In a few words…<br /><ul><li>Netbeans Platform provides to Gephi the module system, the window system, the localization system, the preferences system and more…
  39. 39. Gephi development is integrated within Netbeans IDE.
  40. 40. A Netbeans Platform application (like Gephi) is basically a suite of modules.
  41. 41. Each module has a title, a description, a version, an author and hopefully a well defined role in the application.
  42. 42. Modules expose public APIs and depend on each other (without circular dependencies).</li></ul>GephiPlugin Developer Workshop<br />
  43. 43. Gephi Architecture<br />GephiPlugin Developer Workshop<br />
  44. 44. Gephi APIs<br /><ul><li> Graph API
  45. 45. Attributes API
  46. 46. Import API
  47. 47. Layout API
  48. 48. Statistics API
  49. 49. Filters API
  50. 50. Ranking API
  51. 51. Partition API
  52. 52. Project API
  53. 53. Preview API
  54. 54. Export API
  55. 55. DataLab API
  56. 56. Dynamic API
  57. 57. Generator API
  58. 58. LongTask API
  59. 59. Visualization API</li></ul>Read more on the <br />Javadoc<br />GephiPlugin Developer Workshop<br />
  60. 60. Gephi APIs<br /><ul><li> Each API has a role and a set of public packages other modules can use
  61. 61. Consult the Javadoc to see what an API does and browse classes
  62. 62. While the software evolve, APIs remain backward compatible
  63. 63. When we do changes on APIs, we wrote changes in the “API Changes” section on the Javadoc front-page
  64. 64. If you see an undocumented API, contact us or report a bug</li></ul>GephiPlugin Developer Workshop<br />
  65. 65. GephiSPIs<br />SPI vs API…<br /><ul><li>API: Can be called to do something. For instance a module call the LayoutAPIto run a layout algorithm for 100 iterations.
  66. 66. SPI: Interface to be implemented. For example a plug-in implements the Layout interface to add a new layout</li></ul>SPIs is the classical way how features are implemented in Gephi (and Netbeans). You’ll see some packages ending with ‘spi’ in the Javadoc. <br />GephiPlugin Developer Workshop<br />
  67. 67. GephiSPIs<br /><ul><li> Import SPI
  68. 68. Layout SPI
  69. 69. Statistics SPI
  70. 70. Filters SPI
  71. 71. Ranking SPI
  72. 72. Generator SPI
  73. 73. DataLab SPI
  74. 74. Partition SPI
  75. 75. Preview SPI
  76. 76. Export SPI
  77. 77. Perspective SPI
  78. 78. Tools SPI
  79. 79. Workspace Persistence SPI</li></ul>GephiPlugin Developer Workshop<br />
  80. 80. Graph API<br />Hosts the Graph data. A graph is a collection of nodes and edges and could be directed, undirected or mixed.<br /><ul><li> Iterate over nodes, edges or add/remove items.
  81. 81. Get node counts, degrees, neighbors…
  82. 82. Subscribe to graph events
  83. 83. Create sub-graphs (views)
  84. 84. Supports hierarchical graphs (graphs within graphs)
  85. 85. No parallel edges</li></ul>GephiPlugin Developer Workshop<br />
  86. 86. Attributes API<br />Each node/edge can have additional data, called attributes. Attributes can be any primitive type (Integer, Boolean, String, …), lists or dynamic.<br /><ul><li> Add/Remove columns
  87. 87. Columns are identified by an id and a title.
  88. 88. Push data to nodes/edges specifying the column</li></ul>GephiPlugin Developer Workshop<br />
  89. 89. Import API<br />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.<br /><ul><li> Import data to a new workspace or merge it to an existing
  90. 90. Verify the content of the container, fill a log/warning/error report
  91. 91. Automatically merge parallel edges
  92. 92. Doesn’t support real-time import</li></ul>GephiPlugin Developer Workshop<br />
  93. 93. Layout API<br />Provides real-time layout algorithm execution. Layouts do nothing else than modify the X and Y coordinates of nodes.<br /><ul><li> Control layout execution</li></ul>GephiPlugin Developer Workshop<br />
  94. 94. Statistics API<br />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.<br /><ul><li> Synchronous or asynchronous algorithm execution
  95. 95. Supports progress tracking and cancellation
  96. 96. Get HTML reports from statistics execution
  97. 97. Execute dynamic statistics with sliding window support</li></ul>GephiPlugin Developer Workshop<br />
  98. 98. Filters API<br />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.<br /><ul><li> Execute a filter and obtain the sub-graph
  99. 99. Create more advanced filter queries with operators (And, Or, Not…)
  100. 100. Create advanced chained filter queries
  101. 101. Export the filter result to a new workspace</li></ul>GephiPlugin Developer Workshop<br />
  102. 102. Ranking API<br />Ranking uses numerical attribute columns to visually transform elements (nodes, edges). Typically changing the size or color of the element.<br /><ul><li> Get all possible rankings for a type of element
  103. 103. Transform nodes/edges with default transformers
  104. 104. Define custom interpolations
  105. 105. Enable auto-transformation. Simply a transformation automatically applied when the graph changes.</li></ul>GephiPlugin Developer Workshop<br />
  106. 106. Partition API<br />Partitions are sets of nodes/edges with the same value for a particular column.<br /><ul><li> Get the set of values for a particular columns and the collections of items for each value.
  107. 107. Apply color transformation on the partition
  108. 108. Transform a partition into a hierarchical graph</li></ul>GephiPlugin Developer Workshop<br />
  109. 109. Project API<br />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.<br /><ul><li> Create, open and close projects and workspaces
  110. 110. Retrieve and switch the current workspace
  111. 111. Subscribe to the almighty Workspace events</li></ul>GephiPlugin Developer Workshop<br />
  112. 112. Preview API<br />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.<br /><ul><li> Renders the graph to Processing, PDF or SVG with the same visual output
  113. 113. Customize all sort of things, from fonts to edge thickness or color
  114. 114. Get a Processing viewer out of the box</li></ul>GephiPlugin Developer Workshop<br />
  115. 115. Export API<br />Export’s role is to export graph or preview data to files or streams.<br /><ul><li> Export graph data, for instance to a GEXF or GraphML file
  116. 116. Export preview data, typically to PDF, SVG or PNG files
  117. 117. For graph, one can choose to export the complete or only visible graph</li></ul>GephiPlugin Developer Workshop<br />
  118. 118. Data Laboratory API<br />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.<br /><ul><li> Manipulate columns, Import CSV, Merge elements, clear…
  119. 119. Sophisticated merging strategies (sum, average, join…)
  120. 120. Graph manipulation (group, delete, duplicate…)
  121. 121. Search/Replace</li></ul>GephiPlugin Developer Workshop<br />
  122. 122. Dynamic API<br />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.<br /><ul><li> Retrieve/Set the current visible interval
  123. 123. Get the current time format (date, double, datetime)
  124. 124. Create DynamicGraph, a utility class to apply a sliding window on a dynamic graph</li></ul>GephiPlugin Developer Workshop<br />
  125. 125. Generator API<br />Generators are algorithms to create networks from a set of properties. This API simply let users execute these algorithms in a thread.<br /><ul><li> Execute a generator in a thread
  126. 126. Provides progress and cancellation</li></ul>GephiPlugin Developer Workshop<br />
  127. 127. LongTask API<br />API used by other modules (Statistics, Generator, Import…) to execute long tasks in separate threads with progress, error and cancel support. <br /><ul><li> Execute a LongTask in a separate thread with progress, error and cancel support
  128. 128. Get informed when tasks finishes or returned errors
  129. 129. Each LongTaskExecutor only supports one task at a time</li></ul>GephiPlugin Developer Workshop<br />
  130. 130. Visualization API<br />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.<br />GephiPlugin Developer Workshop<br />
  131. 131. Now SPIs…<br />SPIs define how Gephi can be extended. There are simple Java interfaces like Layout, Importer, Filter or Renderer.<br />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:<br />GephiPlugin Developer Workshop<br />
  132. 132. Import SPI<br />Extend the range of file formats or databases supported. An importer is reading a data source and pushing data to the import container.<br /><ul><li> Add new file formats
  133. 133. Add new types of databases
  134. 134. Add new spigot (API, Socket, Stream…)
  135. 135. Define custom import UI. The UI could be a single settings JPanel or a wizard.
  136. 136. How to write an Import
  137. 137. How to write a Spigot with Wizard</li></ul>GephiPlugin Developer Workshop<br />
  138. 138. Layout SPI<br />Add new layout algorithms. A layout algorithm reads the graph and modify X and Y coordinates.<br /><ul><li> Add new layout algorithm
  139. 139. Define the layout properties
  140. 140. How to write a layout</li></ul>GephiPlugin Developer Workshop<br />
  141. 141. Statistics SPI<br />Add new statistics algorithms. Statistics write result data for each node/edge and write HTML reports.<br /><ul><li> Add new statistics algorithm
  142. 142. Create a settings UI panel
  143. 143. Supports standard and dynamic statistics
  144. 144. How to write a metric</li></ul>GephiPlugin Developer Workshop<br />
  145. 145. Filters SPI<br />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.<br /><ul><li> Create new filters and define parameters
  146. 146. Create a settings UI which modify the parameters
  147. 147. Create filter builders
  148. 148. How to write a filter</li></ul>GephiPlugin Developer Workshop<br />
  149. 149. Ranking SPI<br />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.<br /><ul><li> Create new transformers
  150. 150. Create the transformer UI, a custom JPanel</li></ul>GephiPlugin Developer Workshop<br />
  151. 151. Generator SPI<br />Simple SPI for adding new generators. Generator implements the LongTask interface to support progress and cancellation.<br /><ul><li> Create new generators
  152. 152. Provide a settings UI
  153. 153. How to write a graph generator</li></ul>GephiPlugin Developer Workshop<br />
  154. 154. DataLab SPI<br />The Data Laboratory actions can be extended, whether it’s a contextual or general action.<br /><ul><li> Create new node/edge context menu actions to manipulate one or multiple selected nodes/edges.
  155. 155. Create a general action that will show up in the Toolbar
  156. 156. Create a new action for manipulating attribute columns
  157. 157. Create new merge strategies
  158. 158. How to extend Data Laboratory features</li></ul>GephiPlugin Developer Workshop<br />
  159. 159. Partition SPI<br />The partition SPI allows to create new transformers. However this SPI is not stable yet and will be rewritten in a near future.<br /><ul><li> Create new transformers
  160. 160. Provide a settings UI</li></ul>GephiPlugin Developer Workshop<br />
  161. 161. Preview SPI<br />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).<br /><ul><li> Create new item builders or replace default implementations
  162. 162. Create new renderers or replace default implementations
  163. 163. Add new properties
  164. 164. Add custom UI which will be displayed in an extra tab
  165. 165. How to write a preview renderer</li></ul>GephiPlugin Developer Workshop<br />
  166. 166. Export SPI<br />There is three types of exports: Graph, Vector and custom.<br /><ul><li> Support new graph format extension
  167. 167. Support new type of vector-based file
  168. 168. Create settings UI
  169. 169. Create new type of custom export (ex: stream)
  170. 170. How to write an export</li></ul>GephiPlugin Developer Workshop<br />
  171. 171. Perspective SPI<br />Perspectives are a set of panels. Typically “Overview”, “Data Laboratory” and “Preview” are perspectives.<br /><ul><li> Create new perspectives
  172. 172. Set which panels belong to a perspective
  173. 173. Register a perspective</li></ul>GephiPlugin Developer Workshop<br />
  174. 174. Tools SPI<br />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.<br /><ul><li> Create new tools
  175. 175. Create property toolbar to configure the tool</li></ul>GephiPlugin Developer Workshop<br />
  176. 176. Workspace Persistence SPI<br />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.<br /><ul><li> Add new data to the project file</li></ul>GephiPlugin Developer Workshop<br />
  177. 177. Create a Plug-in (5 minutes)<br />What a plug-in really is…<br />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.<br />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.<br />To create a new module…<br />Once Gephi project is open, right click on “Modules” > “Add new…”<br />GephiPlugin Developer Workshop<br />
  178. 178. Create a Plug-in (5 minutes)<br />Right click on your module > Properties… <br /><ul><li>Manage dependencies</li></ul>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.<br />Your module will use APIs set by other modules and/or define its own APIs which others can use.<br />Depends on<br />My Module<br />GephiPlugin Developer Workshop<br />
  179. 179. Create a Plug-in (5 minutes)<br />Right click in your module > Properties… <br /><ul><li>Module branding</li></ul>Each module has a name, a description, a license, a version and an author.<br />When you update your module, increase the specification version number.<br />GephiPlugin Developer Workshop<br />
  180. 180. Create a Plug-in (5 minutes)<br />Right click on your module > Create NBM…<br />It creates a single file you can distribute and share.<br />Gephi’s website let you upload your NBM file out of the box. You can also update your plug-in with a new version.<br />For multi-modules plug-ins, it also accepts a zip package of several NBMs.<br />GephiPlugin Developer Workshop<br />
  181. 181. Plugin examples – Circular Layout<br />Adds a new Layout. Standard use of the Layout SPI.<br />GephiPlugin Developer Workshop<br />
  182. 182. Plugin examples – Complex Generators<br />Adds new Generators with UI. Standard use of the Generator SPI.<br />GephiPlugin Developer Workshop<br />
  183. 183. Plugin examples – Social Network Analysis<br />Adds new statistics. Standard use of the Statistics SPI.<br />GephiPlugin Developer Workshop<br />
  184. 184. Plugin examples – LinkfluencePlugin<br />Adds new context and global actions in the Data Laboratory. The plug-in has been developed by the Linkfluence company and open-sourced.<br />GephiPlugin Developer Workshop<br />
  185. 185. Plugin examples – HTTP Graph<br />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.<br />GephiPlugin Developer Workshop<br />
  186. 186. Plugin examples – Script console<br />Adds a Python console as a new component. Doesn’t use a SPI but the plugin uses various APIs.<br />GephiPlugin Developer Workshop<br />
  187. 187. Plugin examples – Seadragonplugin<br />Exports the graph from Preview to a zoomable web interface. Extends the Export SPI and uses the Preview API.<br />GephiPlugin Developer Workshop<br />
  188. 188. Plugin distribution and update<br /><ul><li> Plug-ins are available and can be published at
  189. 189. Subscribe to the gephi-plugins mailing-list.
  190. 190. Plug-ins are also available directly from Gephi’sPlugin Center (Tools > Plugins).
  191. 191. Like any other module, plug-ins are updated when a new version is available.</li></ul>GephiPlugin Developer Workshop<br />
  192. 192. Gephi Toolkit<br />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:<br /><ul><li> Headless Gephi from an input graph file (DOT, GML, GEXF, …) to the resulting PDF, with a list of settings.
  193. 193. Servlet Use Gephi toolkit to create graph snippets PNG images automatically in a servlet.</li></ul>The Toolkit is release separately from Gephi and can be download at http:/<br />GephiPlugin Developer Workshop<br />
  194. 194. Gephi Toolkit<br /><ul><li> The Toolkit is basically Gephi without the user interface modules
  195. 195. One can find documentation and tutorials on the wiki: Toolkit Portal
  196. 196. It has a separate Javadoc, as SPI’s implementations are also included
  197. 197. Plug-ins can also be used in the Toolkit. Consult the wiki
  198. 198. It’s easy to use from JRuby or Jython</li></ul>GephiPlugin Developer Workshop<br />
  199. 199. Thank you!Questions?<br />GephiPlugin Developer Workshop<br />
  200. 200. Book recommendations<br />Also checkout How to Design a Good API and Why it Matters (Joshua Bloch)<br />GephiPlugin Developer Workshop<br />