econcomplex 1.0.0__tar.gz

econcomplex-1.0.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## [1.0.0] — 2026-06-12
+
+First official release.
+
+### Added
+- **Single entry point for complexity**: `eci_pci(mat, method="eigenvector" | "reflections" | "fitness")` in its own module (`complexity/eci_pci.py`), mirroring the interface of the R `economiccomplexity` package. Method-specific implementations remain public for advanced use (`eci_pci_eigenvector`, `method_of_reflections`, `fitness_complexity`).
+- **Pre-processing for sparse data**: `trim_core(mat, dmin, umin)` iteratively prunes degenerate units (zero diversity/ubiquity) recomputing RCA each pass; applied automatically by `eci_pci` (`trim=True`, trimmed units returned as `NaN`). Use `dmin=2, umin=2` for the well-connected core recommended for subnational data.
+- **ECI Optimization** (Stojkoski & Hidalgo 2026, *Research Policy* 55:105454): `calibrate_steppingstone`, `effort_matrix`, `forecast_specialization`, and `eci_optimization` (exact 0–1 program via `scipy.optimize.milp`), plus growth targeting (`calibrate_growth_model`, `eci_target_for_growth`, `expected_growth`).
+- **Strategic diffusion** (Alshamsi, Pinheiro & Hidalgo 2018, *Nat. Commun.* 9:1328): `proximity_network`, `calibrate_contagion`, `activation_probabilities`, `diversification_strategy` (5 strategies), `expected_diversification_time` (validated against the paper's closed-form eq. 2), `compare_strategies`, and `optimize_sequence` (simulated annealing).
+- **Documented short API**: aliases bound to the canonical functions (`density`, `relatedness`, `hhi`, `coi`, `cog`, `pgi`, `peii`, `spec_coefficient`, `cross_space_proximity`), new functions `make_sample_data`, `cosine_proximity`, `correlation_proximity`, and long-format panel wrappers `growth_rates`, `entry_tracking`, `exit_tracking`.
+- `log_fitness` option (Cristelli et al. 2015 log scale) and convergence `tol` for the Method of Reflections; non-convergence warning for Fitness-Complexity.
+- `continuous_method="correlation" | "cosine"` in `proximity()`/`continuous_proximity()`.
+- Runnable examples in `examples/` (`basic_usage.py`, `eci_optimization.py`) and an API map section in the documentation.
+- Expanded documentation: complete auto-generated API reference (87 functions, `docs/generate_api_reference.py`), indicator interpretation guide, and rewritten bilingual READMEs with quickstarts, data format, validation notes, and BibTeX citation.
+
+### Changed
+- Default iterations unified at **20** for reflections and fitness (matching the R `economiccomplexity` package; for fitness it is a cap with early stopping at convergence).
+- Method of Reflections output is now sign-oriented like the eigenvector method (ECI correlates positively with diversity, PCI negatively with ubiquity).
+- `compute_complexity` routes all methods through the `eci_pci` dispatcher (validation and trimming included).
+- Internal relative relatedness of the optimization module now follows Pinheiro et al. (2022, eq. 7) exactly (z-transform over the option set).
+- SciPy minimum raised to 1.9 (`scipy.optimize.milp`).
+- Documentation (EN/PT) fully revised: GitHub installation, real API signatures, new sections (pre-processing, ECI Optimization, strategic diffusion), corrected references (Tacchella et al. 2012).
+
+### Fixed
+- NumPy 2.x compatibility: `np.trapz` removal broke `locational_gini`/`hoover_gini`.
+- `cross_relatedness` returned the wrong column labels (crashed whenever the two spaces had different sizes).
+- Missing standard-deviation guards in the eigenvector sign correction (silent NaN on degenerate matrices).
+- Edge-case guards in the optimization layer (`b1 ≈ 0` effort, `a1 + a3·z ≈ 0` growth-target inversion).
+- Documentation/API mismatches reported by external testing (`rpop`, `pgi`, `peii`, `expy` signatures; `coi`/`cog` argument order; `proximity` return type).
+
+## [0.1.0] — 2026 (initial public release)
+
+- Core indicators: RCA, RPOP, Mcp, diversity/ubiquity; ECI/PCI (eigenvector, reflections, fitness); proximity, relatedness density, co-occurrence, cross-space; specialization, inequality, productivity, patents, dynamics, COI/COG; `compute_complexity` pipeline.

econcomplex-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Elton Freitas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

econcomplex-1.0.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include README.pt-BR.md
+include LICENSE
+include CHANGELOG.md
+recursive-include docs *.pdf *.tex *.py
+recursive-include examples *.py
+

econcomplex-1.0.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: econcomplex
+Version: 1.0.0
+Summary: Python library for economic complexity and regional science indicators
+Author: Elton Freitas
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/eltonfreitas/econcomplex
+Project-URL: Documentation, https://github.com/eltonfreitas/econcomplex/tree/main/docs
+Project-URL: Changelog, https://github.com/eltonfreitas/econcomplex/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/eltonfreitas/econcomplex/issues
+Keywords: economic complexity,regional science,economic geography,product space,relatedness
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Requires-Dist: scipy>=1.9
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Provides-Extra: network
+Requires-Dist: networkx>=2.6; extra == "network"
+Dynamic: license-file
+
+# econcomplex
+
+[![version](https://img.shields.io/badge/version-1.0.0-blue)](CHANGELOG.md)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue)](pyproject.toml)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![tests](https://img.shields.io/badge/tests-81%20passing-brightgreen)](tests/)
+
+**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](README.pt-BR.md).*
+
+---
+
+## What it computes
+
+| Group | Indicators |
+|---|---|
+| **Complexity** | ECI / PCI through a single entry point — `eci_pci(mat, method="eigenvector" \| "reflections" \| "fitness")` — plus subnational ECI projected with an external PCI |
+| **Relatedness / Product Space** | Proximity (discrete, correlation, cosine), relatedness density, distance, relative relatedness (option-set z-score), co-occurrence indices, cross-space proximity between two activity spaces |
+| **Specialization** | Location quotient, Hachman, Krugman, Hoover specialization coefficient, export similarity |
+| **Inequality / Concentration** | Gini, locational Gini, Hoover-Gini, Hoover index, Herfindahl-Hirschman, Shannon entropy |
+| **Productivity** | PRODY, EXPY, Product Gini Index, Product Emissions Intensity Index |
+| **Patents** | Ease of recombination, modular complexity |
+| **Dynamics** | Growth rates, entry/exit tracking — matrix-pair and long-panel APIs |
+| **Outlook** | Complexity Outlook Index (COI) and Gain (COG) |
+| **ECI Optimization** | Stepping-stone forecast model, entry-effort matrix, exact 0–1 program for minimal-effort diversification portfolios, growth targeting (Stojkoski & Hidalgo 2026) |
+| **Strategic diffusion** | Complex-contagion calibration, five diversification strategies, optimal entry sequencing (Alshamsi, Pinheiro & Hidalgo 2018) |
+
+87 public functions in total — the PDF documentation carries a complete API
+reference and an interpretation guide for every indicator family.
+
+## Installation
+
+```bash
+pip install econcomplex
+```
+
+Or, for the latest development version straight from GitHub:
+
+```bash
+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:
+
+```bash
+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)
+
+```python
+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
+
+```python
+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*:
+
+```python
+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]):
+
+| region | sector | employment | year |
+|---|---|---:|---|
+| SP | cnae_10 | 12345 | 2022 |
+| SP | cnae_25 | 6789 | 2022 |
+| RJ | cnae_10 | 9012 | 2022 |
+
+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](docs/econcomplex_documentation_en.pdf) ·
+  [Português](docs/econcomplex_documentation_pt.pdf)
+  (LaTeX sources in [docs/](docs/))
+- **Runnable examples**: [examples/basic_usage.py](examples/basic_usage.py)
+  (guided tour of every indicator group) and
+  [examples/eci_optimization.py](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](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
+
+```bibtex
+@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](LICENSE).

