temporal

Graph-level and node-level metrics across a sequence of graphs.

Track graph-level and node-level metrics across a sequence of graphs.

GraphMetric module-attribute

GraphMetric: TypeAlias = Literal[
    "n_nodes",
    "n_edges",
    "density",
    "total_weight",
    "mean_strength",
    "reciprocity",
    "out_strength_hhi",
    "in_strength_hhi",
]

Supported graph-level metrics.

• total_weight: sum of edge weights (for trade, world volume).
• mean_strength: mean total strength per node.
• reciprocity: share of edges whose reverse edge also exists.
• out_strength_hhi / in_strength_hhi: Herfindahl-Hirschman index of out-strength (supplier concentration) or in-strength (buyer concentration) shares, between 1 / n and 1.

graph_summary

graph_summary(
    g: Graph[Any],
    metrics: Sequence[GraphMetric] = DEFAULT_METRICS,
) -> dict[str, float]

Compute graph-level metrics for a single graph.

Parameters:

Name	Type	Description	Default
g	Graph[Any]	A graph whose edges carry "weight".	required
metrics	Sequence[GraphMetric]	Metric names; see GraphMetric.	DEFAULT_METRICS

Returns:

Type	Description
dict	Metric name to value.

Raises:

Type	Description
UnknownMetricError	If a metric name is not supported.

metric_series

metric_series(
    graphs: Mapping[Hashable, Graph[Any]],
    metrics: Sequence[GraphMetric] = DEFAULT_METRICS,
    *,
    custom: Mapping[str, Callable[[Graph[Any]], float]]
    | None = None,
    index_name: str | Sequence[str] | None = None,
) -> DataFrame

Compute graph-level metrics for each graph in a mapping.

Parameters:

Name	Type	Description	Default
graphs	Mapping[Hashable, Graph[Any]]	Graphs keyed by period, for example the output of netviz_tools.graphs_by with by="time".	required
metrics	Sequence[GraphMetric]	Built-in metric names; see GraphMetric.	DEFAULT_METRICS
custom	Mapping[str, Callable[[Graph[Any]], float]] | None	Extra metrics as {name: function}. Each function takes a graph and returns a float.	None
index_name	str | Sequence[str] | None	Name for the index. Tuple keys produce a pandas.MultiIndex.	None

Returns:

Type	Description
DataFrame	One row per graph (in the mapping's order), one column per metric.

Examples:

>>> import netviz_tools as nv
>>> flows = nv.datasets.faostat.load_sample(items="Wheat")
>>> ts = nv.temporal.metric_series(nv.graphs_by(flows, by="time"), ["total_weight"])
>>> int(ts.index.min())
2010

centrality_series

centrality_series(
    graphs: Mapping[Hashable, Graph[Any]],
    kind: CentralityKind = "pagerank",
    *,
    nodes: Sequence[Hashable] | None = None,
    fill_value: float = 0.0,
    index_name: str | Sequence[str] | None = None,
) -> DataFrame

Track one centrality measure for each node across graphs.

Parameters:

Name	Type	Description	Default
graphs	Mapping[Hashable, Graph[Any]]	Graphs keyed by period.	required
kind	CentralityKind	Centrality measure; see netviz_tools.metrics.CentralityKind.	'pagerank'
nodes	Sequence[Hashable] | None	Nodes to keep as columns. Defaults to every node seen in any graph.	None
fill_value	float	Value for a node that is absent from a graph. The default of 0 means "no flows that period".	0.0
index_name	str | Sequence[str] | None	Name for the index.	None

Returns:

Type	Description
DataFrame	One row per graph, one column per node.