biplotpy 0.4.0__py3-none-any.whl

biplotpy/distances.py

@@ -0,0 +1,383 @@
+"""Distance-based biplots: proximities, principal coordinates (PCoA),
+metric/non-metric MDS by SMACOF, external logistic biplots and canonical
+analysis of distances.
+
+* ``binary_distances`` / ``continuous_distances`` / ``gower_distances`` —
+  the coefficients of ``MultBiplotR::BinaryDistances`` and
+  ``ContinuousDistances`` (with three defects of the R code corrected, see
+  ``FIXES``).
+* ``pcoa`` — ``MultBiplotR::PrincipalCoordinates`` (= ``ade4::dudi.pco``).
+* ``mds`` — symmetric SMACOF of ``smacof::mds`` (ratio, interval, ordinal
+  with primary/secondary/tertiary ties).
+* ``ridge_logistic`` / ``external_logistic_biplot`` —
+  ``MultBiplotR::RidgeBinaryLogistic`` and ``ExternalBinaryLogisticBiplot``:
+  binary variables projected onto a PCoA/MDS configuration by penalized
+  logistic regression.
+* ``canonical_distance_analysis`` — ``MultBiplotR::CanonicalDistanceAnalysis``.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from scipy import stats as sps
+
+from .correspondence import OrdinationBiplot
+
+BINARY_COEFFICIENTS = ["Kulczynski", "Russell_and_Rao", "Jaccard", "Simple_Matching", "Anderberg",
+                       "Rogers_and_Tanimoto", "Sorensen_Dice_and_Czekanowski", "Sneath_and_Sokal", "Hamman",
+                       "Kulczynski2", "Anderberg2", "Ochiai", "S13", "Pearson_phi", "Yule", "Sorensen", "Dice"]
+TRANSFORMATIONS = ["Identity", "1-S", "sqrt(1-S)", "-log(s)", "1/S-1", "sqrt(2(1-S))", "1-(S+1)/2", "1-abs(S)",
+                   "1/(S+1)"]
+
+
+def binary_similarity(X, Y=None, coefficient="Jaccard"):
+    X = np.asarray(X, float)
+    Y = X if Y is None else np.asarray(Y, float)
+    a = Y @ X.T; b = Y @ (1 - X).T; c = (1 - Y) @ X.T; d = (1 - Y) @ (1 - X).T
+    with np.errstate(divide="ignore", invalid="ignore"):
+        S = {"Kulczynski": a / (b + c), "Russell_and_Rao": a / (a + b + c + d), "Jaccard": a / (a + b + c),
+             "Simple_Matching": (a + d) / (a + b + c + d), "Anderberg": a / (a + 2 * (b + c)),
+             "Rogers_and_Tanimoto": (a + d) / (a + 2 * (b + c) + d),
+             "Sorensen_Dice_and_Czekanowski": a / (a + 0.5 * (b + c)),
+             "Sneath_and_Sokal": (a + d) / (a + 0.5 * (b + c) + d), "Hamman": (a - (b + c) + d) / (a + b + c + d),
+             "Kulczynski2": 0.5 * (a / (a + b) + a / (a + c)),
+             "Anderberg2": 0.25 * (a / (a + b) + a / (a + c) + d / (c + d) + d / (b + d)),
+             "Ochiai": a / np.sqrt((a + b) * (a + c)), "S13": a * d / np.sqrt((a + b) * (a + c) * (d + b) * (d + c)),
+             "Pearson_phi": (a * d - b * c) / np.sqrt((a + b) * (a + c) * (d + b) * (d + c)),
+             "Yule": (a * d - b * c) / (a * d + b * c), "Sorensen": 2 * a / (2 * a + b + c),
+             "Dice": 2 * a / (2 * a + b + c)}[coefficient]
+    return S
+
+
+def _transform_similarity(S, transformation):
+    f = {"Identity": lambda: S, "1-S": lambda: 1 - S, "sqrt(1-S)": lambda: np.sqrt(np.maximum(1 - S, 0)),
+         "-log(s)": lambda: -np.log(S), "1/S-1": lambda: 1 / S - 1,
+         "sqrt(2(1-S))": lambda: np.sqrt(np.maximum(2 * (1 - S), 0)), "1-(S+1)/2": lambda: 1 - (S + 1) / 2,
+         "1-abs(S)": lambda: 1 - np.abs(S), "1/(S+1)": lambda: 1 / (S + 1)}
+    with np.errstate(divide="ignore", invalid="ignore"):
+        return f[transformation]()
+
+
+def binary_distances(X, Y=None, coefficient="Jaccard", transformation=None):
+    """Dissimilarities between the rows of a 0/1 matrix (``Y`` rows against
+    ``X`` rows when given). Default transformation as MultBiplotR:
+    sqrt(1-S) for most coefficients, 1-(S+1)/2 for Hamman, phi and Yule,
+    1/(S+1) for Kulczynski."""
+    if isinstance(coefficient, int):
+        coefficient = BINARY_COEFFICIENTS[coefficient - 1]
+    if transformation is None:
+        transformation = {"Kulczynski": "1/(S+1)", "Hamman": "1-(S+1)/2", "Pearson_phi": "1-(S+1)/2",
+                          "Yule": "1-(S+1)/2"}.get(coefficient, "sqrt(1-S)")
+    return _transform_similarity(binary_similarity(X, Y, coefficient), transformation)
+
+
+def continuous_distances(X, Y=None, coef="Pythagorean", r=1.0):
+    """Dissimilarities between rows (``MultBiplotR::ContinuousDistances``)."""
+    X = np.asarray(X, float)
+    Y = X if Y is None else np.asarray(Y, float)
+    Dif = Y[:, None, :] - X[None, :, :]
+    Sm = Y[:, None, :] + X[None, :, :]
+    with np.errstate(divide="ignore", invalid="ignore"):
+        if coef == "Pythagorean":
+            return np.sqrt((Dif ** 2).sum(2))
+        if coef == "Taxonomic":
+            return np.sqrt((Dif ** 2 / r ** 2).sum(2))
+        if coef == "City":
+            return np.abs(Dif).sum(2)
+        if coef == "Minkowski":
+            return (np.abs(Dif) ** r).sum(2) ** (1 / r)
+        if coef == "Divergence":
+            return np.sqrt((Dif ** 2 / Sm ** 2).sum(2))
+        if coef == "dif_sum":
+            return (np.abs(Dif) / np.abs(Sm)).sum(2)
+        if coef == "Canberra":
+            return (np.abs(Dif) / (np.abs(Y)[:, None, :] + np.abs(X)[None, :, :])).sum(2)
+        if coef == "Bray_Curtis":
+            return np.abs(Dif).sum(2) / Sm.sum(2)
+        if coef == "Soergel":
+            return np.abs(Dif).sum(2) / np.maximum(Y[:, None, :], X[None, :, :]).sum(2)
+        if coef == "Ware_Hedges":
+            return (1 - np.minimum(Y[:, None, :], X[None, :, :]) / np.maximum(Y[:, None, :], X[None, :, :])).sum(2)
+        if coef == "Gower":
+            rng = np.vstack([X, Y]).max(0) - np.vstack([X, Y]).min(0)
+            return (np.abs(Dif) / rng).sum(2)
+    raise ValueError(f"unknown coefficient {coef}")
+
+
+def gower_distances(df: pd.DataFrame):
+    """Gower dissimilarity (1 - similarity) for mixed numeric / categorical data."""
+    n = len(df)
+    S = np.zeros((n, n)); W = np.zeros((n, n))
+    for col in df.columns:
+        v = df[col]
+        ok = v.notna().to_numpy()
+        w = np.outer(ok, ok).astype(float)
+        if pd.api.types.is_numeric_dtype(v) and v.nunique() > 2:
+            x = v.to_numpy(float); rng = np.nanmax(x) - np.nanmin(x)
+            s = 1 - np.abs(x[:, None] - x[None, :]) / rng
+        else:
+            x = v.astype(str).to_numpy()
+            s = (x[:, None] == x[None, :]).astype(float)
+        S += np.nan_to_num(s) * w; W += w
+    return 1 - S / W
+
+
+# --------------------------------------------------------------------------- PCoA
+def pcoa(D, dim=2, weights=None, row_names=None, sup_distances=None) -> OrdinationBiplot:
+    """Principal coordinates of a dissimilarity matrix (Gower, 1966).
+
+    Weighted version with the correct weighted centring (I - 1 w') on both
+    sides. Fit statistics: stress-1 and -2, s-stress, R2 and Spearman's rho
+    between the dissimilarities and the configuration distances."""
+    D = np.asarray(D, float)
+    n = D.shape[0]
+    w = np.full(n, 1 / n) if weights is None else np.asarray(weights, float) / np.sum(weights)
+    J = np.eye(n) - np.outer(np.ones(n), w)
+    b = -0.5 * J @ D ** 2 @ J.T
+    Bw = np.sqrt(w)[:, None] * b * np.sqrt(w)[None, :]
+    ev, U = np.linalg.eigh(Bw)
+    ev, U = ev[::-1], U[:, ::-1]
+    pos = ev > 1e-10 * ev[0]
+    g = U[:, pos] * np.sqrt(ev[pos]) / np.sqrt(w)[:, None]
+    qual = g ** 2 / (g ** 2).sum(1, keepdims=True) * 100
+    G = g[:, :dim]
+    iu = np.triu_indices(n, 1)
+    Dh = D[iu]
+    Dc = np.sqrt(((G[:, None] - G[None]) ** 2).sum(2))[iu]
+    res = OrdinationBiplot(title="Principal Coordinates Analysis", type="PCoA", dim=dim, eigenvalues=ev,
+                           inertia=ev / ev.sum() * 100, row_coordinates=G, row_qualities=qual[:, :dim],
+                           negative_eigenvalues=ev[ev < -1e-10 * ev[0]], centered_products=b,
+                           stress1=np.sqrt(np.sum((Dc - Dh) ** 2) / np.sum(Dc ** 2)),
+                           stress2=np.sqrt(np.sum((Dc - Dh) ** 2) / np.sum((Dc - Dc.mean()) ** 2)),
+                           sstress1=np.sqrt(np.sum((Dc ** 2 - Dh ** 2) ** 2) / np.sum(Dc ** 4)),
+                           rsq=np.corrcoef(Dh, Dc)[0, 1] ** 2, rho=sps.spearmanr(Dh, Dc)[0],
+                           row_names=row_names or [f"I{i + 1}" for i in range(n)], col_coordinates=None)
+    if sup_distances is not None:
+        Ds = np.asarray(sup_distances, float)
+        sc = 0.5 * (np.diag(b)[None, :] - Ds ** 2) @ g / ev[pos]
+        res.sup_row_coordinates = sc[:, :dim]
+    return res
+
+
+# --------------------------------------------------------------------------- SMACOF (symmetric)
+def _pava(y, w):
+    """Weighted isotonic (non-decreasing) regression by pool-adjacent-violators."""
+    vals, wts, cnt = [], [], []
+    for yi, wi in zip(y, w):
+        vals.append(yi); wts.append(wi); cnt.append(1)
+        while len(vals) > 1 and vals[-2] > vals[-1]:
+            ws = wts[-2] + wts[-1]
+            v = (vals[-2] * wts[-2] + vals[-1] * wts[-1]) / ws if ws > 0 else (vals[-2] + vals[-1]) / 2
+            c = cnt[-2] + cnt[-1]
+            vals[-2:] = [v]; wts[-2:] = [ws]; cnt[-2:] = [c]
+    return np.repeat(vals, cnt)
+
+
+def _torgerson(D, p):
+    n = D.shape[0]
+    D2 = D ** 2
+    B = -0.5 * (D2 - D2.mean(1)[:, None] - D2.mean(0)[None, :] + D2.mean())
+    ev, U = np.linalg.eigh(B)
+    ev, U = ev[::-1], U[:, ::-1]
+    return U[:, :p] * np.sqrt(np.maximum(ev[:p], 0))
+
+
+def mds(D, dim=2, type="ratio", ties="primary", weights=None, init=None, itmax=1000, eps=1e-6,
+        row_names=None) -> OrdinationBiplot:
+    """Symmetric SMACOF (``smacof::mds``): metric (ratio, interval) or
+    non-metric (ordinal) multidimensional scaling with Torgerson start.
+    Returns the configuration, disparities, stress-1 and stress per point."""
+    D = np.asarray(D, float)
+    n = D.shape[0]
+    iu = np.triu_indices(n, 1)
+    diss = D.T[np.tril_indices(n, -1)]                       # column-major lower triangle, as R's dist
+    li, lj = np.tril_indices(n, -1)
+    order_idx = np.lexsort((li, lj))                        # R stores dist by columns
+    li, lj, diss = li[order_idx], lj[order_idx], D[li[order_idx], lj[order_idx]]
+    m = len(diss)
+    W = np.ones((n, n)) if weights is None else np.asarray(weights, float)
+    wg = W[li, lj]
+    nn = n * (n - 1) / 2
+
+    def dist(x):
+        return np.sqrt(((x[li] - x[lj]) ** 2).sum(1))
+
+    def normq(v):
+        return v * np.sqrt(nn / np.sum(wg * v ** 2))
+
+    x = _torgerson(D, dim) if init is None else np.asarray(init, float)
+    dhat = normq(diss)
+    V = -np.zeros((n, n)); V[li, lj] = -wg; V[lj, li] = -wg
+    V[np.diag_indices(n)] = -V.sum(1)
+    Vinv = np.linalg.inv(V + 1 / n) - 1 / n
+    d = dist(x)
+    lb = np.sum(wg * d * dhat) / np.sum(wg * d ** 2)
+    x, d = lb * x, lb * d
+    sold = np.sum(wg * (dhat - d) ** 2) / nn
+    # tie structure of the dissimilarities
+    iord = np.lexsort((np.arange(m), diss))
+    xs = diss[iord]
+    starts = np.r_[0, np.where(np.diff(xs) != 0)[0] + 1]
+    blocks = np.split(iord, starts[1:])
+    xu = xs[starts]
+    itel = 1
+    while True:
+        z = d < 1e-12
+        bv = wg * dhat * (~z) / (d + z)
+        Bm = np.zeros((n, n)); Bm[li, lj] = -bv; Bm[lj, li] = -bv
+        Bm[np.diag_indices(n)] = -Bm.sum(1)
+        y = Vinv @ (Bm @ x)
+        e = dist(y)
+        if type == "ratio":
+            new = diss.copy()
+        elif type == "interval":
+            yb = np.array([np.sum(wg[b] * e[b]) / np.sum(wg[b]) for b in blocks])
+            wb = np.array([np.sum(wg[b]) for b in blocks])
+            Xb = np.column_stack([np.ones(len(xu)), xu - xu[0]])
+            coef = np.linalg.solve(Xb.T @ (wb[:, None] * Xb), Xb.T @ (wb * yb))
+            fitb = Xb @ coef
+            new = np.empty(m)
+            for b, v in zip(blocks, fitb):
+                new[b] = v
+        elif type == "ordinal" and ties == "primary":
+            o = np.lexsort((e, diss))
+            new = np.empty(m); new[o] = _pava(e[o], wg[o])
+        elif type == "ordinal":
+            yb = np.array([np.sum(wg[b] * e[b]) / np.sum(wg[b]) for b in blocks])
+            wb = np.array([np.sum(wg[b]) for b in blocks])
+            ycon = _pava(yb, wb)
+            new = np.empty(m)
+            for b, v, ym in zip(blocks, ycon, yb):
+                new[b] = v if ties == "secondary" else e[b] + (v - ym)
+        else:
+            raise ValueError("type must be ratio, interval or ordinal")
+        dhat = normq(new)
+        snon = np.sum(wg * (dhat - e) ** 2) / nn
+        if (sold - snon) < eps or itel == itmax:
+            break
+        x, d, sold = y, e, snon
+        itel += 1
+    Dh = np.zeros((n, n)); Dh[li, lj] = dhat; Dh = Dh + Dh.T
+    Dc = np.sqrt(((y[:, None] - y[None]) ** 2).sum(2))
+    res_mat = W * (Dh - Dc) ** 2
+    np.fill_diagonal(res_mat, np.nan)
+    spp = np.nanmean(res_mat, 0); spp = spp / spp.sum() * 100
+    return OrdinationBiplot(title=f"MDS ({type})", type="MDS", dim=dim, row_coordinates=y, stress=np.sqrt(snon),
+                            disparities=Dh, config_distances=Dc, spp=spp, niter=itel,
+                            eigenvalues=np.var(y, axis=0) * n, inertia=np.var(y, axis=0) / np.var(y, axis=0).sum() * 100,
+                            row_names=row_names or [f"I{i + 1}" for i in range(n)], col_coordinates=None)
+
+
+# --------------------------------------------------------------------------- logistic regression on a configuration
+def ridge_logistic(y, X, penalization=0.2, intercept=True, tol=1e-5, maxiter=100):
+    """Ridge-penalized binary logistic regression by Newton-Raphson
+    (``MultBiplotR::RidgeBinaryLogistic``): maximizes loglik - lambda * sum(beta_j^2),
+    intercept not penalized. Returns coefficients and fit statistics."""
+    y = np.asarray(y, float).ravel()
+    X = np.asarray(X, float)
+    if X.ndim == 1:
+        X = X[:, None]
+    n = len(y)
+    Xd = np.column_stack([np.ones(n), X]) if intercept else X
+
+    def fit(Xm):
+        m = Xm.shape[1]
+        beta = np.zeros(m)
+        Im = np.eye(m); Im[0, 0] = 0
+        for _ in range(maxiter):
+            mu = 1 / (1 + np.exp(-(Xm @ beta)))
+            In = Xm.T @ ((mu * (1 - mu))[:, None] * Xm) + 2 * penalization * Im
+            U = Xm.T @ (y - mu) - 2 * penalization * Im @ beta
+            new = beta + np.linalg.pinv(In) @ U
+            err = np.sum(np.abs(new - beta)); beta = new
+            if err <= tol:
+                break
+        return beta
+    b0 = fit(np.ones((n, 1)))
+    beta = fit(Xd)
+    p0 = 1 / (1 + np.exp(-b0[0])); p = 1 / (1 + np.exp(-(Xd @ beta)))
+    dev0 = -2 * np.sum(y * np.log(p0) + (1 - y) * np.log(1 - p0))
+    dev = -2 * np.sum(y * np.log(p) + (1 - y) * np.log(1 - p))
+    dif = dev0 - dev; df = Xd.shape[1] - 1
+    cs = 1 - np.exp(-dif / n)
+    pred = (p >= 0.5).astype(float)
+    return {"beta": beta, "fitted": p, "deviance": dev, "null_deviance": dev0, "dif": dif, "df": df,
+            "p": sps.chi2.sf(dif, df), "cox_snell": cs, "nagelkerke": cs / (1 - np.exp(-dev0 / 2) ** (2 / n)),
+            "mcfadden": 1 - dev / dev0, "R2": 1 - np.sum((y - p) ** 2) / np.sum(y ** 2),
+            "percent_correct": np.mean(pred == y)}
+
+
+def external_logistic_biplot(coords, Xbin, penalization=0.2, col_names=None, row_names=None) -> OrdinationBiplot:
+    """External binary logistic biplot: each binary variable is fitted by a
+    ridge logistic regression on a given configuration (PCoA, MDS...), giving
+    its direction in the plane (``MultBiplotR::ExternalBinaryLogisticBiplot``)."""
+    A = np.asarray(coords, float)
+    Xb = np.asarray(Xbin, float)
+    p = Xb.shape[1]
+    fits = [ridge_logistic(Xb[:, j], A, penalization) for j in range(p)]
+    B = np.array([f["beta"] for f in fits])
+    dd = np.sqrt(1 + (B[:, 1:] ** 2).sum(1))
+    info = pd.DataFrame({"Deviance": [f["dif"] for f in fits], "df": [f["df"] for f in fits],
+                         "p-value": [f["p"] for f in fits],
+                         "Bonferroni": np.minimum([f["p"] * p for f in fits], 1),
+                         "Nagelkerke": [f["nagelkerke"] for f in fits], "R2": [f["R2"] for f in fits],
+                         "% correct": [f["percent_correct"] * 100 for f in fits]},
+                        index=col_names or [f"V{j + 1}" for j in range(p)])
+    return OrdinationBiplot(title="External Binary Logistic Biplot", type="ExternalLogistic", dim=A.shape[1],
+                            row_coordinates=A, col_parameters=B, col_coordinates=B[:, 1:], loadings=B[:, 1:] / dd[:, None],
+                            var_info=info, total_percent=np.mean([f["percent_correct"] for f in fits]) * 100,
+                            eigenvalues=np.var(A, axis=0), inertia=np.var(A, axis=0) / np.var(A, axis=0).sum() * 100,
+                            row_names=row_names or [f"I{i + 1}" for i in range(A.shape[0])],
+                            col_names=list(info.index), data=Xb)
+
+
+# --------------------------------------------------------------------------- canonical analysis of distances
+def canonical_distance_analysis(D, groups, dim=2, nperm=999, weighted=False, X=None, seed=None) -> OrdinationBiplot:
+    """Canonical analysis of distances (Gower & Krzanowski, 1999; port of
+    ``MultBiplotR::CanonicalDistanceAnalysis``): pseudo-F (distance-based
+    ANOVA) with permutation p-value, PCoA of the group means and projection of
+    the individuals (Euclidean distances on ``X``, Gower's add-a-point formula)."""
+    D = np.asarray(D, float)
+    g = np.asarray([str(v) for v in groups])
+    levels = list(groups.cat.categories) if hasattr(groups, "cat") else sorted(set(g))
+    levels = [str(v) for v in levels]
+    G = np.column_stack([(g == l).astype(float) for l in levels])
+    ng = G.sum(0); n = len(g); k = len(levels)
+    D2 = 0.5 * D ** 2
+
+    def stats(Dm):
+        Fm = (G.T @ Dm @ G) / np.outer(ng, ng)
+        f = np.diag(Fm)
+        DE = 0.5 * (2 * Fm - f[:, None] - f[None, :])
+        tss = Dm.sum() / n
+        bss = ng @ DE @ ng / n
+        return Fm, tss, bss
+    Fm, tss, bss = stats(D2)
+    wss = tss - bss
+    Fexp = (bss / (k - 1)) / (wss / (n - k))
+    rng = np.random.default_rng(seed)
+    perm = np.empty(nperm)
+    for i in range(nperm):
+        o = rng.permutation(n)
+        _, _, b = stats(D2[np.ix_(o, o)])
+        perm[i] = (b / (k - 1)) / ((tss - b) / (n - k))
+    H = np.eye(k) - (np.outer(np.ones(k), ng) / n if weighted else np.ones((k, k)) / k)
+    B = -H @ Fm @ H.T
+    ev, U = np.linalg.eigh((B + B.T) / 2)
+    ev, U = ev[::-1], U[:, ::-1]
+    Y = U * np.sqrt(np.maximum(ev, 0))
+    d0 = (Y ** 2).sum(1)
+    qual = Y[:, :dim] ** 2 / d0[:, None] * 100
+    res = OrdinationBiplot(title="Canonical Analysis of Distances", type="CDA", dim=dim, F=Fexp, TSS=tss, BSS=bss,
+                           WSS=wss, df=(k - 1, n - k), p_value=float(np.mean(perm > Fexp)), nperm=nperm,
+                           eigenvalues=ev, inertia=ev / ev.sum() * 100, group_coordinates=Y[:, :dim],
+                           group_qualities=qual, group_names=levels, groups=g, row_coordinates=None,
+                           col_coordinates=None)
+    if X is not None:
+        Xm = np.asarray(X, float)
+        means = (G.T @ Xm) / ng[:, None]
+        Di = continuous_distances(means, Xm) ** 2
+        Yd = Y[:, :dim]
+        Yi = -0.5 * np.linalg.solve(Yd.T @ Yd, Yd.T @ H @ (Di - d0[None, :]).T)
+        res.row_coordinates = Yi.T
+    return res

biplotpy/distatis.py

@@ -0,0 +1,69 @@
+"""DISTATIS (Abdi et al., 2005, 2012): STATIS for a set of distance matrices
+on the same objects (port of ``DistatisR::distatis``)."""
+from __future__ import annotations
+
+import numpy as np
+
+
+def _double_center(D):
+    n = D.shape[0]
+    C = np.eye(n) - 1 / n
+    return -0.5 * C @ D @ C
+
+
+def distatis(cube, norm="MFA", distance=True, double_centering=True, rv=True, nfact=3, design=None) -> dict:
+    """``cube``: array n x n x T (or list of T n x n matrices) of distances.
+
+    Returns the RV (or scalar product) matrix C with its eigen-analysis and
+    table factor scores, the weights alpha, the compromise S+ and its factor
+    scores, contributions and squared cosines, and the partial factor scores
+    of every table."""
+    D = np.stack(cube, axis=2) if isinstance(cube, (list, tuple)) else np.asarray(cube, float)
+    if distance and not double_centering:
+        raise ValueError("Distance matrices must be double centered")
+    T = D.shape[2]
+    CP = np.stack([_double_center(D[:, :, t] if distance else -D[:, :, t]) for t in range(T)], 2) \
+        if double_centering else D.copy()
+    for t in range(T):
+        Y = CP[:, :, t]
+        if norm == "MFA":
+            CP[:, :, t] = Y / np.linalg.eigvalsh(Y)[-1]
+        elif norm == "SUMPCA":
+            CP[:, :, t] = Y / np.trace(Y)
+        elif str(norm).upper() == "NUCLEAR":
+            ev = np.linalg.eigvalsh(Y)
+            CP[:, :, t] = Y / np.sum(np.sqrt(ev[ev > 2 * np.finfo(float).eps]))
+    n = CP.shape[0]
+    CP2 = CP.reshape(n * n, T, order="F")
+    C = CP2.T @ CP2
+    if rv:
+        nr = np.sqrt((CP2 ** 2).sum(0))
+        C = C / np.outer(nr, nr)
+    ev, U = np.linalg.eigh(C)
+    ev, U = ev[::-1], U[:, ::-1]
+    U[:, 0] = np.abs(U[:, 0])
+    G = U * np.sqrt(np.abs(ev))
+    if design is None:
+        alpha = U[:, 0] / U[:, 0].sum()
+    else:
+        design = np.asarray(design); levs = np.unique(design); alpha = U[:, 0].copy()
+        for l in levs:
+            m = design == l
+            alpha[m] = alpha[m] / (len(levs) * alpha[m].sum())
+    S = np.tensordot(CP, alpha, axes=([2], [0]))
+    evS, US = np.linalg.eigh(S)
+    evS, US = evS[::-1], US[:, ::-1]
+    sv = np.sqrt(np.abs(evS))
+    F = US * sv
+    F2 = F ** 2
+    d2 = F2.sum(1)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        ctr = F2 / np.abs(evS)
+        cos2 = F2 / d2[:, None]
+        Proj = US / sv
+    Proj = Proj[:, :nfact]
+    partial = np.stack([CP[:, :, t] @ Proj for t in range(T)], 2)
+    return {"C": C, "eig_C": ev, "tau_C": np.round(100 * ev / ev.sum()), "G": G, "alpha": alpha,
+            "cubeSP": CP, "Splus": S, "eig_Splus": evS, "tau_Splus": np.round(100 * evS / evS.sum()),
+            "F": F[:, :nfact], "ctr": ctr[:, :nfact], "cos2": cos2[:, :nfact], "d2": d2,
+            "projection": Proj, "partial_F": partial}

biplotpy/dynamic.py

@@ -0,0 +1,62 @@
+"""Dynamic biplot (Egido & Galindo, 2015).
+
+A reference biplot (HJ by default) is computed on a reference matrix (the mean
+of the occasions or one chosen occasion). The data of every occasion are
+transformed with the statistics of the reference and projected as
+supplementary rows (and, optionally, columns), giving the trajectory of each
+individual and variable in the reference plane.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from .classical import pca_biplot
+
+
+def dynamic_biplot(X, reference="mean", alpha=2, dim=2, scaling=5, names=None, row_names=None,
+                   col_names=None) -> dict:
+    """``X``: list (or dict) of n x p matrices with the same rows and columns.
+
+    Returns the reference biplot, the coordinates of the rows and columns at
+    every occasion, displacement (first to last occasion) and path length of
+    each row, and the quality (%) of the projection of each row at each
+    occasion (squared cosine on the reference plane)."""
+    if isinstance(X, dict):
+        names = names or list(X)
+        X = list(X.values())
+    if isinstance(X[0], pd.DataFrame):
+        row_names = row_names or [str(i) for i in X[0].index]
+        col_names = col_names or [str(c) for c in X[0].columns]
+    X = [np.asarray(x, float) for x in X]
+    T = len(X)
+    names = names or [f"t{i + 1}" for i in range(T)]
+    ref = np.mean(X, axis=0) if reference == "mean" else X[int(reference)]
+    bip = pca_biplot(ref, alpha=alpha, dim=dim, scaling=scaling, row_names=row_names, col_names=col_names)
+    mu, sd = ref.mean(0), ref.std(0, ddof=1)
+    t = bip.transformation
+    if t == "Standardize columns":
+        Z = [(x - mu) / sd for x in X]
+    elif t == "Column centering":
+        Z = [x - mu for x in X]
+    elif t == "Raw Data":
+        Z = X
+    else:
+        raise ValueError("dynamic_biplot supports raw data, column centering and standardized columns")
+    d = bip.d[:dim]
+    U, V = bip.U, bip.V
+    if alpha > 1:
+        rf, cf = np.ones(dim), np.ones(dim)
+    else:
+        rf = (1 / d) ** (1 - alpha) * bip.scale_factor
+        cf = (1 / d) ** alpha / bip.scale_factor
+    rows = [z @ V * rf for z in Z]                   # supplementary rows
+    cols = [z.T @ U * cf for z in Z]                 # supplementary columns
+    qual = np.array([((z @ V) ** 2).sum(1) / np.maximum((z ** 2).sum(1), 1e-300) * 100 for z in Z]).T
+    traj = np.stack(rows, axis=1)                    # n x T x dim
+    disp = np.sqrt(((traj[:, -1] - traj[:, 0]) ** 2).sum(1))
+    path = np.sqrt((np.diff(traj, axis=1) ** 2).sum(2)).sum(1)
+    rn = bip.row_names
+    return {"reference": bip, "row_coordinates": dict(zip(names, rows)), "col_coordinates": dict(zip(names, cols)),
+            "trajectories": traj, "displacement": pd.Series(disp, index=rn), "path_length": pd.Series(path, index=rn),
+            "quality": pd.DataFrame(qual, index=rn, columns=names), "occasions": names}

biplotpy/extras.py

@@ -0,0 +1,158 @@
+"""Bootstrap of the PCA biplot, supplementary variables and calibrated axes."""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from .transforms import initial_transform, transform_name
+from .utils import r_pretty
+
+
+# --------------------------------------------------------------------------- bootstrap
+def pca_bootstrap(X, dim=2, scaling="Standardize columns", B=1000, seed=None, level=0.95) -> dict:
+    """Non-parametric bootstrap of the PCA biplot (port of ``PCA.Bootstrap``).
+
+    Individuals are resampled, the data re-transformed and the SVD recomputed;
+    each axis is reflected to agree in sign with the original solution. Returns
+    the replicated eigenvalues, explained inertia, loadings, structure
+    correlations and qualities of the variables, with percentile and normal
+    ("basic", as in MultBiplotR) intervals for the eigenvalues and percentile
+    intervals for the rest.
+    """
+    rng = np.random.default_rng(seed)
+    X = np.asarray(X, float)
+    n, p = X.shape
+    XT = initial_transform(X, transform_name(scaling))["X"]
+    U0, d0, V0t = np.linalg.svd(XT, full_matrices=False)
+    V0 = V0t.T[:, :dim]
+    k = min(n, p)
+    eig = np.zeros((B, k)); iner = np.zeros((B, k))
+    Vs = np.zeros((B, p, dim)); struct = np.zeros((B, p, dim)); qual = np.zeros((B, p, dim))
+    samples = np.zeros((B, n), dtype=int)
+    for i in range(B):
+        s = rng.integers(n, size=n)
+        samples[i] = s
+        XB = initial_transform(X[s], transform_name(scaling))["X"]
+        U, d, Vt = np.linalg.svd(XB, full_matrices=False)
+        V = Vt.T[:, :dim]
+        signs = np.sign(np.diag(V0.T @ V)); signs[signs == 0] = 1
+        V = V * signs
+        U = U[:, :dim] * signs
+        eig[i, :len(d)] = d[:k]
+        iner[i, :len(d)] = 100 * d[:k] ** 2 / np.sum(d ** 2)
+        Vs[i] = V
+        A = XB @ V
+        struct[i] = np.corrcoef(np.column_stack([XB, A]), rowvar=False)[:p, p:]
+        b = V * d[:dim]
+        qual[i] = np.cumsum(b ** 2 / (XB ** 2).sum(0)[:, None] * 100, axis=1)
+    a = (1 - level) / 2
+    ev2 = eig ** 2
+    med = ev2.mean(0)
+    sdev = ev2.std(0, ddof=1)
+    return {"eigenvalues": eig, "inertia": iner, "loadings": Vs, "structure": struct, "qualities": qual,
+            "samples": samples, "initial_svd": (U0[:, :dim], d0, V0),
+            "mean_eigenvalue": med,
+            "ci_percentile_eigenvalue": np.quantile(ev2, [a, 1 - a], axis=0),
+            "ci_basic_eigenvalue": np.vstack([med - 1.96 * sdev, med + 1.96 * sdev]),
+            "ci_structure": np.quantile(struct, [a, 1 - a], axis=0),
+            "ci_qualities": np.quantile(qual, [a, 1 - a], axis=0),
+            "ci_inertia": np.quantile(iner, [a, 1 - a], axis=0)}
+
+
+# --------------------------------------------------------------------------- supplementary
+def add_continuous_variables(bip, X, dims=None, scaling=5, names=None) -> dict:
+    """Project continuous supplementary variables on a biplot by regressing each
+    (transformed) variable on the row coordinates (port of ``AddContVars2Biplot``).
+
+    Returns intercepts ``b0``, coordinates, R2 (%) and structure correlations."""
+    if isinstance(X, pd.DataFrame):
+        names = names or [str(c) for c in X.columns]
+        X = X.to_numpy(float)
+    X = np.asarray(X, float)
+    if X.ndim == 1:
+        X = X[:, None]
+    n, p = X.shape
+    dims = dims or bip.row_coordinates.shape[1]
+    Xs = initial_transform(X, transform_name(scaling))["X"]
+    A = bip.row_coordinates[:, :dims]
+    DE = np.column_stack([np.ones(n), A])
+    b = np.linalg.solve(DE.T @ DE, DE.T @ Xs).T
+    res = Xs - DE @ b.T
+    R2 = (1 - (res ** 2).sum(0) / (Xs ** 2).sum(0)) * 100
+    structure = np.corrcoef(np.column_stack([Xs, A]), rowvar=False)[:p, p:]
+    names = names or [f"SV{j + 1}" for j in range(p)]
+    return {"b0": b[:, 0], "coordinates": b[:, 1:], "R2": R2, "structure": structure, "names": names,
+            "scaled_data": Xs}
+
+
+def project_rows(bip, X_new):
+    """Coordinates of supplementary individuals (transformed with the statistics
+    of the active data) on a classical biplot."""
+    X_new = np.asarray(X_new, float)
+    t = bip.transformation
+    if t == "Standardize columns":
+        Z = (X_new - bip.means) / bip.deviations
+    elif t == "Column centering":
+        Z = X_new - bip.means
+    elif t == "Substract the global mean":
+        Z = X_new - bip.gmean
+    elif t == "Raw Data":
+        Z = X_new
+    else:
+        raise ValueError(f"Supplementary rows are not defined for '{t}'")
+    a = Z @ bip.V
+    d = bip.d[:bip.dim]
+    if bip.alpha <= 1:
+        a = a * (1 / d) ** (1 - bip.alpha) * bip.scale_factor
+    return a  # HJ-Biplot: principal coordinates X V = U D
+
+
+# --------------------------------------------------------------------------- calibrated axes
+def biplot_scales(bip, nticks=3, type_scale="Complete", values_scale="Original") -> dict:
+    """Ticks (on the transformed scale) and labels (on the original or transformed
+    scale) of the calibrated axis of every variable (port of ``GetBiplotScales``
+    for raw data, global-mean, column-centred and standardized data)."""
+    ticks, labels = [], []
+    t = bip.transformation
+    for j in range(bip.p):
+        mn, mx, mean, sd = bip.minima[j], bip.maxima[j], bip.means[j], bip.deviations[j]
+        if t in ("Raw Data", "Substract the global mean"):
+            lab = r_pretty([mn, mx], nticks)
+            tk = lab - (bip.gmean if t == "Substract the global mean" else 0)
+        elif t == "Column centering":
+            if type_scale == "Complete":
+                if values_scale == "Original":
+                    lab = r_pretty([mn, mx], nticks); tk = lab - mean
+                else:
+                    tk = r_pretty([mn - mean, mx - mean], nticks); lab = np.round(tk, 2)
+            elif type_scale == "StdDev":
+                k = np.array([-3, -2, -1, 1, 2, 3])
+                tk = np.round(k * sd, 2); lab = np.round(mean + k * sd, 2) if values_scale == "Original" else tk
+            else:
+                q = np.array([mn, bip.p25[j], bip.medians[j], bip.p75[j], mx])
+                tk = q - mean; lab = q if values_scale == "Original" else np.round(tk, 2)
+        elif t == "Standardize columns":
+            if type_scale == "Complete":
+                if values_scale == "Original":
+                    lab = r_pretty([mn, mx], nticks); tk = (lab - mean) / sd
+                else:
+                    tk = np.array([-3, -2.5, -2, -1.5, -1, -0.5, 0.5, 1, 1.5, 2, 2.5, 3]); lab = np.round(tk, 2)
+            elif type_scale == "StdDev":
+                tk = np.array([-3., -2, -1, 1, 2, 3])
+                lab = np.round(tk * sd + mean, 1) if values_scale == "Original" else np.round(tk, 2)
+            else:
+                q = np.array([mn, bip.p25[j], bip.medians[j], bip.p75[j], mx])
+                tk = (q - mean) / sd; lab = q if values_scale == "Original" else np.round(tk, 2)
+        else:
+            col = bip.scaled_data[:, j]
+            lab = r_pretty([col.min(), col.max()], nticks); tk = lab
+        ticks.append(np.asarray(tk, float)); labels.append(np.asarray(lab, float))
+    return {"ticks": ticks, "labels": labels}
+
+
+def calibrated_axis(b, ticks):
+    """Positions of the ticks of a calibrated (predictive) axis with direction
+    ``b`` (column marker): the point of the axis whose projection predicts the
+    value ``t`` is ``t * b / |b|^2``."""
+    b = np.asarray(b, float)
+    return np.outer(np.asarray(ticks, float), b / (b @ b))