biplotpy 0.4.0__py3-none-any.whl

biplotpy/rrng.py

@@ -0,0 +1,119 @@
+"""Random numbers identical to those of R.
+
+``RRNG(seed)`` reproduces ``set.seed(seed); rnorm(n)`` of R (Mersenne-Twister
+with R's seed scrambling, normal draws by inversion with
+``qnorm`` of Wichura, algorithm AS 241). With it the procedures of biplotpy that
+start from random numbers (alternating least squares from a random start,
+bootstrap resampling, random starts of BinaryPLSR) give, seed by seed, the
+same results as their R counterparts. About 97% of the normal draws are bitwise equal
+to R's and the rest differ by at most a few units in the last place (rounding
+inside ``qnorm``), which does not change any p-value in practice.
+"""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+_I2_32M1 = 2.328306437080797e-10      # 1 / (2^32 - 1)
+_BIG = 134217728.0                    # 2^27
+
+
+def _r_seed_state(seed: int) -> np.ndarray:
+    s = int(seed) & 0xFFFFFFFF
+    for _ in range(50):
+        s = (69069 * s + 1) & 0xFFFFFFFF
+    st = []
+    for _ in range(625):
+        s = (69069 * s + 1) & 0xFFFFFFFF
+        st.append(s)
+    return np.array(st[1:], dtype=np.uint32)
+
+
+def qnorm_r(p):
+    """R's qnorm(p, 0, 1) (Wichura AS241, nmath/qnorm.c), vectorized."""
+    p = np.asarray(p, float); q = p - 0.5; out = np.empty_like(p)
+    c = np.abs(q) <= 0.425
+    r = 0.180625 - q[c] * q[c]
+    out[c] = q[c] * (((((((r * 2509.0809287301226727 + 33430.575583588128105) * r + 67265.770927008700853) * r
+                + 45921.953931549871457) * r + 13731.693765509461125) * r + 1971.5909503065514427) * r + 133.14166789178437745) * r
+                + 3.387132872796366608) / (((((((r * 5226.495278852545925 + 28729.085735721942674) * r + 39307.89580009271061) * r
+                + 21213.794301586595867) * r + 5394.1960214247511077) * r + 687.1870074920579083) * r + 42.313330701600911252) * r + 1.)
+    nc = ~c
+    pp = np.where(q[nc] < 0, p[nc], 1 - p[nc])
+    r = np.sqrt(-np.array([math.log(v) for v in pp]))
+    v = np.empty_like(r)
+    a = r <= 5.
+    ra = r[a] - 1.6
+    v[a] = (((((((ra * 7.7454501427834140764e-4 + .0227238449892691845833) * ra + .24178072517745061177) * ra
+              + 1.27045825245236838258) * ra + 3.64784832476320460504) * ra + 5.7694972214606914055) * ra + 4.6303378461565452959) * ra
+              + 1.42343711074968357734) / (((((((ra * 1.05075007164441684324e-9 + 5.475938084995344946e-4) * ra + .0151986665636164571966) * ra
+              + .14810397642748007459) * ra + .68976733498510000455) * ra + 1.6763848301838038494) * ra + 2.05319162663775882187) * ra + 1.)
+    b = ~a
+    rb = r[b] - 5.
+    v[b] = (((((((rb * 2.01033439929228813265e-7 + 2.71155556874348757815e-5) * rb + .0012426609473880784386) * rb
+              + .026532189526576123093) * rb + .29656057182850489123) * rb + 1.7848265399172913358) * rb + 5.4637849111641143699) * rb
+              + 6.6579046435011037772) / (((((((rb * 2.04426310338993978564e-15 + 1.4215117583164458887e-7) * rb + 1.8463183175100546818e-5) * rb
+              + 7.868691311456132591e-4) * rb + .0148753612908506148525) * rb + .13692988092273580531) * rb + .59983220655588793769) * rb + 1.)
+    v[q[nc] < 0] = -v[q[nc] < 0]
+    out[nc] = v
+    return out
+
+
+class RRNG:
+    """Generator compatible with R's default ``RNGkind`` (Mersenne-Twister, Inversion).
+
+    It exposes ``standard_normal`` and ``integers`` so that it can be passed
+    wherever the package accepts a ``numpy.random.Generator``. Draws are taken
+    in the order R takes them (``matrix(rnorm(n), ...)`` fills by columns).
+    """
+
+    def __init__(self, seed: int):
+        self.bg = np.random.MT19937()
+        self.bg.state = {"bit_generator": "MT19937", "state": {"key": _r_seed_state(seed), "pos": 624}}
+
+    def unif(self, n: int) -> np.ndarray:
+        """``runif(n)`` of R."""
+        v = self.bg.random_raw(n).astype(np.float64) * 2.3283064365386963e-10
+        v[v <= 0.0] = 0.5 * _I2_32M1
+        v[1.0 - v <= 0.0] = 1.0 - 0.5 * _I2_32M1
+        return v
+
+    def standard_normal(self, size=None) -> np.ndarray:
+        """``rnorm(n)`` of R; ``size`` may be an int or a shape (filled in C order)."""
+        n = 1 if size is None else int(np.prod(size))
+        u = self.unif(2 * n).reshape(n, 2)
+        z = qnorm_r((np.floor(_BIG * u[:, 0]) + u[:, 1]) / _BIG)
+        return z[0] if size is None else z.reshape(size)
+
+    def integers(self, high: int) -> int:
+        """``sample.int(high, 1) - 1`` of R (sample.kind = "Rejection")."""
+        bits = int(math.ceil(math.log2(high))) if high > 1 else 0
+        while True:
+            v = 0.0
+            for _ in range(0, bits + 1, 16):
+                v1 = int(math.floor(self.unif(1)[0] * 65536))
+                v = 65536 * v + v1
+            v = int(v) & ((1 << bits) - 1)       # R masks always (bits = 0 gives 0)
+            if v < high:
+                return int(v)
+
+    def rnorm(self, n: int) -> np.ndarray:
+        """``rnorm(n)`` of R."""
+        return self.standard_normal(int(n))
+
+    def sample_replace(self, n: int, size: int) -> np.ndarray:
+        """0-based indices of ``sample.int(n, size, replace = TRUE)``."""
+        return np.array([self.integers(n) for _ in range(int(size))], dtype=int)
+
+    def sample_noreplace(self, n: int, size: int) -> np.ndarray:
+        """0-based indices of ``sample.int(n, size)`` (no hashing, n <= 1e7)."""
+        x = list(range(int(n)))
+        m = int(n)
+        out = []
+        for _ in range(int(size)):
+            j = self.integers(m)
+            out.append(x[j])
+            m -= 1
+            x[j] = x[m]
+        return np.array(out, dtype=int)

