netviz_tools

A published Python package that turns raw trade-flow tables into interactive network visualizations — built on NetworkX, with first-class support for FAOSTAT agricultural trade data.

At a Glance

Domain: Open-source tooling / network data visualization — extends NetworkX with interactive Plotly, Sankey, and GeoPandas map output, plus a built-in FAOSTAT agricultural trade dataset (551+ commodities)
Role: Solo project — design, implementation, packaging, and PyPI release
Stack: Python 3.13, NetworkX, pandas, GeoPandas, Plotly, Matplotlib, powerlaw, Pydantic, Rich
Install: pip install netviz_tools
Status: Published on PyPI — v0.2.0 (Beta), MIT-licensed

What it is / problem it solves

NetworkX is the standard for building and analyzing graphs in Python, but it stops short of the steps that actually take the most time in practice: getting messy real-world data into a graph, and getting an analyzable graph back out as something a person can look at. The usual workflow is a pile of one-off scripts — read a CSV, coerce column names, dedupe edges, build the graph, then hand-roll a Matplotlib or Plotly figure every single time.

netviz_tools packages that whole path into four classes so the boilerplate disappears:

DataManager — loads network data from CSV, JSON, Excel, pandas DataFrames, or existing NetworkX graphs; cleans and normalizes it; auto-detects key attributes (including a year column for temporal data); and converts cleanly to and from NetworkX.
NetworkManager — wraps a directed graph, computes centrality, and exports interactive visualizations: a Plotly network plot, a Sankey diagram, and a GeoPandas-backed geographic trade-flow map. It can also fit a power-law to the degree distribution via the powerlaw library.
TimeSeries — analyzes how a network's metrics evolve across years and plots the temporal trends.
FAOSTATManager — the headline feature of v0.2.0: a specialized manager that ships agricultural trade data for 551+ FAOSTAT commodities, so you can go from a commodity name to a trade network in a few lines without sourcing or wrangling the data yourself.

The audience is researchers, students, and data analysts who work with relational or trade-flow data and want the clean-build-visualize pipeline handled for them. The FAOSTAT angle makes it immediately useful for anyone studying international agricultural trade.

Key capabilities

Flexible data import. Load from CSV, JSON, Excel, pandas DataFrames, or NetworkX graphs through a single DataManager interface, with automatic cleaning and attribute detection.
Built-in FAOSTAT trade data (551+ commodities). Browse and search commodities, load one or many at once, pull trade flows for a given commodity and year (with volume thresholds), find a country's top trade partners, and build a ready-to-analyze trade network directly.
Interactive visualizations. Export interactive Plotly network plots, Sankey diagrams, and geographic trade-flow maps (GeoPandas + Plotly Scattergeo) — each can be written to JSON for embedding.
Network analysis. Centrality calculation, density and degree metrics, and power-law fitting of the degree distribution.
Temporal analysis. Built-in year detection, per-year filtering, and time-series plots of how network metrics change over time.
Rich CLI output. Commodity listings and summaries render as formatted tables (via the rich library) for quick exploration.

Usage

Install from PyPI and go from a commodity name to an analyzable trade network in a few lines:

# pip install netviz_tools

import networkx as nx
from netviz_tools import FAOSTATManager

faostat = FAOSTATManager()

# Browse what's available, then load wheat trade data
faostat.list_commodities(search="wheat", limit=10)
faostat.load_commodity("wheat")

# Major wheat trade flows in 2020 (volume threshold to drop noise)
flows = faostat.get_trade_flows(commodity="wheat", year=2020, min_volume=10000)

# Build a trade network and analyze it with plain NetworkX
network = faostat.create_trade_network(commodity="wheat", year=2020, min_volume=100000)
print(f"{network.number_of_nodes()} nodes, {network.number_of_edges()} edges")
print(f"Network density: {nx.density(network):.4f}")

The general (non-FAOSTAT) path is just as short — DataManager loads and cleans arbitrary node/edge tables, and NetworkManager produces the interactive Plotly, Sankey, and geographic outputs.

Limitations / Roadmap

Beta maturity. The package is at v0.2.0 / Development Status 4 - Beta. DataManager and FAOSTATManager are the most complete; NetworkManager and TimeSeries are functional but still maturing.
Python 3.13+. The current release targets Python 3.13 and newer.
Roadmap. A contributing guide is planned, and the visualization layer continues to be expanded as the public API stabilizes.

Tech Stack

Graph engine: NetworkX
Data: pandas, NumPy, GeoPandas (geographic layer)
Visualization: Plotly (interactive network, Sankey, Scattergeo maps), Matplotlib
Analysis: powerlaw (degree-distribution fitting)
Validation / CLI: Pydantic (data models), Rich (formatted tables)
Packaging: Poetry, built and published to PyPI; MIT license