econcomplex 1.0.0__py3-none-any.whl

econcomplex/complexity/reflections.py

@@ -0,0 +1,173 @@
+"""
+Method of Reflections (MOR) for Economic Complexity.
+
+References
+----------
+Hidalgo & Hausmann (2009) "The Building Blocks of Economic Complexity".
+Balland & Rigby (2017) for regional adaptation.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Optional, Tuple, Union
+
+from ..core.utils import validate_matrix, safe_divide, normalize_zscore, binarize
+from ..core.rca import rca as compute_rca
+
+
+def _binary_presence(mat, use_rca: bool, threshold: float):
+    """Binary Mcp plus DataFrame metadata, shared by the MoR variants."""
+    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)
+    return m, is_df, row_index, col_index
+
+
+def _reflect(m: np.ndarray, iterations: int, tol: Optional[float] = None):
+    """
+    Iterate the Method of Reflections from the binary matrix `m`:
+      k_{r,n} = (M * k_{c,n-1}) / k_{r,0}
+      k_{c,n} = (M^T * k_{r,n-1}) / k_{c,0}
+    Optionally stop early when the z-scored reflections change by less
+    than `tol`. Returns (kc, kp, kc0, kp0).
+    """
+    kc0 = m.sum(axis=1)  # diversity
+    kp0 = m.sum(axis=0)  # ubiquity
+    kc = kc0.copy()
+    kp = kp0.copy()
+    for _ in range(iterations):
+        kc_new = safe_divide(m @ kp, kc0)
+        kp_new = safe_divide(m.T @ kc, kp0)
+        if tol is not None:
+            delta_c = np.max(np.abs(normalize_zscore(kc_new) - normalize_zscore(kc)))
+            delta_p = np.max(np.abs(normalize_zscore(kp_new) - normalize_zscore(kp)))
+            kc = kc_new
+            kp = kp_new
+            if delta_c < tol and delta_p < tol:
+                break
+        else:
+            kc = kc_new
+            kp = kp_new
+    return kc, kp, kc0, kp0
+
+
+def method_of_reflections(
+    mat: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+    iterations: int = 20,
+    return_both: bool = True,
+    tol: Optional[float] = 1e-10,
+) -> Union[Tuple[pd.Series, pd.Series], Tuple[np.ndarray, np.ndarray]]:
+    """
+    Method of Reflections (iterative) to compute ECI and PCI.
+
+    Starting from the binary Mcp matrix:
+      k_{r,0} = diversity (row sums)
+      k_{c,0} = ubiquity (col sums)
+      k_{r,n} = (M * k_{c,n-1}) / k_{r,0}
+      k_{c,n} = (M^T * k_{r,n-1}) / k_{c,0}
+    Final values are z-score normalized.
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value or pre-binarized matrix.
+    use_rca : bool
+        Compute RCA internally before binarizing.
+    threshold : float
+        Binarization threshold.
+    iterations : int
+        Number of reflection steps (default 20).
+    return_both : bool
+        If True, return (ECI, PCI); if False, return ECI only.
+    tol : float, optional
+        Convergence tolerance: stop early when the z-scored reflections
+        change by less than `tol` between iterations. The check uses the
+        z-scored vectors because the raw reflections converge to a
+        constant. Pass None to always run all `iterations`.
+
+    Returns
+    -------
+    (eci, pci) as pd.Series (or ndarrays if input is ndarray).
+    """
+    m, is_df, row_index, col_index = _binary_presence(mat, use_rca, threshold)
+    kc, kp, kc0, kp0 = _reflect(m, iterations, tol=tol)
+
+    eci = normalize_zscore(kc)
+    pci = normalize_zscore(kp)
+
+    # Sign orientation, as in the eigenvector method: ECI correlates
+    # positively with diversity, PCI negatively with ubiquity
+    if np.std(eci) > 0 and np.std(kc0) > 0 and np.corrcoef(eci, kc0)[0, 1] < 0:
+        eci = -eci
+    if np.std(pci) > 0 and np.std(kp0) > 0 and np.corrcoef(pci, kp0)[0, 1] > 0:
+        pci = -pci
+
+    if is_df:
+        return (
+            pd.Series(eci, index=row_index, name="eci"),
+            pd.Series(pci, index=col_index, name="pci"),
+        )
+    return eci, pci
+
+
+def mor_regions(
+    mat: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+    steps: int = 20,
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Method of Reflections — region/country side only.
+
+    Returns the region complexity at a given reflection step (0–22),
+    rescaled to 0–100 for steps > 1.
+
+    step 0 = raw diversity
+    step 1 = avg ubiquity of industries present in each region
+    step 2+ = higher-order reflections
+    """
+    m, is_df, row_index, _ = _binary_presence(mat, use_rca, threshold)
+    kc, kp, _, _ = _reflect(m, steps)
+
+    if steps > 1:
+        mn, mx = kc.min(), kc.max()
+        result = (kc - mn) / (mx - mn) * 100 if mx != mn else np.zeros_like(kc)
+    else:
+        result = kc
+
+    if is_df:
+        return pd.Series(result, index=row_index, name=f"mor_region_step{steps}")
+    return result
+
+
+def mor_activities(
+    mat: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+    steps: int = 19,
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Method of Reflections — activity/technology side only.
+
+    step 0 = raw ubiquity
+    step 1+ = higher-order reflections; rescaled to 0–100 for steps > 1.
+    """
+    m, is_df, _, col_index = _binary_presence(mat, use_rca, threshold)
+    kc, kp, _, _ = _reflect(m, steps)
+
+    if steps > 1:
+        mn, mx = kp.min(), kp.max()
+        result = (kp - mn) / (mx - mn) * 100 if mx != mn else np.zeros_like(kp)
+    else:
+        result = kp
+
+    if is_df:
+        return pd.Series(result, index=col_index, name=f"mor_activity_step{steps}")
+    return result

econcomplex/complexity/subnational.py

@@ -0,0 +1,82 @@
+"""
+Subnational / external ECI using externally supplied PCI.
+
+References
+----------
+Balland & Rigby (2017); Mealy et al. (2019).
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Tuple, Union
+
+from ..core.utils import validate_matrix, binarize, normalize_zscore
+from ..core.rca import rca as compute_rca
+
+
+def subnational_eci(
+    mat: Union[np.ndarray, pd.DataFrame],
+    pci_external: Union[np.ndarray, pd.Series],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+    standardize: bool = True,
+) -> Tuple[Union[pd.Series, np.ndarray], Union[pd.Series, np.ndarray]]:
+    """
+    Subnational ECI using an externally supplied PCI vector.
+
+    Each region's ECI is the mean PCI of activities it has RCA in:
+      ECI_r = mean(PCI_c for c where M_{rc} = 1)
+
+    Useful when comparing subnational units to a global product space,
+    or when the dataset is too small to compute reliable eigenvectors.
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Regional value matrix.
+    pci_external : array-like (length C)
+        External PCI vector (e.g., global product complexity index).
+    use_rca : bool
+        Compute RCA before binarizing.
+    threshold : float
+        Binarization threshold.
+    standardize : bool
+        If True, z-score normalize the resulting ECI.
+
+    Returns
+    -------
+    (eci, pci_external) 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)
+
+    pci_arr = np.array(pci_external, dtype=float)
+    if len(pci_arr) != m.shape[1]:
+        raise ValueError("Length of pci_external must match number of columns in mat.")
+
+    row_sums = m.sum(axis=1)
+    eci_raw = np.where(
+        row_sums > 0,
+        (m @ pci_arr) / row_sums,
+        0.0,
+    )
+
+    if standardize:
+        eci_raw = normalize_zscore(eci_raw)
+
+    if is_df:
+        pci_out = (
+            pci_external
+            if isinstance(pci_external, pd.Series)
+            else pd.Series(pci_arr, index=col_index, name="pci")
+        )
+        return pd.Series(eci_raw, index=row_index, name="eci_external"), pci_out
+    return eci_raw, pci_arr

econcomplex/core/__init__.py

@@ -0,0 +1,23 @@
+from .rca import rca, rpop, mcp
+from .diversity import diversity, ubiquity, normalized_ubiquity
+from .utils import (
+    pivot_to_matrix,
+    melt_matrix,
+    binarize,
+    normalize_zscore,
+    normalize_01,
+)
+
+__all__ = [
+    "rca",
+    "rpop",
+    "mcp",
+    "diversity",
+    "ubiquity",
+    "normalized_ubiquity",
+    "pivot_to_matrix",
+    "melt_matrix",
+    "binarize",
+    "normalize_zscore",
+    "normalize_01",
+]

econcomplex/core/diversity.py

@@ -0,0 +1,125 @@
+"""
+Diversity and ubiquity indicators.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Union
+
+from .utils import validate_matrix, safe_divide
+from .rca import rca as compute_rca
+
+
+def diversity(
+    mat: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+) -> pd.Series:
+    """
+    Diversity: number of activities in which each region has RCA >= threshold.
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix or pre-computed binary Mcp matrix.
+    use_rca : bool
+        If True, compute RCA internally before binarizing.
+    threshold : float
+        Binarization threshold.
+
+    Returns
+    -------
+    pd.Series indexed by region.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    index = mat.index if is_df else None
+
+    arr = validate_matrix(mat)
+
+    if use_rca:
+        rca_mat = compute_rca(arr)
+        m = (rca_mat >= threshold).astype(float)
+    else:
+        m = (arr >= threshold).astype(float)
+
+    result = m.sum(axis=1)
+
+    if is_df:
+        return pd.Series(result, index=index, name="diversity")
+    return result
+
+
+def ubiquity(
+    mat: Union[np.ndarray, pd.DataFrame],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+) -> pd.Series:
+    """
+    Ubiquity: number of regions where each activity has RCA >= threshold.
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix or pre-computed binary Mcp matrix.
+    use_rca : bool
+        If True, compute RCA internally before binarizing.
+    threshold : float
+        Binarization threshold.
+
+    Returns
+    -------
+    pd.Series indexed by activity.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    columns = mat.columns if is_df else None
+
+    arr = validate_matrix(mat)
+
+    if use_rca:
+        rca_mat = compute_rca(arr)
+        m = (rca_mat >= threshold).astype(float)
+    else:
+        m = (arr >= threshold).astype(float)
+
+    result = m.sum(axis=0)
+
+    if is_df:
+        return pd.Series(result, index=columns, name="ubiquity")
+    return result
+
+
+def normalized_ubiquity(
+    mat: Union[np.ndarray, pd.DataFrame],
+    threshold: float = 1.0,
+) -> pd.Series:
+    """
+    Normalized ubiquity: ratio of activity's share of total value to
+    its share of ubiquity.
+
+    norm_ubiquity_c = (sum_r x_{rc} / sum_{rc} x_{rc}) / (U_c / sum_c U_c)
+
+    Returns
+    -------
+    pd.Series indexed by activity.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    columns = mat.columns if is_df else None
+
+    arr = validate_matrix(mat)
+    total = arr.sum()
+    ub = ubiquity(arr, use_rca=True, threshold=threshold)
+
+    if isinstance(ub, pd.Series):
+        ub_arr = ub.values
+    else:
+        ub_arr = ub
+
+    col_sums = arr.sum(axis=0)
+    value_share = col_sums / total
+    ubiquity_share = safe_divide(ub_arr, ub_arr.sum())
+
+    result = safe_divide(value_share, ubiquity_share)
+
+    if is_df:
+        return pd.Series(result, index=columns, name="norm_ubiquity")
+    return result

econcomplex/core/preprocess.py

@@ -0,0 +1,83 @@
+"""
+Pre-processing utilities for sparse location-activity matrices.
+
+References
+----------
+Hidalgo & Hausmann (2009); OEC Atlas methodology.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Union
+
+from .utils import validate_matrix, binarize
+from .rca import rca as compute_rca
+
+
+def trim_core(
+    mat: Union[np.ndarray, pd.DataFrame],
+    dmin: int = 1,
+    umin: int = 1,
+    use_rca: bool = True,
+    threshold: float = 1.0,
+    max_iter: int = 100,
+) -> Union[np.ndarray, pd.DataFrame]:
+    """
+    Iteratively prune a value matrix to its (dmin, umin)-core.
+
+    Drops locations (rows) with diversity < dmin and activities (columns)
+    with ubiquity < umin, where diversity/ubiquity are counted on the
+    binary presence matrix (RCA >= threshold by default). Because removing
+    a row or column changes the RCA of the remaining cells, the presence
+    matrix is recomputed after each pass until the matrix is stable.
+
+    With the defaults (dmin=1, umin=1) only degenerate units are removed:
+    locations with no activity above the RCA threshold and activities
+    with no location above it. These units cannot be ranked and distort
+    (or break) the complexity calculations. For very sparse networks
+    (e.g. subnational trade data) the literature computes complexity on
+    the well-connected core, typically dmin=2, umin=2
+    (Hidalgo & Hausmann 2009; OEC Atlas).
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    dmin : int
+        Minimum diversity for a location to be kept (default 1).
+    umin : int
+        Minimum ubiquity for an activity to be kept (default 1).
+    use_rca : bool
+        Compute RCA before binarizing (default True).
+    threshold : float
+        Binarization threshold (default 1.0).
+    max_iter : int
+        Safety cap on pruning passes.
+
+    Returns
+    -------
+    The surviving sub-matrix, same type as the input. With a DataFrame
+    the original labels are preserved, so dropped units can be recovered
+    by reindexing (`result.reindex(mat.index)`).
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    work = mat.astype(float) if is_df else pd.DataFrame(validate_matrix(mat))
+
+    # All-zero rows/columns first (always degenerate, whatever the core)
+    work = work.loc[work.sum(axis=1) > 0, work.sum(axis=0) > 0]
+
+    for _ in range(max_iter):
+        if work.shape[0] == 0 or work.shape[1] == 0:
+            break
+        if use_rca:
+            m = binarize(compute_rca(work.values), threshold)
+        else:
+            m = binarize(work.values, threshold)
+        keep_r = m.sum(axis=1) >= dmin
+        keep_c = m.sum(axis=0) >= umin
+        if keep_r.all() and keep_c.all():
+            break
+        work = work.loc[work.index[keep_r], work.columns[keep_c]]
+        work = work.loc[work.sum(axis=1) > 0, work.sum(axis=0) > 0]
+
+    return work if is_df else work.values

econcomplex/core/rca.py

@@ -0,0 +1,161 @@
+"""
+Revealed Comparative Advantage (RCA) / Balassa Index and variants.
+
+References
+----------
+Balassa (1965); Hausmann et al. (2007); Balland & Rigby (2017).
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Optional, Union
+
+from .utils import validate_matrix, safe_divide, binarize
+
+
+def rca(
+    mat: Union[np.ndarray, pd.DataFrame],
+    binary: bool = False,
+    threshold: float = 1.0,
+) -> Union[np.ndarray, pd.DataFrame]:
+    """
+    Revealed Comparative Advantage (Balassa Index).
+
+    RCA_{rc} = (x_{rc} / sum_c x_{rc}) / (sum_r x_{rc} / sum_{rc} x_{rc})
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Region × industry (or country × product) value matrix.
+    binary : bool
+        If True, return binary matrix thresholded at `threshold`.
+    threshold : float
+        Binarization threshold (default 1.0).
+
+    Returns
+    -------
+    Same type as input (DataFrame or ndarray).
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    index = mat.index if is_df else None
+    columns = mat.columns if is_df else None
+
+    arr = validate_matrix(mat)
+    total = arr.sum()
+    if total == 0:
+        raise ValueError("Matrix sum is zero; cannot compute RCA.")
+
+    row_sums = arr.sum(axis=1, keepdims=True)   # R × 1
+    col_sums = arr.sum(axis=0, keepdims=True)   # 1 × C
+
+    share_rc = safe_divide(arr, row_sums)         # share of industry c in region r
+    share_c = col_sums / total                    # national share of industry c
+
+    result = safe_divide(share_rc, share_c)
+
+    if binary:
+        result = binarize(result, threshold)
+
+    if is_df:
+        return pd.DataFrame(result, index=index, columns=columns)
+    return result
+
+
+def rpop(
+    mat: Union[np.ndarray, pd.DataFrame],
+    pop: Union[np.ndarray, pd.Series],
+    binary: bool = False,
+    threshold: float = 1.0,
+) -> Union[np.ndarray, pd.DataFrame]:
+    """
+    Population-normalized RCA (RPOP).
+
+    RPOP_{rc} = (x_{rc} / pop_r) / (sum_r x_{rc} / sum_r pop_r)
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Region × industry value matrix.
+    pop : 1-D array-like (length R)
+        Population vector for each region.
+    binary : bool
+        If True, binarize at `threshold`.
+    threshold : float
+        Binarization threshold (default 1.0).
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    index = mat.index if is_df else None
+    columns = mat.columns if is_df else None
+
+    arr = validate_matrix(mat)
+    pop_arr = np.array(pop, dtype=float).reshape(-1, 1)  # R × 1
+
+    if len(pop_arr) != arr.shape[0]:
+        raise ValueError("Length of pop must equal number of rows in mat.")
+
+    world_pop = pop_arr.sum()
+    col_sums = arr.sum(axis=0, keepdims=True)  # 1 × C
+
+    share_rc = safe_divide(arr, pop_arr)               # x_{rc} / pop_r
+    share_c = col_sums / world_pop                     # X_c / world_pop
+
+    result = safe_divide(share_rc, share_c)
+
+    if binary:
+        result = binarize(result, threshold)
+
+    if is_df:
+        return pd.DataFrame(result, index=index, columns=columns)
+    return result
+
+
+def mcp(
+    mat: Union[np.ndarray, pd.DataFrame],
+    presence_test: str = "rca",
+    rca_threshold: float = 1.0,
+    rpop_threshold: float = 1.0,
+    pop: Optional[Union[np.ndarray, pd.Series]] = None,
+) -> Union[np.ndarray, pd.DataFrame]:
+    """
+    Binary presence matrix (Mcp).
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Raw value matrix.
+    presence_test : str
+        One of 'rca', 'rpop', 'both' (union of rca and rpop), 'manual'
+        (treat mat as already binary).
+    rca_threshold : float
+        RCA binarization threshold.
+    rpop_threshold : float
+        RPOP binarization threshold.
+    pop : array-like (length R), optional
+        Required when presence_test is 'rpop' or 'both'.
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+
+    if presence_test == "manual":
+        result = binarize(mat, 0.5)
+    elif presence_test == "rca":
+        result = binarize(rca(mat), rca_threshold)
+    elif presence_test == "rpop":
+        if pop is None:
+            raise ValueError("pop is required for presence_test='rpop'.")
+        result = binarize(rpop(mat, pop), rpop_threshold)
+    elif presence_test == "both":
+        if pop is None:
+            raise ValueError("pop is required for presence_test='both'.")
+        m_rca = binarize(rca(mat), rca_threshold)
+        m_rpop = binarize(rpop(mat, pop), rpop_threshold)
+        result = ((m_rca + m_rpop) > 0).astype(float)
+    else:
+        raise ValueError(
+            "presence_test must be one of 'rca', 'rpop', 'both', 'manual'."
+        )
+
+    if is_df:
+        index = mat.index
+        columns = mat.columns
+        return pd.DataFrame(result, index=index, columns=columns)
+    return result