afiore / gexf.rb

Ruby library for parsing, serializing, and manipulating GEXF graphs

Gexf.rb

A Ruby library for generating, parsing, and serializing graphs expressed in the GEXF format. Currently, this project implements only a subset of the GEXF specification: the definition of a basic graph topology, and the association of data attributes to nodes and edges. I will possibly implement the rest of the specification later on (i.e. dynamics, hyrarchy, and Phylogeny), as I consolidate the code.

Notice

This gem is not under active development anymore. However, you are wellcome to contribute pull requests, I will do my best to find the time for reviewing and possibly merging them.

Installation

gem install gexf

Usage

The following snippet initializes a GEXF graph, and defines three node attributes:

require 'rubygems'
require 'gexf'

graph = GEXF::Graph.new

graph.define_node_attribute(:url)
graph.define_node_attribute(:indegree, :type    => GEXF::Attribute::INTEGER)
graph.define_node_attribute(:frog,     :type    => GEXF::Attribute::BOOLEAN,
                                       :default => true)

Attribute values can be associated to nodes or edges by using the same syntax used to get/set Ruby Hash keys (symbols are automatically converted into strings).

gephi               = graph.create_node(:label => 'Gephi')
gephi[:url]         = 'http://gephi.org'
gephi[:indegree]    = 1

webatlas            = graph.create_node(:label => 'WebAtlas')
webatlas[:url]      = 'http://webatlas.fr'
webatlas[:indegree] = 2

rtgi                = graph.create_node(:label => 'RTGI')
rtgi[:url]          = 'http://rtgi.fr'
rtgi[:indegree]     = 1

blab                = graph.create_node(:label => 'BarabasiLab')
blab[:url]          = "http://barabasilab.com"
blab[:indegree]     = 1
blab[:frog]         = false

Once associated to a graph, nodes and edges behave as collections, implementing and exposing most of the methods in Ruby's Enumerable module:

graph.nodes.select { |node| !node[:frog] }.map(&:label)
=> 'BarabasiLab'

Edges can be created by calling the graph.create_edges, or more coincisely, by calling connect on the source node.

gephi.connect_to(webatlas)
gephi.connect_to(rtgi)
webatlas.connect_to(gephi)
rtgi.connect_to(webatlas)
gephi.connect_to(blab)

As it is the case for graph.nodes, also edges are enumerable:

graph.edges.count
=> 5

The complete set of edges can be accessed from the main graph object, or fetched on a single node basis:

webatlas.incoming_connections.map { |edge| edge.source.label }
=> ["Gephi", "RTGI"]

Parsing a GEXF document

Gexf.rb provides a basic SAX parser which allows to import GEXF documents into a graph objects suitable to be queried and manipulated. To parse a GEXF file into a graph, just call the GEXF helper method (which is a shortcat to GEXF::Document.parse(file))

require 'gexf'
require 'open-uri'

file  = File.open('http://gexf.net/data/data.gexf', 'r')
graph = GEXF(file)
file.close

graph.nodes.count
=> 4

Exporting a graph into an XML document

A graph object can be easily serialized to XML by just calling:

graph.to_xml
=> "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<gexf xmlns='\"http://www.gexf.net/1.2draft' xmlns....>"

Alternatively, one can obtain the same output by instantiating GEXF::XmlSerializer and calling the serialize! method.

serializer = GEXF::XmlSerializer.new(graph)
serializer.serialize!

Unit tests

Gexf.rb comes with a fairly decent RSpec test suite. The suite can be run from the project directory by issuing the following command:

bundle exec spec -f d spec

Contributors

• Andrea Fiore
• Erik Doernenburg
• Thiago Bueno

gexf.rb's Issues

Xml serializer produces broken files

It's an easy fix though, the namespace declaration for gexf is hosed up:

GEXF_ATTRS = {
    'xmlns'     => '"http://www.gexf.net/1.2draft',
    'xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance',
    'xsi'       => 'http://www.gexf.net/1.2draft http://www.gexf.net/1.2draft/gexf.xsd',
    'version'   => '1.2'
  }

See the messed up quote marks in the xmlns entry.

License missing from gemspec

RubyGems.org doesn't report a license for your gem. This is because it is not specified in the gemspec of your last release.

via e.g.

  spec.license = 'MIT'
  # or
  spec.licenses = ['MIT', 'GPL-2']

Including a license in your gemspec is an easy way for rubygems.org and other tools to check how your gem is licensed. As you can imagine, scanning your repository for a LICENSE file or parsing the README, and then attempting to identify the license or licenses is much more difficult and more error prone. So, even for projects that already specify a license, including a license in your gemspec is a good practice. See, for example, how rubygems.org uses the gemspec to display the rails gem license.

There is even a License Finder gem to help companies/individuals ensure all gems they use meet their licensing needs. This tool depends on license information being available in the gemspec. This is an important enough issue that even Bundler now generates gems with a default 'MIT' license.

I hope you'll consider specifying a license in your gemspec. If not, please just close the issue with a nice message. In either case, I'll follow up. Thanks for your time!

Appendix:

If you need help choosing a license (sorry, I haven't checked your readme or looked for a license file), GitHub has created a license picker tool. Code without a license specified defaults to 'All rights reserved'-- denying others all rights to use of the code.
Here's a list of the license names I've found and their frequencies

p.s. In case you're wondering how I found you and why I made this issue, it's because I'm collecting stats on gems (I was originally looking for download data) and decided to collect license metadata,too, and make issues for gemspecs not specifying a license as a public service :). See the previous link or my blog post about this project for more information.