com.mastfrog.graph

Interface IntGraph

public interface IntGraph

Author:

Tim Boudreau

Method Summary

Modifier and Type	Method and Description
boolean	abortableBreadthFirstSearch(int startingNode, boolean up, IntPredicate cons) Do a breadth-first search which takes a predicate that will abort the search the first time the predicate returns false.
boolean	abortableDepthFirstSearch(int startingNode, boolean up, IntPredicate cons) Do a depth-first search which takes a predicate that will abort the search the first time the predicate returns false.
PairSet	allEdges() Get all edges in the graph.
Bits	bottomLevelNodes() Get the set of nodes which have no outbound edges.
void	breadthFirstSearch(int startingNode, boolean up, IntConsumer cons) Do a breadth-first search from the starting node, visiting all nodes in its closure or reverse-closure depending on the value of up, visiting each node in some order at least once.
static IntGraphBuilder	builder()
static IntGraphBuilder	builder(int expectedSize)
int[]	byClosureSize() Return an array of all nodes in the graph, sorted by the size of their closure (the number of distinct descendant nodes they have).
int[]	byReverseClosureSize() Return an array of all nodes in the graph, sorted by the size of their reverse closure (the number of distinct ancestor nodes they have).
Bits	children(int node) Get the set of nodes which have inbound edges from the passed node.
Bits	closureDisjunction(Bits nodes) Get the set of those nodes which exist in the closure of only one of the passed list of nodes.
Bits	closureDisjunction(int... nodes) Get the set of those nodes which exist in the closure of only one of the passed list of nodes.
Bits	closureDisjunction(int a, int b) Get the disjunction of the closure of two nodes.
Bits	closureOf(int node) Get the closure of this node - the set of all nodes which have this node as an ancestor.
int	closureSize(int node) Get the count of nodes which have the passed node as an ancestor.
Bits	closureUnion(int a, int b) Get the union of the closure of two nodes.
Bits	connectors() Return the set of nodes in the graph which have both inbound and outbound references.
boolean	containsEdge(int a, int b) Determine if an edge from a to b exists.
static IntGraph	create(Bits[] references)
static IntGraph	create(Bits[] reverseReferences, Bits[] references)
static IntGraph	create(BitSet[] references)
static IntGraph	create(BitSet[] reverseReferences, BitSet[] references)
void	depthFirstSearch(int startingNode, boolean up, IntConsumer cons) Perform a depth-first search, traversing the closure or reverse-closure of the starting node depth-first.
void	diff(IntGraph other, BiConsumer<IntGraph,IntGraph> c) Compare this graph and another; it is assumed that they have the same size.
Bits	disjointNodes() Get the set of nodes in the graph whose closure is not shared by any other nodes.
int	distance(int a, int b) Get the minimum distance between two nodes.
default int	edgeCount() Get the total number of edges in the graph.
void	edges(IntBiConsumer bi) Visit all edges in the graph.
double[]	eigenvectorCentrality(int maxIterations, double minDiff, boolean inEdges, boolean ignoreSelfEdges, boolean l2norm) Compute the eigenvector centrality of each node in the graph - an importance measure that could loosely be phrased as most likely to be connected through - meaning, unlike page rank, this emphasizes "connector" nodes rather than most-linked nodes - those nodes which, if removed, would break the most paths in the graph.
boolean	hasInboundEdge(int from, int to) Determine if a direct inbound edge exits from one node to another.
boolean	hasOutboundEdge(int from, int to) Determine if a direct outbound edge exits from one node to another.
int	inboundReferenceCount(int node) Returns the number of inbound edges a node has.
boolean	isIndirectlyRecursive(int node) Determine if a node is indirectly recursive - if the closure of it contains a cycle back to it, not counting cycles to itself.
boolean	isReachableFrom(int a, int b) Determine if node b is contained in the closure of node a.
boolean	isRecursive(int node) Determine if the passed node or a descendant of it has a cycle back to itself.
boolean	isReverseReachableFrom(int a, int b) Determine if the closure of a includes b.
boolean	isUnreferenced(int node) Determine if a node has no inbound edges - no ancestors.
static IntGraph	load(ObjectInputStream objectInputStream)
Bits	neighbors(int startingNode) Get the set of parent and child nodes for a node.
IntGraph	omitting(int... items) Create a new graph, sans the passed array of items - the resulting graph will be smaller and if mapped to objects, have different indices than the original.
Bits	orphans() Return the set of nodes which have no edges in or out.
int	outboundReferenceCount(int node) Returns the number of outbound edges a node has.
double[]	pageRank(double minDifference, double dampingFactor, int maximumIterations, boolean normalize) Rank the nodes in this graph according to the page rank algorithm, which detects most-linked-to nodes in the graph.
Bits	parents(int node) Get the set of nodes which reference the passed node.
List<IntPath>	pathsBetween(int src, int target) Get a list of all paths between the source and target node, sorted low to high by length.
Bits	reverseClosureOf(int node) Collect the reverse closure of a node - the set of all nodes which have an outbound edge to this one or an ancestor of those nodes.
int	reverseClosureSize(int node) Get the count of nodes which have the passed node as a descendant.
void	save(ObjectOutput out) Serialize this graph.
Optional<IntPath>	shortestPathBetween(int src, int target) Get the shortest path between two nodes in the graph.
Optional<IntPath>	shortestUndirectedPathBetween(int src, int target) Get the shortest undirected path between two nodes.
int	size() Get the maximum node id + 1 of this graph, or the number of logical nodes.
default <T> ObjectGraph<T>	toObjectGraph(List<T> items)
PairSet	toPairSet() Convert this graph to a PairSet, which internally uses a single Bits of size * size bits to represent the matrix of all edges.
Bits	topLevelOrOrphanNodes() Get the set of nodes which have no inbound edges - no ancestors.
default IntPath	topologicalSort(Bits bits) Topologically sort a set of ints; note that if a graph contains cycles, topological sorting is impossible - you will get some order that roughly approximates a topological sort for any ints that are not part of a cycle; the order of appearance of ints that participate in cycles is implementation-dependent.
default IntPath	topologicalSort(BitSet bits) Topologically sort a set of ints; note that if a graph contains cycles, topological sorting is impossible - you will get some order that roughly approximates a topological sort for any ints that are not part of a cycle; the order of appearance of ints that participate in cycles is implementation-dependent.
default StringGraph	toStringGraph(String[] sortedNodeNames)
int	totalCardinality() Get the combined cardinality of all nodes in this graph - the total number of edges.
List<IntPath>	undirectedPathsBetween(int src, int target) Get a list of all inbound and outbound paths between two nodes.
void	walk(IntGraphVisitor v) Walk the closure of the graph from top level nodes.
void	walk(int startingWith, IntGraphVisitor v) Walk the closure of a node.
void	walkUpwards(IntGraphVisitor v) Walk the inverse closure of the bottom-most nodes in the graph.
void	walkUpwards(int startingWith, IntGraphVisitor v) Walk the inverse closure of one node, visiting each ancestor exactly once.

