uchicago.src.sim.network
Class NetUtilities

java.lang.Object
  uchicago.src.sim.network.NetUtilities

public class NetUtilities
extends java.lang.Object

Performs various common operations on passed networks and returns them, and/or returns a statistic on a passed network and returns the result. Please note that these may be fairly "naive" algorithm implementations, and no guarantees are made about the accuracy of the statistics. The intention is that these may be used for "on the fly" qualitative evaluation of a model, but real network statistics should be done with more serious software such as UCINET or Pajek.

ALL THE METHODS CAN BE CONSIDERED BETA AND SHOULD ONLY BE USED FOR "ON THE FLY" CALCULATIONS. ACTUAL NETWORK STATISTICS SHOULD BE DONE WITH DEDICATED NETWORK ANALYSIS SOFTWARE, SUCH AS PAJEK OR UCINET.

Version:

$Revision: 1.12 $ $Date: 2004/11/03 19:51:01 $

Author:

Skye Bender-deMoll

Constructor Summary

NetUtilities()
No-Argument constructor for convenience / aliasing.

Method Summary

static double	calcAvgPathLength(java.util.List nodes) Returns a double equal to the average or "characteristic" path length of the graph.
static double	calcClustCoef(java.util.List nodes) Calculates the clustering coefficient (avg. density of "ego networks") in graph.
static double	calcDensity(java.util.List nodes) calculates density (ratio of arcs in network to maximum possible number of arcs) of passed network.
static double	calcDensity(java.util.List nodes, boolean collapseMulti) Calculates density of the network, but if collapseMulti is true, it first collapses any multiplex ties.
static double	calcDiameter(java.util.List nodes) Returns a double equal to the graph-theoretic diameter of the passed network (the length of the longest shortest path).
static double	calcSymmetry(java.util.List nodes) Returns a double indicating the amount of symmetry in the network: fraction of existing i -> j ties for which there is a j -> i tie.
static int	countIJTies(Node iNode, Node jNode) Returns the number of ties from i to j.
static int	getAllDegree(Node iNode) Returns the number of arcs node is involved in.
static cern.colt.matrix.impl.DenseDoubleMatrix2D	getAllShortPathMatrix(java.util.List nodes) Returns a DenseDoubleMatrix2D in which the i,j th entry gives the length of the shortest path between i and j. i and j indexes refer to the position of the node in the ArrayList parameter.
static java.util.ArrayList	getComponents(java.util.List nodes) Returns an ArrayList of length equal to the number of components in the graph, each entry of which is an ArrayList of the nodes in that component.
static double	getIJShortPathLength(java.util.List nodes, Node iNode, Node jNode) Returns a double with a value equal to the length of the shortest path between i and j.
static int	getIJTie(Node iNode, Node jNode) Returns 1 if a tie from i to j exists, 0 otherwise.
static double	getIJTieStrength(Node iNode, Node jNode) Returns double value from getStrength() if tie from i to j exists, returns 0.0 if none exists.
static int	getInDegree(Node iNode) Returns the in degree (number of in edges) of the node.
static int	getNumDirectTriads(Node iNode, Node jNode) Finds and returns the number of "parents" (nodes with links TO both i and j)
static int	getOutDegree(Node iNode) Returns the out degree (number of out edges) of the node.
static java.lang.String	getStatsString(java.util.List nodes) Returns a string, each line of which consists of the name of a graph statistic and its value.
static boolean	hasSelfLoops(java.util.List nodes) Returns a boolean indicating whether the network contains self-loops (links from i -> i)
static boolean	isMultiplexNet(java.util.List nodes) Checks if there are any nodes i j for which there is more than one tie i -> j (almost all network statistics assume that the network is NOT multiplex)
static java.util.List	randomRewire(java.util.List nodes, double rewireProb) Returns a network of the same size and density as the passed network, but randomly "rewires" a fraction of the edges to randomly chosen target nodes.
static java.util.List	randomRewireSymmetric(java.util.List nodes, double rewireProb) Returns a network of the same size and density as the passed network, but randomly "rewires" a fraction of the edges to randomly chosen target nodes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NetUtilities

public NetUtilities()

No-Argument constructor for convenience / aliasing.

Method Detail

calcClustCoef

public static double calcClustCoef(java.util.List nodes)

Calculates the clustering coefficient (avg. density of "ego networks") in graph.

Parameters:

nodes - the network for which the ClustCoef will be calculated

calcDensity

public static double calcDensity(java.util.List nodes)

calculates density (ratio of arcs in network to maximum possible number of arcs) of passed network. Checks to make sure network is non-multiplex. Includes self-loops.

calcDensity

public static double calcDensity(java.util.List nodes,
                                 boolean collapseMulti)

Calculates density of the network, but if collapseMulti is true, it first collapses any multiplex ties. If collapseMulti is false, it runs without checking for multiplex ties. Note: if the argument is false, and multiplex ties exist, calcDensity will still return a value, but it will not exactly correspond to the density. But it will run much faster than calcDensity(ArrayList nodes). The possibility of self-loops is assumed

Parameters:

nodes - the ArrayList of nodes to examine

isMultiplexNet

public static boolean isMultiplexNet(java.util.List nodes)

Checks if there are any nodes i j for which there is more than one tie i -> j (almost all network statistics assume that the network is NOT multiplex)

hasSelfLoops

public static boolean hasSelfLoops(java.util.List nodes)

Returns a boolean indicating whether the network contains self-loops (links from i -> i)

Parameters:

