gomd 2.1.0__py3-none-any.whl

gomd/dynamics.py

@@ -0,0 +1,629 @@
+"""
+gomd.dynamics — Port, Fisheries and Climate Dynamics Toolkit (new in gomd 2.1.0)
+===============================================================================
+Self-contained (pure Python, no NumPy) implementations of the analysis methods
+used in the GOMD research papers on port activity, national marine catch and
+coral heat stress (https://gomd.pirireis.edu.tr/publications.php):
+
+  1. symmetric_growth             — symmetric (Davis-Haltiwanger-Schuh) growth rate
+  2. common_factor_decomposition  — static principal-component global factor and variance shares
+  3. dispersion_index             — variance-to-mean ratio of counts (Poisson benchmark = 1)
+  4. cargo_bunching               — cargo per call, daily-cargo CV and its Poisson benchmark
+  5. weekday_profile              — day-of-week profile and weekend ratio of a daily series
+  6. size_growth_scaling          — Gibrat's-law test and size scaling of growth volatility
+  7. portfolio_effect             — portfolio effect and synchrony of an aggregate
+  8. exceedance_return_interval   — empirical return interval of threshold exceedances
+  9. fdr_benjamini_hochberg       — Benjamini-Hochberg false-discovery-rate control
+ 10. field_significance           — binomial field-significance test for many local tests
+ 11. local_projection_event       — event-study local projections with unit and time fixed effects
+
+Every function returns a plain ``dict`` and reports an ``"error"`` key instead of
+raising when the input is too short. The functions describe data; they do not
+establish causality on their own.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import math
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple, Union
+
+Number = Union[int, float]
+
+
+def _is_num(v: Any) -> bool:
+    if v is None:
+        return False
+    try:
+        f = float(v)
+    except (TypeError, ValueError):
+        return False
+    return not (math.isnan(f) or math.isinf(f))
+
+
+def _clean(values: Sequence[Any]) -> List[float]:
+    return [float(v) for v in values if _is_num(v)]
+
+
+def _mean(x: Sequence[float]) -> float:
+    return sum(x) / len(x)
+
+
+def _var(x: Sequence[float], ddof: int = 1) -> float:
+    m = _mean(x)
+    return sum((v - m) ** 2 for v in x) / (len(x) - ddof)
+
+
+def _normal_sf(z: float) -> float:
+    return 0.5 * math.erfc(z / math.sqrt(2.0))
+
+
+def _ols_simple(x: Sequence[float], y: Sequence[float]) -> Dict[str, float]:
+    """OLS of y on a constant and x with the conventional standard error."""
+    n = len(x)
+    mx, my = _mean(x), _mean(y)
+    sxx = sum((a - mx) ** 2 for a in x)
+    sxy = sum((a - mx) * (b - my) for a, b in zip(x, y))
+    slope = sxy / sxx
+    intercept = my - slope * mx
+    rss = sum((b - intercept - slope * a) ** 2 for a, b in zip(x, y))
+    tss = sum((b - my) ** 2 for b in y)
+    se = math.sqrt(rss / (n - 2) / sxx) if n > 2 and sxx > 0 else float("nan")
+    return {
+        "slope": slope,
+        "intercept": intercept,
+        "se": se,
+        "t": slope / se if se and se > 0 else float("nan"),
+        "r2": 1.0 - rss / tss if tss > 0 else float("nan"),
+        "n": n,
+    }
+
+
+# --------------------------------------------------------------------------- 1
+def symmetric_growth(values: Sequence[Any], lag: int = 12, percent: bool = True) -> Dict[str, Any]:
+    """
+    Symmetric growth rate g_t = (x_t - x_{t-lag}) / ((x_t + x_{t-lag}) / 2)
+    (Davis, Haltiwanger & Schuh, 1996). It is bounded in [-2, 2] (or [-200, 200] %),
+    is defined when one of the two values is zero and treats rises and falls
+    symmetrically. With monthly data ``lag=12`` gives year-on-year growth.
+
+    Returns ``growth`` aligned with the input (``None`` for the first ``lag``
+    positions and where either value is missing or both are zero).
+    """
+    if lag < 1:
+        return {"error": "lag must be at least 1."}
+    n = len(values)
+    out: List[Optional[float]] = [None] * n
+    k = 100.0 if percent else 1.0
+    for t in range(lag, n):
+        a, b = values[t], values[t - lag]
+        if _is_num(a) and _is_num(b):
+            den = (float(a) + float(b)) / 2.0
+            if den != 0:
+                out[t] = k * (float(a) - float(b)) / den
+    valid = [v for v in out if v is not None]
+    return {"growth": out, "n_valid": len(valid), "lag": lag, "unit": "%" if percent else "ratio",
+            "mean": _mean(valid) if valid else None}
+
+
+# --------------------------------------------------------------------------- 2
+def common_factor_decomposition(
+    panel: Mapping[str, Sequence[Any]],
+    max_iter: int = 500,
+    tol: float = 1e-12,
+) -> Dict[str, Any]:
+    """
+    Static principal-component estimate of one common ("global") factor in a panel
+    of series (Stock & Watson, 2002; Bai & Ng, 2002).
+
+    ``panel`` maps a series name (for example a port) to observations on a common
+    time index (for example year-on-year growth rates). Series with a missing value
+    or zero variance are dropped. Each series is standardised; the factor is the
+    first principal component, scaled to unit variance and oriented to correlate
+    positively with the cross-sectional mean.
+
+    Returns the factor, each series' loading and the share of its variance explained
+    by the factor (``share_explained``, the squared correlation), the unweighted mean
+    and median of these shares, and the share of the variance of the cross-sectional
+    aggregate (the simple mean of the standardised series) explained by the factor.
+    The gap between the median series share and the aggregate share shows how much
+    of a "common" movement comes from averaging out series-specific shocks.
+    """
+    names: List[str] = []
+    z: List[List[float]] = []
+    t_len: Optional[int] = None
+    dropped: List[str] = []
+    for name, vals in panel.items():
+        vals = list(vals)
+        if t_len is None:
+            t_len = len(vals)
+        if len(vals) != t_len or not all(_is_num(v) for v in vals):
+            dropped.append(str(name)); continue
+        x = [float(v) for v in vals]
+        m = _mean(x)
+        sd = math.sqrt(sum((v - m) ** 2 for v in x) / len(x))
+        if sd <= 0:
+            dropped.append(str(name)); continue
+        names.append(str(name)); z.append([(v - m) / sd for v in x])
+    n = len(names)
+    if t_len is None or n < 3 or t_len < 8:
+        return {"error": "At least 3 complete series with 8 or more periods are required.", "n_series": n, "dropped": dropped}
+    T = t_len
+    # Dual (T x T) Gram matrix: G = Z'Z / N with Z stored series-by-time.
+    g = [[0.0] * T for _ in range(T)]
+    for row in z:
+        for a in range(T):
+            ra = row[a]
+            if ra == 0.0:
+                continue
+            ga = g[a]
+            for b in range(a, T):
+                ga[b] += ra * row[b]
+    for a in range(T):
+        for b in range(a, T):
+            g[a][b] /= n
+            g[b][a] = g[a][b]
+    f = [sum(row[t] for row in z) / n for t in range(T)]  # start from the cross-sectional mean
+    norm = math.sqrt(sum(v * v for v in f)) or 1.0
+    f = [v / norm for v in f]
+    eig = 0.0
+    converged = False
+    for _ in range(max_iter):
+        nf = [sum(g[a][b] * f[b] for b in range(T)) for a in range(T)]
+        new_eig = math.sqrt(sum(v * v for v in nf))
+        if new_eig == 0:
+            break
+        nf = [v / new_eig for v in nf]
+        delta = max(abs(a - b) for a, b in zip(nf, f))
+        f, eig = nf, new_eig
+        if delta < tol:
+            converged = True
+            break
+    # unit-variance factor (series are mean zero, so the factor is mean zero as well)
+    fm = _mean(f)
+    fsd = math.sqrt(sum((v - fm) ** 2 for v in f) / T)
+    factor = [(v - fm) / fsd for v in f]
+    agg = [sum(row[t] for row in z) / n for t in range(T)]
+    if sum(a * b for a, b in zip(factor, agg)) < 0:
+        factor = [-v for v in factor]
+    loadings = {nm: sum(a * b for a, b in zip(row, factor)) / T for nm, row in zip(names, z)}
+    shares = {nm: l * l for nm, l in loadings.items()}
+    sv = sorted(shares.values())
+    med = sv[n // 2] if n % 2 else 0.5 * (sv[n // 2 - 1] + sv[n // 2])
+    am = _mean(agg)
+    avar = sum((v - am) ** 2 for v in agg) / T
+    acorr = (sum((a - am) * b for a, b in zip(agg, factor)) / T) / math.sqrt(avar) if avar > 0 else float("nan")
+    return {
+        "factor": factor,
+        "loadings": loadings,
+        "share_explained": shares,
+        "mean_share_explained": _mean(sv),
+        "median_share_explained": med,
+        "aggregate_share_explained": acorr * acorr,
+        "eigenvalue_share": eig / T,
+        "n_series": n,
+        "n_periods": T,
+        "dropped": dropped,
+        "converged": converged,
+    }
+
+
+# --------------------------------------------------------------------------- 3
+def dispersion_index(counts: Sequence[Any]) -> Dict[str, Any]:
+    """
+    Index of dispersion (variance-to-mean ratio) of a series of counts, for example
+    daily port calls. It equals 1 for Poisson arrivals; values below 1 indicate more
+    regular (scheduled) arrivals and values above 1 indicate clustered arrivals.
+
+    Also returns the dispersion test statistic (n - 1) * index, which is approximately
+    chi-square with n - 1 degrees of freedom under the Poisson hypothesis, and its
+    normal (Wilson-Hilferty) approximation z-score and two-sided p-value.
+    """
+    x = _clean(counts)
+    n = len(x)
+    if n < 10:
+        return {"error": "At least 10 observations are required.", "n": n}
+    m = _mean(x)
+    if m <= 0:
+        return {"error": "The mean of the counts must be positive.", "n": n}
+    idx = _var(x) / m
+    df = n - 1
+    chi2 = df * idx
+    z = ((chi2 / df) ** (1.0 / 3.0) - (1.0 - 2.0 / (9.0 * df))) / math.sqrt(2.0 / (9.0 * df))
+    p = 2.0 * _normal_sf(abs(z))
+    return {"dispersion_index": idx, "mean": m, "variance": _var(x), "n": n, "chi2": chi2, "df": df, "z": z, "p_value": p,
+            "pattern": "regular" if idx < 1 else "clustered" if idx > 1 else "poisson"}
+
+
+# --------------------------------------------------------------------------- 4
+def cargo_bunching(daily_calls: Sequence[Any], daily_cargo: Sequence[Any]) -> Dict[str, Any]:
+    """
+    Cargo bunching at a port from daily calls and daily cargo volume (same days).
+
+    Returns cargo per call (total cargo / total calls), the coefficient of variation
+    (CV) of daily cargo, the dispersion index of daily calls and the compound-Poisson
+    benchmark. If ships arrive as a Poisson process with rate lambda per day and
+    carry independent loads with coefficient of variation c, daily cargo has
+    CV^2 = (1 + c^2) / lambda. ``cv_benchmark_equal_loads`` is the lower bound
+    1 / sqrt(lambda) (all ships the same size), and ``implied_load_cv`` is the load
+    variability c that would reconcile the observed CV with Poisson arrivals
+    (``None`` when the observed CV is below the lower bound, i.e. arrivals are more
+    regular than Poisson). Holding cargo constant, fewer and larger ships lower
+    lambda and raise the benchmark CV.
+    """
+    pairs = [(float(a), float(b)) for a, b in zip(daily_calls, daily_cargo) if _is_num(a) and _is_num(b)]
+    n = len(pairs)
+    if n < 30:
+        return {"error": "At least 30 days with both calls and cargo are required.", "n": n}
+    calls = [p[0] for p in pairs]
+    cargo = [p[1] for p in pairs]
+    tc, tq = sum(calls), sum(cargo)
+    if tc <= 0 or tq <= 0:
+        return {"error": "Total calls and total cargo must be positive.", "n": n}
+    lam = tc / n
+    mq = tq / n
+    cv = math.sqrt(_var(cargo)) / mq
+    bench = 1.0 / math.sqrt(lam)
+    implied = math.sqrt(cv * cv * lam - 1.0) if cv * cv * lam >= 1.0 else None
+    return {
+        "n_days": n,
+        "total_calls": tc,
+        "total_cargo": tq,
+        "cargo_per_call": tq / tc,
+        "calls_per_day": lam,
+        "daily_cargo_cv": cv,
+        "calls_dispersion_index": _var(calls) / lam,
+        "cv_benchmark_equal_loads": bench,
+        "cv_ratio_to_benchmark": cv / bench,
+        "implied_load_cv": implied,
+    }
+
+
+# --------------------------------------------------------------------------- 5
+def weekday_profile(dates: Sequence[Any], values: Sequence[Any]) -> Dict[str, Any]:
+    """
+    Day-of-week profile of a daily series. ``dates`` are ISO strings (YYYY-MM-DD) or
+    ``datetime.date`` objects. Returns the mean by weekday (Monday first), each
+    weekday's index relative to the overall daily mean (1 = average day), the
+    Saturday-Sunday mean relative to the Monday-Friday mean and the same ratio for
+    Friday-Saturday (the weekend in several countries), and the share of the variance
+    of the series explained by weekday means.
+    """
+    sums = [0.0] * 7
+    cnts = [0] * 7
+    xs: List[Tuple[int, float]] = []
+    for d, v in zip(dates, values):
+        if not _is_num(v):
+            continue
+        if isinstance(d, _dt.datetime):
+            d = d.date()
+        if not isinstance(d, _dt.date):
+            try:
+                d = _dt.date.fromisoformat(str(d)[:10])
+            except ValueError:
+                continue
+        w = d.weekday()
+        sums[w] += float(v); cnts[w] += 1; xs.append((w, float(v)))
+    n = len(xs)
+    if n < 28 or min(cnts) < 2:
+        return {"error": "At least 28 dated observations covering every weekday are required.", "n": n}
+    means = [s / c for s, c in zip(sums, cnts)]
+    overall = sum(v for _, v in xs) / n
+    if overall == 0:
+        return {"error": "The mean of the series is zero.", "n": n}
+    tss = sum((v - overall) ** 2 for _, v in xs)
+    bss = sum(c * (m - overall) ** 2 for c, m in zip(cnts, means))
+    names = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
+
+    def ratio(weekend: Sequence[int]) -> float:
+        we = sum(sums[i] for i in weekend) / sum(cnts[i] for i in weekend)
+        rest = [i for i in range(7) if i not in weekend]
+        wd = sum(sums[i] for i in rest) / sum(cnts[i] for i in rest)
+        return we / wd if wd != 0 else float("nan")
+
+    return {
+        "weekday_mean": dict(zip(names, means)),
+        "weekday_index": {k: m / overall for k, m in zip(names, means)},
+        "sat_sun_ratio": ratio([5, 6]),
+        "fri_sat_ratio": ratio([4, 5]),
+        "variance_share_weekday": bss / tss if tss > 0 else float("nan"),
+        "n": n,
+    }
+
+
+# --------------------------------------------------------------------------- 6
+def size_growth_scaling(size: Sequence[Any], growth: Sequence[Any], n_bins: int = 10) -> Dict[str, Any]:
+    """
+    Gibrat's-law diagnostics for units such as ports or firms.
+
+    ``size`` is the initial size (positive) and ``growth`` the subsequent growth rate
+    (for example log growth) of the same unit. Two regressions are reported:
+      * mean test: growth on log size. Gibrat's law of proportionate growth implies
+        a zero slope.
+      * volatility scaling: units are sorted by size into ``n_bins`` equal-count bins;
+        the log standard deviation of growth in each bin is regressed on the mean log
+        size of the bin. The slope is -beta in sigma(S) ~ S^(-beta). Gibrat's law
+        implies beta = 0; independent sub-units would give beta = 0.5; values between
+        0.1 and 0.3 are typical of firms and countries (Stanley et al., 1996).
+    """
+    pairs = [(math.log(float(s)), float(g)) for s, g in zip(size, growth) if _is_num(s) and _is_num(g) and float(s) > 0]
+    n = len(pairs)
+    if n_bins < 3:
+        return {"error": "n_bins must be at least 3."}
+    if n < max(30, 5 * n_bins):
+        return {"error": "At least max(30, 5 * n_bins) units with positive size are required.", "n": n}
+    pairs.sort(key=lambda p: p[0])
+    ls = [p[0] for p in pairs]
+    gr = [p[1] for p in pairs]
+    mean_fit = _ols_simple(ls, gr)
+    bins = []
+    for b in range(n_bins):
+        lo = b * n // n_bins
+        hi = (b + 1) * n // n_bins
+        gs = gr[lo:hi]
+        sd = math.sqrt(_var(gs))
+        bins.append({"mean_log_size": _mean(ls[lo:hi]), "sd_growth": sd, "mean_growth": _mean(gs), "n": hi - lo})
+    good = [b for b in bins if b["sd_growth"] > 0]
+    if len(good) < 3:
+        return {"error": "Growth has no dispersion within the size bins.", "n": n}
+    vol_fit = _ols_simple([b["mean_log_size"] for b in good], [math.log(b["sd_growth"]) for b in good])
+    return {
+        "n": n,
+        "mean_slope": mean_fit["slope"], "mean_slope_se": mean_fit["se"], "mean_slope_t": mean_fit["t"],
+        "volatility_beta": -vol_fit["slope"], "volatility_beta_se": vol_fit["se"], "volatility_r2": vol_fit["r2"],
+        "bins": bins,
+    }
+
+
+# --------------------------------------------------------------------------- 7
+def portfolio_effect(panel: Mapping[str, Sequence[Any]]) -> Dict[str, Any]:
+    """
+    Portfolio effect of an aggregate made of several components (for example the
+    national catch as the sum of species or stock catches; Doak et al., 1998;
+    Schindler et al., 2010; Thibaut & Connolly, 2013).
+
+    ``panel`` maps a component name to its values on a common time index (levels,
+    not growth rates). Periods in which any component is missing are dropped.
+
+    Returns the CV of the aggregate, the weighted-average CV of the components
+    (weights = mean share of the aggregate), the portfolio effect
+    1 - CV_aggregate / CV_weighted (0 = no stabilisation), the synchrony index of
+    Loreau & de Mazancourt (2008), phi = var(sum) / (sum of sd)^2 (1 = perfectly
+    synchronous, 1/n = independent equal components), and the effective number of
+    components 1 / sum(share^2).
+    """
+    names = [str(k) for k in panel.keys()]
+    series = [list(v) for v in panel.values()]
+    if len(series) < 2:
+        return {"error": "At least two components are required."}
+    T = min(len(s) for s in series)
+    rows = [t for t in range(T) if all(_is_num(s[t]) for s in series)]
+    if len(rows) < 8:
+        return {"error": "At least 8 periods with all components observed are required.", "n_periods": len(rows)}
+    x = [[float(s[t]) for t in rows] for s in series]
+    total = [sum(col[i] for col in x) for i in range(len(rows))]
+    mt = _mean(total)
+    if mt <= 0:
+        return {"error": "The aggregate must have a positive mean."}
+    means = [_mean(c) for c in x]
+    sds = [math.sqrt(_var(c)) for c in x]
+    keep = [i for i, m in enumerate(means) if m > 0]
+    shares = [means[i] / mt for i in keep]
+    cv_w = sum(sh * (sds[i] / means[i]) for sh, i in zip(shares, keep))
+    cv_tot = math.sqrt(_var(total)) / mt
+    sum_sd = sum(sds)
+    return {
+        "cv_aggregate": cv_tot,
+        "cv_weighted_components": cv_w,
+        "portfolio_effect": 1.0 - cv_tot / cv_w if cv_w > 0 else float("nan"),
+        "synchrony": _var(total) / (sum_sd * sum_sd) if sum_sd > 0 else float("nan"),
+        "effective_components": 1.0 / sum(s * s for s in shares) if shares else float("nan"),
+        "n_components": len(names),
+        "n_periods": len(rows),
+        "component_cv": {names[i]: sds[i] / means[i] for i in keep},
+    }
+
+
+# --------------------------------------------------------------------------- 8
+def exceedance_return_interval(
+    years: Sequence[Any],
+    values: Sequence[Any],
+    threshold: float,
+    split_year: Optional[Number] = None,
+) -> Dict[str, Any]:
+    """
+    Empirical return interval of years in which an annual series reaches a threshold,
+    for example annual maximum degree heating weeks (DHW) >= 4 or >= 8 degC-weeks.
+
+    The return interval is (number of years) / (number of exceedance years). With
+    ``split_year`` the record is divided into years before ``split_year`` and years
+    from ``split_year`` onwards, and the two exceedance probabilities are compared
+    with a two-proportion z-test. Also returns the gaps between successive
+    exceedance years and the longest run of consecutive exceedance years.
+    """
+    pairs = sorted((float(y), float(v)) for y, v in zip(years, values) if _is_num(y) and _is_num(v))
+    n = len(pairs)
+    if n < 10:
+        return {"error": "At least 10 annual values are required.", "n": n}
+    hit_years = [y for y, v in pairs if v >= threshold]
+    k = len(hit_years)
+    gaps = [b - a for a, b in zip(hit_years[:-1], hit_years[1:])]
+    run = best = 0
+    for _, v in pairs:
+        run = run + 1 if v >= threshold else 0
+        best = max(best, run)
+    out: Dict[str, Any] = {
+        "n_years": n, "n_exceedance_years": k, "threshold": threshold,
+        "exceedance_probability": k / n,
+        "return_interval_years": n / k if k else None,
+        "exceedance_years": hit_years,
+        "mean_gap_years": _mean(gaps) if gaps else None,
+        "longest_run_years": best,
+    }
+    if split_year is not None:
+        a = [v for y, v in pairs if y < float(split_year)]
+        b = [v for y, v in pairs if y >= float(split_year)]
+        if len(a) >= 5 and len(b) >= 5:
+            ka = sum(1 for v in a if v >= threshold)
+            kb = sum(1 for v in b if v >= threshold)
+            pa, pb = ka / len(a), kb / len(b)
+            pp = (ka + kb) / (len(a) + len(b))
+            se = math.sqrt(pp * (1 - pp) * (1 / len(a) + 1 / len(b)))
+            z = (pb - pa) / se if se > 0 else float("nan")
+            out["split"] = {
+                "split_year": split_year, "n_before": len(a), "n_after": len(b),
+                "probability_before": pa, "probability_after": pb,
+                "return_interval_before": len(a) / ka if ka else None,
+                "return_interval_after": len(b) / kb if kb else None,
+                "z": z, "p_value": 2.0 * _normal_sf(abs(z)) if not math.isnan(z) else None,
+            }
+        else:
+            out["split"] = {"error": "Each sub-period needs at least 5 years."}
+    return out
+
+
+# --------------------------------------------------------------------------- 9
+def fdr_benjamini_hochberg(pvalues: Sequence[Any], q: float = 0.05) -> Dict[str, Any]:
+    """
+    Benjamini & Hochberg (1995) control of the false discovery rate. Returns the
+    adjusted p-values (q-values) in the input order, a rejection flag for each test
+    at level ``q`` and the number of discoveries. Missing p-values stay ``None``.
+    """
+    idx = [i for i, p in enumerate(pvalues) if _is_num(p)]
+    m = len(idx)
+    if m == 0:
+        return {"error": "No valid p-values."}
+    order = sorted(idx, key=lambda i: float(pvalues[i]))
+    adj: List[Optional[float]] = [None] * len(pvalues)
+    prev = 1.0
+    for rank in range(m, 0, -1):
+        i = order[rank - 1]
+        val = min(prev, float(pvalues[i]) * m / rank)
+        adj[i] = val
+        prev = val
+    rejected = [(a is not None and a <= q) for a in adj]
+    return {"adjusted_p": adj, "rejected": rejected, "n_tests": m, "n_discoveries": sum(rejected), "q": q,
+            "n_nominal_below_q": sum(1 for i in idx if float(pvalues[i]) <= q)}
+
+
+# -------------------------------------------------------------------------- 10
+def field_significance(pvalues: Sequence[Any], alpha: float = 0.05) -> Dict[str, Any]:
+    """
+    Field significance of a collection of local tests (Livezey & Chen, 1983): is the
+    number of locally significant tests larger than expected by chance?
+
+    Under the global null and *independent* tests the number of p-values <= alpha is
+    Binomial(m, alpha); the exact upper-tail probability is returned. Tests on
+    spatially or temporally correlated series are not independent, so this p-value
+    is too small for them; in that case use a permutation or Monte Carlo reference
+    distribution and treat this result as a lower bound.
+    """
+    p = _clean(pvalues)
+    m = len(p)
+    if m == 0:
+        return {"error": "No valid p-values."}
+    if not 0 < alpha < 1:
+        return {"error": "alpha must be between 0 and 1."}
+    k = sum(1 for v in p if v <= alpha)
+    la, lb = math.log(alpha), math.log(1.0 - alpha)
+    tail = 0.0
+    for j in range(k, m + 1):
+        tail += math.exp(math.lgamma(m + 1) - math.lgamma(j + 1) - math.lgamma(m - j + 1) + j * la + (m - j) * lb)
+    return {"n_tests": m, "n_significant": k, "expected_by_chance": m * alpha, "share_significant": k / m,
+            "p_value_independent": min(1.0, tail), "alpha": alpha}
+
+
+# -------------------------------------------------------------------------- 11
+def _two_way_demean(vals: List[float], unit: List[int], time: List[int], n_u: int, n_t: int,
+                    max_iter: int = 2000, tol: float = 1e-10) -> List[float]:
+    x = list(vals)
+    cu = [0] * n_u
+    ct = [0] * n_t
+    for u, t in zip(unit, time):
+        cu[u] += 1; ct[t] += 1
+    for _ in range(max_iter):
+        su = [0.0] * n_u
+        for v, u in zip(x, unit):
+            su[u] += v
+        mu = [s / c if c else 0.0 for s, c in zip(su, cu)]
+        x = [v - mu[u] for v, u in zip(x, unit)]
+        st = [0.0] * n_t
+        for v, t in zip(x, time):
+            st[t] += v
+        mt = [s / c if c else 0.0 for s, c in zip(st, ct)]
+        x = [v - mt[t] for v, t in zip(x, time)]
+        if max(max(abs(m) for m in mu), max(abs(m) for m in mt)) < tol:
+            break
+    return x
+
+
+def local_projection_event(
+    outcome: Mapping[str, Sequence[Any]],
+    event: Mapping[str, Sequence[Any]],
+    horizons: Sequence[int] = (0, 1, 2, 3, 4, 5),
+    leads: Sequence[int] = (),
+) -> Dict[str, Any]:
+    """
+    Event-study local projections (Jordà, 2005) in a panel with unit and time fixed
+    effects, for example the response of log reef-fish catch to a mass-bleaching year.
+
+    ``outcome`` and ``event`` map a unit (for example a country) to values on a common
+    time index; ``event`` is 0/1 (or an intensity). For each horizon h the regression is
+        y[i, t+h] - y[i, t-1] = beta_h * event[i, t] + unit effect + time effect + error,
+    estimated by ordinary least squares after two-way demeaning. Standard errors are
+    clustered by unit (with the G / (G - 1) correction). ``leads`` (for example
+    ``(2, 3)``) adds placebo regressions of y[i, t-1-k] - y[i, t-1] on the event, which
+    should be close to zero if units with and without an event followed similar paths
+    beforehand.
+
+    The estimate is a conditional association. It has a causal reading only if the
+    timing of events is unrelated to other shocks to the outcome; with repeated events
+    the windows of successive events overlap.
+    """
+    units = [u for u in outcome.keys() if u in event]
+    if len(units) < 5:
+        return {"error": "At least 5 units present in both outcome and event are required.", "n_units": len(units)}
+
+    def run(shift_fn) -> Optional[Dict[str, Any]]:
+        dep: List[float] = []; x: List[float] = []; ui: List[int] = []; ti: List[int] = []
+        tmap: Dict[int, int] = {}
+        umap: Dict[Any, int] = {}
+        for u in units:
+            y = list(outcome[u]); e = list(event[u])
+            T = min(len(y), len(e))
+            for t in range(1, T):
+                target = shift_fn(t)
+                if target < 0 or target >= T:
+                    continue
+                if not (_is_num(y[target]) and _is_num(y[t - 1]) and _is_num(e[t])):
+                    continue
+                dep.append(float(y[target]) - float(y[t - 1])); x.append(float(e[t]))
+                ui.append(umap.setdefault(u, len(umap))); ti.append(tmap.setdefault(t, len(tmap)))
+        n = len(dep)
+        g = len(umap)
+        if n < 30 or g < 5:
+            return None
+        yd = _two_way_demean(dep, ui, ti, g, len(tmap))
+        xd = _two_way_demean(x, ui, ti, g, len(tmap))
+        sxx = sum(v * v for v in xd)
+        if sxx <= 1e-12:
+            return None
+        beta = sum(a * b for a, b in zip(xd, yd)) / sxx
+        score = [0.0] * g
+        for a, b, u in zip(xd, yd, ui):
+            score[u] += a * (b - beta * a)
+        var = sum(s * s for s in score) / (sxx * sxx) * g / (g - 1)
+        se = math.sqrt(var)
+        t_stat = beta / se if se > 0 else float("nan")
+        return {"beta": beta, "se": se, "t": t_stat, "p_value": 2.0 * _normal_sf(abs(t_stat)) if se > 0 else None,
+                "ci95_low": beta - 1.96 * se, "ci95_high": beta + 1.96 * se, "n_obs": n, "n_units": g,
+                "n_events": sum(1 for v in x if v != 0)}
+
+    res: Dict[str, Any] = {"horizons": {}, "placebo_leads": {}, "n_units_input": len(units)}
+    for h in horizons:
+        r = run(lambda t, h=h: t + int(h))
+        res["horizons"][int(h)] = r if r is not None else {"error": "Too few observations or no variation in the event."}
+    for k in leads:
+        r = run(lambda t, k=k: t - 1 - int(k))
+        res["placebo_leads"][int(k)] = r if r is not None else {"error": "Too few observations or no variation in the event."}
+    return res