Method Detail

create

static IntGraph create(BitSet[] reverseReferences,
                       BitSet[] references)

create

static IntGraph create(Bits[] references)

create

static IntGraph create(BitSet[] references)

create

static IntGraph create(Bits[] reverseReferences,
                       Bits[] references)

load

static IntGraph load(ObjectInputStream objectInputStream)
              throws IOException,
                     ClassNotFoundException

Throws:

IOException

ClassNotFoundException

builder

static IntGraphBuilder builder()

builder

static IntGraphBuilder builder(int expectedSize)

toObjectGraph

default <T> ObjectGraph<T> toObjectGraph(List<T> items)

abortableBreadthFirstSearch

boolean abortableBreadthFirstSearch(int startingNode,
                                    boolean up,
                                    IntPredicate cons)

Do a breadth-first search which takes a predicate that will abort the search the first time the predicate returns false.

Parameters:

startingNode - The starting node

up - Wheather to search antecedent nodes or successor nodes

cons - A predicate

Returns:

True if the predicate returned false at some point (i.e. the thing looked for was found in the graph and no further searching was needed, such as reachability tests).

abortableDepthFirstSearch

boolean abortableDepthFirstSearch(int startingNode,
                                  boolean up,
                                  IntPredicate cons)

Do a depth-first search which takes a predicate that will abort the search the first time the predicate returns false.

