econcomplex 1.0.0__py3-none-any.whl

econcomplex/outlook/coi_cog.py

@@ -0,0 +1,168 @@
+"""
+Complexity Outlook Index (COI) and Complexity Outlook Gain (COG).
+
+References
+----------
+Hausmann & Hidalgo (2011) "The Atlas of Economic Complexity".
+Hidalgo et al. (2007) "The Product Space Conditions the Development of Nations".
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Optional, Union
+
+from ..core.utils import validate_matrix, safe_divide, binarize
+from ..core.rca import rca as compute_rca
+from ..relatedness.density import relatedness_density
+
+
+def complexity_outlook_index(
+    mat: Union[np.ndarray, pd.DataFrame],
+    pci: Union[np.ndarray, pd.Series],
+    phi: Optional[Union[np.ndarray, pd.DataFrame]] = None,
+    use_rca: bool = True,
+    threshold: float = 1.0,
+    proximity_method: str = "max",
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Complexity Outlook Index (COI).
+
+    COI_r = sum_c (density_{rc} * (1 - M_{rc}) * PCI_c)
+
+    Measures a region's potential to diversify into complex activities
+    it does not yet have, weighted by how related those activities are
+    to its current portfolio.
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    pci : array-like (length C)
+        Product / activity complexity index.
+    phi : array-like (C x C), optional
+        Pre-computed proximity matrix. Computed if None.
+    use_rca : bool
+        Compute RCA before binarizing.
+    threshold : float
+        Binarization threshold.
+    proximity_method : str
+        Proximity normalization ('max', 'sqrt', 'min').
+
+    Returns
+    -------
+    pd.Series indexed by region.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    row_index = mat.index if is_df else None
+
+    arr = validate_matrix(mat)
+    pci_arr = np.array(pci, dtype=float)
+
+    if use_rca:
+        m = binarize(compute_rca(arr), threshold)
+    else:
+        m = binarize(arr, threshold)
+
+    dens = relatedness_density(m, phi=phi, use_rca=False, threshold=0.5,
+                                proximity_method=proximity_method)
+    if isinstance(dens, pd.DataFrame):
+        dens = dens.values
+
+    # COI: sum over non-present activities
+    coi = ((dens / 100) * (1 - m) * pci_arr[None, :]).sum(axis=1)
+
+    if is_df:
+        return pd.Series(coi, index=row_index, name="coi")
+    return coi
+
+
+def complexity_outlook_gain(
+    mat: Union[np.ndarray, pd.DataFrame],
+    pci: Union[np.ndarray, pd.Series],
+    phi: Optional[Union[np.ndarray, pd.DataFrame]] = None,
+    use_rca: bool = True,
+    threshold: float = 1.0,
+    proximity_method: str = "max",
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Complexity Outlook Gain (COG).
+
+    COG_{rc} = (1 - M_{rc}) * sum_{c'} (
+        (1 - M_{rc'}) * phi_{cc'} * PCI_{c'} / sum_{c''} phi_{cc''}
+    )
+
+    Gain in COI if region r were to develop activity c.
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    pci : array-like (length C)
+        Activity complexity index.
+    phi : array-like (C x C), optional
+        Pre-computed proximity matrix.
+    use_rca : bool
+        Compute RCA before binarizing.
+    threshold : float
+        Binarization threshold.
+    proximity_method : str
+        Proximity normalization method.
+
+    Returns
+    -------
+    R x C COG matrix.
+    """
+    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)
+    pci_arr = np.array(pci, dtype=float)
+
+    if use_rca:
+        m = binarize(compute_rca(arr), threshold)
+    else:
+        m = binarize(arr, threshold)
+
+    if phi is None:
+        from ..relatedness.proximity import proximity as _prox
+        phi_dict = _prox(m, use_rca=False, threshold=0.5,
+                          method=proximity_method, compute="product")
+        phi_arr = (
+            phi_dict["product"].values
+            if isinstance(phi_dict["product"], pd.DataFrame)
+            else phi_dict["product"]
+        )
+    else:
+        phi_arr = phi.values if isinstance(phi, pd.DataFrame) else np.array(phi, dtype=float)
+
+    # phi_norm_{cc'} = phi_{cc'} / sum_{c''} phi_{cc''}
+    phi_row_sums = phi_arr.sum(axis=1, keepdims=True)
+    phi_norm = safe_divide(phi_arr, phi_row_sums)  # C x C
+
+    # For each region r: weighted PCI of non-present activities
+    # inner = sum_{c'} (1 - M_{rc'}) * phi_norm_{cc'} * PCI_{c'}
+    # Shape: R x C
+    # (1 - m): R x C
+    # phi_norm * pci: sum over c' of phi_norm[c, c'] * pci[c'] = (phi_norm @ pci): C
+    # But conditioned on (1 - m): need element-wise
+
+    cog = np.zeros_like(m)
+    phi_pci = phi_norm * pci_arr[None, :]   # C x C, entry [c, c'] = phi_norm[c,c'] * PCI[c']
+
+    for r in range(m.shape[0]):
+        not_present = (1 - m[r])  # C
+        # For each target activity c: sum_{c'} (1 - m[r,c']) * phi_norm[c, c'] * PCI[c']
+        cog[r] = not_present * (phi_pci @ not_present)
+
+    # Mask to non-present only
+    cog = cog * (1 - m)
+
+    if is_df:
+        return pd.DataFrame(cog, index=row_index, columns=col_index)
+    return cog
+
+
+# Short aliases matching the documented API
+coi = complexity_outlook_index
+cog = complexity_outlook_gain

