econcomplex 1.0.0__py3-none-any.whl

econcomplex/productivity/prody.py

@@ -0,0 +1,218 @@
+"""
+Productivity levels of products and regions.
+
+References
+----------
+Hausmann, Hwang & Rodrik (2007) "What you export matters".
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Union
+
+from ..core.utils import validate_matrix, safe_divide
+from ..core.rca import rca as compute_rca
+
+
+def prody(
+    mat: Union[np.ndarray, pd.DataFrame],
+    gdp: Union[np.ndarray, pd.Series],
+    use_rca: bool = True,
+) -> Union[pd.Series, np.ndarray]:
+    """
+    PRODY: Income / productivity level of each activity.
+
+    PRODY_c = sum_r (LQ_{rc} * GDP_r) / sum_r LQ_{rc}
+
+    Weighted average of regional GDP, weighted by each region's
+    Revealed Comparative Advantage in activity c.
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    gdp : array-like (length R)
+        GDP (or income) per region.
+    use_rca : bool
+        Compute RCA internally (True) or use mat as LQ (False).
+
+    Returns
+    -------
+    pd.Series indexed by activity.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    col_index = mat.columns if is_df else None
+
+    arr = validate_matrix(mat)
+    gdp_arr = np.array(gdp, dtype=float)
+
+    if len(gdp_arr) != arr.shape[0]:
+        raise ValueError("Length of gdp must equal number of rows in mat.")
+
+    if use_rca:
+        lq = compute_rca(arr)
+        if isinstance(lq, pd.DataFrame):
+            lq = lq.values
+    else:
+        lq = arr
+
+    numerator = (lq * gdp_arr[:, None]).sum(axis=0)   # C
+    denominator = lq.sum(axis=0)                        # C
+    result = safe_divide(numerator, denominator)
+
+    if is_df:
+        return pd.Series(result, index=col_index, name="prody")
+    return result
+
+
+def expy(
+    mat: Union[np.ndarray, pd.DataFrame],
+    gdp: Union[np.ndarray, pd.Series],
+    use_rca: bool = True,
+) -> Union[pd.Series, np.ndarray]:
+    """
+    EXPY: Income level of a region's export / activity portfolio.
+
+    EXPY_r = sum_c (s_{rc} * PRODY_c)
+    where s_{rc} = x_{rc} / X_r  (share of activity c in region r)
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    gdp : array-like (length R)
+        GDP (or income) per region.
+    use_rca : bool
+        Whether to compute RCA for PRODY calculation.
+
+    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)
+    gdp_arr = np.array(gdp, dtype=float)
+
+    prody_arr = prody(arr, gdp_arr, use_rca=use_rca)
+    if isinstance(prody_arr, pd.Series):
+        prody_arr = prody_arr.values
+
+    row_sums = arr.sum(axis=1, keepdims=True)
+    shares = safe_divide(arr, row_sums)
+
+    result = (shares * prody_arr[None, :]).sum(axis=1)
+
+    if is_df:
+        return pd.Series(result, index=row_index, name="expy")
+    return result
+
+
+def product_gini_index(
+    mat: Union[np.ndarray, pd.DataFrame],
+    gini_vec: Union[np.ndarray, pd.Series],
+    threshold: float = 1.0,
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Product Gini Index (PGI): inequality embedded in a product.
+
+    PGI_c = sum_r (M_{rc} * s_{rc} * Gini_r) / sum_r (M_{rc} * s_{rc})
+
+    Weighted average of regional Gini coefficients, weighted by
+    specialization (RCA) shares.
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    gini_vec : array-like (length R)
+        Gini coefficient per region.
+    threshold : float
+        RCA binarization threshold.
+
+    Returns
+    -------
+    pd.Series indexed by activity.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    col_index = mat.columns if is_df else None
+
+    arr = validate_matrix(mat)
+    gini_arr = np.array(gini_vec, dtype=float)
+
+    if len(gini_arr) != arr.shape[0]:
+        raise ValueError("Length of gini_vec must equal number of rows in mat.")
+
+    rca_mat = compute_rca(arr)
+    if isinstance(rca_mat, pd.DataFrame):
+        rca_mat = rca_mat.values
+
+    m = (rca_mat >= threshold).astype(float)
+    row_sums = arr.sum(axis=1, keepdims=True)
+    shares = safe_divide(arr, row_sums)
+
+    weights = m * shares  # R x C
+    numerator = (weights * gini_arr[:, None]).sum(axis=0)
+    denominator = weights.sum(axis=0)
+    result = safe_divide(numerator, denominator)
+
+    if is_df:
+        return pd.Series(result, index=col_index, name="pgi")
+    return result
+
+
+def product_emissions_index(
+    mat: Union[np.ndarray, pd.DataFrame],
+    emissions: Union[np.ndarray, pd.Series],
+    threshold: float = 1.0,
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Product Emissions Intensity Index (PEII).
+
+    Same formula as PGI but substitutes emissions intensity for Gini:
+    PEII_c = sum_r (M_{rc} * s_{rc} * emissions_r) / sum_r (M_{rc} * s_{rc})
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    emissions : array-like (length R)
+        Emissions intensity per region.
+    threshold : float
+        RCA binarization threshold.
+
+    Returns
+    -------
+    pd.Series indexed by activity.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    col_index = mat.columns if is_df else None
+
+    arr = validate_matrix(mat)
+    em_arr = np.array(emissions, dtype=float)
+
+    if len(em_arr) != arr.shape[0]:
+        raise ValueError("Length of emissions must equal number of rows in mat.")
+
+    rca_mat = compute_rca(arr)
+    if isinstance(rca_mat, pd.DataFrame):
+        rca_mat = rca_mat.values
+
+    m = (rca_mat >= threshold).astype(float)
+    row_sums = arr.sum(axis=1, keepdims=True)
+    shares = safe_divide(arr, row_sums)
+
+    weights = m * shares
+    numerator = (weights * em_arr[:, None]).sum(axis=0)
+    denominator = weights.sum(axis=0)
+    result = safe_divide(numerator, denominator)
+
+    if is_df:
+        return pd.Series(result, index=col_index, name="peii")
+    return result
+
+
+# Short aliases matching the documented API
+pgi = product_gini_index
+peii = product_emissions_index

econcomplex/relatedness/__init__.py

@@ -0,0 +1,25 @@
+from .proximity import proximity, continuous_proximity
+from .density import (
+    relatedness_density,
+    distance,
+    relatedness_density_internal,
+    relatedness_density_external,
+    relative_relatedness,
+)
+from .cooccurrence import co_occurrence, relatedness_index, z_score_novelty
+from .cross_space import cross_proximity, cross_relatedness
+
+__all__ = [
+    "proximity",
+    "continuous_proximity",
+    "relatedness_density",
+    "distance",
+    "relatedness_density_internal",
+    "relatedness_density_external",
+    "relative_relatedness",
+    "co_occurrence",
+    "relatedness_index",
+    "z_score_novelty",
+    "cross_proximity",
+    "cross_relatedness",
+]

econcomplex/relatedness/cooccurrence.py

@@ -0,0 +1,173 @@
+"""
+Co-occurrence matrices and statistical novelty (z-score).
+
+References
+----------
+Steijn (2017) probability index; Fleming & Sorenson (2001) for patents.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Literal, Union
+
+from ..core.utils import validate_matrix, safe_divide
+
+
+def co_occurrence(
+    mat: Union[np.ndarray, pd.DataFrame],
+    diagonal: bool = False,
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Co-occurrence matrix: number of times two activities appear together
+    across regions/events.
+
+    Cooc = M * M^T  (if mat is events × activities)
+         = M^T * M  (if mat is regions × activities — activity co-occurrence)
+
+    Here we compute the *activity-by-activity* co-occurrence:
+      Cooc_{cc'} = sum_r M_{rc} * M_{rc'}
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Binary (or value) incidence matrix.
+    diagonal : bool
+        If False (default), set diagonal to 0.
+
+    Returns
+    -------
+    C x C co-occurrence matrix.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    col_index = mat.columns if is_df else None
+
+    arr = validate_matrix(mat)
+    cooc = arr.T @ arr
+
+    if not diagonal:
+        np.fill_diagonal(cooc, 0.0)
+
+    if is_df:
+        return pd.DataFrame(cooc, index=col_index, columns=col_index)
+    return cooc
+
+
+def relatedness_index(
+    mat: Union[np.ndarray, pd.DataFrame],
+    method: Literal["probability", "association", "cosine", "jaccard"] = "cosine",
+    diagonal: bool = False,
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Pairwise relatedness index between activities from co-occurrence.
+
+    Methods
+    -------
+    "probability" (Steijn 2017):
+      SM_{ij} = C_{ij} / (((S_i/T)(S_j/(T-S_i)) + (S_j/T)(S_i/(T-S_j))) * T/2)
+
+    "association" (association strength):
+      SA_{ij} = (C_{ij}/T) / ((S_i/T)(S_j/T))
+
+    "cosine":
+      SC_{ij} = C_{ij} / sqrt(S_i * S_j)
+
+    "jaccard":
+      SJ_{ij} = C_{ij} / (S_i + S_j - C_{ij})
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Binary incidence matrix.
+    method : str
+        Normalization method.
+
+    Returns
+    -------
+    C x C normalized relatedness matrix.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    col_index = mat.columns if is_df else None
+
+    arr = validate_matrix(mat)
+    cooc = arr.T @ arr  # C x C
+    n_events = arr.shape[0]  # T = number of regions/events
+    s = cooc.diagonal().copy()  # S_i = total occurrences of activity i
+
+    if method == "cosine":
+        denom = np.sqrt(s[:, None] * s[None, :])
+        result = safe_divide(cooc, denom)
+
+    elif method == "jaccard":
+        denom = s[:, None] + s[None, :] - cooc
+        result = safe_divide(cooc, denom)
+
+    elif method == "association":
+        p_i = s / n_events
+        expected = p_i[:, None] * p_i[None, :]
+        result = safe_divide(cooc / n_events, expected)
+
+    elif method == "probability":
+        T = n_events
+        si = s.astype(float)
+        # expected = ((si/T)(sj/(T-si)) + (sj/T)(si/(T-sj))) * T/2
+        t1 = safe_divide(si[:, None] * si[None, :], T * (T - si[:, None]))
+        t2 = safe_divide(si[None, :] * si[:, None], T * (T - si[None, :]))
+        expected = (t1 + t2) * T / 2
+        result = safe_divide(cooc, expected)
+
+    else:
+        raise ValueError("method must be 'probability', 'association', 'cosine', or 'jaccard'.")
+
+    if not diagonal:
+        np.fill_diagonal(result, 0.0)
+
+    if is_df:
+        return pd.DataFrame(result, index=col_index, columns=col_index)
+    return result
+
+
+def z_score_novelty(
+    incidence: Union[np.ndarray, pd.DataFrame],
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Z-score of technological novelty (atypicality of co-occurrence).
+
+    Measures how much each pair of technologies co-occurs more or less
+    than expected by chance.
+
+      z_{ij} = (C_{ij} - mu_{ij}) / sigma_{ij}
+    where
+      mu_{ij}     = n_i * n_j / P
+      sigma_{ij}  = sqrt(mu_{ij} * (1 - n_i/P) * (P - n_j)/(P-1))
+
+    Parameters
+    ----------
+    incidence : array-like (P x T)
+        Patent × technology (or event × activity) incidence matrix.
+
+    Returns
+    -------
+    T x T z-score matrix.
+    """
+    is_df = isinstance(incidence, pd.DataFrame)
+    col_index = incidence.columns if is_df else None
+
+    arr = validate_matrix(incidence)
+    P = arr.shape[0]  # number of patents/events
+
+    n = arr.sum(axis=0)  # occurrences per technology (T,)
+    cooc = arr.T @ arr   # T x T
+
+    mu = (n[:, None] * n[None, :]) / P  # expected co-occurrence
+
+    variance = mu * (1 - n[:, None] / P) * safe_divide(
+        P - n[None, :], P - 1
+    )
+    sigma = np.sqrt(np.maximum(variance, 0))
+
+    z = safe_divide(cooc - mu, sigma)
+    np.fill_diagonal(z, 0.0)
+
+    if is_df:
+        return pd.DataFrame(z, index=col_index, columns=col_index)
+    return z

econcomplex/relatedness/cross_space.py

@@ -0,0 +1,142 @@
+"""
+Cross-space proximity and relatedness between two different activity spaces.
+
+References
+----------
+Catalan et al. (2020) "Cross-space proximity and relatedness".
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Union
+
+from ..core.utils import validate_matrix, safe_divide, binarize
+from ..core.rca import rca as compute_rca
+
+
+def cross_proximity(
+    mat_a: Union[np.ndarray, pd.DataFrame],
+    mat_b: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Cross-space proximity between activity space A and activity space B.
+
+    X_phi_{ij} = min(C_{ij}/U_j^B, C_{ij}/U_i^A)
+    where C_{ij} = (M_A^T * M_B)_{ij} = co-presence count
+
+    Parameters
+    ----------
+    mat_a : array-like (R x A)
+        Region × activity-A matrix.
+    mat_b : array-like (R x B)
+        Region × activity-B matrix.
+    use_rca : bool
+        Compute RCA before binarizing for both matrices.
+    threshold : float
+        Binarization threshold.
+
+    Returns
+    -------
+    A x B cross-proximity matrix.
+    """
+    is_df_a = isinstance(mat_a, pd.DataFrame)
+    is_df_b = isinstance(mat_b, pd.DataFrame)
+    col_a = mat_a.columns if is_df_a else None
+    col_b = mat_b.columns if is_df_b else None
+
+    arr_a = validate_matrix(mat_a)
+    arr_b = validate_matrix(mat_b)
+
+    if arr_a.shape[0] != arr_b.shape[0]:
+        raise ValueError("mat_a and mat_b must have the same number of rows (locations).")
+
+    if use_rca:
+        m_a = binarize(compute_rca(arr_a), threshold)
+        m_b = binarize(compute_rca(arr_b), threshold)
+    else:
+        m_a = binarize(arr_a, threshold)
+        m_b = binarize(arr_b, threshold)
+
+    # Co-presence: A x B
+    c = m_a.T @ m_b  # (A x R) @ (R x B) = A x B
+
+    ub_a = m_a.sum(axis=0)  # A
+    ub_b = m_b.sum(axis=0)  # B
+
+    # min(C/U_b, C/U_a) = C / max(U_a, U_b)
+    denom = np.maximum(ub_a[:, None], ub_b[None, :])
+    result = safe_divide(c, denom)
+
+    if is_df_a and is_df_b:
+        return pd.DataFrame(result, index=col_a, columns=col_b)
+    return result
+
+
+def cross_relatedness(
+    mat_a: Union[np.ndarray, pd.DataFrame],
+    x_phi: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Cross-space relatedness density.
+
+    x_density_{rb} = (M_A * X_phi)_{rb} / sum_a X_phi_{ab}
+
+    Relatedness of region r to each activity b of space B, given the
+    region's portfolio in space A (the fraction of space-A activities
+    related to b that the region already holds).
+
+    Parameters
+    ----------
+    mat_a : array-like (R x A)
+        Region × activity-A value matrix.
+    x_phi : array-like (A x B)
+        Cross-proximity matrix from `cross_proximity`.
+    use_rca : bool
+        Compute RCA before binarizing mat_a.
+    threshold : float
+        Binarization threshold.
+
+    Returns
+    -------
+    R x B cross-relatedness matrix (columns = activities of space B).
+    """
+    is_df = isinstance(mat_a, pd.DataFrame)
+    row_index = mat_a.index if is_df else None
+    col_b = x_phi.columns if isinstance(x_phi, pd.DataFrame) else None
+
+    arr_a = validate_matrix(mat_a)
+    phi_arr = (
+        x_phi.values if isinstance(x_phi, pd.DataFrame) else np.array(x_phi, dtype=float)
+    )
+
+    if arr_a.shape[1] != phi_arr.shape[0]:
+        raise ValueError(
+            "x_phi must have one row per activity of mat_a "
+            f"(mat_a has {arr_a.shape[1]} activities, x_phi has "
+            f"{phi_arr.shape[0]} rows)."
+        )
+
+    if use_rca:
+        m_a = binarize(compute_rca(arr_a), threshold)
+    else:
+        m_a = binarize(arr_a, threshold)
+
+    # numerator: R x B
+    numerator = m_a @ phi_arr
+
+    # denominator: 1 x B (sum of each column of x_phi)
+    denom = phi_arr.sum(axis=0, keepdims=True)
+
+    result = safe_divide(numerator, denom)
+
+    if is_df:
+        return pd.DataFrame(result, index=row_index, columns=col_b)
+    return result
+
+
+# Short alias matching the documented API
+cross_space_proximity = cross_proximity