it.unimi.dsi.webgraph

Class ArcListASCIIGraph

java.lang.Object

it.unimi.dsi.webgraph.ImmutableGraph

it.unimi.dsi.webgraph.ImmutableSequentialGraph

it.unimi.dsi.webgraph.ArcListASCIIGraph

All Implemented Interfaces:

FlyweightPrototype<ImmutableGraph>

Direct Known Subclasses:

ShiftedByOneArcListASCIIGraph

public class ArcListASCIIGraph
extends ImmutableSequentialGraph

An ImmutableGraph that corresponds to graphs stored in a human-readable ASCII format were each line contains an arc.

The file format is very simple: each line contains an arc specified as two nodes separated by whitespace (but we suggest exactly one TAB character). Sources must be in increasing order, but targets can be in any order. The constructor provides an additional parameter, called shift, which will be added to all node indices. The default is 0, but for lists that number nodes starting from 1 it can be set to -1. Actually, the class ShiftedByOneArcListASCIIGraph can be used in place of this class for setting the shift to -1 without specifying additional parameters.

Contrarily to other classes, the load methods of this class do not always return instances of this class. In particular, loadOnce(InputStream) will return an instance of this class for read-once access. The instance will not provide offline or random access, but read-once access will be backed by the original input stream and only the successors of a single node will be loaded in core memory at any time.

The load(CharSequence) method, on the other hand, will return an instance of ArrayListMutableGraph built by copying an offline instance of this class.

Using ArcListASCIIGraph to convert your data

A simple (albeit rather inefficient) way to import data into WebGraph is using ASCII graphs specified by arc lists. Suppose you create the following file, named example.arcs:

  0 1
  1 2
  2 1
  

Then, the command

  java it.unimi.dsi.webgraph.BVGraph -g ArcListASCIIGraph example.arcs bvexample
  

will produce a compressed graph in BVGraph format with basename bvexample. Even more convenient, and extremely more efficient, is the loadOnce(InputStream) method, which reads from an input stream an arc-list ASCII graph and exposes it for a single traversal. It can be used, for instance, with the main method of BVGraph to generate somehow an arc-list ASCII graph and store it in compressed form on the fly. The previous example could be then rewritten as

  java it.unimi.dsi.webgraph.BVGraph -1 -g ArcListASCIIGraph dummy bvexample <example.arcs
  

Nested Class Summary

Nested classes/interfaces inherited from class it.unimi.dsi.webgraph.ImmutableGraph

ImmutableGraph.LoadMethod

Field Summary

Fields inherited from class it.unimi.dsi.webgraph.ImmutableGraph

GRAPHCLASS_PROPERTY_KEY, NUMBER_OF_THREADS_PROPERTY, PROPERTIES_EXTENSION

Constructor Summary

Constructors

Constructor and Description
ArcListASCIIGraph(java.io.InputStream is, int shift) Creates a read-once arc-list ASCII graph.

Method Summary

Modifier and Type	Method and Description
static ImmutableGraph	load(java.lang.CharSequence basename)
static ImmutableGraph	load(java.lang.CharSequence basename, ProgressLogger unused)
static ImmutableGraph	loadMapped(java.lang.CharSequence basename)
static ImmutableGraph	loadMapped(java.lang.CharSequence basename, ProgressLogger unused)
static ImmutableGraph	loadOffline(java.lang.CharSequence basename)
static ImmutableGraph	loadOffline(java.lang.CharSequence basename, ProgressLogger unused)
static ArcListASCIIGraph	loadOnce(java.io.InputStream is)
static ArcListASCIIGraph	loadOnce(java.io.InputStream is, int shift)
static ImmutableGraph	loadSequential(java.lang.CharSequence basename) Deprecated.
static ImmutableGraph	loadSequential(java.lang.CharSequence basename, ProgressLogger unused) Deprecated.
static void	main(java.lang.String[] args)
NodeIterator	nodeIterator(int from) Returns a node iterator for scanning the graph sequentially, starting from the given node.
int	numNodes() Returns the number of nodes of this graph.
NodeIterator[]	splitNodeIterators(int howMany) Returns an array of node iterators, scanning each a portion of the nodes of a graph.
static void	store(ImmutableGraph graph, java.lang.CharSequence basename)
static void	store(ImmutableGraph graph, java.lang.CharSequence basename, int shift) Stores an arc-list ASCII graph with a given shift.
static void	store(ImmutableGraph graph, java.lang.CharSequence basename, ProgressLogger unused)

Methods inherited from class it.unimi.dsi.webgraph.ImmutableSequentialGraph

copy, outdegree, randomAccess, successorArray

Methods inherited from class it.unimi.dsi.webgraph.ImmutableGraph

basename, equals, hasCopiableIterators, hashCode, load, nodeIterator, numArcs, outdegrees, store, store, successors, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

ArcListASCIIGraph

public ArcListASCIIGraph(java.io.InputStream is,
                         int shift)
                  throws java.lang.NumberFormatException,
                         java.io.IOException

