Network File Formats

There are many popular network storage file formats. These formats are heterogeneous, providing different features and requiring specific parsers. NOESIS provides a unified interface for reading and writing networks using several widely-used network storage file formats.

Reading a network

All network readers inherit from the NetworkReader class, which defines a simple interface for reading networks. Network readers implemented in NOESIS provide a great flexibility by relying on the standard Java Reader, which allows reading networks from any source that can be defined as a stream of characters. For example, the Pajek file format network reader for a file named "mynetwork.net" can be created as:

FileReader fileReader = new FileReader("mynetwork.net");

PajekNetworkReader networkReader = new PajekNetworkReader(fileReader);

Once a network reader has been instantiated, the network can be read using the read method as follows:

Network network = networkReader.read();

The resources used by the reader should always be the released by using the close method as follows:

networkReader.close();

Writing a network

All network writers implement an interface called NetworkWriter. This interface defines the two methods required to use network writers; namely, write and close. In this case, network writers rely on the standard Java Writer, which defines an interface for writing characters to a stream. For example, in order to store a network in a file using the GML file format, we would instantiate the network writer as:

FileWriter fileWriter = new FileWriter("mynetwork.gml");

GMLNetworkWriter networkWriter = new GMLNetworkWriter(fileWriter);

Once the network writer has been instantiated, we just pass the network that we want to store as an argument to the write method:

networkWriter.write(network);

As always, the resources used by the network writer should be released using its close method:

networkWriter.close();

Creating a custom network reader

NOESIS can be easily extended to support new network file formats. In order to implement a custom network reader, you must define a custom subclass of the NetworkReader class. An example is provided below:

public class MyNetworkReader extends NetworkReader 

{

    public MyNetworkReader(...) 

    {

        // Use the constructor ONLY to store the reader parameters in class fields

        ...

    }

    @Override

    public Network read() throws IOException 

    {

        Network network = ...;

        // Read and build the network here

        ...

        return network;

    }

    @Override

    public void close() throws IOException 

    {

        // Free resources

        ...

    }

}

It should be noted that both methods can throw exceptions related to IO operations, so we recommend not handling exceptions within these methods. Even though it is not mandatory, we strongly recommend using a standard Java Reader as the interface to read the network. This provides a greater flexibility, since we can read the network from disparate sources without modifying the reader implementation.

Creating a custom network writer

In a similar way, NOESIS can be easily extended to write networks using a custom file format. A custom network writer can be implemented by creating a custom class implementing the NetworkWriter interface. The code provided below shows the structure of a custom network writer:

public class MyNetworkWriter implements NetworkWriter 

{

    public MyNetworkWriter() 

    {

        // Use the constructor ONLY to store the writer parameters in class fields

        ...

    }

    @Override

    public void write(Network network) throws IOException 

    {

        // Write the network passed as an argument to the write method

        ...

    }

    @Override

    public void close() throws IOException 

    {

        // Free resources

        ...

    }

}

As happened with network readers, we recommend not handling exceptions within the write and close methods. In addition, we suggest using a standard Java Writer, as it allows us serializing the network and sending it to different destinations using the same implementation of the NetworkWriter.

Supported file formats

Currently, NOESIS supports the following network file formats:

ASCII

A simple ASCII text-based file format with the following structure:

[Number of nodes] [Number of edges]

[First edge source node id] [First edge target node id] [First edge cost/weight]

...

[Last edge source node id] [Last edge target node id] [Last edge cost/weight]

This file format can be read using ASCIINetworkReader, as shown in the following code snippet:

FileReader fileReader = new FileReader("mynetwork.txt");

ASCIINetworkReader networkReader = new ASCIINetworkReader(fileReader);

Network network = networkReader.read();

networkReader.close();

Pajek

Files using the Pajek file format commonly use the ".net" extension.

This file format can be read using PajekNetworkReader, as show in the following example:

FileReader fileReader = new FileReader("mynetwork.net");

PajekNetworkReader networkReader = new PajekNetworkReader(fileReader);

Network network = networkReader.read();

networkReader.close();

You can also write a network in the Pajek file format using PajekNetworkWriter as shown below:

FileWriter fileWriter = new FileWriter("mynetwork.gml");

GMLNetworkWriter networkWriter = new GMLNetworkWriter(fileWriter);

networkWriter.write(network);

networkWriter.close();

GUESS (GDF)

The GDF file format stores networks in a table format, similar to the popular coma separated file (CSV) format. This format supports attributes, both for nodes and links. The file format is structured in two sections. The first section is used to declare the nodes in the network and their attributes. The second section is used to store the links in the network and their corresponding attributes, if any.

The following example shows how to use GDFNetworkReader for reading a network in GUESS (GDF) format:

FileReader fileReader = new FileReader("mynetwork.gdf");

GDFNetworkReader networkReader = new GDFNetworkReader(fileReader);

Network network = networkReader.read();

networkReader.close();

A code snippet illustrating how to use GDFNetworkWriter for writing a network using the GDF file format is shown below:

FileWriter fileWriter = new FileWriter("mynetwork.gdf");

GDFNetworkWriter networkWriter = new GDFNetworkWriter(fileWriter);

networkWriter.write(network);

networkWriter.close();

Graph Modeling Language (GML)

The Graph Modeling Language is a text-based network storage file format that represents a network using a hierarchical document, similar in some sense to the XML file format, yet less verbose.

This file format can be read using GMLNetworkReader as shown below:

FileReader fileReader = new FileReader("mynetwork.gml");

GMLNetworkReader networkReader = new GMLNetworkReader(fileReader);

Network network = networkReader.read();

networkReader.close();

The following example shows how to use GMLNetworkWriter for writing a network using the GML file format:

FileWriter fileWriter = new FileWriter("mynetwork.gml");

GMLNetworkWriter networkWriter = new GMLNetworkWriter(fileWriter);

networkWriter.write(network);

networkWriter.close();

GraphML

The GraphML file format is based on the XML markup language. GraphML networks are hierarchical documents that store the topology of the networks and their attributes, for both nodes and links.

The GraphML file format can be read using GraphMLNetworkReader as shown in the following example:

InputStream inputStream = new FileInputStream("mynetwork.graphml");

GraphMLNetworkReader networkReader = new GraphMLNetworkReader(inputStream);

Network network = networkReader.read();

networkReader.close();

GraphMLNetworkWriter lets us store a given network in GraphML format:

FileWriter fileWriter = new FileWriter("mynetwork.graphml");

GraphMLNetworkWriter networkWriter = new GraphMLNetworkWriter(fileWriter);

networkWriter.write(network);

networkWriter.close();

SNAP

The SNAP file format is used by the Stanford Large Network Dataset Collection. This file format stores each link as a tab-separated value pair indicating the identifiers of the two nodes connected by the link.

The SNAP file format can be read using SNAPNetworkReader, as shown in the following example:

FileReader fileReader = new FileReader("mynetwork.txt");

SNAPNetworkReader networkReader = new SNAPNetworkReader(fileReader);

Network network = networkReader.read();

networkReader.close();

Additionally, SNAPGZNetworkReader provides support for reading directly from compressed SNAP files as shown below:

InputStream inputStream = new FileInputStream("mynetwork.tar.gz");

SNAPGZNetworkReader networkReader = new SNAPGZNetworkReader(inputStream);

Network network = networkReader.read();

networkReader.close();