metrics

Node centrality, community detection, modularity and community graphs.

Node centrality and community detection for flow graphs.

CentralityKind module-attribute

CentralityKind: TypeAlias = Literal[
    "in_strength",
    "out_strength",
    "strength",
    "in_degree",
    "out_degree",
    "degree",
    "pagerank",
    "reverse_pagerank",
    "betweenness",
]

Supported centrality measures.

• in_strength / out_strength / strength: weighted in, out and total degree, in the graph's unit.
• in_degree / out_degree / degree: number of partners.
• On a directed graph, degree and strength count incoming plus outgoing edges.
• pagerank: weighted PageRank. A node ranks high when large flows arrive from nodes that themselves rank high (an important destination).
• reverse_pagerank: PageRank on the reversed graph. A node ranks high when it sends large flows to nodes that themselves rank high (an important source). Equal to pagerank on undirected graphs.
• betweenness: weighted betweenness, using 1 / weight as the edge length so that large flows count as short, well-used routes.

centrality

centrality(
    g: Graph[Any],
    kinds: Sequence[CentralityKind] = DEFAULT_KINDS,
    *,
    normalized: bool = True,
    alpha: float = 0.85,
) -> DataFrame

Compute several centrality measures at once.

Parameters:

Name	Type	Description	Default
g	Graph[Any]	A graph whose edges carry "weight", as built by netviz_tools.build_graph.	required
kinds	Sequence[CentralityKind]	Measures to compute, in column order. See CentralityKind.	DEFAULT_KINDS
normalized	bool	Normalize betweenness by the number of node pairs.	True
alpha	float	PageRank damping factor.	0.85

Returns:

Type	Description
DataFrame	One row per node, one column per measure, sorted by the first measure in descending order. The index is named "node".

Raises:

Type	Description
UnknownMetricError	If a name in kinds is not supported.

Examples:

>>> import netviz_tools as nv
>>> g = nv.build_graph(nv.datasets.faostat.load_sample(items="Wheat", years=2021))
>>> nv.metrics.centrality(g, ["out_strength", "pagerank"]).columns.tolist()
['out_strength', 'pagerank']

communities

communities(
    g: Graph[Any],
    method: CommunityMethod = "louvain",
    *,
    seed: int = 0,
    resolution: float = 1.0,
) -> Series

Partition the nodes of a graph into communities.

Parameters:

Name	Type	Description	Default
g	Graph[Any]	A graph whose edges carry "weight". Directed graphs use the directed form of modularity.	required
method	CommunityMethod	"louvain" (default) or "greedy_modularity" (Clauset, Newman and Moore), both from NetworkX.	'louvain'
seed	int	Random seed for Louvain, so results are reproducible.	0
resolution	float	Modularity resolution. Values above 1 give more, smaller communities.	1.0

Returns:

Type	Description
Series	Community id per node, named "community". Ids are 0, 1, ... in order of decreasing community size, with ties broken by the smallest member label, so the labelling is stable across runs.

Raises:

Type	Description
UnknownMetricError	If method is not supported.
InsufficientDataError	If the graph has no edges.

modularity

modularity(g: Graph[Any], partition: Series) -> float

Return the weighted modularity of a partition.

Parameters:

Name	Type	Description	Default
g	Graph[Any]	The graph that was partitioned.	required
partition	Series	Community id per node, as returned by communities.	required

Returns:

Type	Description
float	Modularity, between -0.5 and 1. Higher means denser within-community flows than expected by chance.

community_graph

community_graph(
    g: Graph[Any], partition: Series
) -> DiGraph[Any] | Graph[Any]

Collapse each community into a single node.

Parameters:

Name	Type	Description	Default
g	Graph[Any]	The graph that was partitioned.	required
partition	Series	Community id per node, as returned by communities.	required

Returns:

Type	Description
DiGraph or Graph	One node per community with attributes size and members. Edge weight is the total flow between communities; flows inside a community become a self-loop.