econcomplex-1.0.0/README.md

@@ -0,0 +1,186 @@
+# econcomplex
+
+[![version](https://img.shields.io/badge/version-1.0.0-blue)](CHANGELOG.md)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue)](pyproject.toml)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![tests](https://img.shields.io/badge/tests-81%20passing-brightgreen)](tests/)
+
+**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](README.pt-BR.md).*
+
+---
+
+## What it computes
+
+| Group | Indicators |
+|---|---|
+| **Complexity** | ECI / PCI through a single entry point — `eci_pci(mat, method="eigenvector" \| "reflections" \| "fitness")` — plus subnational ECI projected with an external PCI |
+| **Relatedness / Product Space** | Proximity (discrete, correlation, cosine), relatedness density, distance, relative relatedness (option-set z-score), co-occurrence indices, cross-space proximity between two activity spaces |
+| **Specialization** | Location quotient, Hachman, Krugman, Hoover specialization coefficient, export similarity |
+| **Inequality / Concentration** | Gini, locational Gini, Hoover-Gini, Hoover index, Herfindahl-Hirschman, Shannon entropy |
+| **Productivity** | PRODY, EXPY, Product Gini Index, Product Emissions Intensity Index |
+| **Patents** | Ease of recombination, modular complexity |
+| **Dynamics** | Growth rates, entry/exit tracking — matrix-pair and long-panel APIs |
+| **Outlook** | Complexity Outlook Index (COI) and Gain (COG) |
+| **ECI Optimization** | Stepping-stone forecast model, entry-effort matrix, exact 0–1 program for minimal-effort diversification portfolios, growth targeting (Stojkoski & Hidalgo 2026) |
+| **Strategic diffusion** | Complex-contagion calibration, five diversification strategies, optimal entry sequencing (Alshamsi, Pinheiro & Hidalgo 2018) |
+
+87 public functions in total — the PDF documentation carries a complete API
+reference and an interpretation guide for every indicator family.
+
+## Installation
+
+```bash
+pip install econcomplex
+```
+
+Or, for the latest development version straight from GitHub:
+
+```bash
+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:
+
+```bash
+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)
+
+```python
+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
+
+```python
+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*:
+
+```python
+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]):
+
+| region | sector | employment | year |
+|---|---|---:|---|
+| SP | cnae_10 | 12345 | 2022 |
+| SP | cnae_25 | 6789 | 2022 |
+| RJ | cnae_10 | 9012 | 2022 |
+
+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](docs/econcomplex_documentation_en.pdf) ·
+  [Português](docs/econcomplex_documentation_pt.pdf)
+  (LaTeX sources in [docs/](docs/))
+- **Runnable examples**: [examples/basic_usage.py](examples/basic_usage.py)
+  (guided tour of every indicator group) and
+  [examples/eci_optimization.py](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](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
+
+```bibtex
+@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](LICENSE).