Parameters:

startingNode - The starting node

up - Wheather to search antecedent nodes or successor nodes

cons - A predicate

Returns:

True if the predicate returned false at some point (i.e. the thing looked for was found in the graph and no further searching was needed, such as reachability tests).

allEdges

PairSet allEdges()

Get all edges in the graph.

Returns:

A set of pairs of edges

bottomLevelNodes

Bits bottomLevelNodes()

Get the set of nodes which have no outbound edges.

Returns:

The set of nodes which have no outbound edges

breadthFirstSearch

void breadthFirstSearch(int startingNode,
                        boolean up,
                        IntConsumer cons)

Do a breadth-first search from the starting node, visiting all nodes in its closure or reverse-closure depending on the value of up, visiting each node in some order at least once.

Parameters:

startingNode - The starting node

up - If true, traverse antecedents of the starting node, not descendants

cons - A consumer which will visit nodes

byClosureSize

int[] byClosureSize()

Return an array of all nodes in the graph, sorted by the size of their closure (the number of distinct descendant nodes they have).

Returns:

A count of nodes

byReverseClosureSize

int[] byReverseClosureSize()

Return an array of all nodes in the graph, sorted by the size of their reverse closure (the number of distinct ancestor nodes they have).

Returns:

A count of nodes

children

Bits children(int node)

Get the set of nodes which have inbound edges from the passed node.

Parameters:

node - A node

Returns:

A set

closureDisjunction

Bits closureDisjunction(int a,
                        int b)

Get the disjunction of the closure of two nodes.

Parameters:

a - The first node

b - The second node

Returns:

A set of nodes

closureDisjunction

Bits closureDisjunction(int... nodes)

Get the set of those nodes which exist in the closure of only one of the passed list of nodes.

Parameters:

nodes - An array of nodes

Returns:

A set

closureDisjunction

Bits closureDisjunction(Bits nodes)

Get the set of those nodes which exist in the closure of only one of the passed list of nodes.

Parameters:

nodes - A set of nodes

Returns:

A set

closureOf

Bits closureOf(int node)

Get the closure of this node - the set of all nodes which have this node as an ancestor.

Parameters:

node - A node

Returns:

A set

closureSize

int closureSize(int node)

Get the count of nodes which have the passed node as an ancestor.

Parameters:

node - A node

Returns:

The number of nodes which have the passed node as an ancestor

closureUnion

Bits closureUnion(int a,
                  int b)

Get the union of the closure of two nodes.

Parameters:

a - The first node

b - The second node

Returns:

A set of nodes

connectors

Bits connectors()

Return the set of nodes in the graph which have both inbound and outbound references.

Returns:

The connector nodes

containsEdge

boolean containsEdge(int a,
                     int b)

Determine if an edge from a to b exists.

Parameters:

a - The first edge

b - The second edge

Returns:

True if the edge exists

depthFirstSearch

void depthFirstSearch(int startingNode,
                      boolean up,
                      IntConsumer cons)

Perform a depth-first search, traversing the closure or reverse-closure of the starting node depth-first.

Parameters:

startingNode - The starting node

up - If true, traverse the reverse-closure

cons - A consumer which will visit nodes

disjointNodes

Bits disjointNodes()

Get the set of nodes in the graph whose closure is not shared by any other nodes.

Returns:

A set of nodes

distance

int distance(int a,
             int b)

Get the minimum distance between two nodes.

Parameters:

a - One node

b - Another node

Returns:

A distance

edges

void edges(IntBiConsumer bi)

Visit all edges in the graph.

Parameters:

bi - A consumer

edgeCount

default int edgeCount()

Get the total number of edges in the graph.

Returns:

The number of edges

eigenvectorCentrality

