econcomplex 1.0.0__py3-none-any.whl

econcomplex/__init__.py

@@ -0,0 +1,220 @@
+"""
+econcomplex — Economic Complexity and Geographic Indicators Library
+===================================================================
+
+A consolidated Python library for computing Economic Complexity indicators
+and Geographic/Regional Science metrics, combining the best implementations
+from EconGeo (R), economiccomplexity (R), py-ecomplexity, and
+py-economic-complexity.
+
+Quick start
+-----------
+>>> import econcomplex as ec
+>>> import pandas as pd
+>>>
+>>> # Long-format data: location × activity × value
+>>> df = pd.read_csv("my_data.csv")
+>>>
+>>> # Full pipeline (single period)
+>>> result = ec.compute_complexity(
+...     df,
+...     cols={"loc": "region", "act": "sector", "val": "employment"},
+...     method="eigenvector",
+... )
+>>>
+>>> # Individual indicators
+>>> mat = ec.pivot_to_matrix(df, "region", "sector", "employment")
+>>> rca_mat    = ec.rca(mat)
+>>> eci, pci   = ec.eci_pci(mat)
+>>> phi        = ec.proximity(mat)["product"]
+>>> density    = ec.relatedness_density(mat, phi=phi)
+
+Submodules
+----------
+core          : RCA, RPOP, Mcp, diversity, ubiquity, trim_core, utilities
+complexity    : eci_pci() — single entry point (eigenvector, reflections,
+                fitness) — plus the method-specific implementations and
+                subnational ECI
+relatedness   : proximity (discrete/continuous/cosine/correlation),
+                relatedness density, distance, co-occurrence,
+                z-score novelty, cross-space proximity/relatedness
+specialization: location quotient, Hachman, Krugman, specialization coeff,
+                export similarity
+inequality    : Gini, locational Gini, Hoover-Gini, Hoover index,
+                Herfindahl-Hirschman, Shannon entropy
+productivity  : PRODY, EXPY, Product Gini Index, PEII
+patents       : ease of recombination, modular complexity
+dynamics      : growth rates, entry/exit tracking (matrix and panel APIs)
+outlook       : COI, COG (Complexity Outlook)
+optimization  : ECI Optimization (Stojkoski & Hidalgo 2026), growth
+                targeting, strategic diffusion (Alshamsi et al. 2018)
+pipeline      : high-level compute_complexity() function
+
+Note: short names like density, hhi, coi, cog, pgi are aliases bound to
+the same objects as their canonical functions (see the API map in the
+documentation).
+"""
+
+__version__ = "1.0.0"
+__author__ = "Elton Freitas and contributors"
+
+# ── Core ──────────────────────────────────────────────────────────────────────
+from .core.rca import rca, rpop, mcp
+from .core.diversity import diversity, ubiquity, normalized_ubiquity
+from .core.utils import (
+    pivot_to_matrix,
+    melt_matrix,
+    binarize,
+    normalize_zscore,
+    normalize_01,
+    make_sample_data,
+)
+from .core.preprocess import trim_core
+
+# ── Complexity ─────────────────────────────────────────────────────────────────
+from .complexity.eci_pci import eci_pci
+from .complexity.eigenvector import eci_pci_eigenvector
+from .complexity.reflections import method_of_reflections, mor_regions, mor_activities
+from .complexity.fitness import fitness_complexity
+from .complexity.subnational import subnational_eci
+
+# ── Relatedness ────────────────────────────────────────────────────────────────
+from .relatedness.proximity import (
+    proximity,
+    continuous_proximity,
+    cosine_proximity,
+    correlation_proximity,
+    relatedness,
+)
+from .relatedness.density import (
+    relatedness_density,
+    density,
+    distance,
+    relatedness_density_internal,
+    relatedness_density_external,
+    relative_relatedness,
+)
+from .relatedness.cooccurrence import co_occurrence, relatedness_index, z_score_novelty
+from .relatedness.cross_space import cross_proximity, cross_relatedness, cross_space_proximity
+
+# ── Specialization ─────────────────────────────────────────────────────────────
+from .specialization.location_quotient import (
+    location_quotient,
+    location_quotient_avg,
+    hachman_index,
+    specialization_coefficient,
+    spec_coefficient,
+    krugman_index,
+)
+from .specialization.similarity import export_similarity
+
+# ── Inequality ─────────────────────────────────────────────────────────────────
+from .inequality.gini import gini, locational_gini, hoover_gini
+from .inequality.concentration import herfindahl, hhi, shannon_entropy, hoover_index
+
+# ── Productivity ───────────────────────────────────────────────────────────────
+from .productivity.prody import (
+    prody,
+    expy,
+    product_gini_index,
+    pgi,
+    product_emissions_index,
+    peii,
+)
+
+# ── Patents ────────────────────────────────────────────────────────────────────
+from .patents.recombination import (
+    ease_of_recombination,
+    modular_complexity,
+    modular_complexity_avg,
+)
+
+# ── Dynamics ───────────────────────────────────────────────────────────────────
+from .dynamics.growth import growth_rate, growth_matrix, growth_rates
+from .dynamics.entry_exit import (
+    entry,
+    exit,
+    entry_exit_summary,
+    entry_tracking,
+    exit_tracking,
+)
+
+# ── Outlook ────────────────────────────────────────────────────────────────────
+from .outlook.coi_cog import complexity_outlook_index, complexity_outlook_gain, coi, cog
+
+# ── ECI Optimization (Stojkoski & Hidalgo 2026) ───────────────────────────────
+from .optimization import (
+    calibrate_steppingstone,
+    effort_matrix,
+    forecast_specialization,
+    eci_optimization,
+    calibrate_growth_model,
+    expected_growth,
+    eci_target_for_growth,
+)
+
+# ── Strategic diffusion (Alshamsi, Pinheiro & Hidalgo 2018) ───────────────────
+from .optimization import (
+    proximity_network,
+    activation_probabilities,
+    calibrate_contagion,
+    diversification_strategy,
+    expected_diversification_time,
+    compare_strategies,
+    optimize_sequence,
+)
+
+# ── High-level pipeline ────────────────────────────────────────────────────────
+from .pipeline import compute_complexity
+
+__all__ = [
+    # core
+    "rca", "rpop", "mcp",
+    "diversity", "ubiquity", "normalized_ubiquity",
+    "pivot_to_matrix", "melt_matrix", "binarize",
+    "normalize_zscore", "normalize_01",
+    "make_sample_data", "trim_core",
+    # complexity
+    "eci_pci", "eci_pci_eigenvector",
+    "method_of_reflections", "mor_regions", "mor_activities",
+    "fitness_complexity",
+    "subnational_eci",
+    # relatedness
+    "proximity", "continuous_proximity",
+    "cosine_proximity", "correlation_proximity",
+    "relatedness_density", "density", "relatedness", "distance",
+    "relatedness_density_internal", "relatedness_density_external",
+    "relative_relatedness",
+    "co_occurrence", "relatedness_index", "z_score_novelty",
+    "cross_proximity", "cross_relatedness", "cross_space_proximity",
+    # specialization
+    "location_quotient", "location_quotient_avg",
+    "hachman_index", "specialization_coefficient", "spec_coefficient",
+    "krugman_index",
+    "export_similarity",
+    # inequality
+    "gini", "locational_gini", "hoover_gini",
+    "herfindahl", "hhi", "shannon_entropy", "hoover_index",
+    # productivity
+    "prody", "expy",
+    "product_gini_index", "pgi",
+    "product_emissions_index", "peii",
+    # patents
+    "ease_of_recombination", "modular_complexity", "modular_complexity_avg",
+    # dynamics
+    "growth_rate", "growth_matrix", "growth_rates",
+    "entry", "exit", "entry_exit_summary",
+    "entry_tracking", "exit_tracking",
+    # outlook
+    "complexity_outlook_index", "complexity_outlook_gain", "coi", "cog",
+    # optimization
+    "calibrate_steppingstone", "effort_matrix", "forecast_specialization",
+    "eci_optimization",
+    "calibrate_growth_model", "expected_growth", "eci_target_for_growth",
+    # strategic diffusion
+    "proximity_network", "activation_probabilities", "calibrate_contagion",
+    "diversification_strategy", "expected_diversification_time",
+    "compare_strategies", "optimize_sequence",
+    # pipeline
+    "compute_complexity",
+]

