econcomplex 1.0.0__py3-none-any.whl

econcomplex/relatedness/density.py

@@ -0,0 +1,232 @@
+"""
+Relatedness density, distance, and related indicators.
+
+References
+----------
+Hidalgo et al. (2007); Hausmann & Klinger (2007);
+Balland et al. (2019).
+"""
+
+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
+
+
+def _get_mcp_and_phi(
+    mat,
+    phi,
+    use_rca: bool,
+    threshold: float,
+    proximity_method: str,
+):
+    """Helper: returns binary M and proximity matrix as ndarrays."""
+    is_df = isinstance(mat, pd.DataFrame)
+
+    arr = validate_matrix(mat)
+
+    if use_rca:
+        m = binarize(compute_rca(arr), threshold)
+    else:
+        m = binarize(arr, threshold)
+
+    if phi is None:
+        from .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)
+
+    return m, phi_arr, is_df
+
+
+def relatedness_density(
+    mat: Union[np.ndarray, pd.DataFrame],
+    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]:
+    """
+    Relatedness density for each (region, activity) pair.
+
+    density_{rc} = (M * Phi)_{rc} / rowSums(Phi)_c * 100
+
+    Fraction of activities related to c that region r already has,
+    expressed as a percentage.
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    phi : array-like (C x C), optional
+        Pre-computed product proximity matrix. Computed internally if None.
+    use_rca : bool
+        Compute RCA before binarizing.
+    threshold : float
+        Binarization threshold.
+    proximity_method : str
+        Normalization method for proximity ('max', 'sqrt', 'min').
+
+    Returns
+    -------
+    R x C relatedness density matrix (values 0–100).
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    row_index = mat.index if is_df else None
+    col_index = mat.columns if is_df else None
+
+    m, phi_arr, _ = _get_mcp_and_phi(mat, phi, use_rca, threshold, proximity_method)
+
+    col_sums_phi = phi_arr.sum(axis=0, keepdims=True)  # 1 x C
+    numerator = m @ phi_arr                              # R x C
+    density = safe_divide(numerator, col_sums_phi) * 100
+
+    if is_df:
+        return pd.DataFrame(density, index=row_index, columns=col_index)
+    return density
+
+
+def distance(
+    mat: Union[np.ndarray, pd.DataFrame],
+    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]:
+    """
+    Distance (1 - density/100).
+
+    Weighted fraction of related activities that region r does NOT have.
+
+    Returns
+    -------
+    R x C distance matrix (values 0–1).
+    """
+    dens = relatedness_density(mat, phi=phi, use_rca=use_rca,
+                                threshold=threshold, proximity_method=proximity_method)
+    if isinstance(dens, pd.DataFrame):
+        return 1 - dens / 100
+    return 1 - dens / 100
+
+
+def relatedness_density_internal(
+    mat: Union[np.ndarray, pd.DataFrame],
+    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]:
+    """
+    Internal relatedness density: density values for activities
+    the region ALREADY has (M_{rc} = 1).
+    Other cells are NaN.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    row_index = mat.index if is_df else None
+    col_index = mat.columns if is_df else None
+
+    m, phi_arr, _ = _get_mcp_and_phi(mat, phi, use_rca, threshold, proximity_method)
+
+    col_sums_phi = phi_arr.sum(axis=0, keepdims=True)
+    numerator = m @ phi_arr
+    density = safe_divide(numerator, col_sums_phi) * 100
+
+    mask = m == 0
+    density_internal = density.copy()
+    density_internal[mask] = np.nan
+
+    if is_df:
+        return pd.DataFrame(density_internal, index=row_index, columns=col_index)
+    return density_internal
+
+
+def relatedness_density_external(
+    mat: Union[np.ndarray, pd.DataFrame],
+    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]:
+    """
+    External relatedness density: density values for activities
+    the region does NOT yet have (M_{rc} = 0).
+    Other cells are NaN.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    row_index = mat.index if is_df else None
+    col_index = mat.columns if is_df else None
+
+    m, phi_arr, _ = _get_mcp_and_phi(mat, phi, use_rca, threshold, proximity_method)
+
+    col_sums_phi = phi_arr.sum(axis=0, keepdims=True)
+    numerator = m @ phi_arr
+    density = safe_divide(numerator, col_sums_phi) * 100
+
+    mask = m == 1
+    density_external = density.copy()
+    density_external[mask] = np.nan
+
+    if is_df:
+        return pd.DataFrame(density_external, index=row_index, columns=col_index)
+    return density_external
+
+
+def relative_relatedness(
+    mat: Union[np.ndarray, pd.DataFrame],
+    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]:
+    """
+    Relative relatedness (Pinheiro et al. 2021, eq. 7): z-transform of the
+    relatedness density against the statistics of the region's option set
+    (activities it does NOT currently hold, M_{rc} = 0).
+
+    relative_density_{rc} = (density_{rc} - mean_non_held_r) / std_non_held_r
+    for cells where M_{rc} = 0; NaN otherwise.
+
+    References
+    ----------
+    Pinheiro, Hartmann, Boschma & Hidalgo (2022) "The time and frequency
+    of unrelated diversification", Research Policy 51, 104323.
+
+    Returns
+    -------
+    R x C standardized density 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
+
+    m, phi_arr, _ = _get_mcp_and_phi(mat, phi, use_rca, threshold, proximity_method)
+
+    col_sums_phi = phi_arr.sum(axis=0, keepdims=True)
+    numerator = m @ phi_arr
+    density = safe_divide(numerator, col_sums_phi) * 100
+
+    result = np.full_like(density, np.nan)
+    for i in range(m.shape[0]):
+        non_held = m[i] == 0
+        vals = density[i, non_held]
+        std = vals.std()
+        if std > 0:
+            result[i, non_held] = (vals - vals.mean()) / std
+
+    if is_df:
+        return pd.DataFrame(result, index=row_index, columns=col_index)
+    return result
+
+
+# Short alias matching the documented API
+density = relatedness_density