biplotpy/statis.py

@@ -0,0 +1,162 @@
+"""STATIS-ACT family (port of MultBiplotR::StatisBiplot, DualStatisBiplot and
+CanonicalStatisBiplot; Lavit et al., 1994; Vallejo-Arboleda,
+Vicente-Villardón & Galindo-Villardón, 2007).
+
+* ``statis``: several tables with the same individuals (rows). Objects
+  W_t = X_t X_t'; interstructure from the RV matrix; compromise
+  W = sum alpha_t W_t with alpha from the first eigenvector; biplot of the
+  compromise with the variables of every table.
+* ``dual_statis``: several tables with the same variables (columns). Objects
+  W_t = X_t' X_t (cross-product matrices); compromise of the variables.
+* ``canonical_statis``: several tables with the same individuals and a group
+  structure; objects W_t = Xb_t S_t^{-1} Xb_t' (Mahalanobis scalar products
+  between group means), giving a compromise canonical biplot of the groups.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from .transforms import initial_transform, transform_name
+
+
+class StatisResult:
+    def __init__(self, **kw):
+        self.__dict__.update(kw)
+
+    def plot(self, *args, **kwargs):
+        from .plot import plot_statis
+        return plot_statis(self, *args, **kwargs)
+
+    def __repr__(self):
+        return (f"{self.title}: {self.n_tables} tables\nRV matrix:\n{self.RV.round(3).to_string()}\n"
+                f"Weights: {np.round(self.weights, 4)}\nEigenvalues of the compromise: {np.round(self.eigenvalues[:5], 4)}")
+
+
+def _interstructure(Wt, names):
+    ng = len(Wt)
+    P = np.array([[np.sum(Wt[i] * Wt[j]) for j in range(ng)] for i in range(ng)])
+    s = 1 / np.sqrt(np.diag(P))
+    RV = P * s[:, None] * s[None, :]
+    u, d, _ = np.linalg.svd(RV)
+    weights = np.abs(u[:, 0]) / np.abs(u[:, 0]).sum()
+    inter = -1 * u * np.sqrt(d)
+    return (pd.DataFrame(P, index=names, columns=names), pd.DataFrame(RV, index=names, columns=names),
+            d, d / d.sum() * 100, inter, weights)
+
+
+def _compromise(Wt, weights):
+    W = sum(w * M for w, M in zip(weights, Wt))
+    U, d, _ = np.linalg.svd(W)
+    r = int(np.sum(d > 1e-5))
+    return W, U, d, r
+
+
+def statis(X, transform=5, dim=2, names=None) -> StatisResult:
+    """STATIS-ACT for tables with the same rows (list or dict of n x p_t matrices)."""
+    if isinstance(X, dict):
+        names = names or list(X)
+        X = list(X.values())
+    names = names or [f"Occasion_{i + 1}" for i in range(len(X))]
+    col_names = [list(x.columns) if isinstance(x, pd.DataFrame) else [f"V{j + 1}" for j in range(np.shape(x)[1])] for x in X]
+    X = [initial_transform(np.asarray(x, float), transform_name(transform))["X"] for x in X]
+    n = X[0].shape[0]
+    if any(x.shape[0] != n for x in X):
+        raise ValueError("The number of rows must be the same in all occasions")
+    Wt = [x @ x.T for x in X]
+    P, RV, eig, iner, inter, w = _interstructure(Wt, names)
+    W, U, d, r = _compromise(Wt, w)
+    rows = U[:, :dim] * np.sqrt(d[:dim])
+    sf = ((U[:, :r] * np.sqrt(d[:r])) ** 2).sum(1)
+    row_contr = rows ** 2 / sf[:, None] * 100
+    trajin = [Wt[j] @ U[:, :r] * np.sqrt(1 / d[:r]) for j in range(len(X))]
+    contvar, cols, col_labels = [], [], []
+    for j, x in enumerate(X):
+        tv = x.T @ U[:, :r]
+        contvar.append(tv ** 2 / (tv ** 2).sum(1, keepdims=True) * 100)
+        cols.append(x.T @ U[:, :r] / d[:r])
+        col_labels += [f"{c}-{names[j]}" for c in col_names[j]]
+    col_coords = np.vstack([c[:, :dim] for c in cols])
+    col_contr = np.vstack([c[:, :dim] for c in contvar])
+    p = col_coords.shape[0]
+    sca = (rows ** 2).sum() / n
+    scb = (col_coords ** 2).sum() / p
+    scf = np.sqrt(np.sqrt(scb / sca))
+    return StatisResult(title="STATIS-ACT", n_tables=len(X), names=names, data=X, objects=Wt, scalar_products=P,
+                        RV=RV, eig_inter=eig, inertia_inter=iner, interstructure=inter, weights=w, compromise=W,
+                        eigenvalues=d[:r], inertia=d[:r] / d[:r].sum() * 100,
+                        row_coordinates=rows * scf, row_contributions=row_contr,
+                        col_coordinates=col_coords / scf, col_contributions=col_contr, col_labels=col_labels,
+                        scale_factor=scf, trajectories=[t[:, :dim] * scf for t in trajin])
+
+
+def _common_sd_transform(X, transform):
+    if transform_name(transform) == "Standardize columns":
+        nr = np.array([x.shape[0] for x in X])
+        sds = np.array([np.std(x, axis=0, ddof=1) for x in X])
+        common = np.sqrt(((nr - 1)[:, None] * sds ** 2).sum(0) / (nr - 1).sum())
+        return [(x - x.mean(0)) / common for x in X], common
+    return [initial_transform(x, transform_name(transform))["X"] for x in X], None
+
+
+def dual_statis(X, transform=5, dim=2, names=None) -> StatisResult:
+    """Dual STATIS for tables with the same variables (columns). Standardization
+    uses the pooled within-table standard deviation (as MultBiplotR)."""
+    if isinstance(X, dict):
+        names = names or list(X)
+        X = list(X.values())
+    names = names or [f"Occasion_{i + 1}" for i in range(len(X))]
+    var_names = list(X[0].columns) if isinstance(X[0], pd.DataFrame) else [f"V{j + 1}" for j in range(np.shape(X[0])[1])]
+    X, common = _common_sd_transform([np.asarray(x, float) for x in X], transform)
+    Wt = [x.T @ x for x in X]
+    P, RV, eig, iner, inter, w = _interstructure(Wt, names)
+    W, U, d, r = _compromise(Wt, w)
+    cols = U[:, :dim] * np.sqrt(d[:dim])
+    sf = ((U[:, :r] * np.sqrt(d[:r])) ** 2).sum(1)
+    contr = cols ** 2 / sf[:, None] * 100
+    rows = [x @ U[:, :dim] for x in X]     # individuals of each table projected on the compromise axes
+    return StatisResult(title="Dual STATIS-ACT", n_tables=len(X), names=names, data=X, objects=Wt,
+                        scalar_products=P, RV=RV, eig_inter=eig, inertia_inter=iner, interstructure=inter, weights=w,
+                        compromise=W, eigenvalues=d[:r], inertia=d[:r] / d[:r].sum() * 100, col_coordinates=cols,
+                        col_contributions=contr, var_names=var_names, row_coordinates=rows, common_sd=common)
+
+
+def canonical_statis(X, groups, transform=5, dim=2, names=None) -> StatisResult:
+    """Canonical STATIS-ACT (Vallejo-Arboleda et al., 2007)."""
+    if isinstance(X, dict):
+        names = names or list(X)
+        X = list(X.values())
+    names = names or [f"Occasion_{i + 1}" for i in range(len(X))]
+    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]
+    X = [initial_transform(np.asarray(x, float), transform_name(transform))["X"] for x in X]
+    Z = np.column_stack([(g == lev).astype(float) for lev in levels])
+    ng = Z.sum(0)
+    Xbt, Bt, St, Wt = [], [], [], []
+    for x in X:
+        Xb = (Z.T @ x) / ng[:, None]
+        B = Xb.T @ np.diag(ng) @ Xb
+        S = x.T @ x - B
+        Xbt.append(Xb); Bt.append(B); St.append(S)
+        Wt.append(Xb @ np.linalg.solve(S, Xb.T))
+    P, RV, eig, iner, inter, w = _interstructure(Wt, names)
+    W, U, d, r = _compromise(Wt, w)
+    rows = U[:, :dim] * np.sqrt(d[:dim])
+    sf = ((U[:, :r] * np.sqrt(d[:r])) ** 2).sum(1)
+    contr = rows ** 2 / sf[:, None] * 100
+    trajin = [Wt[j] @ U[:, :r] * np.sqrt(1 / d[:r]) for j in range(len(X))]
+    cols, ccontr = [], []
+    for xb in Xbt:
+        tv = xb.T @ U[:, :r]
+        ccontr.append((tv ** 2 / (tv ** 2).sum(1, keepdims=True) * 100)[:, :dim])
+        cols.append((tv / d[:r])[:, :dim])
+    col_coords = np.vstack(cols)
+    p = col_coords.shape[0]
+    scf = np.sqrt(np.sqrt(((col_coords ** 2).sum() / p) / ((rows ** 2).sum() / len(levels))))
+    return StatisResult(title="Canonical STATIS-ACT", n_tables=len(X), names=names, levels=levels, data=X,
+                        means=Xbt, between=Bt, within=St, objects=Wt, scalar_products=P, RV=RV, eig_inter=eig,
+                        inertia_inter=iner, interstructure=inter, weights=w, compromise=W, eigenvalues=d[:r],
+                        inertia=d[:r] / d[:r].sum() * 100, row_coordinates=rows * scf, row_contributions=contr,
+                        col_coordinates=col_coords / scf, col_contributions=np.vstack(ccontr), scale_factor=scf,
+                        trajectories=[t[:, :dim] * scf for t in trajin])

biplotpy/transforms.py

@@ -0,0 +1,129 @@
+"""Initial transformations of a data matrix (port of MultBiplotR::InitialTransform).
+
+The transformation can be given by name or by its number in MultBiplotR (1-12).
+Two documented defects of the R code are corrected here (see ``FIXES``).
+"""
+from __future__ import annotations
+
+import numpy as np
+
+TRANSFORMS = ["Raw Data", "Substract the global mean", "Double centering", "Column centering",
+              "Standardize columns", "Row centering", "Standardize rows",
+              "Divide by the column means and center", "Normalized residuals from independence",
+              "Divide by the range", "Within groups standardization", "Ranks"]
+
+FIXES = {
+    "Within groups standardization": "MultBiplotR divides by the within-group variance; biplotpy divides by its square root (standard deviation).",
+    "Logit": "MultBiplotR computes the logit into an unused variable, so the data are not transformed; biplotpy applies it.",
+    "Supplementary rows": "PCA.Biplot in MultBiplotR projects the untransformed supplementary rows; biplotpy projects the transformed ones.",
+    "StatisBiplot transform": "StatisBiplot and CanonicalStatisBiplot pass InitTransform positionally to the wrong argument of TransformIni, so the data are always standardized whatever is requested; biplotpy honours `transform` (the default, 5, gives identical results).",
+    "StatisBiplot column names": "StatisBiplot fails when the tables have no column names; biplotpy generates them.",
+    "DualStatisBiplot": "DualStatisBiplot is unfinished in MultBiplotR (stops with a dimnames error); biplotpy implements the full method, and its core (pooled SD, RV, weights, compromise) is validated against MultBiplotR's own lines.",
+    "CanonicalStatisBiplot within": "CanonicalStatisBiplot stores the group means in $Within; biplotpy stores the within-group SSCP matrices.",
+    "BinaryLogBiplotGD": "MultBiplotR's gradient-descent binary logistic biplot divides the log-likelihood by 2 in the objective but not in the gradient; biplotpy minimizes a single consistent penalized objective, validated against R optim on that objective.",
+    "NIPALS.Biplot": "MultBiplotR's NIPALS.Biplot multiplies the row scores X V by the singular values again (rows = U D^2), so the biplot does not reproduce the data; biplotpy uses U D (and ade4's algorithm when there are missing values, which MultBiplotR does not handle).",
+    "Coinertia": "MultBiplotR's Coinertia replaces Y by X (Y = InitialTransform(X, ...)) and returns no coordinates; biplotpy follows ade4::coinertia.",
+    "BinaryDistances": "In MultBiplotR's BinaryDistances, Kulczynski2 is unreachable (the switch has Kulezynski twice), the sqrt(2(1-S)) transformation uses == instead of = (error), and 1/(S+1) computes 1/S + 1; biplotpy implements the stated formulas.",
+    "PrincipalCoordinates weights": "MultBiplotR's PrincipalCoordinates centres with (I - 1 w) on both sides, which is not the weighted double centring unless the weights are equal; biplotpy uses (I - 1 w') b (I - w 1'). Equal weights give identical results.",
+    "FA.Biplot scores": "MultBiplotR's FA.Biplot calls 'Regression' the Bartlett formula and vice versa, and squares the uniquenesses in Psi^-1; biplotpy uses the standard formulas (validated against psych::factor.scores).",
+    "PolyBiplot": "MultBiplotR's PolyBiplot multiplies the loadings and thresholds by sqrt(1 - h^2) instead of dividing (normal-ogive to item parameters) and uses unpenalized scores that diverge for all-extreme response patterns; biplotpy divides, rescales by 1.702 to the logistic metric and uses a standard normal prior on the scores.",
+    "PLSR": "MultBiplotR's PLSR normalizes the scores by their squared norm and reports W C' as regression coefficients without (P'W)^-1, which gives wrong coefficients; biplotpy follows pls::plsr (oscorespls) and reproduces its scores, loadings, coefficients and fitted values.",
+    "Unfolding stress at perfect fit": "smacof can return NaN stress-1 when the fit is exact (1 - x slightly negative by rounding); biplotpy truncates at 0.",
+}
+
+
+def transform_name(t):
+    return TRANSFORMS[t - 1] if isinstance(t, (int, np.integer)) else t
+
+
+def _sd(a, axis):
+    return np.std(a, axis=axis, ddof=1)
+
+
+def _rank(v):
+    from scipy.stats import rankdata
+    return rankdata(v, method="average")
+
+
+def initial_transform(X, transform="Standardize columns", sup_rows=None, sup_cols=None, grouping=None,
+                      init_transform="None"):
+    """Transform ``X`` (and optional supplementary rows/columns).
+
+    Returns a dict with ``X``, ``sup_rows``, ``sup_cols`` and the statistics used
+    (``col_means``, ``col_sds``, ``gmean``, ``col_ranges``)."""
+    X = np.array(X, float)
+    n, p = X.shape
+    transform = transform_name(transform)
+    sr = None if sup_rows is None else np.array(sup_rows, float)
+    sc = None if sup_cols is None else np.array(sup_cols, float)
+    if init_transform == "Log":
+        if np.any(X <= 0):
+            raise ValueError("Initial log transformation needs positive values")
+        X = np.log(X)
+        sr = None if sr is None else np.log(sr)
+        sc = None if sc is None else np.log(sc)
+    elif init_transform == "Logit":
+        X = X + 0.01 * (X == 0) - 0.01 * (X == 1)
+        X = np.log(X / (1 - X))
+    out = {"transform": transform, "gmean": X.mean(), "col_means": X.mean(0), "col_sds": _sd(X, 0),
+           "row_means": X.mean(1), "row_sds": _sd(X, 1) if p > 1 else np.full(n, np.nan), "col_ranges": X.max(0) - X.min(0)}
+    nsup = (0 if sr is None else len(sr)) + (0 if sc is None else sc.shape[1])
+    if transform in ("Double centering", "Divide by the column means and center",
+                     "Normalized residuals from independence") and nsup > 0:
+        raise ValueError(f"'{transform}' is not compatible with supplementary rows or columns")
+    cm, cs = out["col_means"], out["col_sds"]
+    if transform == "Raw Data":
+        pass
+    elif transform == "Substract the global mean":
+        X = X - out["gmean"]
+        sr = None if sr is None else sr - out["gmean"]
+        sc = None if sc is None else sc - out["gmean"]
+    elif transform == "Double centering":
+        X = X - X.mean(0) - X.mean(1)[:, None] + X.mean()
+    elif transform == "Column centering":
+        X = X - cm
+        sr = None if sr is None else sr - cm
+        sc = None if sc is None else sc - sc.mean(0)
+    elif transform == "Standardize columns":
+        X = (X - cm) / cs
+        sr = None if sr is None else (sr - cm) / cs
+        sc = None if sc is None else (sc - sc.mean(0)) / _sd(sc, 0)
+    elif transform == "Row centering":
+        X = X - X.mean(1)[:, None]
+        sr = None if sr is None else sr - sr.mean(1)[:, None]
+        sc = None if sc is None else sc - sc.mean(1)[:, None]
+    elif transform == "Standardize rows":
+        rs = out["row_sds"]
+        X = (X - X.mean(1)[:, None]) / rs[:, None]
+        sr = None if sr is None else (sr - sr.mean(1)[:, None]) / _sd(sr, 1)[:, None]
+        sc = None if sc is None else (sc - out["row_means"][:, None]) / rs[:, None]
+    elif transform == "Divide by the column means and center":
+        X = X / cm
+        X = X - X.mean(0)
+    elif transform == "Normalized residuals from independence":
+        nt = X.sum()
+        dr, dc = X.sum(1), X.sum(0)
+        esp = np.outer(dr, dc) / nt
+        var = np.outer(1 - dr / nt, 1 - dc / nt)
+        X = ((X - esp) / np.sqrt(esp)) / np.sqrt(var)
+    elif transform == "Divide by the range":
+        X = X / out["col_ranges"]
+    elif transform == "Within groups standardization":
+        if grouping is None:
+            raise ValueError("A grouping factor is needed for the within groups standardization")
+        g = np.asarray(grouping)
+        levs = list(dict.fromkeys(g))
+        Xc = X - cm
+        wss = np.zeros(p)
+        for lev in levs:
+            m = g == lev
+            wss += ((X[m] - X[m].mean(0)) ** 2).sum(0)
+        sdw = np.sqrt(wss / (n - len(levs)))
+        out["col_sds"] = sdw
+        X = Xc / sdw
+    elif transform == "Ranks":
+        X = np.column_stack([_rank(X[:, j]) for j in range(p)])
+    else:
+        raise ValueError(f"Unknown transformation: {transform}")
+    out.update(X=X, sup_rows=sr, sup_cols=sc)
+    return out

biplotpy/unfolding.py

@@ -0,0 +1,74 @@
+"""Metric (ratio) unfolding by SMACOF for a rectangular dissimilarity matrix
+(rows: individuals, columns: objects), following ``smacof::unfolding``
+(de Leeuw & Mair, 2009) for ``type = "ratio"`` and no constraints."""
+from __future__ import annotations
+
+import numpy as np
+
+
+def _dist(x, y):
+    return np.sqrt(np.maximum(((x[:, None, :] - y[None, :, :]) ** 2).sum(2), 0))
+
+
+def _pstress(dhat, d, w, wpp, omega=1.0, lam=0.5):
+    nrmd2 = np.sum(w * (dhat - d) ** 2)
+    mnc1 = nrmd2 / wpp
+    wsum = np.sum(w * dhat)
+    nrmw2 = np.sum(w * dhat ** 2)
+    nrmm2 = wsum ** 2 / wpp
+    nrmv2 = nrmw2 - nrmm2
+    mnc2 = (nrmv2 + omega * nrmm2) / nrmv2
+    return np.sqrt(mnc1 ** lam * mnc2)
+
+
+def unfolding(delta, ndim=2, weights=None, init=None, itmax=10000, eps=1e-6, relax=True) -> dict:
+    """Returns row and column configurations, distances, stress-1, stress per
+    point (%) and number of iterations."""
+    diss = np.asarray(delta, float)
+    n, m = diss.shape
+    w = np.ones((n, m)) if weights is None else np.asarray(weights, float)
+    w = np.where(np.isnan(diss), 0.0, w)
+    wpp = w.sum()
+    dhat = np.nan_to_num(diss)
+    e = dhat ** 2
+    e = -0.5 * (e - (e.sum(1)[:, None] / m + e.sum(0)[None, :] / n) + e.sum() / (n * m))
+    if init is None:
+        U, s, Vt = np.linalg.svd(e)
+        x = U[:, :ndim]
+        y = e.T @ x
+    else:
+        x, y = np.asarray(init[0], float)[:, :ndim], np.asarray(init[1], float)[:, :ndim]
+    dil = np.trace(x.T @ (e @ y)) / np.trace((x.T @ x) @ (y.T @ y))
+    x = np.sqrt(dil) / np.sqrt((x ** 2).sum()) * x
+    y = np.sqrt(dil) / np.sqrt((y ** 2).sum()) * y
+    d = _dist(x, y)
+    lold = _pstress(dhat, d, w, wpp)
+    wr, wc = w.sum(1), w.sum(0)
+    v = np.linalg.inv(np.diag(wc) + 1 / m - w.T @ (w / wr[:, None])) - 1 / m
+    itel = 1
+    while True:
+        d0 = d < eps
+        b = w * dhat * (~d0) / (d + d0)
+        br, bc = b.sum(1), b.sum(0)
+        xraw = br[:, None] * x - b @ y
+        yraw = bc[:, None] * y - b.T @ x
+        xold, yold = x, y
+        y = v @ (yraw + w.T @ (xraw / wr[:, None]))
+        x = (xraw + w @ y) / wr[:, None]
+        if relax and itel > 100:
+            x = 2 * x - xold
+            y = 2 * y - yold
+        d = _dist(x, y)
+        lnew = _pstress(dhat, d, w, wpp)
+        if itel == itmax or 2 * (lold - lnew) <= eps * (lold + lnew + 1e-15):
+            break
+        lold = lnew
+        itel += 1
+    resmat = (d - dhat) ** 2
+    spp_col = (w * resmat).sum(0) / w.sum(0); spp_col = spp_col / spp_col.sum() * 100
+    spp_row = (w * resmat).sum(1) / w.sum(1); spp_row = spp_row / spp_row.sum() * 100
+    scale = np.sqrt(w.sum() / np.sum(w * d ** 2))
+    d, x, y, dhat = scale * d, scale * x, scale * y, scale * dhat
+    stress = np.sqrt(max(0.0, 1 - np.sum(w * dhat * d) ** 2 / (np.sum(w * dhat ** 2) * np.sum(w * d ** 2))))
+    return {"conf_row": x, "conf_col": y, "confdist": d, "dhat": dhat, "stress": stress, "spp_row": spp_row,
+            "spp_col": spp_col, "niter": itel}

biplotpy/utils.py

@@ -0,0 +1,79 @@
+"""Numerical helpers shared by the biplot methods."""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+DBL_EPS = np.finfo(float).eps
+
+
+def matrix_sqrt(S, tol=math.sqrt(DBL_EPS), inverse=False):
+    """Square root (or inverse square root) of a symmetric PSD matrix via SVD,
+    dropping singular values below ``tol`` (as ``matrixsqrt``/``matrixsqrtinv``
+    in MultBiplotR)."""
+    u, d, vt = np.linalg.svd(np.asarray(S, float))
+    nz = d > tol
+    f = 1 / np.sqrt(d[nz]) if inverse else np.sqrt(d[nz])
+    return u[:, nz] @ np.diag(f) @ vt[nz]
+
+
+def r_pretty(x, n=5, min_n=None, shrink_sml=0.75, high_u_bias=1.5, u5_bias=None):
+    """Port of R's ``pretty()`` (``R_pretty`` in src/appl/pretty.c, eps.correct = 0)."""
+    x = np.asarray(x, float)
+    x = x[np.isfinite(x)]
+    lo, up = float(x.min()), float(x.max())
+    if min_n is None:
+        min_n = n // 3
+    h = high_u_bias
+    h5 = 0.5 + 1.5 * h if u5_bias is None else u5_bias
+    ndiv = n
+    dx = up - lo
+    if dx == 0 and up == 0:
+        cell = 1.0
+        i_small = True
+    else:
+        cell = max(abs(lo), abs(up))
+        U = 1 + (1 / (1 + h) if h5 >= 1.5 * h + 0.5 else 1.5 / (1 + h5))
+        U *= max(1, ndiv) * DBL_EPS
+        i_small = dx < cell * U * 3
+    if i_small:
+        if cell > 10:
+            cell = 9 + cell / 10
+        cell *= shrink_sml
+        if min_n > 1:
+            cell /= min_n
+    else:
+        cell = dx
+        if ndiv > 1:
+            cell /= ndiv
+    if cell < 20 * np.finfo(float).tiny:
+        cell = 20 * np.finfo(float).tiny
+    base = 10.0 ** math.floor(math.log10(cell))
+    unit = base
+    ns = 2 * base
+    if ns - cell < h * (cell - unit):
+        unit = ns
+        ns = 5 * base
+        if ns - cell < h5 * (cell - unit):
+            unit = ns
+            ns = 10 * base
+            if ns - cell < h * (cell - unit):
+                unit = ns
+    ns = math.floor(lo / unit + 1e-7)
+    nu = math.ceil(up / unit - 1e-7)
+    rounding_eps = 1e-10
+    while ns * unit > lo + rounding_eps * unit:
+        ns -= 1
+    while nu * unit < up - rounding_eps * unit:
+        nu += 1
+    k = int(0.5 + nu - ns)
+    if k < min_n:
+        k = min_n - k
+        if ns >= 0:
+            nu += k // 2
+            ns -= k // 2 + k % 2
+        else:
+            ns -= k // 2
+            nu += k // 2 + k % 2
+    return np.arange(ns, nu + 1) * unit