econcomplex/complexity/__init__.py

@@ -0,0 +1,23 @@
+"""
+Economic complexity indicators.
+
+`eci_pci(mat, method=...)` is the single entry point (eigenvector,
+reflections, or fitness). The method-specific implementations remain
+public for advanced use.
+"""
+
+from .eci_pci import eci_pci
+from .eigenvector import eci_pci_eigenvector
+from .reflections import method_of_reflections, mor_regions, mor_activities
+from .fitness import fitness_complexity
+from .subnational import subnational_eci
+
+__all__ = [
+    "eci_pci",
+    "eci_pci_eigenvector",
+    "method_of_reflections",
+    "mor_regions",
+    "mor_activities",
+    "fitness_complexity",
+    "subnational_eci",
+]

econcomplex/complexity/eci_pci.py

@@ -0,0 +1,131 @@
+"""
+ECI / PCI — single entry point for all complexity methods.
+
+`eci_pci(mat, method=...)` is the recommended way to compute economic
+complexity with this library. It dispatches between the three methods
+(mirroring `complexity_measures()` of the R `economiccomplexity` package),
+pre-trims degenerate units, and returns results aligned with the input.
+
+The underlying implementations remain available for advanced use:
+`eci_pci_eigenvector` (module `eigenvector`), `method_of_reflections`
+(module `reflections`), and `fitness_complexity` (module `fitness`).
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Literal, Optional, Tuple, Union
+
+from .eigenvector import eci_pci_eigenvector
+from .reflections import method_of_reflections
+from .fitness import fitness_complexity
+
+
+def eci_pci(
+    mat: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+    method: Literal["eigenvector", "reflections", "fitness"] = "eigenvector",
+    iterations: Optional[int] = None,
+    extremality: float = 1.0,
+    tol: float = 1e-10,
+    log_fitness: bool = False,
+    trim: bool = True,
+    dmin: int = 1,
+    umin: int = 1,
+) -> Tuple[Union[pd.Series, np.ndarray], Union[pd.Series, np.ndarray]]:
+    """
+    Economic Complexity Index (ECI) and Product Complexity Index (PCI).
+
+    Single entry point for the three complexity methods (mirrors the
+    `complexity_measures()` interface of the R `economiccomplexity`
+    package):
+
+    - 'eigenvector' (default): second eigenvector of the Markov-style
+      co-occurrence matrices (Hidalgo & Hausmann 2009, OEC Atlas form).
+      ECI/PCI are z-score normalized, sign-corrected so that ECI
+      correlates positively with diversity and PCI negatively with
+      ubiquity.
+    - 'reflections': iterative Method of Reflections
+      (delegates to `method_of_reflections`).
+    - 'fitness': non-linear Fitness-Complexity algorithm of
+      Tacchella et al. (2012) (delegates to `fitness_complexity`;
+      returns raw fitness/complexity scores, not z-scores).
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    use_rca : bool
+        Compute RCA before binarizing.
+    threshold : float
+        Binarization threshold.
+    method : str
+        'eigenvector', 'reflections', or 'fitness'.
+    iterations : int, optional
+        Iterations for 'reflections' and 'fitness' (default 20 for both,
+        matching the R `economiccomplexity` package; for 'fitness' it is
+        a cap — the loop stops at convergence and warns if the cap is hit
+        first). Ignored by 'eigenvector'.
+    extremality : float
+        Non-linearity parameter alpha for 'fitness' (default 1.0).
+    tol : float
+        Convergence tolerance for 'reflections' and 'fitness'.
+    log_fitness : bool
+        For 'fitness': return the natural log of fitness/complexity
+        (Cristelli et al. 2015). Ignored by the other methods.
+    trim : bool
+        If True (default), pre-trim the matrix with `trim_core` so that
+        degenerate units — locations with zero diversity and activities
+        with zero ubiquity — are excluded from the calculation. Trimmed
+        units are returned as NaN, preserving the original index/shape.
+    dmin, umin : int
+        Diversity/ubiquity thresholds passed to `trim_core` (default 1).
+        Use 2 for the well-connected core recommended for very sparse
+        networks.
+
+    Returns
+    -------
+    (eci, pci) as pd.Series or ndarrays, aligned with the input matrix
+    (NaN for units removed by trimming).
+    """
+    if trim:
+        from ..core.preprocess import trim_core
+        is_df_in = isinstance(mat, pd.DataFrame)
+        df = mat if is_df_in else pd.DataFrame(np.asarray(mat, dtype=float))
+        trimmed = trim_core(df, dmin=dmin, umin=umin,
+                            use_rca=use_rca, threshold=threshold)
+        if trimmed.shape[0] < 2 or trimmed.shape[1] < 2:
+            raise ValueError(
+                f"After trimming to the ({dmin}, {umin})-core the matrix has "
+                f"shape {trimmed.shape}; not enough connected units to "
+                "compute complexity."
+            )
+        if trimmed.shape != df.shape:
+            res_r, res_c = eci_pci(
+                trimmed, use_rca=use_rca, threshold=threshold, method=method,
+                iterations=iterations, extremality=extremality, tol=tol,
+                log_fitness=log_fitness, trim=False,
+            )
+            res_r = res_r.reindex(df.index)
+            res_c = res_c.reindex(df.columns)
+            if not is_df_in:
+                return res_r.values, res_c.values
+            return res_r, res_c
+
+    if method == "eigenvector":
+        return eci_pci_eigenvector(mat, use_rca=use_rca, threshold=threshold)
+    if method == "reflections":
+        return method_of_reflections(
+            mat, use_rca=use_rca, threshold=threshold,
+            iterations=iterations if iterations is not None else 20,
+            tol=tol,
+        )
+    if method == "fitness":
+        return fitness_complexity(
+            mat, use_rca=use_rca, threshold=threshold,
+            iterations=iterations if iterations is not None else 20,
+            extremality=extremality, tol=tol, log_fitness=log_fitness,
+        )
+    raise ValueError(
+        "method must be 'eigenvector', 'reflections', or 'fitness'."
+    )

econcomplex/complexity/eigenvector.py

@@ -0,0 +1,115 @@
+"""
+Eigenvector implementation of Economic Complexity (ECI / PCI).
+
+This module holds the eigenvector method only. The recommended entry
+point for users is `eci_pci()` (module `complexity.eci_pci`), which
+dispatches between the eigenvector, reflections, and fitness methods.
+
+References
+----------
+Hidalgo & Hausmann (2009); Balland & Rigby (2017).
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Tuple, Union
+
+from ..core.utils import validate_matrix, safe_divide, normalize_zscore, binarize
+from ..core.rca import rca as compute_rca
+
+
+def _second_eigenvector(mat: np.ndarray) -> np.ndarray:
+    """Return the eigenvector corresponding to the second largest eigenvalue.
+
+    The Markov-style co-occurrence matrix (Mcc / Mpp) is in general NOT
+    symmetric, because each row is normalised by its own diversity/ubiquity.
+    We therefore use the general (non-symmetric) eigensolver ``np.linalg.eig``
+    and select the eigenvector associated with the second-largest eigenvalue
+    by real part. The largest eigenvalue corresponds to the trivial constant
+    vector; the second is the Hidalgo-Hausmann (2009) complexity index.
+
+    Using ``np.linalg.eigh`` here would be incorrect: it assumes a symmetric
+    matrix and reads only one triangle, yielding the eigenvector of an
+    arbitrarily symmetrised matrix rather than the true second eigenvector.
+    """
+    eigenvalues, eigenvectors = np.linalg.eig(mat)
+    order = np.argsort(eigenvalues.real)
+    return np.real(eigenvectors[:, order[-2]])
+
+
+def eci_pci_eigenvector(
+    mat: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+) -> Tuple[Union[pd.Series, np.ndarray], Union[pd.Series, np.ndarray]]:
+    """
+    ECI and PCI via the eigenvector method (advanced implementation;
+    prefer `eci_pci(mat, method="eigenvector")`, which adds the automatic
+    trimming of degenerate units).
+
+    Builds Markov matrices:
+      Mcc_{rr'} = sum_c (M_{rc}/D_r) * (M_{r'c}/U_c)
+      Mpp_{pp'} = sum_r (M_{rp}/U_p) * (M_{rp'}/D_r)
+
+    ECI = second eigenvector of Mcc (sign: positive correlation with diversity).
+    PCI = second eigenvector of Mpp (sign: negative correlation with ubiquity).
+    Both are z-score normalized.
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    use_rca : bool
+        Compute RCA before binarizing.
+    threshold : float
+        Binarization threshold.
+
+    Returns
+    -------
+    (eci, pci) as pd.Series or ndarrays.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    row_index = mat.index if is_df else None
+    col_index = mat.columns if is_df else None
+
+    arr = validate_matrix(mat)
+
+    if use_rca:
+        m = binarize(compute_rca(arr), threshold)
+    else:
+        m = binarize(arr, threshold)
+
+    kc0 = m.sum(axis=1)  # diversity  R
+    kp0 = m.sum(axis=0)  # ubiquity   C
+
+    # Row-normalized and column-normalized matrices
+    m_div_kc = safe_divide(m, kc0[:, None])   # M / D_r  (R x C)
+    m_div_kp = safe_divide(m, kp0[None, :])   # M / U_c  (R x C)
+
+    # Mcc: R x R
+    mcc = m_div_kc @ m_div_kp.T
+
+    # Mpp: C x C
+    mpp = m_div_kp.T @ m_div_kc
+
+    # Second eigenvectors
+    eci_raw = _second_eigenvector(mcc)
+    pci_raw = _second_eigenvector(mpp)
+
+    # Sign correction
+    # ECI should correlate positively with diversity
+    if np.std(eci_raw) > 0 and np.std(kc0) > 0 and np.corrcoef(eci_raw, kc0)[0, 1] < 0:
+        eci_raw = -eci_raw
+    # PCI should correlate negatively with ubiquity
+    if np.std(pci_raw) > 0 and np.std(kp0) > 0 and np.corrcoef(pci_raw, kp0)[0, 1] > 0:
+        pci_raw = -pci_raw
+
+    eci = normalize_zscore(eci_raw)
+    pci = normalize_zscore(pci_raw)
+
+    if is_df:
+        return (
+            pd.Series(eci, index=row_index, name="eci"),
+            pd.Series(pci, index=col_index, name="pci"),
+        )
+    return eci, pci

econcomplex/complexity/fitness.py

@@ -0,0 +1,130 @@
+"""
+Fitness-Complexity method (non-linear iterative).
+
+References
+----------
+Tacchella et al. (2012) "A New Metrics for Countries' Fitness and Products' Complexity".
+Cristelli et al. (2013).
+"""
+
+import warnings
+
+import numpy as np
+import pandas as pd
+from typing import Tuple, Union
+
+from ..core.utils import validate_matrix, safe_divide, binarize
+from ..core.rca import rca as compute_rca
+
+
+def fitness_complexity(
+    mat: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+    iterations: int = 20,
+    extremality: float = 1.0,
+    tol: float = 1e-10,
+    log_fitness: bool = False,
+) -> Tuple[Union[pd.Series, np.ndarray], Union[pd.Series, np.ndarray]]:
+    """
+    Fitness-Complexity algorithm.
+
+    Iterative update rules (normalized at each step):
+      F_r^{(n)} = sum_c M_{rc} * Q_c^{(n-1)}
+      Q_c^{(n)} = 1 / ( sum_r M_{rc} * (1/F_r^{(n-1)})^alpha )^{1/alpha}
+
+    where alpha = `extremality` (default 1).
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    use_rca : bool
+        Compute RCA before binarizing.
+    threshold : float
+        Binarization threshold.
+    iterations : int
+        Maximum iterations (default 20, matching the R `economiccomplexity`
+        package). The loop stops earlier as soon as `tol` is reached.
+        At 20 iterations the algorithm is practically converged on typical
+        data (relative change ~1e-7); a RuntimeWarning is issued only when
+        the final relative change still exceeds 1e-3, which signals real
+        instability (e.g. oscillation on pathological matrices).
+    extremality : float
+        Non-linearity parameter alpha (default 1.0).
+    tol : float
+        Convergence tolerance on relative change.
+    log_fitness : bool
+        If True, return natural log of fitness and complexity
+        (Cristelli et al. 2015 recommend the log scale for analysis).
+        Zeros are returned as NaN.
+
+    Returns
+    -------
+    (fitness, complexity) as pd.Series or ndarrays.
+    fitness = region/country fitness score.
+    complexity = product/activity complexity score.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    row_index = mat.index if is_df else None
+    col_index = mat.columns if is_df else None
+
+    arr = validate_matrix(mat)
+
+    if use_rca:
+        m = binarize(compute_rca(arr), threshold)
+    else:
+        m = binarize(arr, threshold)
+
+    n_r, n_c = m.shape
+    fitness = np.ones(n_r)
+    complexity = np.ones(n_c)
+
+    converged = False
+    delta_f = delta_q = np.inf
+    for _ in range(iterations):
+        fitness_new = m @ complexity
+        # Normalize by mean
+        mean_f = fitness_new.mean()
+        if mean_f > 0:
+            fitness_new /= mean_f
+
+        # Q update with extremality
+        inv_f = safe_divide(1.0, fitness_new ** extremality)
+        q_denom = (m.T @ inv_f) ** (1.0 / extremality)
+        complexity_new = safe_divide(1.0, q_denom)
+        mean_q = complexity_new.mean()
+        if mean_q > 0:
+            complexity_new /= mean_q
+
+        # Convergence check
+        delta_f = np.max(np.abs(fitness_new - fitness)) / (np.max(np.abs(fitness)) + 1e-15)
+        delta_q = np.max(np.abs(complexity_new - complexity)) / (np.max(np.abs(complexity)) + 1e-15)
+
+        fitness = fitness_new
+        complexity = complexity_new
+
+        if delta_f < tol and delta_q < tol:
+            converged = True
+            break
+
+    if not converged and (delta_f > 1e-3 or delta_q > 1e-3):
+        warnings.warn(
+            f"fitness_complexity did not converge within {iterations} "
+            f"iterations (final relative change {max(delta_f, delta_q):.1e}); "
+            "results may be unstable. Increase `iterations`.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+
+    if log_fitness:
+        with np.errstate(divide="ignore", invalid="ignore"):
+            fitness = np.where(fitness > 0, np.log(fitness), np.nan)
+            complexity = np.where(complexity > 0, np.log(complexity), np.nan)
+
+    if is_df:
+        return (
+            pd.Series(fitness, index=row_index, name="fitness"),
+            pd.Series(complexity, index=col_index, name="complexity"),
+        )
+    return fitness, complexity