econcomplex/patents/__init__.py

@@ -0,0 +1,7 @@
+from .recombination import ease_of_recombination, modular_complexity, modular_complexity_avg
+
+__all__ = [
+    "ease_of_recombination",
+    "modular_complexity",
+    "modular_complexity_avg",
+]

econcomplex/patents/recombination.py

@@ -0,0 +1,135 @@
+"""
+Patent-based recombination complexity.
+
+References
+----------
+Fleming & Sorenson (2001) "Technology as a Complex Adaptive System:
+Evidence from Patent Data".
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Union
+
+from ..core.utils import validate_matrix, safe_divide
+
+
+def ease_of_recombination(
+    incidence: Union[np.ndarray, pd.DataFrame],
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Ease of Recombination (EOR) for each technology/class.
+
+    EOR_t = (number of patents in which t co-occurs with any other tech)
+            / (total number of patents containing t)
+
+    A high EOR means the technology is easily combined with others.
+
+    Parameters
+    ----------
+    incidence : array-like (P x T)
+        Patent × technology binary incidence matrix.
+
+    Returns
+    -------
+    pd.Series indexed by technology.
+    """
+    is_df = isinstance(incidence, pd.DataFrame)
+    col_index = incidence.columns if is_df else None
+
+    arr = validate_matrix(incidence)
+
+    # For each patent, does it contain more than one technology?
+    patents_with_multiple = (arr.sum(axis=1) > 1).astype(float)  # P
+
+    # For each technology: number of patents where it appears with others
+    numerator = arr.T @ patents_with_multiple   # T
+
+    # Total patents containing each technology
+    denominator = arr.sum(axis=0)               # T
+
+    result = safe_divide(numerator, denominator)
+
+    if is_df:
+        return pd.Series(result, index=col_index, name="ease_of_recombination")
+    return result
+
+
+def modular_complexity(
+    incidence: Union[np.ndarray, pd.DataFrame],
+    eor: Union[np.ndarray, pd.Series, None] = None,
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Modular Complexity of each patent.
+
+    MC_p = (number of technologies in patent p)
+           / (sum of EOR for each technology in patent p)
+
+    Higher MC = technologies are harder to recombine = more complex patent.
+
+    Parameters
+    ----------
+    incidence : array-like (P x T)
+        Patent × technology binary incidence matrix.
+    eor : array-like (length T), optional
+        Pre-computed EOR vector. Computed internally if None.
+
+    Returns
+    -------
+    pd.Series indexed by patent.
+    """
+    is_df = isinstance(incidence, pd.DataFrame)
+    row_index = incidence.index if is_df else None
+
+    arr = validate_matrix(incidence)
+
+    if eor is None:
+        eor_arr = ease_of_recombination(arr)
+        if isinstance(eor_arr, pd.Series):
+            eor_arr = eor_arr.values
+    else:
+        eor_arr = np.array(eor, dtype=float)
+
+    # number of technologies per patent
+    n_techs = arr.sum(axis=1)  # P
+
+    # sum of EOR for technologies present in each patent
+    eor_sum = arr @ eor_arr   # P
+
+    result = safe_divide(n_techs, eor_sum)
+
+    if is_df:
+        return pd.Series(result, index=row_index, name="modular_complexity")
+    return result
+
+
+def modular_complexity_avg(
+    incidence: Union[np.ndarray, pd.DataFrame],
+    eor: Union[np.ndarray, pd.Series, None] = None,
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Average Modular Complexity aggregated per technology (column).
+
+    avg_MC_t = mean(MC_p for all patents p containing technology t)
+
+    Returns
+    -------
+    pd.Series indexed by technology.
+    """
+    is_df = isinstance(incidence, pd.DataFrame)
+    col_index = incidence.columns if is_df else None
+
+    arr = validate_matrix(incidence)
+    mc = modular_complexity(arr, eor=eor)
+    if isinstance(mc, pd.Series):
+        mc_arr = mc.values
+    else:
+        mc_arr = mc
+
+    col_sums = arr.sum(axis=0)
+    numerator = arr.T @ mc_arr
+    result = safe_divide(numerator, col_sums)
+
+    if is_df:
+        return pd.Series(result, index=col_index, name="modular_complexity_avg")
+    return result

econcomplex/pipeline.py

@@ -0,0 +1,255 @@
+"""
+High-level pipeline: compute all complexity indicators in one call.
+
+Mirrors the API of py-ecomplexity but with richer output and support
+for all indicator methods.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, Literal, Optional
+
+import numpy as np
+import pandas as pd
+
+from .core.rca import rca, mcp
+from .complexity.eci_pci import eci_pci
+from .relatedness.proximity import proximity, continuous_proximity
+from .relatedness.density import relatedness_density
+from .outlook.coi_cog import complexity_outlook_index, complexity_outlook_gain
+from .core.utils import pivot_to_matrix
+
+
+def compute_complexity(
+    data: pd.DataFrame,
+    cols: Dict[str, str],
+    *,
+    method: Literal["eigenvector", "reflections", "fitness"] = "eigenvector",
+    presence_test: Literal["rca", "rpop", "both", "manual"] = "rca",
+    threshold: float = 1.0,
+    iterations: int = 20,
+    proximity_type: Literal["discrete", "continuous"] = "discrete",
+    proximity_method: Literal["max", "sqrt", "min"] = "max",
+    pop: Optional[pd.DataFrame] = None,
+    compute_coi_cog: bool = True,
+    time_col: Optional[str] = None,
+) -> pd.DataFrame:
+    """
+    Compute a full suite of economic complexity indicators.
+
+    Parameters
+    ----------
+    data : pd.DataFrame
+        Long-format DataFrame.
+    cols : dict
+        Mapping with keys:
+          'loc'  → column name for locations/regions
+          'act'  → column name for activities/products
+          'val'  → column name for values
+        Optionally:
+          'time' → column name for time periods (enables panel mode)
+    method : str
+        ECI/PCI method: 'eigenvector', 'reflections', or 'fitness'.
+    presence_test : str
+        How to binarize: 'rca', 'rpop', 'both', 'manual'.
+    threshold : float
+        Binarization threshold (default 1.0).
+    iterations : int
+        Iterations for reflections/fitness methods.
+    proximity_type : str
+        'discrete' (co-occurrence) or 'continuous' (correlation).
+    proximity_method : str
+        Proximity normalization: 'max', 'sqrt', or 'min'.
+    pop : pd.DataFrame, optional
+        Population data with columns ['loc', 'time'?, 'pop'].
+        Required when presence_test is 'rpop' or 'both'.
+    compute_coi_cog : bool
+        Whether to compute COI and COG (slower).
+    time_col : str, optional
+        Override for time column name (or use cols['time']).
+
+    Returns
+    -------
+    Original DataFrame with new columns:
+      rca, mcp, diversity, ubiquity, eci, pci, density, distance, [coi, cog]
+      [fitness, complexity] (when method='fitness')
+    """
+    loc_col = cols.get("loc") or cols.get("location")
+    act_col = cols.get("act") or cols.get("activity") or cols.get("product")
+    val_col = cols.get("val") or cols.get("value")
+    t_col = time_col or cols.get("time")
+
+    if not all([loc_col, act_col, val_col]):
+        raise ValueError("cols must contain 'loc', 'act', and 'val' keys.")
+
+    if t_col and t_col in data.columns:
+        periods = data[t_col].unique()
+        results = []
+        for period in sorted(periods):
+            period_data = data[data[t_col] == period].copy()
+            pop_period = None
+            if pop is not None:
+                if t_col in pop.columns:
+                    pop_period = pop[pop[t_col] == period]
+                else:
+                    pop_period = pop
+            period_result = _compute_single_period(
+                period_data, loc_col, act_col, val_col,
+                method=method,
+                presence_test=presence_test,
+                threshold=threshold,
+                iterations=iterations,
+                proximity_type=proximity_type,
+                proximity_method=proximity_method,
+                pop=pop_period,
+                compute_coi_cog=compute_coi_cog,
+            )
+            results.append(period_result)
+        return pd.concat(results, ignore_index=True)
+    else:
+        return _compute_single_period(
+            data, loc_col, act_col, val_col,
+            method=method,
+            presence_test=presence_test,
+            threshold=threshold,
+            iterations=iterations,
+            proximity_type=proximity_type,
+            proximity_method=proximity_method,
+            pop=pop,
+            compute_coi_cog=compute_coi_cog,
+        )
+
+
+def _compute_single_period(
+    data: pd.DataFrame,
+    loc_col: str,
+    act_col: str,
+    val_col: str,
+    *,
+    method: str,
+    presence_test: str,
+    threshold: float,
+    iterations: int,
+    proximity_type: str,
+    proximity_method: str,
+    pop: Optional[pd.DataFrame],
+    compute_coi_cog: bool,
+) -> pd.DataFrame:
+    """Compute indicators for a single time period."""
+
+    # --- Build pivot matrix ---
+    mat = pivot_to_matrix(data, index=loc_col, columns=act_col, values=val_col)
+
+    # --- RCA ---
+    rca_mat = rca(mat)
+
+    # --- Population for RPOP ---
+    pop_vec = None
+    if presence_test in ("rpop", "both") and pop is not None:
+        pop_col = [c for c in pop.columns if c not in (loc_col,)][0]
+        pop_aligned = pop.set_index(loc_col).reindex(mat.index)[pop_col]
+        pop_vec = pop_aligned.values
+
+    # --- Mcp binary matrix ---
+    mcp_mat = mcp(
+        mat,
+        presence_test=presence_test,
+        rca_threshold=threshold,
+        rpop_threshold=threshold,
+        pop=pop_vec,
+    )
+
+    # --- Diversity & Ubiquity ---
+    div = mcp_mat.sum(axis=1)
+    ubi = mcp_mat.sum(axis=0)
+
+    # --- ECI / PCI ---
+    # Routed through the eci_pci dispatcher: validates the method and
+    # pre-trims degenerate (zero diversity/ubiquity) units, returned as NaN.
+    eci_s, pci_s = eci_pci(
+        mat, use_rca=True, threshold=threshold, method=method,
+        iterations=iterations if method != "eigenvector" else None,
+    )
+    if method == "fitness":
+        eci_s.name = "eci"
+        pci_s.name = "pci"
+
+    # --- Proximity ---
+    if proximity_type == "continuous":
+        phi = continuous_proximity(rca_mat)
+    else:
+        phi_dict = proximity(mcp_mat, use_rca=False, threshold=0.5,
+                             method=proximity_method, compute="product")
+        phi = phi_dict["product"]
+
+    # --- Density & Distance ---
+    dens_mat = relatedness_density(mcp_mat, phi=phi, use_rca=False, threshold=0.5)
+    dist_mat = 1 - dens_mat / 100
+
+    # --- COI / COG (optional) ---
+    coi_s = None
+    cog_mat = None
+    if compute_coi_cog:
+        pci_arr = pci_s.values if isinstance(pci_s, pd.Series) else pci_s
+        coi_s = complexity_outlook_index(
+            mcp_mat, pci_arr, phi=phi, use_rca=False, threshold=0.5
+        )
+        cog_mat = complexity_outlook_gain(
+            mcp_mat, pci_arr, phi=phi, use_rca=False, threshold=0.5
+        )
+
+    # --- Merge everything back into long format ---
+    result = data.copy()
+
+    # Add location-level indicators
+    loc_indicators = pd.DataFrame({
+        "diversity": div,
+        "eci": eci_s,
+        "coi": coi_s if coi_s is not None else np.nan,
+    })
+    result = result.merge(
+        loc_indicators.reset_index().rename(columns={"index": loc_col}),
+        on=loc_col,
+        how="left",
+    )
+
+    # Add activity-level indicators
+    act_indicators = pd.DataFrame({
+        "ubiquity": ubi,
+        "pci": pci_s,
+    })
+    result = result.merge(
+        act_indicators.reset_index().rename(columns={"index": act_col}),
+        on=act_col,
+        how="left",
+    )
+
+    # Add cell-level indicators
+    rca_long = (
+        rca_mat.reset_index()
+        .melt(id_vars=rca_mat.index.name, var_name=act_col, value_name="rca")
+    )
+    mcp_long = (
+        mcp_mat.reset_index()
+        .melt(id_vars=mcp_mat.index.name, var_name=act_col, value_name="mcp")
+    )
+    dens_long = (
+        dens_mat.reset_index()
+        .melt(id_vars=dens_mat.index.name, var_name=act_col, value_name="density")
+    )
+    dist_long = (
+        dist_mat.reset_index()
+        .melt(id_vars=dist_mat.index.name, var_name=act_col, value_name="distance")
+    )
+
+    for long_df in [rca_long, mcp_long, dens_long, dist_long]:
+        result = result.merge(long_df, on=[loc_col, act_col], how="left")
+
+    if cog_mat is not None:
+        cog_long = (
+            cog_mat.reset_index()
+            .melt(id_vars=cog_mat.index.name, var_name=act_col, value_name="cog")
+        )
+        result = result.merge(cog_long, on=[loc_col, act_col], how="left")
+
+    return result

econcomplex/productivity/__init__.py

@@ -0,0 +1,8 @@
+from .prody import prody, expy, product_gini_index, product_emissions_index
+
+__all__ = [
+    "prody",
+    "expy",
+    "product_gini_index",
+    "product_emissions_index",
+]