de.ipk_gatersleben.ag_nw.centilib.utils
Class CentralityHandler

java.lang.Object
  extended by de.ipk_gatersleben.ag_nw.centilib.utils.CentralityHandler

public class CentralityHandler
extends Object

This class contains only static members and manages all centralities in CentiLib. You can get a list of available centralities with getCentList() or use the static fields for a specific centrality.

Use isPossible(graph, centName) to test whether a graph meets the requirements for a given centrality.

The method getParameter(centName) returns null if no parameter value is needed for the given centrality. Otherwise it returns an instance of the abstract class CentralityParameter. If so, you will need to set a parameter value with setValue(value).

To compute a graph or node centrality call getGraphCentralityValue(..) or getScorer(..). See the documentation for details.

To store computed values, activate the cache function with useCache(true). Be sure to remove these values with removeFromCache(graph) if a graph changes. Otherwise you may work with unreliable values.

To compute centralities for a weighted graph, first set the edge weights with GraphCachingUtils.setEdgeWeights(graph, weights) after activating the cache. Afterwards use the CentralityHandler as you would normally do.

You may also activate a faster computation of shortest-path based centralities by calling useBrandes(true). To start the computations use startBrandes(). For example:

Collection<VertexCentrality<V,E> > cents = new HashSet<VertexCentrality<V, E> >();
CentralityHandler.useCache(true);
CentralityHandler.useBrandes(true);

