canbiplotme 0.3.0__py3-none-any.whl

canbiplotme/__init__.py

@@ -0,0 +1,34 @@
+"""canbiplotme: canonical biplot for grouped estimates measured with error.
+
+Python port of the R package ``gcbiplot`` (Gravity Canonical Biplot;
+formerly ``canbiplotME``), Freire-Cadme (2026). The ``gcb*`` names are aliases
+of the ``cbme*`` ones and match the R functions.
+"""
+from .data import (MEData, me_data, deviation_matrix, replicate_array, select_components, subset_individuals,
+                   error_correlation)
+from .stage2 import CBMEFit, cbme
+from .inference import simulate_coefs, cbme_test, boot_pvalue, cbme_influence, procrustes_align, holm, cbme_permutation_test
+from .regions import cbme_regions, choose_region
+from .simulation import cbme_simulate_tests, cbme_coverage
+from .stage1 import (gravity_by_individual, pairs_bootstrap, support_counts, identify_d6, as_me_data,
+                     refit_on_pairs)
+from .dynamic import gravity_dynamic, dynamic_test, cbme_trajectory
+from .reml import cbme_reml
+from .meta import mvmeta
+from .datasets import load_sim_me, load_sim_trade, load_gcb_trade, load_gcb_trade_a21
+from .rng import RRNG
+
+# names of the R package gcbiplot
+gcb_data = me_data
+gcb = cbme
+gcb_test = cbme_test
+gcb_influence = cbme_influence
+gcb_regions = cbme_regions
+
+__version__ = "0.3.0"
+__all__ = ["MEData", "me_data", "deviation_matrix", "CBMEFit", "cbme", "simulate_coefs", "cbme_test",
+           "cbme_influence", "procrustes_align", "holm", "cbme_permutation_test", "cbme_regions", "choose_region",
+           "cbme_simulate_tests", "cbme_coverage", "gravity_by_individual", "pairs_bootstrap",
+           "support_counts", "identify_d6", "as_me_data", "refit_on_pairs", "gravity_dynamic",
+           "dynamic_test", "cbme_trajectory", "cbme_reml", "mvmeta", "load_sim_me", "load_sim_trade", "load_gcb_trade", "load_gcb_trade_a21", "RRNG", "boot_pvalue", "replicate_array",
+           "select_components", "subset_individuals", "error_correlation", "gcb_data", "gcb", "gcb_test", "gcb_influence", "gcb_regions"]

canbiplotme/data.py