nodes - the ArrayList of nodes to examine for loops

getIJTie

public static int getIJTie(Node iNode,
                           Node jNode)

Returns 1 if a tie from i to j exists, 0 otherwise.

Parameters:

iNode - the node the tie is from

jNode - the node the tie is to

getIJTieStrength

public static double getIJTieStrength(Node iNode,
                                      Node jNode)

Returns double value from getStrength() if tie from i to j exists, returns 0.0 if none exists. Note: will also return 0.0 if strength of existing tie is 0.0. Use getIJTie(iNode, jNode) to test for existence. If more than one tie exists, this returns the value of first tie encountered.

Parameters:

iNode - the node the tie is from

jNode - the node the tie is to

countIJTies

public static int countIJTies(Node iNode,
                              Node jNode)

Returns the number of ties from i to j. Note: this is not necessarily the same as the number of ties from j to i !

Parameters:

iNode - the node ties are from

jNode - the node ties are to

getOutDegree

public static int getOutDegree(Node iNode)

Returns the out degree (number of out edges) of the node.

Parameters:

iNode - the node the degree will be returned for

getInDegree

public static int getInDegree(Node iNode)

Returns the in degree (number of in edges) of the node. (Assumes inEdges have been set correctly)

Parameters:

iNode - the node the degree will be returned for

getAllDegree

public static int getAllDegree(Node iNode)

Returns the number of arcs node is involved in. (Outdegree + Indegree). (Assumes inEdges have been set correctly)

Parameters:

iNode - the node the degree will be returned for

getNumDirectTriads

public static int getNumDirectTriads(Node iNode,
                                     Node jNode)

Finds and returns the number of "parents" (nodes with links TO both i and j)

Parameters:

iNode - one node of triad

jNode - the second node of the triad

getIJShortPathLength

public static double getIJShortPathLength(java.util.List nodes,
                                          Node iNode,
                                          Node jNode)

Returns a double with a value equal to the length of the shortest path between i and j. Paths are calculated according to an implementation of "Dijkstra's" algorithm. Distances are obtained from the outedge's getStrength() method, and are assumed to be symmetric and non-negitive. If it is known that all edge strengths are equal to 1 (the default), the graph distance can be obtained by casting the double to an int.

Parameters:

nodes - the complete network of nodes

iNode - the originating node for the path

jNode - the destination node for the path

getAllShortPathMatrix

public static cern.colt.matrix.impl.DenseDoubleMatrix2D getAllShortPathMatrix(java.util.List nodes)

Returns a DenseDoubleMatrix2D in which the i,j th entry gives the length of the shortest path between i and j. i and j indexes refer to the position of the node in the ArrayList parameter. Paths are calculated according to an implementation of Dijkstra's algorithm, and timing will be approx. O(N E log N). Distances are obtained from the outedge's getStrength() method, and are assumed to be symmetric and non-negitive. !!!!BETA!!!!

Parameters:

nodes - the network which the matrix will be returned for

calcDiameter

public static double calcDiameter(java.util.List nodes)

Returns a double equal to the graph-theoretic diameter of the passed network (the length of the longest shortest path). Requires the calculation of all shortest paths using "Dijkstra's" algorithm, and timing will be approx. O(N E log N).Distances are obtained from the outedge's getStrength() method, and are assumed to be symmetric and non-negitive.

Parameters:

nodes - the network for which the diameter will be calculated

calcAvgPathLength

public static double calcAvgPathLength(java.util.List nodes)

Returns a double equal to the average or "characteristic" path length of the graph. Uses the "Dijkstra's" shortest path method. Ignores diagonal. BETA AND TAKES AN UNREASONABLY LONG PERIOD OF TIME

Parameters:

nodes - the network to evaluate

calcSymmetry

public static double calcSymmetry(java.util.List nodes)

Returns a double indicating the amount of symmetry in the network: fraction of existing i -> j ties for which there is a j -> i tie. Assumes that inEdges have been set. Doesn't make sense for multiplex nets Will return 1.0 if network is Symmetric, or if size of network is 0;

Parameters:

nodes - the network to evaluate for symmetry

getComponents

public static java.util.ArrayList getComponents(java.util.List nodes)

Returns an ArrayList of length equal to the number of components in the graph, each entry of which is an ArrayList of the nodes in that component.

Parameters:

nodes - the network in which components will be counted

randomRewire

public static java.util.List randomRewire(java.util.List nodes,
                                          double rewireProb)

Returns a network of the same size and density as the passed network, but randomly "rewires" a fraction of the edges to randomly chosen target nodes. Will not create self loops or multiplex ties.

Parameters:

rewireProb - the fraction of edges to rewire

randomRewireSymmetric

public static java.util.List randomRewireSymmetric(java.util.List nodes,
                                                   double rewireProb)

Returns a network of the same size and density as the passed network, but randomly "rewires" a fraction of the edges to randomly chosen target nodes. Will not create self loops or multiplex ties. Will also rewire j to i ties, throws repast exception if network is not symmetric.

Parameters:

rewireProb - the fraction of edges to rewire

getStatsString

public static java.lang.String getStatsString(java.util.List nodes)

Returns a string, each line of which consists of the name of a graph statistic and its value. The order is: Size: int NumComponents: int Density: double ClustringCoeff: double isMultiplex: boolean hasSelfLoops: boolean Diameter: double AvgPathLength: double Symmetry: double

Please note that this call will be quite "expensive" on large networks!

Parameters:

nodes - the network for which the statistics will be calculated