econcomplex 1.0.0__py3-none-any.whl

econcomplex/optimization/growth_target.py

@@ -0,0 +1,170 @@
+"""
+Growth targeting for ECI Optimization.
+
+Calibrates the growth regression (eq. 3 of Stojkoski & Hidalgo 2026) and
+inverts it to find the ECI compatible with a target growth rate, which can
+then be fed to `eci_optimization` as `target_eci`.
+
+References
+----------
+Stojkoski & Hidalgo (2026) "Optimizing economic complexity",
+Research Policy 55, 105454.
+Hausmann et al. (2014) "The Atlas of Economic Complexity".
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Dict, Union
+
+
+def calibrate_growth_model(
+    df: pd.DataFrame,
+    loc: str,
+    time: str,
+    gdppc: str,
+    eci: str,
+    horizon: int = 10,
+) -> Dict:
+    """
+    Calibrate the panel growth regression (eq. 3 of Stojkoski & Hidalgo
+    2026) by OLS:
+
+      annualized log growth of GDPpc over `horizon`
+        = a1*ECI + a2*z + a3*(ECI x z) + period fixed effects + u
+
+    where z is the log of initial GDP per capita, z-score normalized
+    across locations within each initial period (Solow convergence term).
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Long format with one row per (location, period).
+    loc, time, gdppc, eci : str
+        Column names for location, (numeric) period, GDP per capita, and
+        ECI.
+    horizon : int
+        Growth horizon in period units (default 10).
+
+    Returns
+    -------
+    dict with keys 'a1_eci', 'a2_z_gdppc', 'a3_interaction',
+    'period_effects' (dict period -> fixed effect), 'z_stats'
+    (dict period -> (mean, std) of log GDPpc), 'horizon', 'n_obs'.
+    """
+    periods = sorted(df[time].unique())
+    initial = [t for t in periods if (t + horizon) in periods]
+    if not initial:
+        raise ValueError(
+            f"No initial period t has t+{horizon} in the panel "
+            f"(periods available: {periods})."
+        )
+
+    obs_y, obs_eci, obs_z, obs_t = [], [], [], []
+    z_stats = {}
+
+    for t in initial:
+        d0 = df[df[time] == t].set_index(loc)
+        d1 = df[df[time] == t + horizon].set_index(loc)
+        common = d0.index.intersection(d1.index)
+        d0, d1 = d0.loc[common], d1.loc[common]
+        ok = (d0[gdppc] > 0) & (d1[gdppc] > 0) & d0[eci].notna()
+        if ok.sum() < 5:
+            continue
+        lg = np.log(d0.loc[ok, gdppc].astype(float))
+        mu, sd = lg.mean(), lg.std()
+        if sd == 0:
+            continue
+        z_stats[t] = (float(mu), float(sd))
+        z = (lg - mu) / sd
+        growth = (np.log(d1.loc[ok, gdppc].astype(float)).values - lg.values) / horizon
+        obs_y.append(growth)
+        obs_eci.append(d0.loc[ok, eci].astype(float).values)
+        obs_z.append(z.values)
+        obs_t.append(np.full(ok.sum(), t))
+
+    if not obs_y:
+        raise ValueError("Not enough observations to fit the growth model.")
+
+    y = np.concatenate(obs_y)
+    e = np.concatenate(obs_eci)
+    z = np.concatenate(obs_z)
+    t_arr = np.concatenate(obs_t)
+    used_periods = sorted(set(t_arr))
+
+    # Design: [ECI, z, ECI*z, one dummy per initial period (no intercept)]
+    dummies = np.column_stack([(t_arr == t).astype(float) for t in used_periods])
+    X = np.column_stack([e, z, e * z, dummies])
+    beta, *_ = np.linalg.lstsq(X, y, rcond=None)
+
+    return {
+        "a1_eci": float(beta[0]),
+        "a2_z_gdppc": float(beta[1]),
+        "a3_interaction": float(beta[2]),
+        "period_effects": {t: float(b) for t, b in zip(used_periods, beta[3:])},
+        "z_stats": z_stats,
+        "horizon": horizon,
+        "n_obs": int(len(y)),
+    }
+
+
+def _z_and_gamma(model: Dict, gdppc_now, period=None):
+    """z-score of log GDPpc and period effect for prediction."""
+    ref = period if period is not None else max(model["z_stats"])
+    mu, sd = model["z_stats"][ref]
+    z = (np.log(np.asarray(gdppc_now, dtype=float)) - mu) / sd
+    gamma = model["period_effects"][ref]
+    return z, gamma
+
+
+def expected_growth(
+    model: Dict,
+    eci: Union[float, pd.Series],
+    gdppc_now: Union[float, pd.Series],
+    period=None,
+) -> Union[float, pd.Series]:
+    """
+    Annualized log growth rate implied by the calibrated model for a given
+    ECI and current GDP per capita (using the most recent period's fixed
+    effect unless `period` is given).
+    """
+    z, gamma = _z_and_gamma(model, gdppc_now, period)
+    e = eci.values if isinstance(eci, pd.Series) else np.asarray(eci, dtype=float)
+    g = model["a1_eci"] * e + model["a2_z_gdppc"] * z \
+        + model["a3_interaction"] * e * z + gamma
+    if isinstance(eci, pd.Series):
+        return pd.Series(g, index=eci.index, name="expected_growth")
+    return float(g) if np.ndim(g) == 0 else g
+
+
+def eci_target_for_growth(
+    model: Dict,
+    growth_target: float,
+    gdppc_now: Union[float, pd.Series],
+    period=None,
+) -> Union[float, pd.Series]:
+    """
+    Invert the growth regression to find the ECI compatible with a target
+    annualized log growth rate (e.g. 0.035 for ~3.5 % per year):
+
+      ECI* = (growth - a2*z - gamma) / (a1 + a3*z)
+
+    The result can be passed to `eci_optimization` as `target_eci`.
+    """
+    import warnings
+
+    z, gamma = _z_and_gamma(model, gdppc_now, period)
+    denom = np.asarray(model["a1_eci"] + model["a3_interaction"] * z, dtype=float)
+    near_zero = np.abs(denom) < 1e-12
+    if np.any(near_zero):
+        warnings.warn(
+            "eci_target_for_growth: the marginal effect of ECI "
+            "(a1 + a3*z) is ~0 for some inputs; the target is undefined "
+            "there and returned as NaN.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        denom = np.where(near_zero, np.nan, denom)
+    target = (growth_target - model["a2_z_gdppc"] * z - gamma) / denom
+    if isinstance(gdppc_now, pd.Series):
+        return pd.Series(target, index=gdppc_now.index, name="eci_target")
+    return float(target) if np.ndim(target) == 0 else target

econcomplex/optimization/portfolio.py

@@ -0,0 +1,178 @@
+"""
+ECI Optimization: 0-1 portfolio selection.
+
+Selects the minimal-effort set of new specializations that raises a
+location's projection ECI (mean PCI of its portfolio) to a target.
+
+References
+----------
+Stojkoski & Hidalgo (2026) "Optimizing economic complexity",
+Research Policy 55, 105454.
+"""
+
+import warnings
+
+import numpy as np
+import pandas as pd
+from typing import Dict, Optional, Union
+
+from .steppingstone import effort_matrix, forecast_specialization
+
+try:
+    from scipy.optimize import milp, LinearConstraint, Bounds
+    _HAS_MILP = True
+except ImportError:  # SciPy < 1.9
+    _HAS_MILP = False
+
+
+def _select_portfolio(costs: np.ndarray, surplus: np.ndarray, deficit: float,
+                      solver: str) -> Optional[np.ndarray]:
+    """
+    Minimize sum(costs[x]) s.t. sum(surplus[x]) >= deficit, x binary.
+    Returns a boolean mask over the candidates, or None if infeasible.
+    """
+    if surplus.sum() < deficit:
+        return None
+
+    if solver == "milp" and _HAS_MILP:
+        res = milp(
+            c=costs,
+            constraints=LinearConstraint(surplus[None, :], lb=deficit),
+            integrality=np.ones_like(costs),
+            bounds=Bounds(0, 1),
+        )
+        if res.status == 0 and res.x is not None:
+            return res.x > 0.5
+        return None
+
+    # Greedy fallback: cheapest cost per unit of ECI surplus first
+    order = np.argsort(costs / surplus)
+    chosen = np.zeros(len(costs), dtype=bool)
+    covered = 0.0
+    for i in order:
+        if covered >= deficit:
+            break
+        chosen[i] = True
+        covered += surplus[i]
+    return chosen if covered >= deficit else None
+
+
+def eci_optimization(
+    mat: pd.DataFrame,
+    model: Dict,
+    delta_eci: float = 0.1,
+    target_eci: Optional[Union[float, Dict, pd.Series]] = None,
+    locations: Optional[list] = None,
+    solver: str = "milp",
+) -> pd.DataFrame:
+    """
+    ECI Optimization (Stojkoski & Hidalgo 2026): identify, per location,
+    the minimal-effort portfolio of new specializations that raises the
+    projected ECI to a target.
+
+    The pipeline: (i) project the no-policy specialization matrix and PCI
+    at t+horizon (`forecast_specialization`); (ii) compute the effort
+    W_cp required for each candidate entry (`effort_matrix`); (iii) solve
+    the 0-1 program
+
+        min sum_p W_cp x_cp
+        s.t. mean PCI of (projected portfolio + selected) >= target ECI
+
+    linearized as sum_p (PCI_p - target) x_cp >= deficit and solved
+    exactly with `scipy.optimize.milp` (greedy fallback on SciPy < 1.9).
+
+    Parameters
+    ----------
+    mat : pd.DataFrame (R x C)
+        Value matrix at the initial period.
+    model : dict
+        Output of `calibrate_steppingstone`.
+    delta_eci : float
+        Target increase over each location's projected ECI (default 0.1,
+        in PCI standard-deviation units). Ignored when `target_eci` given.
+    target_eci : float, dict, or pd.Series, optional
+        Absolute ECI target (single value or per location).
+    locations : list, optional
+        Subset of locations to optimize (default: all rows of `mat`).
+    solver : str
+        'milp' (exact, default) or 'greedy'.
+
+    Returns
+    -------
+    pd.DataFrame with one row per suggested activity:
+      [location, activity, effort, pci_projected, eci_projected,
+       eci_target, eci_achieved]
+    Locations whose projected ECI already meets the target contribute no
+    rows; infeasible locations are skipped with a warning.
+    """
+    forecast = forecast_specialization(mat, model)
+    W = effort_matrix(mat, model)
+    pci = forecast["pci"]
+    mcp_hat = forecast["mcp"]
+    eci_proj = forecast["eci"]
+
+    locs = locations if locations is not None else list(mat.index)
+    valid_p = pci.notna()
+    rows = []
+
+    for c in locs:
+        base_eci = eci_proj.get(c, np.nan)
+        if np.isnan(base_eci):
+            warnings.warn(f"Location {c!r}: empty projected portfolio; skipped.")
+            continue
+
+        if target_eci is None:
+            target = base_eci + delta_eci
+        elif np.isscalar(target_eci):
+            target = float(target_eci)
+        else:
+            target = float(pd.Series(target_eci).get(c, np.nan))
+            if np.isnan(target):
+                warnings.warn(f"Location {c!r}: no target provided; skipped.")
+                continue
+
+        m_row = mcp_hat.loc[c].values.astype(bool) & valid_p.values
+        deficit = -float(((pci[valid_p] - target) * mcp_hat.loc[c][valid_p]).sum())
+        if deficit <= 0:
+            continue  # target already met by the projected portfolio
+
+        # Candidates: not in projected portfolio, PCI above target
+        # (others cannot help the constraint), finite positive-side effort
+        cand = (~m_row) & valid_p.values & (pci.values > target) \
+            & np.isfinite(np.nan_to_num(W.loc[c].values, nan=np.inf))
+        if not cand.any():
+            warnings.warn(f"Location {c!r}: no feasible candidates; skipped.")
+            continue
+
+        costs = np.clip(W.loc[c].values[cand], 0.0, None)
+        surplus = (pci.values - target)[cand]
+        chosen = _select_portfolio(costs, surplus, deficit, solver)
+        if chosen is None:
+            warnings.warn(
+                f"Location {c!r}: target ECI {target:.3f} infeasible with "
+                "the available candidates; skipped."
+            )
+            continue
+
+        acts = mat.columns[cand][chosen]
+        n_new = chosen.sum()
+        achieved = (
+            (pci[valid_p] * mcp_hat.loc[c][valid_p]).sum()
+            + pci[acts].sum()
+        ) / (mcp_hat.loc[c][valid_p].sum() + n_new)
+
+        for a in acts:
+            rows.append({
+                "location": c,
+                "activity": a,
+                "effort": float(W.loc[c, a]),
+                "pci_projected": float(pci[a]),
+                "eci_projected": float(base_eci),
+                "eci_target": target,
+                "eci_achieved": float(achieved),
+            })
+
+    return pd.DataFrame(
+        rows, columns=["location", "activity", "effort", "pci_projected",
+                       "eci_projected", "eci_target", "eci_achieved"],
+    )

econcomplex/optimization/steppingstone.py

@@ -0,0 +1,267 @@
+"""
+Stepping-stone forward model for ECI Optimization.
+
+Calibrates the forecast model of specialization (eq. 1 of the paper),
+computes the closed-form effort matrix W_cp (eq. 2), and projects the
+future specialization matrix (no-policy baseline, W = 0).
+
+References
+----------
+Stojkoski & Hidalgo (2026) "Optimizing economic complexity",
+Research Policy 55, 105454.
+Pinheiro et al. (2021) for relative relatedness.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Dict, List
+
+from ..core.utils import pivot_to_matrix, safe_divide
+from ..core.rca import rca as compute_rca
+from ..relatedness.density import relatedness_density
+
+COEF_NAMES = ["b1_r_stepping", "b2_r_initial", "b3_relatedness",
+              "b4_relative_relatedness", "b0_intercept"]
+
+
+def _features(mat: pd.DataFrame, threshold: float, proximity_method: str):
+    """RCA, log(1+RCA), relatedness (0-1) and relative relatedness for `mat`."""
+    R = compute_rca(mat.values)
+    r = np.log1p(R)
+    dens = relatedness_density(mat, threshold=threshold,
+                                proximity_method=proximity_method)
+    omega = dens.values / 100.0  # 0-1 scale, as in the paper
+    # Relative relatedness (Pinheiro et al. 2021, eq. 7): z-transform
+    # against the statistics of the location's option set (RCA < threshold).
+    # The same standardization is applied to specialized cells so the exit
+    # model shares the scale of the entry model.
+    opt = R < threshold
+    n_opt = opt.sum(axis=1, keepdims=True)
+    mu = safe_divide(np.where(opt, omega, 0.0).sum(axis=1, keepdims=True), n_opt)
+    var = safe_divide(
+        np.where(opt, (omega - mu) ** 2, 0.0).sum(axis=1, keepdims=True), n_opt
+    )
+    rel = safe_divide(omega - mu, np.sqrt(var))
+    return R, r, omega, rel
+
+
+def calibrate_steppingstone(
+    df: pd.DataFrame,
+    loc: str,
+    act: str,
+    val: str,
+    time: str,
+    horizon: int = 10,
+    steppingstone: int = 5,
+    threshold: float = 1.0,
+    proximity_method: str = "max",
+) -> Dict:
+    """
+    Calibrate the stepping-stone forecast model (eq. 1 of Stojkoski &
+    Hidalgo 2026) on a long-format panel.
+
+    For every initial period t with t+steppingstone and t+horizon also
+    present in the panel, fits by OLS:
+
+      r_cp(t+horizon) = b1*r_cp(t+steppingstone) + b2*r_cp(t)
+                        + b3*relatedness_cp(t) + b4*relative_relatedness_cp(t)
+                        + b0
+
+    where r = log(1 + RCA). Entry models use only cells with RCA(t) < 1;
+    exit models use only cells with RCA(t) >= 1. Coefficients are averaged
+    across all available initial periods.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Long-format panel.
+    loc, act, val, time : str
+        Column names for location, activity, value, and (numeric) period.
+    horizon : int
+        Forecast horizon Delta-t in period units (default 10).
+    steppingstone : int
+        Steppingstone tau < horizon (default 5).
+    threshold : float
+        RCA binarization threshold for the relatedness features.
+    proximity_method : str
+        Proximity normalization ('max', 'sqrt', 'min').
+
+    Returns
+    -------
+    dict with keys:
+      'entry', 'exit' : coefficient dicts (b1, b2, b3, b4, b0)
+      'horizon', 'steppingstone', 'initial_periods',
+      'n_obs_entry', 'n_obs_exit'
+    """
+    if steppingstone >= horizon:
+        raise ValueError("steppingstone must be smaller than horizon.")
+
+    periods = sorted(df[time].unique())
+    initial = [t for t in periods
+               if (t + steppingstone) in periods and (t + horizon) in periods]
+    if not initial:
+        raise ValueError(
+            f"No initial period t has both t+{steppingstone} and "
+            f"t+{horizon} in the panel (periods available: {periods})."
+        )
+
+    coefs_entry: List[np.ndarray] = []
+    coefs_exit: List[np.ndarray] = []
+    n_entry = n_exit = 0
+
+    for t in initial:
+        mats = {}
+        for y in (t, t + steppingstone, t + horizon):
+            mats[y] = pivot_to_matrix(df[df[time] == y], loc, act, val)
+        rows = mats[t].index
+        cols = mats[t].columns
+        for m in mats.values():
+            rows = rows.union(m.index)
+            cols = cols.union(m.columns)
+        for y in mats:
+            mats[y] = mats[y].reindex(index=rows, columns=cols, fill_value=0.0)
+
+        R_t, r_t, omega, rel = _features(mats[t], threshold, proximity_method)
+        r_tau = np.log1p(compute_rca(mats[t + steppingstone].values))
+        r_T = np.log1p(compute_rca(mats[t + horizon].values))
+
+        X = np.column_stack([
+            r_tau.ravel(), r_t.ravel(), omega.ravel(), rel.ravel(),
+            np.ones(r_t.size),
+        ])
+        y_vec = r_T.ravel()
+        entry_mask = (R_t < threshold).ravel()
+
+        for mask, store in ((entry_mask, coefs_entry), (~entry_mask, coefs_exit)):
+            if mask.sum() > X.shape[1]:
+                beta, *_ = np.linalg.lstsq(X[mask], y_vec[mask], rcond=None)
+                store.append(beta)
+        n_entry += int(entry_mask.sum())
+        n_exit += int((~entry_mask).sum())
+
+    if not coefs_entry or not coefs_exit:
+        raise ValueError("Not enough observations to fit entry/exit models.")
+
+    entry = dict(zip(COEF_NAMES, np.mean(coefs_entry, axis=0)))
+    exit_ = dict(zip(COEF_NAMES, np.mean(coefs_exit, axis=0)))
+    return {
+        "entry": entry,
+        "exit": exit_,
+        "horizon": horizon,
+        "steppingstone": steppingstone,
+        "threshold": threshold,
+        "proximity_method": proximity_method,
+        "initial_periods": initial,
+        "n_obs_entry": n_entry,
+        "n_obs_exit": n_exit,
+    }
+
+
+def effort_matrix(
+    mat: pd.DataFrame,
+    model: Dict,
+) -> pd.DataFrame:
+    """
+    Effort W_cp: the added RCA an economy must reach by the steppingstone
+    period for the calibrated model to predict entry (RCA = 1) at the
+    horizon (eq. 2 of Stojkoski & Hidalgo 2026, solved in closed form).
+
+    Setting r_cp(t+horizon) = log(2) in the stepping-stone equation:
+
+      W_cp = exp[(log 2 - b0 - b2*r - b3*omega - b4*rel) / b1] - 1 - RCA_cp
+
+    Values are returned only for candidate cells (RCA < threshold);
+    currently specialized cells are NaN. W <= 0 means the model already
+    predicts entry without any boost.
+
+    Parameters
+    ----------
+    mat : pd.DataFrame (R x C)
+        Value matrix at the initial period.
+    model : dict
+        Output of `calibrate_steppingstone`.
+
+    Returns
+    -------
+    R x C DataFrame of efforts.
+    """
+    b = model["entry"]
+    if abs(b["b1_r_stepping"]) < 1e-12:
+        raise ValueError(
+            "The steppingstone coefficient (b1) of the entry model is ~0; "
+            "the effort W_cp is undefined. Recalibrate the model (more "
+            "periods or a different steppingstone/horizon)."
+        )
+    threshold = model.get("threshold", 1.0)
+    R, r, omega, rel = _features(mat, threshold,
+                                 model.get("proximity_method", "max"))
+
+    numerator = (np.log(2.0) - b["b0_intercept"]
+                 - b["b2_r_initial"] * r
+                 - b["b3_relatedness"] * omega
+                 - b["b4_relative_relatedness"] * rel)
+    with np.errstate(over="ignore"):
+        W = np.exp(numerator / b["b1_r_stepping"]) - 1.0 - R
+
+    W = np.where(R < threshold, W, np.nan)
+    return pd.DataFrame(W, index=mat.index, columns=mat.columns)
+
+
+def forecast_specialization(
+    mat: pd.DataFrame,
+    model: Dict,
+) -> Dict:
+    """
+    No-policy baseline forecast (W = 0): project RCA at t+horizon with the
+    calibrated stepping-stone model, using entry coefficients for cells
+    with RCA < threshold and exit coefficients otherwise.
+
+    Parameters
+    ----------
+    mat : pd.DataFrame (R x C)
+        Value matrix at the initial period.
+    model : dict
+        Output of `calibrate_steppingstone`.
+
+    Returns
+    -------
+    dict with:
+      'rca' : projected RCA matrix (DataFrame)
+      'mcp' : projected binary specialization matrix (DataFrame)
+      'pci' : projected PCI (Series, z-scored; NaN for activities trimmed
+              from the projected matrix)
+      'eci' : projection ECI per location = mean projected PCI over the
+              projected portfolio (Series)
+    """
+    from ..complexity.eci_pci import eci_pci
+
+    threshold = model.get("threshold", 1.0)
+    R, r, omega, rel = _features(mat, threshold,
+                                 model.get("proximity_method", "max"))
+
+    r_hat = np.empty_like(r)
+    for key, mask in (("entry", R < threshold), ("exit", R >= threshold)):
+        b = model[key]
+        pred = (b["b0_intercept"]
+                + (b["b1_r_stepping"] + b["b2_r_initial"]) * r
+                + b["b3_relatedness"] * omega
+                + b["b4_relative_relatedness"] * rel)
+        r_hat[mask] = pred[mask]
+
+    R_hat = np.expm1(np.clip(r_hat, 0.0, None))
+    rca_hat = pd.DataFrame(R_hat, index=mat.index, columns=mat.columns)
+    mcp_hat = (rca_hat >= threshold).astype(float)
+
+    _, pci = eci_pci(rca_hat, use_rca=False, threshold=threshold)
+    pci = pci.rename("pci_projected")
+
+    weights = mcp_hat.mul(pci.notna().astype(float), axis=1)
+    portfolio = weights.values * np.nan_to_num(pci.values)[None, :]
+    counts = weights.sum(axis=1).values
+    eci_proj = pd.Series(
+        safe_divide(portfolio.sum(axis=1), counts),
+        index=mat.index, name="eci_projection",
+    )
+    eci_proj[counts == 0] = np.nan
+
+    return {"rca": rca_hat, "mcp": mcp_hat, "pci": pci, "eci": eci_proj}

econcomplex/outlook/__init__.py

@@ -0,0 +1,6 @@
+from .coi_cog import complexity_outlook_index, complexity_outlook_gain
+
+__all__ = [
+    "complexity_outlook_index",
+    "complexity_outlook_gain",
+]