@@ -0,0 +1,304 @@
+"""Input data: grouped estimates measured with error (port of ``me_data``)."""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+class MEData:
+    """Grouped estimates measured with error.
+
+    Parameters
+    ----------
+    beta : array-like (N, K)
+        Estimated coefficients; ``NaN`` marks a component that is not
+        identified for that individual (decision D3).
+    V : array-like (N, K, K) or list of (K, K), optional
+        Measurement-error covariance of each individual. Derived from the
+        replicates when omitted.
+    group : array-like (N,)
+        Group of each individual.
+    replicates : dict, optional
+        ``{group: array (R, n_g, K)}`` bootstrap replicates of the individuals of
+        each group (in the order in which they appear in ``beta``). They give
+        the joint error covariance of the group.
+    Omega : dict, optional
+        ``{group: array (n_g K, n_g K)}`` joint error covariance, ordered
+        individual-major. Ignored when ``replicates`` or ``D`` is given.
+    D : dict, optional
+        ``{group: array (R, n_g K)}`` matrices of replicate deviations (already
+        built); alternative to ``replicates``.
+    id : sequence of str, optional
+        Labels of the individuals.
+    components : sequence of str, optional
+        Names of the components.
+    levels : sequence, optional
+        Order of the groups (default: categorical order or sorted unique values).
+    error_blocks : array-like (N,), optional
+        Blocks of individuals whose errors are correlated, when they are not
+        the groups (e.g. one block when the first stage uses fixed effects
+        common to all individuals). ``replicates``, ``D`` and ``Omega`` are then
+        keyed by block, and pairwise comparisons include the covariance between
+        the means of groups of the same block.
+    """
+
+    def __init__(self, beta, V=None, group=None, replicates=None, Omega=None, D=None,
+                 id=None, components=None, levels=None, error_blocks=None):
+        if isinstance(beta, pd.DataFrame):
+            if components is None:
+                components = list(beta.columns)
+            if id is None:
+                id = [str(i) for i in beta.index]
+            beta = beta.to_numpy()
+        beta = np.array(beta, dtype=float)
+        if beta.ndim == 1:
+            beta = beta[:, None]
+        N, K = beta.shape
+        self.components = list(components) if components is not None else [f"z{k + 1}" for k in range(K)]
+        self.id = list(id) if id is not None else [f"i{i + 1}" for i in range(N)]
+        if group is None:
+            raise ValueError("`group` is required.")
+        if levels is not None:
+            levs = [str(v) for v in levels]
+        elif isinstance(group, (pd.Categorical, pd.Series)) and isinstance(getattr(group, "dtype", None), pd.CategoricalDtype):
+            cat = pd.Categorical(group).remove_unused_categories()
+            levs = [str(v) for v in cat.categories]
+        else:
+            levs = sorted({str(v) for v in np.asarray(group, dtype=object)})
+        self.levels = levs
+        self.group = np.array([str(v) for v in np.asarray(group, dtype=object)], dtype=object)
+        if not set(self.group) <= set(levs):
+            raise ValueError("Some groups are not in `levels`.")
+        if len(self.group) != N:
+            raise ValueError("`group` must have one element per row of `beta`.")
+        self.N, self.K, self.G = N, K, len(self.levels)
+        self.block = None
+        if error_blocks is not None:
+            self.block = np.array([str(v) for v in np.asarray(error_blocks, dtype=object)], dtype=object)
+            if len(self.block) != N:
+                raise ValueError("`error_blocks` must have one element per row of `beta`.")
+            for lev in self.levels:
+                if len(set(self.block[self.group == lev])) > 1:
+                    raise ValueError("Each group must lie in a single error block.")
+        self.D = None
+        self.Omega = None
+        if replicates is not None:
+            self.D = {}
+            for lev in self.block_levels:
+                r = np.asarray(replicates[lev], dtype=float)
+                idx = np.where(self.block_of == lev)[0]
+                if r.ndim != 3 or r.shape[1] != len(idx) or r.shape[2] != K:
+                    raise ValueError(f"replicates[{lev!r}] must be an array (R, n_g, K).")
+                self.D[lev] = deviation_matrix(r, beta[idx])
+        elif D is not None:
+            self.D = {lev: np.asarray(D[lev], dtype=float) for lev in self.block_levels}
+        elif Omega is not None:
+            self.Omega = {lev: np.asarray(Omega[lev], dtype=float) for lev in self.block_levels}
+        if V is None:
+            if self.D is not None:
+                V = _V_from_blocks(lambda lev: self.D[lev].T @ self.D[lev] / (self.D[lev].shape[0] - 1), self)
+            elif self.Omega is not None:
+                V = _V_from_blocks(lambda lev: self.Omega[lev], self)
+            else:
+                raise ValueError("Provide `V`, `replicates`, `D` or `Omega`.")
+        V = np.array(V, dtype=float)
+        if V.shape != (N, K, K):
+            raise ValueError("`V` must have shape (N, K, K).")
+        self.V = V
+        vd = np.einsum("ikk->ik", V)
+        ok = np.isfinite(beta) & np.isfinite(vd) & (vd > 0)
+        beta = beta.copy()
+        beta[~ok] = np.nan
+        self.beta = beta
+        if np.any(pd.Series(self.group).value_counts() < 2):
+            import warnings
+            warnings.warn("Some groups have fewer than two individuals.")
+
+    # ------------------------------------------------------------------
+    @property
+    def has_joint(self) -> bool:
+        return self.D is not None or self.Omega is not None
+
+    @property
+    def block_of(self) -> np.ndarray:
+        """Error block of each individual (the group unless ``error_blocks`` was given)."""
+        return self.group if self.block is None else self.block
+
+    @property
+    def block_levels(self) -> list:
+        if self.block is None:
+            return list(self.levels)
+        return sorted(set(self.block.tolist()))      # as R's factor(): sorted levels
+
+    def block_omega(self, b):
+        """Joint error covariance of an error block."""
+        if self.D is not None:
+            D = self.D[b]
+            return D.T @ D / (D.shape[0] - 1)
+        return self.Omega[b]
+
+    def group_omega(self, lev):
+        """Joint error covariance of a group (n_g K x n_g K)."""
+        if self.block is not None and self.has_joint:
+            b = self.block[self.group == lev][0]
+            inb = np.where(self.block == b)[0]
+            pos = np.searchsorted(inb, np.where(self.group == lev)[0])
+            cols = (pos[:, None] * self.K + np.arange(self.K)[None, :]).ravel()
+            return self.block_omega(b)[np.ix_(cols, cols)]
+        if self.D is not None:
+            D = self.D[lev]
+            return D.T @ D / (D.shape[0] - 1)
+        if self.Omega is not None:
+            return self.Omega[lev]
+        idx = np.where(self.group == lev)[0]
+        K = self.K
+        O = np.zeros((len(idx) * K, len(idx) * K))
+        for j, i in enumerate(idx):
+            v = np.nan_to_num(self.V[i], nan=0.0, posinf=0.0, neginf=0.0)
+            O[j * K:(j + 1) * K, j * K:(j + 1) * K] = v
+        return O
+
+    def identified_table(self) -> pd.DataFrame:
+        rows = []
+        for lev in self.levels:
+            b = self.beta[self.group == lev]
+            rows.append([b.shape[0]] + list(np.isfinite(b).sum(axis=0)))
+        return pd.DataFrame(rows, index=self.levels, columns=["n"] + self.components)
+
+    def __repr__(self) -> str:
+        err = ("joint (bootstrap replicates)" if self.D is not None else
+               "joint (Omega)" if self.Omega is not None else "independent")
+        return (f"<MEData> {self.N} individuals, {self.K} components, {self.G} groups\n"
+                f"Identified components per group:\n{self.identified_table()}\n"
+                f"Error correlation within groups: {err}")
+
+
+def me_data(*args, **kwargs) -> MEData:
+    """Functional alias of :class:`MEData` (same name as in R)."""
+    return MEData(*args, **kwargs)
+
+
+def deviation_matrix(r: np.ndarray, beta_g: np.ndarray) -> np.ndarray:
+    """Deviation matrix D_g (R x n_g K), individual-major columns.
+
+    Failed replicates (every coefficient missing) are dropped and R is the
+    number of valid replicates, as in the thesis (``omega_regimen``). Missing
+    coefficients of a replicate are set to zero after centring and the column
+    is rescaled by sqrt(R / R_valid), which keeps its variance and makes
+    D'D/(R-1) positive semidefinite.
+    """
+    r = np.asarray(r, float)
+    r = r[np.isfinite(r).reshape(r.shape[0], -1).any(axis=1)]
+    R, n, K = r.shape
+    D = np.zeros((R, n * K))
+    for i in range(n):
+        for k in range(K):
+            x = r[:, i, k]
+            ok = np.isfinite(x)
+            if not np.isfinite(beta_g[i, k]) or not ok.any():
+                continue
+            d = x - x[ok].mean()
+            d[~ok] = 0.0
+            D[:, i * K + k] = d * np.sqrt(R / ok.sum())
+    return D
+
+
+def replicate_array(reps, id, components, name=lambda i, k: f"{i}_{k}") -> np.ndarray:
+    """Arrange replicate coefficient vectors (dicts or pandas Series keyed by
+    coefficient name; ``None`` = failed replicate) into an array (R, n_g, K)."""
+    reps = [r for r in reps if r is not None]
+    out = np.full((len(reps), len(id), len(components)), np.nan)
+    for j, r in enumerate(reps):
+        for a, i in enumerate(id):
+            for b, k in enumerate(components):
+                v = r.get(name(i, k), np.nan) if hasattr(r, "get") else np.nan
+                out[j, a, b] = np.nan if v is None else float(v)
+    return out
+
+
+def select_components(x: "MEData", components) -> "MEData":
+    """Keep some components (with their covariance blocks and replicate
+    deviations) and drop individuals left without identified components."""
+    import copy
+    j = [x.components.index(c) if isinstance(c, str) else int(c) for c in components]
+    K = x.K
+    out = copy.copy(x)
+    out.__dict__ = dict(x.__dict__)
+    out.beta = x.beta[:, j]
+    out.V = x.V[:, j][:, :, j]
+    out.components = [x.components[k] for k in j]
+    out.K = len(j)
+
+    def cols(n):
+        return np.array([i * K + k for i in range(n) for k in j], dtype=int)
+    if x.D is not None:
+        out.D = {lev: D[:, cols(D.shape[1] // K)] for lev, D in x.D.items()}
+    if x.Omega is not None:
+        out.Omega = {lev: O[np.ix_(cols(O.shape[1] // K), cols(O.shape[1] // K))] for lev, O in x.Omega.items()}
+    keep = np.where(np.isfinite(out.beta).any(axis=1))[0]
+    if len(keep) < x.N:
+        out = subset_individuals(out, keep)
+    return out
+
+
+def subset_individuals(x: "MEData", keep) -> "MEData":
+    """Keep some individuals (indices), with the matching replicate columns."""
+    import copy
+    keep = np.sort(np.asarray(keep, int))
+    out = copy.copy(x)
+    out.__dict__ = dict(x.__dict__)
+    K = x.K
+    blk = x.block_of
+    def cols(lev):
+        idx = np.where(blk == lev)[0]
+        pos = [p for p, i in enumerate(idx) if i in set(keep)]
+        return np.array([p * K + k for p in pos for k in range(K)], dtype=int)
+    if x.D is not None:
+        out.D = {lev: x.D[lev][:, cols(lev)] for lev in x.block_levels}
+    if x.Omega is not None:
+        out.Omega = {lev: x.Omega[lev][np.ix_(cols(lev), cols(lev))] for lev in x.block_levels}
+    if x.block is not None:
+        out.block = x.block[keep]
+    out.beta = x.beta[keep]; out.V = x.V[keep]; out.group = x.group[keep]
+    out.id = [x.id[i] for i in keep]; out.N = len(keep)
+    out.levels = [l for l in x.levels if np.any(out.group == l)]; out.G = len(out.levels)
+    if out.D is not None:
+        out.D = {l: out.D[l] for l in out.block_levels}
+    if out.Omega is not None:
+        out.Omega = {l: out.Omega[l] for l in out.block_levels}
+    return out
+
+
+def _V_from_blocks(omega_of, x: MEData) -> np.ndarray:
+    V = np.full((x.N, x.K, x.K), np.nan)
+    for lev in x.block_levels:
+        Om = omega_of(lev)
+        idx = np.where(x.block_of == lev)[0]
+        for j, i in enumerate(idx):
+            V[i] = Om[j * x.K:(j + 1) * x.K, j * x.K:(j + 1) * x.K]
+    return V
+
+
+def error_correlation(x: MEData) -> pd.DataFrame:
+    """Mean correlation of the errors and design effect of the simple mean, by
+    group and component (cells with at least two identified individuals)."""
+    if not x.has_joint:
+        raise ValueError("`x` has no joint error covariance.")
+    K = x.K
+    rows = []
+    for lev in x.levels:
+        O = x.group_omega(lev)
+        idx = np.where(x.group == lev)[0]
+        for k in range(K):
+            j = np.where(np.isfinite(x.beta[idx, k]))[0]
+            m = len(j)
+            if m < 2:
+                continue
+            r = j * K + k
+            Ok = O[np.ix_(r, r)]
+            sd = np.sqrt(np.diag(Ok))
+            C = Ok / np.outer(sd, sd)
+            rows.append({"group": lev, "component": x.components[k], "m": m,
+                         "rho": float(C[np.triu_indices(m, 1)].mean()),
+                         "deff": float((Ok.sum() / m ** 2) / (np.mean(np.diag(Ok)) / m))})
+    return pd.DataFrame(rows)

canbiplotme/datasets/__init__.py

@@ -0,0 +1,56 @@
+"""Example datasets (simulated)."""
+from importlib import resources
+
+import numpy as np
+import pandas as pd
+
+
+def load_sim_me():
+    """Simulated second-stage data: 46 individuals, 4 components, 4 groups,
+    structurally missing components and 99 bootstrap-like replicates per group
+    (same data as ``data(sim_me)`` in the R package)."""
+    from ..data import MEData
+    with resources.files(__package__).joinpath("sim_me.npz").open("rb") as f:
+        z = np.load(f, allow_pickle=False)
+        levels = sorted(set(z["group"].tolist()))
+        D = {g: z[f"D_{g}"] for g in levels}
+        return MEData(z["beta"], z["V"], z["group"].tolist(), D=D, id=z["id"].tolist(),
+                      components=z["components"].tolist())
+
+
+def load_sim_trade() -> pd.DataFrame:
+    """Small simulated gravity panel (18 origins in 3 regimes, 36 destinations, 4 years)."""
+    with resources.files(__package__).joinpath("sim_trade.csv").open("r") as f:
+        return pd.read_csv(f)
+
+
+def load_gcb_trade():
+    """Second-stage data of the thesis (same as ``data(gcb_trade)`` in R).
+
+    Gravity coefficients of 115 exporters in six trade regimes (CEPII Gravity
+    V202211 and BACI flows, 2010-2020): log distance, common official language,
+    colonial link, common religion and WTO trade agreement; bootstrap error
+    covariances, rule D6 already applied (non-identified components are
+    ``NaN``), and the deviation matrices of the 199 pairs-bootstrap replicates
+    of each regime, which give the joint error covariance within regimes.
+    """
+    from ..data import MEData
+    with resources.files(__package__).joinpath("gcb_trade.npz").open("rb") as f:
+        z = np.load(f, allow_pickle=False)
+        levels = z["levels"].tolist()
+        D = {g: z[f"D_{g}"] for g in levels}
+        return MEData(z["beta"], z["V"], z["group"].tolist(), D=D, id=z["id"].tolist(),
+                      components=z["components"].tolist(), levels=levels)
+
+
+def load_gcb_trade_a21():
+    """Analysis 21 of the thesis (same as ``data(gcb_trade_a21)`` in R): first
+    stage with importer-year fixed effects common to the 115 exporters, so the
+    errors are correlated across regimes (one error block with the deviation
+    matrix of the 199 pairs-bootstrap replicates of the whole sample)."""
+    from ..data import MEData
+    with resources.files(__package__).joinpath("gcb_trade_a21.npz").open("rb") as f:
+        z = np.load(f, allow_pickle=False)
+        return MEData(z["beta"], z["V"], z["group"].tolist(), D={"all": z["D_all"]}, id=z["id"].tolist(),
+                      components=z["components"].tolist(), levels=z["levels"].tolist(),
+                      error_blocks=z["block"].tolist())