if(CentratiyHandler.isPossible(graph,CentralityHandler.STRESS)
  cents.add( CentralityHandler.getScorer(graph, CentralityHandler.STRESS, null, true));

if(CentralityHandler.isPossible(graph,CentralityHandler.SPBETWEENNESS))
  cents.add( CentralityHandler.getScorer(graph, CentralityHandler.SPBETWEENNESS, null, true));

CentralityHandler.startBrandes();

Author:
Johannes Graessler

Field Summary
static String AVERAGEDISTANCE
           
static String CENTROID
           
static String CLOSENESS
           
static String CLUSTERINGCOEFFICIENT
           
static String CURRENTFLOWBETWEENNESS
           
static String CURRENTFLOWCLOSENESS
           
static String DEGREE
           
static String DIAMETER
           
static String ECCENTRICITY
           
static String EIGENVECTOR
           
static String HITSAUTHS
           
static String HITSHUBS
           
static String HUBBEL
           
static String INDEGREE
           
static String KATZ
           
static String OUTDEGREE
           
static String PAGERANK
           
static String RADIALITY
           
static String SPBETWEENNESS
           
static String STRESS
           
static String WIENERINDEX
           
 
Constructor Summary
CentralityHandler()
           
 
Method Summary
static
<V,E> Collection<String>
getAvailableCentNames(Graph<V,E> graph)
          Returns a list with the names of already computed centralities for the given graph.
static Collection<String> getCentList()
          Returns the list of all known node centralities
static String getErrorMessage()
          Returns a String with errors that occured in one of this classes methods.
static Collection<String> getGraphCentList()
          Returns the list of all known graph centralities.
static
<V,E> Double
getGraphCentralityValue(Graph<V,E> graph, String centName, boolean compute)
          Computes the graph centralities.
static
<V,E> CentralityParameter
getParameter( centilib, Graph<V,E> graph, String centName, boolean setValue)
           Use the method getParameter(graph, centName) instead.
static
<V,E> CentralityParameter
getParameter(Graph<V,E> graph, String centName)
          If the given centrality needs a parameter value, this method returns an instance of the abstract class CentralityParameter.
static
<V,E> VertexCentrality<V,E>
getScorer(Graph<V,E> graph, String centName, CentralityParameter param, boolean createScorer)
           Returns an instance of VertexCentrality for the given centrality.
static
<V,E> boolean
isPossible(Graph<V,E> graph, String centName)
          Tests whether a graph meets the requirements for the given centrality, i.e.
static void removeFromCache(Graph<?,?> graph)
          Removes the given graph and all its values from the cache.
static void startBrandes()
          If useBrandes(true) was called, this method starts the computation of all shortest-path based centralities which were invoked with getScorer(..).
static void useBrandes(boolean use)
           Compute the shortest-path based centralities in one run.
static void useCache(boolean use)
          Activate or deactivate the cache.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CENTROID

public static final String CENTROID
See Also:
Constant Field Values

CLOSENESS

public static final String CLOSENESS
See Also:
Constant Field Values

CURRENTFLOWBETWEENNESS

public static final String CURRENTFLOWBETWEENNESS
See Also:
Constant Field Values

CURRENTFLOWCLOSENESS

public static final String CURRENTFLOWCLOSENESS
See Also:
Constant Field Values

DEGREE

public static final String DEGREE
See Also:
Constant Field Values

ECCENTRICITY

public static final String ECCENTRICITY
See Also:
Constant Field Values

EIGENVECTOR

public static final String EIGENVECTOR
See Also:
Constant Field Values

HITSAUTHS

public static final String HITSAUTHS
See Also:
Constant Field Values

HITSHUBS

public static final String HITSHUBS
See Also:
Constant Field Values

HUBBEL

public static final String HUBBEL
See Also:
Constant Field Values

INDEGREE

public static final String INDEGREE
See Also:
Constant Field Values

KATZ

public static final String KATZ
See Also:
Constant Field Values

OUTDEGREE

public static final String OUTDEGREE
See Also:
Constant Field Values

PAGERANK

public static final String PAGERANK
See Also:
Constant Field Values

RADIALITY

public static final String RADIALITY
See Also:
Constant Field Values

SPBETWEENNESS

public static final String SPBETWEENNESS
See Also:
Constant Field Values

STRESS

public static final String STRESS
See Also:
Constant Field Values

AVERAGEDISTANCE

public static final String AVERAGEDISTANCE
See Also:
Constant Field Values

CLUSTERINGCOEFFICIENT

public static final String CLUSTERINGCOEFFICIENT
See Also:
Constant Field Values

DIAMETER

public static final String DIAMETER
See Also:
Constant Field Values

WIENERINDEX

public static final String WIENERINDEX
See Also:
Constant Field Values
Constructor Detail

CentralityHandler

public CentralityHandler()
Method Detail

getCentList

public static Collection<String> getCentList()
Returns the list of all known node centralities

Returns:
a list of known node centralities

getGraphCentList

public static Collection<String> getGraphCentList()
Returns the list of all known graph centralities.

Returns:
the list of known graph centralities

useBrandes

public static void useBrandes(boolean use)

Compute the shortest-path based centralities in one run. Use the method getScorer(..) for all needed centralities as you would normaly do and call startBrandes() afterwards. (see the introduction of this class for an example)

If false is given, pending computations will be started before disabling this feature. Otherwise already created instances which didn't compute their values yet, would never be able to do so.

Parameters:
use - sets whether to use this feature or not

startBrandes

public static void startBrandes()
If useBrandes(true) was called, this method starts the computation of all shortest-path based centralities which were invoked with getScorer(..).


useCache

public static void useCache(boolean use)
Activate or deactivate the cache. If the cache is activated, all values like graph properties and centralities will be computed only once. Therefore, make sure to remove a graphs values if it changes (removeFromCache(graph)).

Parameters:
use - sets whether to use the cache or not

removeFromCache

public static void removeFromCache(Graph<?,?> graph)
Removes the given graph and all its values from the cache.

Parameters:
graph - the graph to remove

isPossible

public static <V,E> boolean isPossible(Graph<V,E> graph,
                                       String centName)
Tests whether a graph meets the requirements for the given centrality, i.e. is connected, simple or loop free.
If a centrality is not possible for a given graph, you can get the errors with getErrorMessage(). It only returns a string, which combines all errors that occured and was introduced to inform the user.

Type Parameters:
V - Type of nodes
E - Type of edges
Parameters:
graph - the graph to test
centName - the centrality to test the graph for
Returns:
true if the given centrality can be computed for the graph, false otherwise

getParameter

public static <V,E> CentralityParameter getParameter( centilib,
                                                     Graph<V,E> graph,
                                                     String centName,
                                                     boolean setValue)

Use the method getParameter(graph, centName) instead.

If the given centrality needs a parameter value, this method will return an instance of the abstract class CentralityParameter. The CentiLib instance is used to ask the user for a value (only needed, if the CentiLib GUI is used). If you want to ask him later use false for 'setValue' and call the method askUserForValue() later.

Type Parameters:
V - Type of nodes
E - Type of edges
Parameters:
centilib - used to ask the user for a value
graph - the graph the given centrality shall be computed for
centName - the centrality to get the parameter for, if nedded
setValue - whether to ask the user for a value now or not
Returns:
an instance of CentralityParameter if the given centrality needs a parameter value, null otherwise

getParameter

public static <V,E> CentralityParameter getParameter(Graph<V,E> graph,
                                                     String centName)
If the given centrality needs a parameter value, this method returns an instance of the abstract class CentralityParameter. You have to set a value with setValue(value). You can get the range with getMinValue() and getMaxValue();

Type Parameters:
V - Type of nodes
E - Type of edges
Parameters:
graph - the graph the given centrality shall be computed for
centName - the centrality to get the parameter for
Returns:
an instance of CentralityParameter if needed for the given centrality, null otherwise

getErrorMessage

public static String getErrorMessage()
Returns a String with errors that occured in one of this classes methods. This method was introduced to inform the user about errors. It's not possible to determine single errors.
After this method is called, the errors are deleted.

Returns:
a String with errors that occured since the last call of this method

getAvailableCentNames

public static <V,E> Collection<String> getAvailableCentNames(Graph<V,E> graph)
Returns a list with the names of already computed centralities for the given graph. That is, all centralities for a given Graph, that exist in GraphCachingUtils.
To use this function, the cache has to be activated with useCache(true) before computing centralities.

Parameters:
graph - the graph to get already computed centralities for
Returns:
the names of centralities which are already computed for the given graph

getGraphCentralityValue

public static <V,E> Double getGraphCentralityValue(Graph<V,E> graph,
                                                   String centName,
                                                   boolean compute)
Computes the graph centralities.

Type Parameters:
V - Type of nodes
E - Type of edges
Parameters:
graph - the graph to compute the centrality
centName - the centrality to compute
compute - if true: compute the centrality if it does not exist in the cache
Returns:
the value for the given graph centrality; returns null if not possible or 'compute' is set to false and the value is not available in the cache

getScorer

public static <V,E> VertexCentrality<V,E> getScorer(Graph<V,E> graph,
                                                    String centName,
                                                    CentralityParameter param,
                                                    boolean createScorer)

Returns an instance of VertexCentrality for the given centrality. If the centrality needs a parameter use getParameter(graph, centName). The parameter 'createScorer' determines whether to compute the centrality, if it isn't already available in the cache.

If useBrandes(true) was called, shortest-path based centralities will be computed immediatly. Instead getScorer(.., true) will return an instance, which does not contain any values yet. You also have to start the appropriate computations by calling startBrandes(). The following example shows how to compute all centralities, which do not need a parameter, for a given graph.

CentralityHandler.useCache(true);
CentralityHandler.useBrandes(true);

Collection<VertexCentrality<V,E> > cents = new HashSet<VertexCentrality<V,E> >();
VertexCentrality<V,E> cent;

for(String centName : CentralityHandler.getCentList())
  if(CentralityHandler.isPossible(graph,centName)){
    cent = CentralityHandler.getScorer(graph,centName,null,true);
    if(cent != null)
      cents.add(cent);
  }
CentralityHandler.startBrandes();

Type Parameters:
V - Type of nodes
E - Type of edges
Parameters:
graph - The graph to compute the given centrality for.
centName - The name of the requested centrality.
param - The parameter for the given centrality, if needed, null otherwise.
createScorer - Determines whether to compute the centrality if it is not available in the cache or not.
Returns:
an instance of the given centrality if possible, null otherwise