econcomplex

econcomplex is a Python library for economic complexity and regional science indicators. It consolidates, in a single coherent API, the tools scattered across the reference packages of the field — EconGeo (R), economiccomplexity (R), py-ecomplexity, py-economic-complexity — and adds a target-oriented optimization layer (ECI Optimization and strategic diffusion) that, to our knowledge, is not available in any other package.

Leia em português: README.pt-BR.md.

What it computes

87 public functions in total — the PDF documentation carries a complete API reference and an interpretation guide for every indicator family.

Installation

pip install econcomplex

Or, for the latest development version straight from GitHub:

pip install git+https://github.com/eltonfreitas/econcomplex.git

Requires Python ≥ 3.9 with numpy ≥ 1.21 (1.x and 2.x supported), pandas ≥ 1.3, scipy ≥ 1.9. For local development:

git clone https://github.com/eltonfreitas/econcomplex.git
cd econcomplex
pip install -e .[dev]
pytest          # 81 tests

Quick start

1. One call, every indicator (long-format data)

import pandas as pd
import econcomplex as ec

df = pd.read_csv("my_data.csv")        # columns: region, sector, employment[, year]

result = ec.compute_complexity(
    df,
    cols={"loc": "region", "act": "sector", "val": "employment", "time": "year"},
    method="eigenvector",              # or "reflections" / "fitness"
)
# adds columns: rca, mcp, diversity, ubiquity, eci, pci, density, distance, coi, cog
# with a "time" column the pipeline recomputes everything per period automatically

2. Working with matrices

mat = ec.pivot_to_matrix(df, "region", "sector", "employment")

eci, pci   = ec.eci_pci(mat)                      # eigenvector method (default)
eci2, pci2 = ec.eci_pci(mat, method="fitness")    # same call, other method

phi     = ec.proximity(mat)["product"]            # product space
density = ec.density(mat, phi=phi)                # 0–100 % relatedness density
coi     = ec.coi(mat, pci, phi=phi)               # diversification potential

Degenerate units (zero diversity or ubiquity) are trimmed automatically and returned as NaN; for very sparse data (e.g. municipal trade) use the well-connected core: ec.eci_pci(mat, dmin=2, umin=2) or ec.trim_core(mat, 2, 2).

3. Diversification targets (ECI Optimization)

Requires a panel with at least the periods t, t+τ and t+Δt:

model = ec.calibrate_steppingstone(panel, "region", "sector", "employment",
                                   "year", horizon=10, steppingstone=5)

portfolio = ec.eci_optimization(mat, model, delta_eci=0.1)
# → minimal-effort set of new activities per region that raises its ECI by 0.1

# Growth targeting: convert a 3.5 %/yr target into an ECI target
gm       = ec.calibrate_growth_model(macro, "region", "year", "gdppc", "eci")
eci_star = ec.eci_target_for_growth(gm, 0.035, gdppc_now)
portfolio = ec.eci_optimization(mat, model, target_eci=eci_star)

# When to make unrelated bets (strategic diffusion)
adj  = ec.proximity_network(mat)
fit  = ec.calibrate_contagion(panel, "region", "sector", "employment", "year",
                              adjacency=adj)
best = ec.optimize_sequence(adj, ec.mcp(mat).loc["my_region"],
                            B=fit["B"], alpha=fit["alpha"])

Data format

The high-level API expects long-format (tidy) data — one row per (location, activity[, period]):

Requirements: no duplicate (location, activity, period) rows, non-negative values, no NaN, a single geographic level and a single activity classification per analysis. Works with employment, exports, patents, payroll — anything shaped location × activity × value. To experiment without data: df = ec.make_sample_data(n_locs=50, n_acts=30, seed=42).

Documentation and examples

• Technical documentation (PDF) — formulas, step-by-step usage, interpretation guide, and the complete API reference: English · Português (LaTeX sources in docs/)
• Runnable examples: examples/basic_usage.py (guided tour of every indicator group) and examples/eci_optimization.py (optimization layer end to end)
• In-code reference: every function has a full NumPy-style docstring — help(ec.eci_pci)
• CHANGELOG.md — release history

The API has three layers (detailed map in the PDF): entry points such as eci_pci and compute_complexity; advanced implementations they delegate to (method_of_reflections, fitness_complexity, …); and short aliases bound to the same objects (density, hhi, coi, pgi, …).

Validation

The 81-test suite includes exact validations against the literature: the eigenvector ECI/PCI uses the proper non-symmetric solver; the strategic diffusion module reproduces the closed-form solution of Alshamsi et al. (2018, eq. 2) on the wheel network; relative relatedness follows Pinheiro et al. (2022, eq. 7) exactly; and the 0–1 portfolio program is solved exactly with scipy.optimize.milp. On the 2022–2024 BACI trade data the library recovers the canonical ECI country ranking.

Citation

@software{freitas_econcomplex_2026,
  author  = {Freitas, Elton},
  title   = {econcomplex: economic complexity and regional science indicators in Python},
  year    = {2026},
  version = {1.0.0},
  url     = {https://github.com/eltonfreitas/econcomplex}
}

Please also cite the original papers of the indicators you use — full list in the PDF documentation. Key references: Hidalgo & Hausmann (2009, PNAS); Hidalgo et al. (2007, Science); Tacchella et al. (2012, Sci. Rep.); Alshamsi, Pinheiro & Hidalgo (2018, Nat. Commun.); Pinheiro et al. (2022, Res. Policy); Stojkoski & Hidalgo (2026, Res. Policy).

License

MIT — see LICENSE.