Graph
Graph functions let you explore the graph structure of your data.
- To consider the top level of your chart, which takes combos into account but ignores their children, use the chart.graph() namespace.
- To consider the underlying level of the chart, or use graph functions without also rendering the chart, use the Graph Engine.
For more information about chart levels, and using graph functions with combos, see the Running graph analysis section in Combos Concepts.
Calculates the betweenness centrality of all nodes in the graph.
Return Object
The returned objects properties are the ids of the nodes in the graph. The values are the betweenness values.
chart.graph().betweenness({}).then((betweenness) => {
const sizes = Object.keys(betweenness).map((id) => {
return { id: id, e: Math.pow(1 + betweenness[id], 2) };
});
return chart.animateProperties(sizes, { time: 500 });
});The betweenness call is asynchronous - the function will return before the betweenness has completed. To discover the progress of the betweenness use the progress event.
Use the returned promise to detect when betweenness has finished.
Parameters
Options which define if the graph is directed, the result normalized and values associated with the links.
boolean
default: false Whether the function should also iterate over hidden items in the chart.
boolean
default: false Whether the betweenness computation should consider the direction of links.
"chart" | "unnormalized" | "component"
default: 'component' Defines how the betweenness measure should be normalized.
string The key of the custom data value on the node's d property that defines each link's length.
boolean
default: false If true, the path length of any link is the reciprocal of the value ( 1 / value ).
Returns
Promise
A Promise that resolves to an object whose properties are the ids of the nodes in the graph. The values are the betweenness values.
Removes all items from the graph engine.
Returns
void
Calculates the closeness centrality of all nodes in the graph.
Return Object
The function returns an object whose properties are the ids of the nodes in the graph. The values are the closeness values.
chart.graph().closeness({}).then((closeness) => {
Object.keys(closeness).forEach((id) => {
console.info(`node '${id}' closeness is ${closeness[id]}`);
});
});The closeness call is asynchronous - the function will return before the closeness has completed. To discover the progress of the closeness use the progress event.
Use a promise function to detect when the closeness has finished.
Parameters
Options which define if the graph is directed, the result normalized and values associated with the links.
- 'from': counts only links with arrows pointing away from nodes (out-degree).
- 'to': counts only links with arrows pointing to nodes (in-degree).
- 'any': counts all links regardless of whether they have arrows.
boolean
default: false Whether the function should also iterate over hidden items in the chart.
"from" | "to" | "any"
default: 'any' How to treat the direction of links:
Note that to use 'from' or 'to', your graph must have arrows on links.
"chart" | "unnormalized" | "component"
default: 'component' Defines how the closeness measure should be normalized.
string The key of the custom data value on the node's d property that defines each link's length.
boolean
default: false This option means that the path length of any link is the reciprocal of the value, i.e. ( 1 / value ).
Returns
Promise
A Promise that resolves to an object whose properties are the ids of the nodes in the graph. The values are the closeness values.
Groups nodes in the graph into a set of clusters, and then returns an array describing them.
Parameters
Options which control how the calculation is done.
boolean
default: false Whether the function should also iterate over hidden items in the chart.
boolean
default: true If true, returns the same result every time you run a cluster.
number
default: 5 A number from 0 to 10 that affects cluster size. Higher values give smaller clusters, but more of them, whereas lower values give larger clusters, but not as many.
string The custom property which defines each link's value. Custom properties are set on the d property of the links. Higher valued links tend to cluster their nodes more closely.
Returns
array
An array [cluster1, cluster2, ...] where cluster1, cluster2... are arrays containing ids of nodes that are all in the same cluster.
Returns the separate 'connected components' of the graph.
Parameters
Options which define special rules for items iteration.
boolean
default: false Whether the function should also iterate over hidden items in the chart.
Returns
array
An array of objects describing the items contained by each component:
[
{ nodes: ['node1', 'node2'], links: ['link-12']},
{ nodes: ['node3']}
]Calculates the degrees (number of links) of all nodes in the graph.
The degrees function does not count any self links (links that have the same node at both ends).
Return Object
The function returns an object whose properties are the ids of the nodes in the graph. The values are the degree values.
const outDegrees = chart.graph().degrees({ direction: 'from' });
const sizes = Object.keys(outDegrees).map((id) => {
return { id: id, e: Math.sqrt(outDegrees[id]) };
});
chart.animateProperties(sizes, { time: 500 });Parameters
Options which define the direction and values associated with the links.
- 'from': counts only links with arrows pointing away from nodes (out-degree).
- 'to': counts only links with arrows pointing to nodes (in-degree).
- 'any': counts all links regardless of whether they have arrows.
boolean
default: false Whether the function should also iterate over hidden items in the chart.
"from" | "to" | "any"
default: 'any' How to treat the direction of links:
Note that to use 'from' or 'to', your graph must have arrows on links.
string The custom property which defines each link's value. Custom properties mean properties set on the d property of the links.
Returns
IdMap
An object whose properties are the ids of the nodes, the values of which are the degree values.
Calculates the distances of all nodes from the node specified. The distance is the number of edges in a shortest path.
All values must be positive numbers. If there are multiple links between two nodes, the minimum distance value will be used. No results are returned for disconnected nodes.
If you do not specify a value property, the distance values of all links are set to 1.
const distances = chart.graph().distances(chart.selection()[0]);
const labels = Object.keys(distances).map((key) => {
return { id: key, t: distances[key] };
});
chart.setProperties(labels);Parameters
Options for the direction and values associated with the paths.
- 'from': counts only links with arrows pointing away from nodes (out-degree).
- 'to': counts only links with arrows pointing to nodes (in-degree).
- 'any': counts all links regardless of whether they have arrows.
boolean
default: false Whether the function should also iterate over hidden items in the chart.
"from" | "to" | "any"
default: 'any' How to treat the direction of links:
Note that to use 'from' or 'to', your graph must have arrows on links.
string The custom property which defines the distance value of a link. Custom properties mean properties set on the d property of the links.
boolean
default: false This option means that the path length of any link is the reciprocal of the value, i.e. ( 1 / value ).
Returns
IdMap
An object whose properties are the ids of the nodes and whose values are the distances.
Computes the eigenvector centrality of each node.
Eigenvector centrality is a measure of influence that takes into account the number of links each node has and the number of links their connections have, and so on throughout the network.
All values must be positive numbers. If there are multiple links between two nodes, the sum of the values of each link will be used.
If you do not specify a value property, the values of all links are set to 1.
The results are normalised so that the sum of the eigenvector centrality values in each component equals the number of nodes in that component. For example, an isolated node will always have an eigenvector centrality of 1.
Link direction does not affect the eigenvector centrality calculation.
Parameters
Options which define special rules for the eigenCentrality computation.
Returns
IdMap
An object listing the eigenvector centrality of each node.
Calculates subgraphs of the graph where each node has a degree of at least k. It works by successively removing nodes of degree less than k until no further nodes can be removed.
Return Object
The function returns an object with all kCores values and the maximum k found in the chart. With a given k it is possible to find all cores components:
const kCores = chart.graph().kCores();
const hidden = Object.keys(kCores.values).filter((id) => {
return kCores.values[id] < 5;
});
chart.hide(hidden, { time: 500 });
// the next call identifies the separate cores
chart.graph().components();Parameters
Options which define special rules for items iteration.
boolean
default: false Whether the function should also iterate over hidden items in the chart.
Returns
object
An object which describes the kCores found.
Replaces the graph data with the new data specified.
Note that the data argument is a JavaScript Object, not a JSON string. It should have the properties specified in Item Format.
Returns
void
Finds items that are neighbours (are linked to) the id or ids passed in.
Parameters
Options which define special rules for items iteration.
- 'from': counts only links with arrows pointing away from nodes (out-degree).
- 'to': counts only links with arrows pointing to nodes (in-degree).
- 'any': counts all links regardless of whether they have arrows.
boolean
default: false Whether the function should also iterate over hidden items in the chart.
"from" | "to" | "any"
default: 'any' How to treat the direction of links:
Note that to use 'from' or 'to', your graph must have arrows on links.
number This defines how far away neighbours can be from the passed ids.@default 1.
Returns
object
A catalogue of the neighbours of the items specified.
Computes the PageRank of each node.
The PageRank measure identifies important nodes by assigning each node a score based on its number of incoming links (its ‘indegree’). These links are weighted depending on the relative scores of their originating nodes.
All values must be positive numbers. If there are multiple links between two nodes, the sum of the values of each link will be used.
If you do not specify a value property, the values of all links are set to 1.
Parameters
Options which define special rules for PageRank computation.
boolean
default: false Whether the function should also iterate over hidden items in the chart.
boolean
default: true If false, all the links are treated as undirected for the PageRank computation.
string The custom property which defines the value of a link. Custom properties mean properties set on the d property of the links. If not set, all links have value 1.
Returns
IdMap
An object containing the PageRank of each node.
Calculates all the shortest paths between the nodes specified.
const paths = chart.graph().shortestPaths('start', 'end', { direction: 'any' });
console.log('Number of hops = ' + paths.distance);
chart.selection(paths.items);All values must be positive numbers.
If you do not specify a value property, the values of all links are set to 1.
Parameters
Options for the direction and values associated with the paths.
- 'from': counts only links with arrows pointing away from nodes (out-degree).
- 'to': counts only links with arrows pointing to nodes (in-degree).
- 'any': counts all links regardless of whether they have arrows.
boolean
default: false Whether the function should also iterate over hidden items in the chart.
"from" | "to" | "any"
default: 'any' How to treat the direction of links:
Note that to use 'from' or 'to', your graph must have arrows on links.
string The custom property which defines the value of a link. Custom properties mean properties set on the d property of the links.
boolean
default: false Whether the path length of any link is the reciprocal of the value, i.e. ( 1 / value ).
Returns
object
An object which describes the path structure.
onePath
required string[] One of the shortest paths found - returned as an array of alternating node and link ids, including the start and end nodes.
one
required string[] An array describing the same path as onePath, but containing node ids only, including the start and end nodes.
items
required string[] An array of all node and link ids that are on any of the shortest paths, including the start and end nodes.
distance
required number The length of the shortest path - more precisely the combined link value of the path.