double[] eigenvectorCentrality(int maxIterations,
                               double minDiff,
                               boolean inEdges,
                               boolean ignoreSelfEdges,
                               boolean l2norm)

Compute the eigenvector centrality of each node in the graph - an importance measure that could loosely be phrased as most likely to be connected through - meaning, unlike page rank, this emphasizes "connector" nodes rather than most-linked nodes - those nodes which, if removed, would break the most paths in the graph.

Parameters:

maxIterations - The maxmum number of iterations to use refining the answer before assuming an optimal answer has been determined

minDiff - The minimum difference in values between iterations which, when reached, indicates that an optimal answer has been determined even if the algorithm has refined the answer for less than maxIterations

inEdges - If true, use inbound rather than outbound edges for the calculation

ignoreSelfEdges - If true, do not count a node's direct cycles to themselves in the score

l2norm - If set, attempt to normalize the result so scores will be comparable across different graphs

Returns:

An array of doubles the same size as the number of nodes in the graph, where the value for each node (the array index) is the score

hasInboundEdge

boolean hasInboundEdge(int from,
                       int to)

Determine if a direct inbound edge exits from one node to another.

Parameters:

from - The source node

to - The destination node

Returns:

True if the edge exists

hasOutboundEdge

boolean hasOutboundEdge(int from,
                        int to)

Determine if a direct outbound edge exits from one node to another.

Parameters:

from - The source node

to - The destination node

Returns:

True if the edge exists

inboundReferenceCount

int inboundReferenceCount(int node)

Returns the number of inbound edges a node has.

Parameters:

node - A node

Returns:

The edge count

isIndirectlyRecursive

boolean isIndirectlyRecursive(int node)

Determine if a node is indirectly recursive - if the closure of it contains a cycle back to it, not counting cycles to itself.

Parameters:

node - A node

Returns:

Whether or not it is indirectly recursive

isReachableFrom

boolean isReachableFrom(int a,
                        int b)

Determine if node b is contained in the closure of node a.

Parameters:

a - A node

b - Another node

Returns:

True if it is reachable

isRecursive

boolean isRecursive(int node)

Determine if the passed node or a descendant of it has a cycle back to itself.

Parameters:

node - A node

Returns:

True if any outbound path from this node directly or indirectly recurses back to it

isReverseReachableFrom

boolean isReverseReachableFrom(int a,
                               int b)

Determine if the closure of a includes b.

Parameters:

a - A node

b - Another node

Returns:

If b is a descendant of a

isUnreferenced

boolean isUnreferenced(int node)

Determine if a node has no inbound edges - no ancestors.

Parameters:

node - The node

Returns:

true if the passed node is not referenced by any other nodes in this graph

neighbors

Bits neighbors(int startingNode)

Get the set of parent and child nodes for a node.

Parameters:

startingNode - A node

Returns:

A set of nodes

orphans

Bits orphans()

Return the set of nodes which have no edges in or out.

Returns:

The set of orphan nodes

outboundReferenceCount

int outboundReferenceCount(int node)

Returns the number of outbound edges a node has.

Parameters:

node - A node

Returns:

The edge count

pageRank

double[] pageRank(double minDifference,
                  double dampingFactor,
                  int maximumIterations,
                  boolean normalize)

Rank the nodes in this graph according to the page rank algorithm, which detects most-linked-to nodes in the graph.

Parameters:

minDifference - The minimum difference after an iteration, at which point the algorithm should bail out and return the answer

dampingFactor - The damping factor

maximumIterations - The maximum number of iterations before the algorithm should assume it has computed an optimal answer and bail out

normalize - If true, normalize the results so they are comparable across calls to this method on different graphs

Returns:

An array of doubles, where the index is the node id and the value is the score

parents

Bits parents(int node)

Get the set of nodes which reference the passed node.

Parameters:

node - A node

Returns:

Nodes which have an outbound edge to the passed one

pathsBetween

List<IntPath> pathsBetween(int src,
                           int target)

Get a list of all paths between the source and target node, sorted low to high by length.

Parameters:

src - The source node

target - The target node

Returns:

A list of paths

reverseClosureOf

Bits reverseClosureOf(int node)

