analysis

Table-level questions: partner rankings and category comparisons. partners and compare_categories are re-exported as nv.partners and nv.compare_categories.

Table-level questions about flows: who a node exchanges with, and how categories compare.

Role module-attribute

Role: TypeAlias = Literal['out', 'in', 'both']

Which flows of the focal node to rank: outgoing ("out", for trade its export destinations), incoming ("in", its import sources), or both side by side.

CategoryMetric module-attribute

CategoryMetric: TypeAlias = Literal[
    "total_weight",
    "n_flows",
    "n_sources",
    "n_targets",
    "n_nodes",
]

Metrics for compare_categories: total weight, number of flow rows, number of distinct sources, of distinct targets, and of distinct nodes (sources and targets combined).

suggest

suggest(
    name: str, choices: Iterable[str], n: int = 5
) -> list[str]

Return up to n choices that resemble name.

Substring matches (case-insensitive) come first, then fuzzy matches from difflib.get_close_matches.

Parameters:

Name	Type	Description	Default
name	str	The string that failed to match.	required
choices	Iterable[str]	Candidate strings.	required
n	int	Maximum number of suggestions.	5

Returns:

Type	Description
list of str	Suggestions, best first, without duplicates.

partners

partners(
    flows: FlowFrame,
    node: str,
    role: Role = "out",
    *,
    top_n: int | None = 10,
    time: int | Iterable[int] | None = None,
    category: Hashable | Iterable[Hashable] | None = None,
) -> DataFrame

Rank the partners of one node.

Parameters:

Name	Type	Description	Default
flows	FlowFrame	A flow frame.	required
node	str	The focal node, matched exactly against source and target.	required
role	Role	"out" ranks where node sends flows (for trade, its export destinations); "in" ranks where its inflows come from (its import sources); "both" returns outflows and inflows per partner, ranked by their total.	'out'
top_n	int | None	Number of partners to return. None returns all.	10
time	int | Iterable[int] | None	Optional filters, each a value or an iterable of values, applied before ranking. Without them, flows over all times and categories in flows are summed.	None
category	int | Iterable[int] | None	Optional filters, each a value or an iterable of values, applied before ranking. Without them, flows over all times and categories in flows are summed.	None

Returns:

Type	Description
DataFrame	Indexed by partner. For "out" and "in" the columns are weight and share (of the node's total for that direction). For "both" the columns are out_weight, in_weight and total_weight.

Raises:

Type	Description
UnknownNodeError	If node does not appear in the (filtered) flows. The error lists close matches.
MixedUnitError	If the flows being summed have more than one unit.
ValueError	If role is not one of the supported values.

Examples:

>>> import netviz_tools as nv
>>> flows = nv.datasets.faostat.load_sample(items="Wheat", years=2021)
>>> top = nv.partners(flows, "Ukraine", role="out", top_n=3)
>>> list(top.columns)
['weight', 'share']

compare_categories

compare_categories(
    flows: FlowFrame,
    metric: CategoryMetric = "total_weight",
    *,
    by_time: bool = False,
) -> DataFrame | Series

Compare categories (for trade, commodities) on one metric.

Parameters:

Name	Type	Description	Default
flows	FlowFrame	A flow frame containing one or more categories.	required
metric	CategoryMetric	"total_weight", "n_flows", "n_sources", "n_targets" or "n_nodes" (sources and targets combined).	'total_weight'
by_time	bool	Return one column per time value instead of a single total.	False

Returns:

Type	Description
Series or DataFrame	Indexed by category, sorted in descending order of the metric (of the latest time value when by_time is true). For total_weight the unit is part of the index so that different units are never compared directly.

Raises:

Type	Description
UnknownMetricError	If metric is not supported.

Examples:

>>> import netviz_tools as nv
>>> flows = nv.datasets.faostat.load_sample(years=2022)
>>> nv.compare_categories(flows, "n_sources").index.tolist()
['Maize (corn)', 'Soya beans', 'Wheat']