Wiki‎ > ‎

Network File Formats

There are many popular network storage file formats. These formats are very 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 flexibly by reliying on the standard Java Reader, which allows to read networks from any source than can be defined as a stream of characters. For example, a network reader for a file named "mynetwork.net", defined using the Pajek file format, 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();
Always remember to release the resources used by the reader 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, 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 NOESIS 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, passing the network that we want to write to the write method as follows:
networkWriter.write(network);
Always remember to release the resources used by the reader by using the close method as follows:
networkWriter.close();

Creating a custom network reader

NOESIS can be easily extended to read new network file formats. In order to implement a custom network reader, you must define a custom class inheriting from the NetworkReader class. An example is provided below:
public class MyNetworkReader extends NetworkReader {

    public MyNetworkReader(...) {
        // Only use the constructor to store the reader parameters in class members
        ...
    }

    @Override
    public Network read() throws IOException {
        Network network = ...;
        // Read and build the network here
        ...
        return network;
    }

    @Override
    public void close() throws IOException {
        // Free any used resource
        ...
    }

}

Note that both methods can throw exceptions related with IO operations, so we recommend to not handle exceptions within these methods. Despite not mandatory, we strongly recommend using a standard Java Reader as interface to read the network. This allows a greater flexibility to read the network from very 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 that a custom network writer must follow:
public class MyNetworkWriter implements NetworkWriter {

    public MyNetworkWriter() {
        // Only use the constructor to store the writer parameters in class members
        ...
    }

    @Override
    public void write(Network network) throws IOException {
        // Write the network passed as parameter here
        ...
    }


    @Override
    public void close() throws IOException {
        // Free any used resource
        ...
    }

}

In the same way that happened with network readers, we recommend to not handle exceptions in the write and close methods. In addition, we suggest using a standard Java Writer as interface to write the network, allowing to write the network to different sources using the same implementation.

Supported file formats

At the present time, NOESIS supports the following 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 format can be read using ASCIINetworkReader, as shown in the following code fragment:
FileReader fileReader = new FileReader("mynetwork.txt");
ASCIINetworkReader networkReader = new ASCIINetworkReader(fileReader);
Network network = networkReader.read();
networkReader.close();

Pajek

Files using the Pajek format commonly use the ".net" extension. This format does not support attributes, only allowing to represent the network topology. Optionally, a weight or a cost can be assigned to each edge.

This 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 to this 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 is structured as a table, 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:
FileReader fileReader = new FileReader("mynetwork.gdf");
GDFNetworkReader networkReader = new GDFNetworkReader(fileReader);
Network network = networkReader.read();
networkReader.close();

An example of how to use GDFNetworkWriter for writing a network using the GDF 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 hierarchy.

This 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 this format:
FileWriter fileWriter = new FileWriter("mynetwork.gml");
GMLNetworkWriter networkWriter = new GMLNetworkWriter(fileWriter);
networkWriter.write(network);
networkWriter.close();

GraphML

This file format uses the XML markup language to store the topology of the network and attributes, both for nodes and links.

This 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();

A network can be written using this format with GraphMLNetworkWriter as shown in the following code snippet:
FileWriter fileWriter = new FileWriter("mynetwork.graphml");
GraphMLNetworkWriter networkWriter = new GraphMLNetworkWriter(fileWriter);
networkWriter.write(network);
networkWriter.close();

SNAP

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

This format can be read using SNAPNetworkReader as 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 directly reading from compressed files as shown below:
InputStream inputStream = new FileInputStream("mynetwork.tar.gz");
SNAPGZNetworkReader networkReader = new SNAPGZNetworkReader(inputStream);
Network network = networkReader.read();
networkReader.close();

Comments