Collect the reverse closure of a node - the set of all nodes which have an outbound edge to this one or an ancestor of those nodes.

Parameters:

node - An element in the graph

Returns:

A bit set

reverseClosureSize

int reverseClosureSize(int node)

Get the count of nodes which have the passed node as a descendant.

Parameters:

node - A node

Returns:

The number of nodes which have the passed node as a descendant

shortestPathBetween

Optional<IntPath> shortestPathBetween(int src,
                                      int target)

Get the shortest path between two nodes in the graph. If multiple paths of the shortest length exist, one will be returned, but which is unspecified.

Parameters:

src - The source node

target - The target node

Returns:

An optional which, if non-empty, contains a path for which no shorter path between the same two nodes exists

toPairSet

PairSet toPairSet()

Convert this graph to a PairSet, which internally uses a single Bits of size * size bits to represent the matrix of all edges. For sparse graphs, this may be a larger data structure than the original graph.

Returns:

A PairSet

topLevelOrOrphanNodes

Bits topLevelOrOrphanNodes()

Get the set of nodes which have no inbound edges - no ancestors.

Returns:

A set

totalCardinality

int totalCardinality()

Get the combined cardinality of all nodes in this graph - the total number of edges.

Returns:

The edge count

walk

void walk(IntGraphVisitor v)

Walk the closure of the graph from top level nodes.

Parameters:

v - A visitor

walk

void walk(int startingWith,
          IntGraphVisitor v)

Walk the closure of a node.

Parameters:

startingWith - The starting node

v - A visitor

walkUpwards

void walkUpwards(IntGraphVisitor v)

Walk the inverse closure of the bottom-most nodes in the graph. Note that this will not traverse subgraphs which are entirely cyclical.

Parameters:

v - A visitor

walkUpwards

void walkUpwards(int startingWith,
                 IntGraphVisitor v)

Walk the inverse closure of one node, visiting each ancestor exactly once.

Parameters:

startingWith - The starting node

v - A visitor

size

int size()

Get the maximum node id + 1 of this graph, or the number of logical nodes. Note that this is not the same as the number of nodes that have edges.

Returns:

The size

save

void save(ObjectOutput out)
   throws IOException

Serialize this graph.

Parameters:

out - Output

Throws:

IOException - If something goes wrong

shortestUndirectedPathBetween

Optional<IntPath> shortestUndirectedPathBetween(int src,
                                                int target)

Get the shortest undirected path between two nodes.

Parameters:

src - The first node

target - The second node

Returns:

A path if one exists

undirectedPathsBetween

List<IntPath> undirectedPathsBetween(int src,
                                     int target)

Get a list of all inbound and outbound paths between two nodes.

Parameters:

src - The first node

target - The second node

Returns:

A list of paths

toStringGraph

default StringGraph toStringGraph(String[] sortedNodeNames)

omitting

IntGraph omitting(int... items)

Create a new graph, sans the passed array of items - the resulting graph will be smaller and if mapped to objects, have different indices than the original.

Parameters:

items - Items which should not be present - indices previously present will be shifted downwards.

Returns:

A new graph with some items removed.

diff

void diff(IntGraph other,
          BiConsumer<IntGraph,IntGraph> c)

Compare this graph and another; it is assumed that they have the same size.

Parameters:

other - Another graph

c - A consumer which will be passed two arguments: A graph containing only added edges, and a graph containing only removed edges

topologicalSort

default IntPath topologicalSort(BitSet bits)

Topologically sort a set of ints; note that if a graph contains cycles, topological sorting is impossible - you will get some order that roughly approximates a topological sort for any ints that are not part of a cycle; the order of appearance of ints that participate in cycles is implementation-dependent.

Parameters:

items - some items

Returns:

A list

topologicalSort

default IntPath topologicalSort(Bits bits)

Topologically sort a set of ints; note that if a graph contains cycles, topological sorting is impossible - you will get some order that roughly approximates a topological sort for any ints that are not part of a cycle; the order of appearance of ints that participate in cycles is implementation-dependent.

Parameters:

items - some items

Returns:

A list