econcomplex 1.0.0__py3-none-any.whl

econcomplex/core/utils.py

@@ -0,0 +1,137 @@
+"""
+Utility functions for matrix/dataframe handling.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Union
+
+
+def pivot_to_matrix(
+    df: pd.DataFrame,
+    index: str,
+    columns: str,
+    values: str,
+    fill_value: float = 0.0,
+) -> pd.DataFrame:
+    """Convert long-format DataFrame to wide (pivot) matrix."""
+    return df.pivot_table(
+        index=index, columns=columns, values=values, aggfunc="sum", fill_value=fill_value
+    )
+
+
+def melt_matrix(
+    mat: pd.DataFrame,
+    index_name: str = "location",
+    columns_name: str = "activity",
+    values_name: str = "value",
+) -> pd.DataFrame:
+    """Convert wide matrix to long-format DataFrame."""
+    df = mat.copy()
+    # Ensure index has a name so reset_index() gives a usable column
+    if df.index.name is None:
+        df.index.name = index_name
+    actual_index_name = df.index.name
+    df.columns.name = None  # avoid extra label
+    return df.reset_index().melt(
+        id_vars=actual_index_name,
+        var_name=columns_name,
+        value_name=values_name,
+    )
+
+
+def validate_matrix(mat: Union[np.ndarray, pd.DataFrame]) -> np.ndarray:
+    """Return a 2-D numpy array; raise on bad input."""
+    if isinstance(mat, pd.DataFrame):
+        arr = mat.values.astype(float)
+    elif isinstance(mat, np.ndarray):
+        arr = mat.astype(float)
+    else:
+        arr = np.array(mat, dtype=float)
+    if arr.ndim != 2:
+        raise ValueError("Input must be a 2-D matrix.")
+    return arr
+
+
+def binarize(mat: Union[np.ndarray, pd.DataFrame], threshold: float = 1.0) -> np.ndarray:
+    """Return binary matrix: 1 where mat >= threshold, else 0."""
+    arr = validate_matrix(mat)
+    return (arr >= threshold).astype(float)
+
+
+def safe_divide(numerator: np.ndarray, denominator: np.ndarray) -> np.ndarray:
+    """Element-wise division, returning 0 where denominator == 0."""
+    with np.errstate(divide="ignore", invalid="ignore"):
+        result = np.where(denominator != 0, numerator / denominator, 0.0)
+    return result
+
+
+def normalize_zscore(vec: np.ndarray) -> np.ndarray:
+    """Z-score normalize a 1-D vector."""
+    std = np.std(vec)
+    if std == 0:
+        return np.zeros_like(vec)
+    return (vec - np.mean(vec)) / std
+
+
+def normalize_01(vec: np.ndarray) -> np.ndarray:
+    """Min-max normalize a 1-D vector to [0, 1]."""
+    rng = vec.max() - vec.min()
+    if rng == 0:
+        return np.zeros_like(vec)
+    return (vec - vec.min()) / rng
+
+
+def make_sample_data(
+    n_locs: int = 50,
+    n_acts: int = 30,
+    seed: int = 42,
+    loc_col: str = "loc",
+    act_col: str = "act",
+    val_col: str = "val",
+) -> pd.DataFrame:
+    """
+    Generate synthetic long-format data for examples and testing.
+
+    The data has the nested (triangular) structure typical of real
+    location-activity matrices: high-capability locations are active in
+    many activities (including complex ones), while low-capability
+    locations concentrate on ubiquitous activities. This makes the
+    resulting ECI/PCI, proximity, and density values meaningful.
+
+    Parameters
+    ----------
+    n_locs : int
+        Number of locations (rows).
+    n_acts : int
+        Number of activities (columns).
+    seed : int
+        Random seed for reproducibility.
+    loc_col, act_col, val_col : str
+        Column names of the returned DataFrame.
+
+    Returns
+    -------
+    pd.DataFrame
+        Long format with columns [loc_col, act_col, val_col],
+        containing only positive entries.
+    """
+    rng = np.random.default_rng(seed)
+
+    # Capability of each location and requirement of each activity
+    capability = np.sort(rng.uniform(0.1, 1.0, n_locs))[::-1]
+    requirement = np.sort(rng.uniform(0.0, 0.9, n_acts))
+
+    # Presence probability falls with the capability gap (nested structure)
+    gap = capability[:, None] - requirement[None, :]
+    presence = rng.random((n_locs, n_acts)) < 1 / (1 + np.exp(-10 * gap))
+
+    values = presence * rng.lognormal(mean=3.0, sigma=1.0, size=(n_locs, n_acts))
+
+    locs = [f"L{i + 1:03d}" for i in range(n_locs)]
+    acts = [f"A{j + 1:03d}" for j in range(n_acts)]
+
+    df = pd.DataFrame(values, index=locs, columns=acts)
+    long = melt_matrix(df, loc_col, act_col, val_col)
+    long = long[long[val_col] > 0].reset_index(drop=True)
+    return long

econcomplex/dynamics/__init__.py

@@ -0,0 +1,10 @@
+from .growth import growth_rate, growth_matrix
+from .entry_exit import entry, exit, entry_exit_summary
+
+__all__ = [
+    "growth_rate",
+    "growth_matrix",
+    "entry",
+    "exit",
+    "entry_exit_summary",
+]

econcomplex/dynamics/entry_exit.py

@@ -0,0 +1,248 @@
+"""
+Industry entry and exit tracking across time periods.
+
+References
+----------
+Balland & Rigby (2017); EconGeo (R package).
+"""
+
+import numpy as np
+import pandas as pd
+from typing import List, Union
+
+from ..core.utils import validate_matrix, binarize, melt_matrix, pivot_to_matrix
+from ..core.rca import rca as compute_rca
+
+
+def _panel_to_matrices(
+    df: pd.DataFrame, loc: str, act: str, val: str, time: str
+) -> List[pd.DataFrame]:
+    """Split a long-format panel into one aligned matrix per time period."""
+    periods = sorted(df[time].unique())
+    if len(periods) < 2:
+        raise ValueError("Need at least 2 time periods.")
+    mats = [pivot_to_matrix(df[df[time] == t], loc, act, val) for t in periods]
+    rows = mats[0].index
+    cols = mats[0].columns
+    for m in mats[1:]:
+        rows = rows.union(m.index)
+        cols = cols.union(m.columns)
+    return [m.reindex(index=rows, columns=cols, fill_value=0.0) for m in mats]
+
+
+def entry(
+    mats: List[Union[np.ndarray, pd.DataFrame]],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Industry entry matrix: 1 when a (region, activity) transitions from
+    absent (M=0) to present (M=1) between consecutive time periods.
+
+    Parameters
+    ----------
+    mats : list of array-like (R x C)
+        Ordered list of value matrices (at least 2).
+    use_rca : bool
+        Compute RCA before binarizing.
+    threshold : float
+        Binarization threshold.
+
+    Returns
+    -------
+    R x C entry matrix (1 = entry event occurred in at least one period).
+    """
+    if len(mats) < 2:
+        raise ValueError("Need at least 2 matrices to detect entry.")
+
+    is_df = isinstance(mats[0], pd.DataFrame)
+    row_index = mats[0].index if is_df else None
+    col_index = mats[0].columns if is_df else None
+
+    def _bin(m):
+        arr = validate_matrix(m)
+        if use_rca:
+            return binarize(compute_rca(arr), threshold)
+        return binarize(arr, threshold)
+
+    binary = [_bin(m) for m in mats]
+    result = np.zeros_like(binary[0])
+
+    for t in range(1, len(binary)):
+        entry_t = ((binary[t - 1] == 0) & (binary[t] == 1)).astype(float)
+        result = np.maximum(result, entry_t)
+
+    if is_df:
+        return pd.DataFrame(result, index=row_index, columns=col_index)
+    return result
+
+
+def exit(
+    mats: List[Union[np.ndarray, pd.DataFrame]],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Industry exit matrix: 1 when a (region, activity) transitions from
+    present (M=1) to absent (M=0) between consecutive time periods.
+
+    Parameters
+    ----------
+    mats : list of array-like (R x C)
+        Ordered list of value matrices (at least 2).
+    use_rca : bool
+        Compute RCA before binarizing.
+    threshold : float
+        Binarization threshold.
+
+    Returns
+    -------
+    R x C exit matrix (1 = exit event occurred in at least one period).
+    """
+    if len(mats) < 2:
+        raise ValueError("Need at least 2 matrices to detect exit.")
+
+    is_df = isinstance(mats[0], pd.DataFrame)
+    row_index = mats[0].index if is_df else None
+    col_index = mats[0].columns if is_df else None
+
+    def _bin(m):
+        arr = validate_matrix(m)
+        if use_rca:
+            return binarize(compute_rca(arr), threshold)
+        return binarize(arr, threshold)
+
+    binary = [_bin(m) for m in mats]
+    result = np.zeros_like(binary[0])
+
+    for t in range(1, len(binary)):
+        exit_t = ((binary[t - 1] == 1) & (binary[t] == 0)).astype(float)
+        result = np.maximum(result, exit_t)
+
+    if is_df:
+        return pd.DataFrame(result, index=row_index, columns=col_index)
+    return result
+
+
+def entry_exit_summary(
+    mats: List[Union[np.ndarray, pd.DataFrame]],
+    use_rca: bool = True,
+    threshold: float = 1.0,
+) -> pd.DataFrame:
+    """
+    Summary of entry and exit events per (region, activity) pair.
+
+    Returns a long-format DataFrame with columns:
+    - location, activity, n_entries, n_exits, net_change
+
+    Parameters
+    ----------
+    mats : list of array-like (R x C)
+        Ordered list of value matrices.
+    use_rca : bool
+        Compute RCA before binarizing.
+    threshold : float
+        Binarization threshold.
+    """
+    if len(mats) < 2:
+        raise ValueError("Need at least 2 matrices.")
+
+    is_df = isinstance(mats[0], pd.DataFrame)
+    row_index = mats[0].index if is_df else range(mats[0].shape[0])
+    col_index = mats[0].columns if is_df else range(mats[0].shape[1])
+
+    def _bin(m):
+        arr = validate_matrix(m)
+        if use_rca:
+            return binarize(compute_rca(arr), threshold)
+        return binarize(arr, threshold)
+
+    binary = [_bin(m) for m in mats]
+    n_r, n_c = binary[0].shape
+
+    n_entries = np.zeros((n_r, n_c))
+    n_exits = np.zeros((n_r, n_c))
+
+    for t in range(1, len(binary)):
+        n_entries += ((binary[t - 1] == 0) & (binary[t] == 1)).astype(float)
+        n_exits += ((binary[t - 1] == 1) & (binary[t] == 0)).astype(float)
+
+    rows = []
+    for i, loc in enumerate(row_index):
+        for j, act in enumerate(col_index):
+            if n_entries[i, j] > 0 or n_exits[i, j] > 0:
+                rows.append({
+                    "location": loc,
+                    "activity": act,
+                    "n_entries": int(n_entries[i, j]),
+                    "n_exits": int(n_exits[i, j]),
+                    "net_change": int(n_entries[i, j] - n_exits[i, j]),
+                })
+
+    return pd.DataFrame(rows)
+
+
+def entry_tracking(
+    df: pd.DataFrame,
+    loc: str,
+    act: str,
+    val: str,
+    time: str,
+    use_rca: bool = True,
+    threshold: float = 1.0,
+) -> pd.DataFrame:
+    """
+    Long-format wrapper around `entry` for panel data.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Long-format data.
+    loc, act, val, time : str
+        Column names for location, activity, value, and time period.
+    use_rca : bool
+        Compute RCA before binarizing.
+    threshold : float
+        Binarization threshold.
+
+    Returns
+    -------
+    pd.DataFrame with columns [loc, act, 'entry'] (entry = 1 when the
+    pair entered in at least one period transition).
+    """
+    mats = _panel_to_matrices(df, loc, act, val, time)
+    result = entry(mats, use_rca=use_rca, threshold=threshold)
+    return melt_matrix(result, loc, act, "entry")
+
+
+def exit_tracking(
+    df: pd.DataFrame,
+    loc: str,
+    act: str,
+    val: str,
+    time: str,
+    use_rca: bool = True,
+    threshold: float = 1.0,
+) -> pd.DataFrame:
+    """
+    Long-format wrapper around `exit` for panel data.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Long-format data.
+    loc, act, val, time : str
+        Column names for location, activity, value, and time period.
+    use_rca : bool
+        Compute RCA before binarizing.
+    threshold : float
+        Binarization threshold.
+
+    Returns
+    -------
+    pd.DataFrame with columns [loc, act, 'exit'] (exit = 1 when the
+    pair exited in at least one period transition).
+    """
+    mats = _panel_to_matrices(df, loc, act, val, time)
+    result = exit(mats, use_rca=use_rca, threshold=threshold)
+    return melt_matrix(result, loc, act, "exit")

econcomplex/dynamics/growth.py

@@ -0,0 +1,146 @@
+"""
+Regional and industry growth rates.
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Union
+
+from ..core.utils import validate_matrix, safe_divide, pivot_to_matrix
+
+
+def growth_rate(
+    mat1: Union[np.ndarray, pd.DataFrame],
+    mat2: Union[np.ndarray, pd.DataFrame],
+    axis: int = 0,
+    pct: bool = True,
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Growth rate between two time periods.
+
+    g = (sum_t2 - sum_t1) / sum_t1  [* 100 if pct]
+
+    Parameters
+    ----------
+    mat1 : array-like (R x C)
+        Matrix for time period 1.
+    mat2 : array-like (R x C)
+        Matrix for time period 2 (same shape as mat1).
+    axis : int
+        0 = aggregate over columns (regional growth), rows returned.
+        1 = aggregate over rows (industry growth), columns returned.
+    pct : bool
+        If True, multiply by 100 to return percentage.
+
+    Returns
+    -------
+    pd.Series or ndarray.
+    """
+    is_df = isinstance(mat1, pd.DataFrame)
+
+    arr1 = validate_matrix(mat1)
+    arr2 = validate_matrix(mat2)
+
+    if arr1.shape != arr2.shape:
+        raise ValueError("mat1 and mat2 must have the same shape.")
+
+    sum1 = arr1.sum(axis=1 - axis)  # opposite axis
+    sum2 = arr2.sum(axis=1 - axis)
+
+    g = safe_divide(sum2 - sum1, sum1)
+    if pct:
+        g = g * 100
+
+    if is_df:
+        index = mat1.index if axis == 0 else mat1.columns
+        name = "growth_region" if axis == 0 else "growth_industry"
+        return pd.Series(g, index=index, name=name)
+    return g
+
+
+def growth_matrix(
+    mat1: Union[np.ndarray, pd.DataFrame],
+    mat2: Union[np.ndarray, pd.DataFrame],
+    pct: bool = True,
+) -> Union[pd.DataFrame, np.ndarray]:
+    """
+    Element-wise growth rate matrix.
+
+    g_{rc} = (x_{rc,t2} - x_{rc,t1}) / x_{rc,t1}
+
+    Parameters
+    ----------
+    mat1, mat2 : array-like (R x C)
+    pct : bool
+        Multiply by 100.
+
+    Returns
+    -------
+    R x C growth rate matrix.
+    """
+    is_df = isinstance(mat1, pd.DataFrame)
+    row_index = mat1.index if is_df else None
+    col_index = mat1.columns if is_df else None
+
+    arr1 = validate_matrix(mat1)
+    arr2 = validate_matrix(mat2)
+
+    if arr1.shape != arr2.shape:
+        raise ValueError("mat1 and mat2 must have the same shape.")
+
+    g = safe_divide(arr2 - arr1, arr1)
+    if pct:
+        g = g * 100
+
+    if is_df:
+        return pd.DataFrame(g, index=row_index, columns=col_index)
+    return g
+
+
+def growth_rates(
+    df: pd.DataFrame,
+    loc: str,
+    act: str,
+    val: str,
+    time: str,
+    axis: int = 0,
+    pct: bool = True,
+) -> pd.DataFrame:
+    """
+    Long-format wrapper around `growth_rate` for panel data.
+
+    Computes the growth rate between each pair of consecutive time periods.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Long-format data.
+    loc, act, val, time : str
+        Column names for location, activity, value, and time period.
+    axis : int
+        0 = growth per location, 1 = growth per activity.
+    pct : bool
+        If True, return percentage.
+
+    Returns
+    -------
+    pd.DataFrame with columns [unit, time, 'growth'], where unit is `loc`
+    (axis=0) or `act` (axis=1) and `time` marks the end of each interval.
+    """
+    periods = sorted(df[time].unique())
+    if len(periods) < 2:
+        raise ValueError("Need at least 2 time periods to compute growth.")
+
+    unit_col = loc if axis == 0 else act
+    out = []
+    for t1, t2 in zip(periods[:-1], periods[1:]):
+        m1 = pivot_to_matrix(df[df[time] == t1], loc, act, val)
+        m2 = pivot_to_matrix(df[df[time] == t2], loc, act, val)
+        rows = m1.index.union(m2.index)
+        cols = m1.columns.union(m2.columns)
+        m1 = m1.reindex(index=rows, columns=cols, fill_value=0.0)
+        m2 = m2.reindex(index=rows, columns=cols, fill_value=0.0)
+        g = growth_rate(m1, m2, axis=axis, pct=pct)
+        out.append(pd.DataFrame({unit_col: g.index, time: t2, "growth": g.values}))
+
+    return pd.concat(out, ignore_index=True)

econcomplex/inequality/__init__.py

@@ -0,0 +1,11 @@
+from .gini import gini, locational_gini, hoover_gini
+from .concentration import herfindahl, shannon_entropy, hoover_index
+
+__all__ = [
+    "gini",
+    "locational_gini",
+    "hoover_gini",
+    "herfindahl",
+    "shannon_entropy",
+    "hoover_index",
+]

econcomplex/inequality/concentration.py

@@ -0,0 +1,148 @@
+"""
+Concentration and dispersion measures.
+
+References
+----------
+Herfindahl-Hirschman (1945/1950); Shannon (1948); Hoover (1936).
+"""
+
+import numpy as np
+import pandas as pd
+from typing import Optional, Union
+
+from ..core.utils import validate_matrix, safe_divide
+
+
+def herfindahl(
+    mat: Union[np.ndarray, pd.DataFrame],
+    normalize: bool = True,
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Herfindahl-Hirschman Index (HHI) per region.
+
+    HHI_r = sum_c (x_{rc} / X_r)^2
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    normalize : bool
+        If True, normalize to [0, 1] using (HHI - 1/C) / (1 - 1/C).
+
+    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)
+    row_sums = arr.sum(axis=1, keepdims=True)
+    shares = safe_divide(arr, row_sums)
+    hhi = (shares ** 2).sum(axis=1)
+
+    if normalize:
+        n = arr.shape[1]
+        min_hhi = 1.0 / n
+        hhi = safe_divide(hhi - min_hhi, 1.0 - min_hhi)
+
+    if is_df:
+        return pd.Series(hhi, index=row_index, name="herfindahl")
+    return hhi
+
+
+def shannon_entropy(
+    mat: Union[np.ndarray, pd.DataFrame],
+    base: float = 2.0,
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Shannon entropy per region.
+
+    H_r = -sum_c (s_{rc} * log_base(s_{rc}))
+    where s_{rc} = x_{rc} / X_r
+
+    Higher entropy = more diversified regional economy.
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    base : float
+        Logarithm base (default 2 = bits).
+
+    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)
+    row_sums = arr.sum(axis=1, keepdims=True)
+    shares = safe_divide(arr, row_sums)
+
+    with np.errstate(divide="ignore", invalid="ignore"):
+        log_shares = np.where(shares > 0, np.log(shares) / np.log(base), 0.0)
+
+    result = -(shares * log_shares).sum(axis=1)
+
+    if is_df:
+        return pd.Series(result, index=row_index, name="shannon_entropy")
+    return result
+
+
+def hoover_index(
+    mat: Union[np.ndarray, pd.DataFrame],
+    pop: Optional[Union[np.ndarray, pd.Series]] = None,
+) -> Union[pd.Series, np.ndarray]:
+    """
+    Hoover Index (Robin Hood Index) per activity.
+
+    H_c = (1/2) * sum_r |E_r/E_total - A_r/A_total| * 100
+
+    where E_r = employment of region r in activity c,
+          A_r = total employment / population of region r.
+
+    Parameters
+    ----------
+    mat : array-like (R x C)
+        Value matrix.
+    pop : array-like (length R), optional
+        Population/reference vector. If None, uses row sums.
+
+    Returns
+    -------
+    pd.Series indexed by activity (values 0–100).
+    """
+    is_df = isinstance(mat, pd.DataFrame)
+    col_index = mat.columns if is_df else None
+
+    arr = validate_matrix(mat)
+
+    if pop is None:
+        pop_arr = arr.sum(axis=1)
+    else:
+        pop_arr = np.array(pop, dtype=float)
+
+    total_pop = pop_arr.sum()
+
+    col_sums = arr.sum(axis=0)
+
+    results = []
+    for c in range(arr.shape[1]):
+        if col_sums[c] == 0:
+            results.append(0.0)
+            continue
+        share_e = arr[:, c] / col_sums[c]
+        share_a = pop_arr / total_pop
+        hi = 0.5 * np.abs(share_e - share_a).sum() * 100
+        results.append(hi)
+
+    result = np.array(results)
+    if is_df:
+        return pd.Series(result, index=col_index, name="hoover_index")
+    return result
+
+
+# Short alias matching the documented API
+hhi = herfindahl