econcomplex/relatedness/proximity.py

@@ -0,0 +1,214 @@
+"""
+Product Space proximity matrices.
+
+References
+----------
+Hidalgo et al. (2007) "The Product Space Conditions the Development of Nations".
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Literal, Union
+
+from ..core.utils import validate_matrix, safe_divide, binarize
+from ..core.rca import rca as compute_rca
+
+
+def proximity(
+    mat: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+    method: Literal["max", "sqrt", "min"] = "max",
+    compute: Literal["product", "location", "both"] = "both",
+    continuous: bool = False,
+    continuous_method: Literal["correlation", "cosine"] = "correlation",
+) -> dict:
+    """
+    Compute product and/or location proximity matrices.
+
+    Product proximity (phi_pp'):
+      numerator    = M^T * M  (co-export / co-presence count)
+      "max"   norm = max(U_p, U_p')
+      "sqrt"  norm = sqrt(U_p * U_p')   (geometric mean, cosine-like)
+      "min"   norm = min(U_p, U_p')     (conditional probability)
+
+    Location proximity (phi_rr'):
+      Same structure but on M * M^T, normalized by diversity.
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    use_rca : bool
+        Compute RCA before binarizing.
+    threshold : float
+        Binarization threshold.
+    method : str
+        Normalization method: 'max', 'sqrt', or 'min'.
+    compute : str
+        Which side to compute: 'product', 'location', or 'both'.
+    continuous : bool
+        If True, skip binarization and compute the proximity on the
+        continuous RCA values (see `continuous_proximity`); `method`
+        and `threshold` are ignored.
+    continuous_method : str
+        Similarity used when `continuous=True`: 'correlation'
+        (Pearson, rescaled to [0, 1]) or 'cosine'.
+
+    Returns
+    -------
+    dict with keys 'product' and/or 'location' as DataFrames (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 continuous:
+        rca_arr = compute_rca(arr) if use_rca else arr
+        results = {}
+        if compute in ("product", "both"):
+            phi_p = continuous_proximity(rca_arr, method=continuous_method)
+            if is_df:
+                results["product"] = pd.DataFrame(phi_p, index=col_index, columns=col_index)
+            else:
+                results["product"] = phi_p
+        if compute in ("location", "both"):
+            phi_l = continuous_proximity(rca_arr.T, method=continuous_method)
+            if is_df:
+                results["location"] = pd.DataFrame(phi_l, index=row_index, columns=row_index)
+            else:
+                results["location"] = phi_l
+        return results
+
+    if use_rca:
+        m = binarize(compute_rca(arr), threshold)
+    else:
+        m = binarize(arr, threshold)
+
+    results = {}
+
+    def _normalize(cooc: np.ndarray, counts: np.ndarray) -> np.ndarray:
+        """Normalize co-occurrence matrix by row/col counts."""
+        if method == "max":
+            denom = np.maximum(counts[:, None], counts[None, :])
+        elif method == "sqrt":
+            denom = np.sqrt(counts[:, None] * counts[None, :])
+        elif method == "min":
+            denom = np.minimum(counts[:, None], counts[None, :])
+        else:
+            raise ValueError("method must be 'max', 'sqrt', or 'min'.")
+        return safe_divide(cooc, denom)
+
+    if compute in ("product", "both"):
+        ubiq = m.sum(axis=0)   # C
+        cooc_p = m.T @ m       # C x C
+        phi_p = _normalize(cooc_p, ubiq)
+        np.fill_diagonal(phi_p, 0.0)
+        if is_df:
+            results["product"] = pd.DataFrame(phi_p, index=col_index, columns=col_index)
+        else:
+            results["product"] = phi_p
+
+    if compute in ("location", "both"):
+        div = m.sum(axis=1)    # R
+        cooc_l = m @ m.T       # R x R
+        phi_l = _normalize(cooc_l, div)
+        np.fill_diagonal(phi_l, 0.0)
+        if is_df:
+            results["location"] = pd.DataFrame(phi_l, index=row_index, columns=row_index)
+        else:
+            results["location"] = phi_l
+
+    return results
+
+
+def continuous_proximity(
+    rca_mat: Union[np.ndarray, pd.DataFrame],
+    method: Literal["correlation", "cosine"] = "correlation",
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Continuous product proximity from a (continuous) RCA matrix.
+
+    method='correlation' (default):
+      phi_{pp'} = (1 + corr(RCA_p, RCA_{p'})) / 2
+      (Pearson correlation rescaled from [-1, 1] to [0, 1])
+    method='cosine':
+      phi_{pp'} = (RCA_p . RCA_{p'}) / (||RCA_p|| * ||RCA_{p'}||)
+
+    Parameters
+    ----------
+    rca_mat : array-like (R x C)
+        Pre-computed (continuous) RCA matrix.
+    method : str
+        'correlation' or 'cosine'.
+
+    Returns
+    -------
+    C x C proximity matrix with zero diagonal.
+    """
+    is_df = isinstance(rca_mat, pd.DataFrame)
+    col_index = rca_mat.columns if is_df else None
+
+    arr = validate_matrix(rca_mat)
+
+    if method == "correlation":
+        corr = np.corrcoef(arr.T)  # C x C
+        phi = (1 + corr) / 2.0
+    elif method == "cosine":
+        norms = np.linalg.norm(arr, axis=0)  # C
+        phi = safe_divide(arr.T @ arr, norms[:, None] * norms[None, :])
+    else:
+        raise ValueError("method must be 'correlation' or 'cosine'.")
+    np.fill_diagonal(phi, 0.0)
+
+    if is_df:
+        return pd.DataFrame(phi, index=col_index, columns=col_index)
+    return phi
+
+
+def _continuous_on_values(mat, use_rca, method):
+    """Shortcut: RCA (optional) + continuous_proximity with given method."""
+    is_df = isinstance(mat, pd.DataFrame)
+    col_index = mat.columns if is_df else None
+    arr = validate_matrix(mat)
+    rca_arr = compute_rca(arr) if use_rca else arr
+    phi = continuous_proximity(rca_arr, method=method)
+    if is_df:
+        return pd.DataFrame(phi, index=col_index, columns=col_index)
+    return phi
+
+
+def cosine_proximity(
+    mat: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Shortcut for `continuous_proximity(rca(mat), method='cosine')`:
+    cosine similarity between the RCA vectors of each pair of activities.
+
+    Returns a C x C proximity matrix with zero diagonal.
+    """
+    return _continuous_on_values(mat, use_rca, "cosine")
+
+
+def correlation_proximity(
+    mat: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Shortcut for `continuous_proximity(rca(mat), method='correlation')`:
+    Pearson correlation between RCA vectors, rescaled to [0, 1].
+
+    Returns a C x C proximity matrix with zero diagonal.
+    """
+    return _continuous_on_values(mat, use_rca, "correlation")
+
+
+# Documented-API alias: relatedness(mat, phi) == relatedness_density
+from .density import relatedness_density as _relatedness_density  # noqa: E402
+
+relatedness = _relatedness_density
+
+

econcomplex/specialization/__init__.py

@@ -0,0 +1,17 @@
+from .location_quotient import (
+    location_quotient,
+    location_quotient_avg,
+    hachman_index,
+    specialization_coefficient,
+    krugman_index,
+)
+from .similarity import export_similarity
+
+__all__ = [
+    "location_quotient",
+    "location_quotient_avg",
+    "hachman_index",
+    "specialization_coefficient",
+    "krugman_index",
+    "export_similarity",
+]

econcomplex/specialization/location_quotient.py

@@ -0,0 +1,163 @@
+"""
+Location quotient (LQ) variants and specialization indices.
+
+References
+----------
+Hoover & Giarratani (1985); Hachman (various); Balland & Rigby (2017).
+"""
+
+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 location_quotient(
+    mat: Union[np.ndarray, pd.DataFrame],
+    binary: bool = False,
+    threshold: float = 1.0,
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Location Quotient (identical to RCA / Balassa Index).
+
+    LQ_{rc} = (x_{rc}/X_r) / (X_c/X_total)
+
+    Alias of `core.rca.rca`.
+    """
+    return compute_rca(mat, binary=binary, threshold=threshold)
+
+
+def location_quotient_avg(
+    mat: Union[np.ndarray, pd.DataFrame],
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Weighted average LQ per region (Coefficient of Specialization, Hoover 1985).
+
+    avg_LQ_r = sum_c (LQ_{rc} * s_{rc})
+    where s_{rc} = x_{rc} / X_r  (share of activity c in region r)
+
+    A value > 1 indicates region is more specialized than the nation average.
+
+    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)
+    lq = compute_rca(arr)
+    if isinstance(lq, pd.DataFrame):
+        lq = lq.values
+
+    row_sums = arr.sum(axis=1, keepdims=True)
+    shares = safe_divide(arr, row_sums)  # s_{rc}
+
+    result = (lq * shares).sum(axis=1)
+
+    if is_df:
+        return pd.Series(result, index=row_index, name="lq_avg")
+    return result
+
+
+def hachman_index(
+    mat: Union[np.ndarray, pd.DataFrame],
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Hachman Index (structural similarity to national economy).
+
+    H_r = 1 / avg_LQ_r
+
+    Ranges 0 to 1; value of 1 means the regional economy perfectly
+    mirrors the national structure.
+
+    Returns
+    -------
+    pd.Series indexed by region (clipped to [0, 1]).
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    row_index = mat.index if is_df else None
+
+    avg_lq = location_quotient_avg(mat)
+    if isinstance(avg_lq, pd.Series):
+        avg_lq_arr = avg_lq.values
+    else:
+        avg_lq_arr = avg_lq
+
+    result = np.clip(safe_divide(1.0, avg_lq_arr), 0, 1)
+
+    if is_df:
+        return pd.Series(result, index=row_index, name="hachman")
+    return result
+
+
+def specialization_coefficient(
+    mat: Union[np.ndarray, pd.DataFrame],
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Hoover Coefficient of Specialization.
+
+    spec_r = (1/2) * sum_c |s_{rc} - s_c|
+
+    where s_{rc} = share of activity c in region r,
+          s_c    = national share of activity c.
+
+    Equivalent to half the Krugman Index.
+    Ranges [0, 1]: 0 = region mirrors national structure.
+
+    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)
+    total = arr.sum()
+
+    row_sums = arr.sum(axis=1, keepdims=True)
+    col_sums = arr.sum(axis=0, keepdims=True)
+
+    s_rc = safe_divide(arr, row_sums)
+    s_c = col_sums / total
+
+    result = 0.5 * np.abs(s_rc - s_c).sum(axis=1)
+
+    if is_df:
+        return pd.Series(result, index=row_index, name="spec_coeff")
+    return result
+
+
+def krugman_index(
+    mat: Union[np.ndarray, pd.DataFrame],
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Krugman Specialization Index.
+
+    K_r = sum_c |s_{rc} - s_c|
+
+    where s_{rc} = share of activity c in region r,
+          s_c    = national share of activity c.
+
+    = 2 * specialization_coefficient.
+    Ranges [0, 2].
+
+    Returns
+    -------
+    pd.Series indexed by region.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    row_index = mat.index if is_df else None
+
+    coeff = specialization_coefficient(mat)
+    result = 2 * (coeff.values if isinstance(coeff, pd.Series) else coeff)
+
+    if is_df:
+        return pd.Series(result, index=row_index, name="krugman_index")
+    return result
+
+
+# Short alias matching the documented API
+spec_coefficient = specialization_coefficient

econcomplex/specialization/similarity.py

@@ -0,0 +1,68 @@
+"""
+Export / portfolio similarity between locations.
+
+References
+----------
+Bahar et al. (2014) "Neighbors and the Evolution of the Comparative Advantage
+of Nations".
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Union
+
+from ..core.utils import validate_matrix
+from ..core.rca import rca as compute_rca
+
+
+def export_similarity(
+    mat: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+    epsilon: float = 0.1,
+    log: bool = True,
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Export Similarity Index (Bahar et al. 2014).
+
+    Pearson correlation of (log-)RCA vectors between location pairs.
+
+    SCC_{rr'} = corr(log(RCA_r + epsilon), log(RCA_{r'} + epsilon))
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    use_rca : bool
+        Compute RCA internally (True) or treat mat as RCA (False).
+    epsilon : float
+        Small constant added before log to avoid log(0).
+    log : bool
+        If True, apply log transform before correlation.
+
+    Returns
+    -------
+    R x R similarity matrix.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    row_index = mat.index if is_df else None
+
+    arr = validate_matrix(mat)
+
+    if use_rca:
+        rca_arr = compute_rca(arr)
+        if isinstance(rca_arr, pd.DataFrame):
+            rca_arr = rca_arr.values
+    else:
+        rca_arr = arr
+
+    if log:
+        transformed = np.log(rca_arr + epsilon)
+    else:
+        transformed = rca_arr
+
+    result = np.corrcoef(transformed)  # R x R
+    np.fill_diagonal(result, 1.0)
+
+    if is_df:
+        return pd.DataFrame(result, index=row_index, columns=row_index)
+    return result