econcomplex-1.0.0/README.pt-BR.md

@@ -0,0 +1,187 @@
+# econcomplex
+
+[![version](https://img.shields.io/badge/vers%C3%A3o-1.0.0-blue)](CHANGELOG.md)
+[![python](https://img.shields.io/badge/python-3.9%2B-blue)](pyproject.toml)
+[![license](https://img.shields.io/badge/licen%C3%A7a-MIT-green)](LICENSE)
+[![tests](https://img.shields.io/badge/testes-81%20passando-brightgreen)](tests/)
+
+**econcomplex** é uma biblioteca Python para **indicadores de complexidade
+econômica e ciência regional**. Ela consolida, numa API única e coerente, as
+ferramentas espalhadas pelos pacotes de referência da área — `EconGeo` (R),
+`economiccomplexity` (R), `py-ecomplexity`, `py-economic-complexity` — e
+adiciona uma **camada de otimização orientada a metas** (Otimização de ECI e
+difusão estratégica) que, até onde sabemos, não existe em nenhum outro pacote.
+
+*Read in English: [README.md](README.md).*
+
+---
+
+## O que ela calcula
+
+| Grupo | Indicadores |
+|---|---|
+| **Complexidade** | ECI / PCI por uma porta de entrada única — `eci_pci(mat, method="eigenvector" \| "reflections" \| "fitness")` — além de ECI subnacional projetado com PCI externo |
+| **Relatedness / Product Space** | Proximidade (discreta, correlação, cosseno), densidade de relatedness, distância, relatedness relativa (z-score no option set), índices de coocorrência, proximidade cross-space entre dois espaços de atividades |
+| **Especialização** | Quociente locacional, Hachman, Krugman, coeficiente de especialização de Hoover, similaridade de exportações |
+| **Desigualdade / Concentração** | Gini, Gini locacional, Hoover-Gini, índice de Hoover, Herfindahl-Hirschman, entropia de Shannon |
+| **Produtividade** | PRODY, EXPY, Product Gini Index, Product Emissions Intensity Index |
+| **Patentes** | Facilidade de recombinação, complexidade modular |
+| **Dinâmica** | Taxas de crescimento, rastreamento de entrada/saída — APIs por pares de matrizes e por painel longo |
+| **Outlook** | Complexity Outlook Index (COI) e Gain (COG) |
+| **Otimização de ECI** | Modelo de previsão com steppingstone, matriz de esforço de entrada, programa 0–1 exato para portfólios de diversificação de menor esforço, metas de crescimento (Stojkoski & Hidalgo 2026) |
+| **Difusão estratégica** | Calibração de contágio complexo, cinco estratégias de diversificação, sequenciamento ótimo de entrada (Alshamsi, Pinheiro & Hidalgo 2018) |
+
+São 87 funções públicas — a documentação em PDF traz a referência completa da
+API e um guia de interpretação para cada família de indicadores.
+
+## Instalação
+
+```bash
+pip install econcomplex
+```
+
+Ou, para a versão de desenvolvimento mais recente direto do GitHub:
+
+```bash
+pip install git+https://github.com/eltonfreitas/econcomplex.git
+```
+
+Exige Python ≥ 3.9 com `numpy ≥ 1.21` (compatível com 1.x **e** 2.x),
+`pandas ≥ 1.3`, `scipy ≥ 1.9`. Para desenvolvimento local:
+
+```bash
+git clone https://github.com/eltonfreitas/econcomplex.git
+cd econcomplex
+pip install -e .[dev]
+pytest          # 81 testes
+```
+
+## Começando
+
+### 1. Uma chamada, todos os indicadores (dados em formato longo)
+
+```python
+import pandas as pd
+import econcomplex as ec
+
+df = pd.read_csv("meus_dados.csv")     # colunas: regiao, setor, emprego[, ano]
+
+resultado = ec.compute_complexity(
+    df,
+    cols={"loc": "regiao", "act": "setor", "val": "emprego", "time": "ano"},
+    method="eigenvector",              # ou "reflections" / "fitness"
+)
+# adiciona as colunas: rca, mcp, diversity, ubiquity, eci, pci, density,
+# distance, coi, cog — com a coluna de tempo, recalcula tudo por período
+```
+
+### 2. Trabalhando com matrizes
+
+```python
+mat = ec.pivot_to_matrix(df, "regiao", "setor", "emprego")
+
+eci, pci   = ec.eci_pci(mat)                      # método do autovetor (padrão)
+eci2, pci2 = ec.eci_pci(mat, method="fitness")    # mesma chamada, outro método
+
+phi     = ec.proximity(mat)["product"]            # product space
+density = ec.density(mat, phi=phi)                # densidade de relatedness (0–100 %)
+coi     = ec.coi(mat, pci, phi=phi)               # potencial de diversificação
+```
+
+Unidades degeneradas (diversidade ou ubiquidade zero) são **podadas
+automaticamente** e retornadas como `NaN`; para dados muito esparsos (ex.:
+comércio municipal) use o núcleo conectado: `ec.eci_pci(mat, dmin=2, umin=2)`
+ou `ec.trim_core(mat, 2, 2)`.
+
+### 3. Alvos de diversificação (Otimização de ECI)
+
+Exige um painel com ao menos os períodos *t*, *t+τ* e *t+Δt*:
+
+```python
+model = ec.calibrate_steppingstone(painel, "regiao", "setor", "emprego",
+                                   "ano", horizon=10, steppingstone=5)
+
+portfolio = ec.eci_optimization(mat, model, delta_eci=0.1)
+# → menor conjunto de esforço de novas atividades, por região, que eleva o ECI em 0.1
+
+# Meta de crescimento: converter 3,5 %/ano em alvo de ECI
+gm       = ec.calibrate_growth_model(macro, "regiao", "ano", "pibpc", "eci")
+eci_alvo = ec.eci_target_for_growth(gm, 0.035, pibpc_atual)
+portfolio = ec.eci_optimization(mat, model, target_eci=eci_alvo)
+
+# Quando fazer a aposta não-relacionada (difusão estratégica)
+adj   = ec.proximity_network(mat)
+fit   = ec.calibrate_contagion(painel, "regiao", "setor", "emprego", "ano",
+                               adjacency=adj)
+otimo = ec.optimize_sequence(adj, ec.mcp(mat).loc["minha_regiao"],
+                             B=fit["B"], alpha=fit["alpha"])
+```
+
+## Formato dos dados
+
+A API de alto nível espera dados em **formato longo** (tidy) — uma linha por
+(local, atividade[, período]):
+
+| regiao | setor | emprego | ano |
+|---|---|---:|---|
+| SP | cnae_10 | 12345 | 2022 |
+| SP | cnae_25 | 6789 | 2022 |
+| RJ | cnae_10 | 9012 | 2022 |
+
+Requisitos: sem linhas duplicadas de (local, atividade, período), valores não
+negativos, sem `NaN`, um único nível geográfico e uma única classificação de
+atividades por análise. Funciona com emprego, exportações, patentes, massa
+salarial — qualquer dado no formato local × atividade × valor. Para
+experimentar sem dados: `df = ec.make_sample_data(n_locs=50, n_acts=30, seed=42)`.
+
+## Documentação e exemplos
+
+- **Documentação técnica (PDF)** — fórmulas, passo a passo de uso, guia de
+  interpretação e a referência completa da API:
+  [Português](docs/econcomplex_documentation_pt.pdf) ·
+  [English](docs/econcomplex_documentation_en.pdf)
+  (fontes LaTeX em [docs/](docs/))
+- **Exemplos executáveis**: [examples/basic_usage.py](examples/basic_usage.py)
+  (tour guiado por todos os grupos de indicadores) e
+  [examples/eci_optimization.py](examples/eci_optimization.py)
+  (camada de otimização de ponta a ponta)
+- **Referência no código**: toda função tem docstring completo no estilo
+  NumPy — `help(ec.eci_pci)`
+- **[CHANGELOG.md](CHANGELOG.md)** — histórico de versões
+
+A API tem três camadas (mapa detalhado no PDF): *portas de entrada* como
+`eci_pci` e `compute_complexity`; *implementações avançadas* para as quais
+elas delegam (`method_of_reflections`, `fitness_complexity`, …); e *aliases*
+curtos ligados aos mesmos objetos (`density`, `hhi`, `coi`, `pgi`, …).
+
+## Validação
+
+A suíte de 81 testes inclui validações exatas contra a literatura: o ECI/PCI
+por autovetor usa o solver não-simétrico correto; o módulo de difusão
+estratégica reproduz a solução fechada de Alshamsi et al. (2018, eq. 2) na
+rede wheel; a relatedness relativa segue Pinheiro et al. (2022, eq. 7)
+exatamente; e o programa 0–1 de portfólio é resolvido de forma exata com
+`scipy.optimize.milp`. Nos dados de comércio BACI 2022–2024 a biblioteca
+recupera o ranking canônico de ECI dos países.
+
+## Citação
+
+```bibtex
+@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}
+}
+```
+
+Cite também os artigos originais dos indicadores utilizados — lista completa
+na documentação em PDF. Referências centrais: 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*).
+
+## Licença
+
+MIT — veja [LICENSE](LICENSE).