Creates a read-once arc-list ASCII graph. Instances created using this constructor can be only accessed using a single call to nodeIterator(int).

Parameters:

is - an input stream containing an arc-list ASCII graph.

Throws:

java.lang.NumberFormatException

java.io.IOException

Method Detail

numNodes

public int numNodes()

Description copied from class: ImmutableGraph

Returns the number of nodes of this graph.

Albeit this method is not optional, it is allowed that this method throws an UnsupportedOperationException if this graph has never been entirely traversed using a node iterator. This apparently bizarre behaviour is necessary to support implementations as ArcListASCIIGraph, which do not know the actual number of nodes until a traversal has been completed.

Specified by:

numNodes in class ImmutableGraph

Returns:

the number of nodes.

nodeIterator

public NodeIterator nodeIterator(int from)

Description copied from class: ImmutableGraph

Returns a node iterator for scanning the graph sequentially, starting from the given node.

This implementation just calls the random-access methods (ImmutableGraph.successors(int) and ImmutableGraph.outdegree(int)). More specific implementations may choose to maintain some extra state to make the enumeration more efficient.

Overrides:

nodeIterator in class ImmutableSequentialGraph

Parameters:

from - the node from which the iterator will iterate.

Returns:

a NodeIterator for accessing nodes and successors sequentially.

splitNodeIterators

public NodeIterator[] splitNodeIterators(int howMany)

Description copied from class: ImmutableGraph

Returns an array of node iterators, scanning each a portion of the nodes of a graph. Iterators are guaranteed to scan mutually disjoint sets of nodes, and every node is guaranteed to be scanned by one iterator.

This is an optional operation. If implemented, though, the returned iterators must properly implement NodeIterator.copy(int).

Overrides:

splitNodeIterators in class ImmutableGraph

Parameters:

howMany - the number of iterators to be returned (at the end of the array, some of them may be empty).

Returns:

the required iterators.

loadSequential

@Deprecated
public static ImmutableGraph loadSequential(java.lang.CharSequence basename)
                                                 throws java.io.IOException

Deprecated.

Throws:

java.io.IOException

loadSequential

@Deprecated
public static ImmutableGraph loadSequential(java.lang.CharSequence basename,
                                                        ProgressLogger unused)
                                                 throws java.io.IOException

Deprecated.

Throws:

java.io.IOException

loadOffline

public static ImmutableGraph loadOffline(java.lang.CharSequence basename)
                                  throws java.io.IOException

Throws:

java.io.IOException

loadOffline

public static ImmutableGraph loadOffline(java.lang.CharSequence basename,
                                         ProgressLogger unused)
                                  throws java.io.IOException

Throws:

java.io.IOException

loadMapped

public static ImmutableGraph loadMapped(java.lang.CharSequence basename)
                                 throws java.io.IOException

Throws:

java.io.IOException

loadMapped

public static ImmutableGraph loadMapped(java.lang.CharSequence basename,
                                        ProgressLogger unused)
                                 throws java.io.IOException

Throws:

java.io.IOException

loadOnce

public static ArcListASCIIGraph loadOnce(java.io.InputStream is)
                                  throws java.io.IOException

Throws:

java.io.IOException

loadOnce

public static ArcListASCIIGraph loadOnce(java.io.InputStream is,
                                         int shift)
                                  throws java.io.IOException

Throws:

java.io.IOException

load

public static ImmutableGraph load(java.lang.CharSequence basename)
                           throws java.io.IOException

Throws:

java.io.IOException

load

public static ImmutableGraph load(java.lang.CharSequence basename,
                                  ProgressLogger unused)
                           throws java.io.IOException

Throws:

java.io.IOException

store

public static void store(ImmutableGraph graph,
                         java.lang.CharSequence basename,
                         ProgressLogger unused)
                  throws java.io.IOException

Throws:

java.io.IOException

store

public static void store(ImmutableGraph graph,
                         java.lang.CharSequence basename)
                  throws java.io.IOException

Throws:

java.io.IOException

store

public static void store(ImmutableGraph graph,
                         java.lang.CharSequence basename,
                         int shift)
                  throws java.io.IOException

Stores an arc-list ASCII graph with a given shift.

Parameters:

graph - a graph to be stored.

basename - the name of the output file.

shift - a shift that will be added to each node; note that is the opposite of the shift that will have to be used to load the generated file.

Throws:

java.io.IOException

main

public static void main(java.lang.String[] args)
                 throws java.lang.IllegalArgumentException,
                        java.lang.SecurityException,
                        java.lang.IllegalAccessException,
                        java.lang.reflect.InvocationTargetException,
                        java.lang.NoSuchMethodException,
                        java.io.IOException,
                        JSAPException

Throws:

java.lang.IllegalArgumentException

java.lang.SecurityException

java.lang.IllegalAccessException

java.lang.reflect.InvocationTargetException

java.lang.NoSuchMethodException

java.io.IOException

JSAPException