Small, tested building blocks for international-trade analytics on public data — concentration (Herfindahl), trade balance, growth decomposition, and product-classification labels (HS / SITC) from official UN reference files.
Pure pandas, no country-specific assumptions, MIT-licensed. Extracted and generalised from production work on automated trade reporting — kept deliberately small and dependency-light so you can drop it into a notebook or a pipeline.
pip install -e . # core (pandas only)
pip install -e ".[viz]" # + Plotly charts
pip install -e ".[dev]" # + pytest, ruffEverything works on a tidy trade frame — one row per (period, flow, partner, product):
| column | type | example |
|---|---|---|
period |
str / period | "2024-Q1" |
flow |
export/import |
"export" |
partner |
str (ISO-2/3/name) | "US" |
hs6 |
str (6-digit HS) | "260111" |
value |
float | 5200.0 |
A ready-made sample lives in data/sample_trade.csv.
import pandas as pd
from trade_analytics import (
herfindahl_index, trade_balance, bilateral_balance,
sector_contributions, top_movers,
)
df = pd.read_csv("data/sample_trade.csv")
cur = df[df.period == "2024-Q1"]
prev = df[df.period == "2023-Q1"]
# How concentrated are exports across partners? (0 = diversified, 1 = single partner)
herfindahl_index(cur[cur.flow == "export"], by="partner") # normalized HHI*
# Headline balance
trade_balance(cur) # exports / imports / balance
# Who do we run surpluses and deficits with?
bilateral_balance(cur) # per-partner, sorted surplus-first
# What drove the year-over-year change?
sector_contributions(cur, prev, key="hs6") # contribution-to-growth (sums to total growth)
top_movers(cur, prev, key="hs6", n=5) # biggest gainers and losersfrom trade_analytics import viz
viz.balance_bar(bilateral_balance(cur)).show()
viz.top_movers_chart(top_movers(cur, prev)).show()from trade_analytics import references
hs = references.fetch_hs_labels() # {"260111": "Iron ores...", ...} merged HS2012/17/22
df["product"] = references.label_column(df["hs6"], hs)| module | functions |
|---|---|
concentration |
herfindahl_index, concentration_table |
balance |
trade_balance, bilateral_balance |
contributions |
sector_contributions, top_movers |
viz |
treemap_shares, balance_bar, top_movers_chart |
references |
fetch_hs_labels, fetch_sitc_labels, label_column |
See notebooks/comtrade_demo.ipynb for an end-to-end example on
open UN Comtrade data.
pytest # hand-computed oracles for every metric
ruff check .This toolkit distills a few of the reusable, non-proprietary pieces from TradeTensor — an automated, on-premise trade-report generator (customs microdata → analytics → AI-written institutional report). The toolkit ships only the generic, public-data building blocks.
MIT © Romeo Adjovi