biplotpy 0.4.0__py3-none-any.whl

biplotpy/plsbin.py

@@ -0,0 +1,224 @@
+"""PLS regression with binary responses (MultBiplotR).
+
+* ``plsr1_bin``: PLS regression of one binary response on continuous
+  predictors (``PLSR1Bin``, algorithm 1 of Bastien, Esposito Vinzi & Tenenhaus
+  2005): each component is built from the slopes of univariate ridge logistic
+  regressions and the response is finally regressed on the components.
+* ``binary_plsr``: PLS regression for binary data (``BinaryPLSR``), with
+  binary predictors and binary responses, both modelled by logistic biplots
+  whose row scores are shared; fitted by alternating conjugate gradients
+  (R's ``optim(method = "CG")``) from random starts.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from scipy.special import expit
+
+from .distances import ridge_logistic
+from .roptim import optim_cg
+from .rrng import RRNG
+from .transforms import initial_transform, transform_name
+
+
+def plsr1_bin(y, X, S=2, scaling=5, penalization=0.0, row_names=None, col_names=None) -> dict:
+    """PLS regression of a binary response ``y`` (0/1) on ``X``
+    (``MultBiplotR::PLSR1Bin`` with ``Algorithm = 1``).
+
+    Component ``s``: for each predictor, a ridge logistic regression (penalty
+    0.2, as in R) of ``y`` on the previous components and the predictor gives
+    a slope; the normalized slopes are the weights ``w``, the scores are
+    ``t = X_(s-1) w`` (deflated ``X``) and the loadings ``p = X't / t't``. The
+    response is finally regressed on the components with ``penalization``.
+
+    Returns scores ``T``, weights ``W``, loadings ``P``, the final logistic fit
+    and the structure correlations between the predictors and the scores."""
+    if isinstance(X, pd.DataFrame):
+        col_names = col_names or [str(c) for c in X.columns]
+        row_names = row_names or [str(i) for i in X.index]
+    Xo = np.asarray(X, float)
+    y = np.asarray(y, float).ravel()
+    if not np.all(np.isin(y, (0, 1))):
+        raise ValueError("The response must be binary (0 or 1)")
+    Xs = initial_transform(Xo, transform_name(scaling))["X"]
+    n, J = Xs.shape
+    T = np.zeros((n, S)); W = np.zeros((J, S)); P = np.zeros((J, S))
+    w = np.zeros(J)
+    for j in range(J):
+        w[j] = ridge_logistic(y, Xs[:, j], 0.2, intercept=True)["beta"][1]
+    w = w / np.sqrt(np.sum(w ** 2))
+    t = Xs @ w
+    T[:, 0] = t; W[:, 0] = w
+    p = Xs.T @ t / np.sum(t ** 2); P[:, 0] = p
+    X1 = Xs - np.outer(t, p)
+    for s in range(1, S):
+        for j in range(J):
+            x = np.column_stack([T[:, :s], Xs[:, j]])
+            w[j] = ridge_logistic(y, x, 0.2, intercept=True)["beta"][s + 1]
+        w = w / np.sqrt(np.sum(w ** 2))
+        t = X1 @ w
+        T[:, s] = t; W[:, s] = w
+        p = Xs.T @ t / np.sum(t ** 2); P[:, s] = p
+        X1 = X1 - np.outer(t, p)
+    fit = ridge_logistic(y, T, penalization, intercept=True)
+    comps = [f"Comp. {k + 1}" for k in range(S)]
+    col_names = col_names or [f"X{j + 1}" for j in range(J)]
+    row_names = row_names or [f"I{i + 1}" for i in range(n)]
+    structure = np.corrcoef(np.column_stack([Xo, T]), rowvar=False)[:J, J:]
+    return {"method": "PLSR1 Binary", "scores": pd.DataFrame(T, index=row_names, columns=comps),
+            "weights": pd.DataFrame(W, index=col_names, columns=comps),
+            "loadings": pd.DataFrame(P, index=col_names, columns=comps),
+            "structure": pd.DataFrame(structure, index=col_names, columns=comps), "fit": fit,
+            "y_weights": fit["beta"], "scaled_X": Xs}
+
+
+# --------------------------------------------------------------------------- BinaryPLSR
+def _rsum(v):
+    """``sum(v, na.rm = TRUE)`` of R: sequential accumulation in long double,
+    in column-major order, skipping NaN (keeps the CG path close to R's)."""
+    v = np.asarray(v, float).ravel(order="F")
+    v = v[~np.isnan(v)]
+    return float(np.cumsum(v.astype(np.longdouble))[-1]) if v.size else 0.0
+
+
+def _mm(A, B):
+    """``A %*% B`` with the summation order of the reference BLAS used by R
+    (sequential over the inner index, in double precision)."""
+    A = np.atleast_2d(A); B = np.atleast_2d(B)
+    C = np.zeros((A.shape[0], B.shape[1]))
+    for l in range(A.shape[1]):
+        C += A[:, l:l + 1] * B[l:l + 1, :]
+    return C
+
+
+def _sig(z):
+    return 1 / (1 + np.exp(-1 * z))
+
+
+def _cost(H, X):
+    with np.errstate(divide="ignore", invalid="ignore"):
+        return _rsum(-1 * X * np.log(H) - (1 - X) * np.log(1 - H))
+
+
+def _J_b0(par, X):
+    H = _sig(_mm(np.ones((X.shape[0], 1)), par[None, :]))
+    return _cost(H, X) / 2
+
+
+def _g_b0(par, X):
+    H = _sig(_mm(np.ones((X.shape[0], 1)), par[None, :]))
+    return _mm((H - X).T, np.ones((X.shape[0], 1))).ravel()
+
+
+def _J_B(par, X, A, B, lam):
+    r = A.shape[1] - 1
+    B = B.copy(); B[:, r] = par
+    H = _sig(_mm(A, B.T))
+    return _cost(H, X) / 2 + lam * _rsum(B[:, 1:] ** 2) / 2
+
+
+def _g_B(par, X, A, B, lam):
+    r = A.shape[1] - 1
+    B = B.copy(); B[:, r] = par
+    E = _sig(_mm(A, B.T)) - X
+    E[np.isnan(X)] = 0
+    G = _mm(E.T, A) + lam * np.column_stack([np.zeros(B.shape[0]), B[:, 1:]])
+    return G[:, r]
+
+
+def _J_A(par, X, A, B, lam):
+    r = B.shape[1] - 1
+    A = A.copy(); A[:, r] = par
+    H = _sig(_mm(A, B.T))
+    return _cost(H, X) / 2 + lam * _rsum(A ** 2) / 2
+
+
+def _g_A(par, X, A, B, lam):
+    r = B.shape[1] - 1
+    A = A.copy(); A[:, r] = par
+    E = _sig(_mm(A, B.T)) - X
+    E[np.isnan(X)] = 0
+    return (_mm(E, B) + lam * A)[:, r]
+
+
+def _scale(v):
+    """R's ``scale()`` of a vector: ``colMeans`` (long double sum / n) and the root
+    of the sum of squares (long double sum) over n - 1."""
+    v = np.asarray(v, float).ravel()
+    n = v.size
+    m = float(np.cumsum(v.astype(np.longdouble))[-1] / n)
+    c = v - m
+    ss = float(np.cumsum((c * c).astype(np.longdouble))[-1])
+    return c / np.sqrt(ss / max(1, n - 1))
+
+
+def binary_plsr(Y, X, S=2, penalization=0.1, tol=5e-5, maxiter=100, seed=0, row_names=None,
+                x_names=None, y_names=None) -> dict:
+    """PLS regression for binary data (``MultBiplotR::BinaryPLSR``).
+
+    ``X`` (n x J) and ``Y`` (n x K) are binary. Both are modelled by logistic
+    biplots with intercepts ``p0`` and ``q0``; component ``s`` alternates, until
+    the scores stabilize, ridge-penalized conjugate-gradient updates of the
+    ``X`` loadings, the ``X`` scores, the ``Y`` loadings and the ``Y`` scores,
+    the scores being standardized after each update (R's ``optim`` CG, ported in
+    ``biplotpy.roptim``). Starting values are normal random numbers drawn
+    with R's generator after ``set.seed(seed)``, so a given seed gives R's
+    result. Returns scores, loadings, intercepts, fitted probabilities and the
+    percentages of correct classification of ``Y``."""
+    if isinstance(X, pd.DataFrame):
+        x_names = x_names or [str(c) for c in X.columns]; row_names = row_names or [str(i) for i in X.index]
+    if isinstance(Y, pd.DataFrame):
+        y_names = y_names or [str(c) for c in Y.columns]
+    X = np.asarray(X, float); Y = np.asarray(Y, float)
+    if Y.ndim == 1:
+        Y = Y[:, None]
+    if not np.all(np.isin(Y[np.isfinite(Y)], (0, 1))):
+        raise ValueError("The response must be binary (0 or 1)")
+    I, J = X.shape
+    K = Y.shape[1]
+    rng = RRNG(seed)
+    p0 = optim_cg(_J_b0, _g_b0, rng.rnorm(J), args=(X,))["par"]
+    q0 = optim_cg(_J_b0, _g_b0, rng.rnorm(K), args=(Y,))["par"]
+    TT = np.ones((I, 1)); U = np.ones((I, 1)); P = p0[:, None]; Q = q0[:, None]
+    iters = []
+    for k in range(S):
+        tt = rng.rnorm(I); TT = np.column_stack([TT, tt])
+        u = rng.rnorm(I); U = np.column_stack([U, u])
+        parP = rng.rnorm(J); P = np.column_stack([P, parP])
+        parQ = rng.rnorm(K); Q = np.column_stack([Q, parQ])
+        t = u
+        error, it = 1.0, 0
+        while error > tol and it < maxiter:
+            it += 1
+            told = t
+            parP = optim_cg(_J_B, _g_B, parP, args=(X, TT, P, penalization))["par"]
+            P[:, k + 1] = parP
+            t = optim_cg(_J_A, _g_A, t, args=(X, TT, P, penalization))["par"]
+            t = _scale(t)
+            tt = t
+            u = t
+            U[:, k + 1] = u
+            parQ = optim_cg(_J_B, _g_B, parQ, args=(Y, U, Q, penalization))["par"]
+            Q[:, k + 1] = parQ
+            u = optim_cg(_J_A, _g_A, u, args=(Y, U, Q, penalization))["par"]
+            U[:, k + 1] = _scale(u)
+            t = _scale(u)
+            TT[:, k + 1] = t
+            error = np.sum((told - t) ** 2)
+        TT[:, k + 1] = tt
+        iters.append(it)
+    U, Q, P = U[:, 1:], Q[:, 1:], P[:, 1:]
+    lin = TT @ np.column_stack([q0, Q]).T
+    E = expit(lin)
+    pred = (E > 0.5).astype(float)
+    right = Y == pred
+    comps = [f"Comp. {k + 1}" for k in range(S)]
+    row_names = row_names or [f"I{i + 1}" for i in range(I)]
+    x_names = x_names or [f"X{j + 1}" for j in range(J)]
+    y_names = y_names or [f"Y{j + 1}" for j in range(K)]
+    return {"method": "PLSR for binary data", "x_scores": pd.DataFrame(TT[:, 1:], index=row_names, columns=comps),
+            "x_loadings": pd.DataFrame(P, index=x_names, columns=comps),
+            "y_scores": pd.DataFrame(U, index=row_names, columns=comps),
+            "y_loadings": pd.DataFrame(Q, index=y_names, columns=comps), "x_intercepts": p0, "y_intercepts": q0,
+            "linear_terms": lin, "expected": E, "predictions": pred, "percent_correct": right.mean(),
+            "percent_correct_cols": right.mean(0), "iterations": iters, "seed": seed}

biplotpy/restricted.py

@@ -0,0 +1,300 @@
+"""Constrained (restricted) logistic biplots and the external ordinal logistic
+biplot of MultBiplotR.
+
+* ``constrained_logistic_biplot``: binary responses ``Y`` explained by
+  continuous variables ``X`` (``ConstrainedLogisticBiplot``). Each response is
+  regressed on ``X`` by ridge logistic regression; the standardized linear
+  predictors are summarized by an SVD, whose first components are the row
+  coordinates, and each response is then refitted on those coordinates.
+* ``constrained_ordinal_logistic_biplot``: the same with ordinal responses and
+  ridge cumulative-logit regressions (``ConstrainedOrdinalLogisticBiplot``).
+* ``external_ordinal_logistic_biplot``: ordinal variables fitted by ridge
+  cumulative-logit regressions on a given configuration (PCA, PCoA, MDS...),
+  as ``AddOrdVars2Biplot``.
+* ``ridge_ordinal_logistic``: the Newton (Fisher scoring) fit of MultBiplotR
+  (``OrdinalLogisticFit``/``RidgeOrdinalLogistic``), with the ridge penalty on
+  thresholds and slopes.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+import scipy.stats as sps
+from scipy.special import expit
+
+from .distances import ridge_logistic
+from .extras import add_continuous_variables
+from .logistic import LogisticBiplot
+from .transforms import initial_transform, transform_name
+
+
+# --------------------------------------------------------------------------- helpers
+def _ridge_binary_fit(y, Xd, penalization=0.2, tol=1e-5, maxiter=100):
+    """``RidgeBinaryLogisticFit``: Newton-Raphson with ridge penalty (first column,
+    the intercept, not penalized). ``Xd`` already contains the intercept."""
+    n, m = Xd.shape
+    beta = np.zeros(m)
+    Im = np.eye(m); Im[0, 0] = 0.0
+    err, it = 0.1, 0
+    while err > tol and it < maxiter:
+        it += 1
+        old = beta
+        mu = expit(Xd @ old)
+        In = Xd.T @ ((mu * (1 - mu))[:, None] * Xd) + 2 * penalization * Im
+        U = Xd.T @ (y - mu) - 2 * penalization * Im @ old
+        beta = old + np.linalg.pinv(In) @ U
+        err = np.sum(np.abs(old - beta))
+    return beta
+
+
+def _codes(y):
+    """Ordinal variable -> integer codes 1..C (pandas ordered categorical, or numbers)."""
+    if hasattr(y, "cat"):
+        return y.cat.codes.to_numpy() + 1, list(y.cat.categories)
+    y = np.asarray(y)
+    lev = sorted(set(y.tolist()))
+    return np.array([lev.index(v) + 1 for v in y]), lev
+
+
+def ridge_ordinal_logistic(y, x=None, penalization=0.1, tol=1e-4, maxiter=200) -> dict:
+    """Ridge cumulative-logit regression, ``logit P(y <= c) = tau_c - x beta``,
+    fitted by Fisher scoring as ``MultBiplotR::OrdinalLogisticFit`` (the
+    penalty ``penalization * |(tau, beta)|^2`` includes the thresholds).
+
+    ``y``: integer codes 1..J. Returns thresholds, coefficients, linear
+    predictors, fitted category probabilities, log-likelihood, deviance and,
+    against the model without covariates, the likelihood-ratio test and the
+    pseudo R2 of Cox-Snell, Nagelkerke and McFadden."""
+    def fit(xm):
+        y_ = np.asarray(y, int)
+        n = len(y_)
+        p = 0 if xm is None else xm.shape[1]
+        J = int(y_.max())
+        if J < 2:
+            raise ValueError("There is a variable with the same value for all the items.")
+        npar = J + p - 1
+        Y = np.zeros((n, J))
+        for i in range(n):
+            if y_[i] > 0:
+                Y[i, y_[i] - 1] = 1
+        R = np.cumsum(Y, axis=1)
+        A = R[:, :J - 1].sum(0) / n
+        Beta = np.zeros(p)
+        B = np.concatenate([A, Beta])
+        err, it = 0.1, 0
+        while err > tol and it < maxiter:
+            it += 1
+            ETA = np.tile(A, (n, 1)) if xm is None else A[None, :] - (xm @ Beta)[:, None]
+            PIA = np.column_stack([np.exp(ETA) / (1 + np.exp(ETA)), np.ones(n)])
+            PI = np.column_stack([PIA[:, :1], PIA[:, 1:J] - PIA[:, :J - 1]])
+            Rho = np.log(PIA[:, :J - 1] / (PIA[:, 1:J] - PIA[:, :J - 1]))
+            gRho = np.log(1 + np.exp(Rho))
+            U = PIA[:, 1:J] / (PIA[:, :J - 1] * (PIA[:, 1:J] - PIA[:, :J - 1]))
+            D = R[:, :J - 1] - R[:, 1:J] * (PIA[:, :J - 1] / PIA[:, 1:J])
+            D2 = PIA[:, :J] * (1 - PIA[:, :J])
+            Q = np.zeros((n, J - 1, npar))
+            GR = np.zeros(npar)
+            for k in range(npar):
+                P = np.zeros((n, J))
+                if k < J - 1:
+                    P[:, k] = 1.0
+                else:
+                    P[:, :J - 1] = -xm[:, k - (J - 1)][:, None]
+                Q[:, :, k] = P[:, :J - 1] * D2[:, :J - 1] - P[:, 1:J] * (PIA[:, :J - 1] / PIA[:, 1:J]) * D2[:, 1:J]
+                GR[k] = np.sum(D * U * Q[:, :, k])
+            HESS = np.einsum("nj,njs,njk->sk", U, Q, Q) + 2 * np.eye(npar) * penalization
+            Bnew = B + np.linalg.solve(HESS, GR - 2 * B * penalization)
+            err = np.sum((Bnew - B) ** 2)
+            B = Bnew
+            A = B[:J - 1]
+            Beta = np.zeros(p) if xm is None else B[J - 1:J - 1 + p]
+        L = np.sum(R[:, :J - 1] * Rho - R[:, 1:J] * gRho)
+        pred = PI.argmax(1) + 1
+        return {"thresholds": A, "coefficients": Beta, "eta": ETA, "fitted": PI, "pred": pred,
+                "logLik": L, "deviance": -2 * L, "percent_correct": np.mean(y_ == pred), "iter": it,
+                "J": J, "nvar": p, "covariances": np.linalg.inv(HESS)}
+    x = None if x is None else np.asarray(x, float).reshape(len(y), -1)
+    model = fit(x)
+    null = fit(None)
+    n = len(y)
+    dif = null["deviance"] - model["deviance"]
+    cs = 1 - np.exp(-dif / n)
+    model.update({"null_deviance": null["deviance"], "dif": dif, "df": model["nvar"],
+                  "p": sps.chi2.sf(dif, model["nvar"]), "cox_snell": cs,
+                  "nagelkerke": cs / (1 - np.exp(null["deviance"] / -2) ** (2 / n)),
+                  "mcfadden": 1 - model["deviance"] / null["deviance"]})
+    return model
+
+
+def _ordinal_columns(Ycodes, A, penalization, tol, maxiter, names):
+    """Fit each ordinal variable on the configuration ``A`` (``AddOrdVars2Biplot``)."""
+    n, p = Ycodes.shape
+    dim = A.shape[1]
+    ncat = [int(Ycodes[:, j].max()) for j in range(p)]
+    coef = np.zeros((p, dim)); thr = np.zeros((p, max(ncat) - 1))
+    fitcols = ["logLik", "Deviance", "df", "p-value", "PCC", "CoxSnell", "Macfaden", "Nagelkerke", "NullDeviance"]
+    fit = np.zeros((p, 9)); models = []
+    for j in range(p):
+        m = ridge_ordinal_logistic(Ycodes[:, j], A, penalization, tol, maxiter)
+        models.append(m)
+        coef[j] = m["coefficients"]; thr[j, :len(m["thresholds"])] = m["thresholds"]
+        fit[j] = [m["logLik"], m["deviance"], m["df"], m["p"], m["percent_correct"], m["cox_snell"],
+                  m["mcfadden"], m["nagelkerke"], m["null_deviance"]]
+    d = np.sqrt((coef ** 2).sum(1) + 1)
+    loadings = coef / d[:, None]
+    nn = n * p
+    dev0, dev, df = fit[:, 8].sum(), fit[:, 1].sum(), fit[:, 2].sum()
+    dif = dev0 - dev
+    cs = 1 - np.exp(-dif / nn)
+    ll = fit[:, 0].sum()
+    return {"coefficients": pd.DataFrame(coef, index=names, columns=[f"Dim_{k + 1}" for k in range(dim)]),
+            "thresholds": pd.DataFrame(thr, index=names, columns=[f"C_{c + 1}" for c in range(thr.shape[1])]),
+            "fit": pd.DataFrame(fit, index=names, columns=fitcols), "loadings": loadings,
+            "communalities": (loadings ** 2).sum(1), "ncats": ncat, "logLik": ll, "deviance": dev,
+            "null_deviance": dev0, "df": df, "dif": dif, "p": sps.chi2.sf(dif, df), "cox_snell": cs,
+            "nagelkerke": cs / (1 - np.exp(dev0 / -2) ** (2 / nn)), "mcfadden": 1 - dev / dev0,
+            "AIC": -2 * ll + 2 * df, "BIC": -2 * ll + df * np.log(nn), "models": models}
+
+
+def _ordinal_frame(Y):
+    if isinstance(Y, pd.DataFrame):
+        names = [str(c) for c in Y.columns]
+        cols = [_codes(Y[c]) for c in Y.columns]
+    else:
+        Y = np.asarray(Y)
+        names = [f"V{j + 1}" for j in range(Y.shape[1])]
+        cols = [_codes(Y[:, j]) for j in range(Y.shape[1])]
+    return np.column_stack([c[0] for c in cols]), [c[1] for c in cols], names
+
+
+# --------------------------------------------------------------------------- binary
+def constrained_logistic_biplot(Y, X, dim=2, scaling=5, penalization=0.1, tol=1e-5, maxiter=100,
+                                row_names=None) -> LogisticBiplot:
+    """Constrained binary logistic biplot (``MultBiplotR::ConstrainedLogisticBiplot``).
+
+    The row coordinates are linear combinations of the explanatory variables
+    ``X``: each binary response is regressed on ``X`` (ridge logistic
+    regression, ``penalization``), the standardized linear predictors are
+    decomposed by SVD and the first ``dim`` components (scaled by the singular
+    values) are the row coordinates. Each response is then refitted on them
+    (ridge penalty 0.2, as in R) and the explanatory variables are projected as
+    supplementary continuous variables.
+
+    Two details differ from MultBiplotR on purpose: the p-values of the
+    deviance tests use ``dim`` degrees of freedom (R uses 1), and the
+    percentages of correct classification threshold the probability at 0.5 (R
+    thresholds the linear predictor at 0.5)."""
+    if isinstance(Y, pd.DataFrame):
+        col_names = [str(c) for c in Y.columns]; row_names = row_names or [str(i) for i in Y.index]
+    else:
+        col_names = [f"V{j + 1}" for j in range(np.shape(Y)[1])]
+    x_names = [str(c) for c in X.columns] if isinstance(X, pd.DataFrame) else None
+    Y = np.asarray(Y, float); Xo = np.asarray(X, float)
+    n, p = Y.shape
+    q = Xo.shape[1]
+    r = min(p, q)
+    tname = transform_name(scaling)
+    Xs = initial_transform(Xo, tname)["X"]
+    Xd = np.column_stack([np.ones(n), Xs])
+    Yh = np.zeros((n, p)); Betas = np.zeros((p, q + 1))
+    for j in range(p):
+        fit = ridge_logistic(Y[:, j], Xd, penalization=penalization, intercept=False, tol=tol, maxiter=maxiter)
+        Betas[j] = fit["beta"]; Yh[:, j] = Xd @ fit["beta"]
+    Yh = initial_transform(Yh, "Standardize columns")["X"]
+    U, d, Vt = np.linalg.svd(Yh, full_matrices=False)
+    ev = d[:r] ** 2
+    A = U[:, :dim] * d[:dim]
+    aa = np.column_stack([np.ones(n), A])
+    B = np.vstack([_ridge_binary_fit(Y[:, j], aa, 0.2, tol, maxiter) for j in range(p)])
+    esp = aa @ B.T
+    P = expit(esp)
+    pred = (P > 0.5).astype(float)
+    acier = pred == Y
+    pres = Y.sum(0); abs_ = n - pres
+    sens = ((acier) & (Y == 1)).sum(0) / pres
+    spec = ((acier) & (Y == 0)).sum(0) / abs_
+    p0 = expit(B[:, 0])
+    d1 = -2 * (Y * np.log(p0) + (1 - Y) * np.log(1 - p0)).sum(0)
+    d2 = -2 * (Y * np.log(P) + (1 - Y) * np.log(1 - P)).sum(0)
+    dev = d1 - d2
+    cs = 1 - np.exp(-dev / n)
+    dd = np.sqrt(1 + (B[:, 1:] ** 2).sum(1))
+    loadings = B[:, 1:] / dd[:, None]
+    row_names = row_names or [f"I{i + 1}" for i in range(n)]
+    cols = pd.DataFrame(np.column_stack([B, dev, sps.chi2.sf(dev, dim), acier.mean(0) * 100, 1 - d2 / d1]),
+                        index=col_names, columns=["b0"] + [f"b{k + 1}" for k in range(dim)] +
+                        ["Deviance", "p-value", "% correct", "McFadden R2"])
+    out = LogisticBiplot(
+        title="Constrained Binary Logistic Biplot", n=n, p=p, dim=dim, penalization=penalization, A=A, B=B,
+        fitted=P, objective=float(d2.sum() / 2), converged=True, columns=cols,
+        betas=pd.DataFrame(Betas, index=col_names, columns=["Intercept"] + (x_names or [f"X{k + 1}" for k in range(q)])),
+        eigenvalues=ev, inertia=ev / ev.sum() * 100, null_deviances=d1, model_deviances=d2, deviances=dev,
+        cox_snell=cs, nagelkerke=cs / (1 - np.exp(d1 / -2) ** (2 / n)), mcfadden=1 - d2 / d1,
+        loadings=loadings, communalities=(loadings ** 2).sum(1), sensitivity=sens, specificity=spec,
+        global_percent=acier.mean() * 100, row_percent=acier.mean(1) * 100, row_names=row_names, col_names=col_names)
+    out.row_coordinates = A
+    out.sup_variables = add_continuous_variables(out, Xo, dims=dim, scaling=scaling, names=x_names)
+    return out
+
+
+# --------------------------------------------------------------------------- ordinal
+def constrained_ordinal_logistic_biplot(Y, X, dim=2, scaling=5, penalization=0.1, tol=1e-5, maxiter=100,
+                                        row_names=None) -> LogisticBiplot:
+    """Constrained ordinal logistic biplot (``MultBiplotR::ConstrainedOrdinalLogisticBiplot``).
+
+    ``Y``: ordinal variables (DataFrame of ordered categoricals, or integer
+    codes 1..C). Each is regressed on the transformed ``X`` by ridge
+    cumulative-logit regression; the standardized linear predictors (first
+    threshold) are decomposed by SVD; the first ``dim`` components are the row
+    coordinates and each ordinal variable is refitted on them."""
+    Yc, cats, names = _ordinal_frame(Y)
+    if isinstance(Y, pd.DataFrame):
+        row_names = row_names or [str(i) for i in Y.index]
+    x_names = [str(c) for c in X.columns] if isinstance(X, pd.DataFrame) else None
+    Xs = initial_transform(np.asarray(X, float), transform_name(scaling))["X"]
+    n, p = Yc.shape
+    r = min(p, Xs.shape[1])
+    Yh = np.zeros((n, p)); fits = []
+    for j in range(p):
+        m = ridge_ordinal_logistic(Yc[:, j], Xs, penalization, tol, maxiter)
+        fits.append(m)
+        e = m["eta"][:, 0]
+        Yh[:, j] = (e - e.mean()) / e.std(ddof=1)
+    U, d, Vt = np.linalg.svd(Yh, full_matrices=False)
+    ev = d[:r] ** 2
+    A = U[:, :dim] * d[:dim]
+    cp = _ordinal_columns(Yc, A, penalization, tol, maxiter, names)
+    row_names = row_names or [f"I{i + 1}" for i in range(n)]
+    cols = pd.concat([cp["coefficients"], cp["fit"][["Deviance", "p-value", "PCC"]]], axis=1)
+    out = LogisticBiplot(
+        title="Constrained Ordinal Logistic Biplot", n=n, p=p, dim=dim, penalization=penalization, A=A,
+        B=cp["coefficients"].to_numpy(), thresholds=[cp["thresholds"].to_numpy()[j, :cp["ncats"][j] - 1] for j in range(p)],
+        objective=-cp["logLik"], converged=True, columns=cols, column_parameters=cp, eigenvalues=ev,
+        inertia=ev / ev.sum() * 100, categories=cats, regressions=fits,
+        global_percent=float(np.mean(cp["fit"]["PCC"]) * 100), row_names=row_names, col_names=names,
+        loadings=cp["loadings"], communalities=cp["communalities"], deviance=cp["deviance"],
+        null_deviance=cp["null_deviance"], df=cp["df"], pvalue=cp["p"], AIC=cp["AIC"], BIC=cp["BIC"])
+    out.row_coordinates = A
+    out.sup_variables = add_continuous_variables(out, Xs, dims=dim, scaling=scaling, names=x_names)
+    return out
+
+
+def external_ordinal_logistic_biplot(coords, Y, penalization=0.2, tol=1e-6, maxiter=100,
+                                     row_names=None) -> LogisticBiplot:
+    """External ordinal logistic biplot: each ordinal variable is fitted by a
+    ridge cumulative-logit regression on a given configuration ``coords``
+    (principal components, coordinates of a PCoA or an MDS...), as
+    ``MultBiplotR::AddOrdVars2Biplot``. The lines of the variables and the
+    category boundaries are drawn with ``plot()``."""
+    A = np.asarray(getattr(coords, "row_coordinates", coords), float)
+    Yc, cats, names = _ordinal_frame(Y)
+    n, p = Yc.shape
+    cp = _ordinal_columns(Yc, A, penalization, tol, maxiter, names)
+    cols = pd.concat([cp["coefficients"], cp["fit"][["Deviance", "p-value", "PCC"]]], axis=1)
+    return LogisticBiplot(
+        title="External Ordinal Logistic Biplot", n=n, p=p, dim=A.shape[1], penalization=penalization, A=A,
+        B=cp["coefficients"].to_numpy(), thresholds=[cp["thresholds"].to_numpy()[j, :cp["ncats"][j] - 1] for j in range(p)],
+        objective=-cp["logLik"], converged=True, columns=cols, column_parameters=cp, categories=cats,
+        global_percent=float(np.mean(cp["fit"]["PCC"]) * 100), row_names=row_names or [f"I{i + 1}" for i in range(n)],
+        col_names=names, loadings=cp["loadings"], communalities=cp["communalities"], deviance=cp["deviance"],
+        null_deviance=cp["null_deviance"], df=cp["df"], pvalue=cp["p"], AIC=cp["AIC"], BIC=cp["BIC"])

biplotpy/roptim.py

@@ -0,0 +1,104 @@
+"""R's ``optim(method = "CG")``: conjugate gradients of Nash (1990), as coded in
+R's ``src/appl/optim.c`` (``cgmin``), so that procedures that MultBiplotR runs
+with ``optim(..., method = "CG")`` follow the same path in Python."""
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+_STEPREDN = 0.2
+_ACCTOL = 0.0001
+_RELTEST = 10.0
+
+
+def optim_cg(fn, gr, par, args=(), type: int = 1, maxit: int = 100, abstol: float = -math.inf,
+             reltol: float = 1.4901161193847656e-08):
+    """Minimize ``fn`` from ``par`` with R's CG method (``type`` 1 Fletcher-Reeves,
+    2 Polak-Ribiere, 3 Beale-Sorenson). Returns a dict like ``optim``: ``par``,
+    ``value``, ``counts`` and ``convergence`` (1 when ``maxit`` is reached)."""
+    B = [float(v) for v in np.asarray(par, float).ravel()]
+    n = len(B)
+    f_ = lambda b: float(fn(np.array(b), *args))
+    g_ = lambda b: [float(v) for v in np.asarray(gr(np.array(b), *args), float).ravel()]
+    if maxit <= 0:
+        return {"par": np.array(B), "value": f_(B), "counts": (0, 0), "convergence": 0}
+    c = [0.0] * n; t = [0.0] * n; X = [0.0] * n
+    setstep = 1.7
+    fail = 0
+    cyclimit = n
+    tol = reltol * n * math.sqrt(reltol)
+    f = f_(B)
+    if not math.isfinite(f):
+        raise ValueError("Function cannot be evaluated at initial parameters")
+    Fmin = f
+    funcount, gradcount = 1, 0
+    steplength = 1.0
+    while True:
+        t = [0.0] * n; c = [0.0] * n
+        cycle = 0
+        oldstep = 1.0
+        count = 0
+        while True:
+            cycle += 1
+            gradcount += 1
+            if gradcount > maxit:
+                return {"par": np.array(X), "value": Fmin, "counts": (funcount, gradcount), "convergence": 1}
+            g = g_(B)
+            G1 = 0.0; G2 = 0.0
+            for i in range(n):
+                X[i] = B[i]
+                if type == 1:
+                    G1 += g[i] * g[i]; G2 += c[i] * c[i]
+                elif type == 2:
+                    G1 += g[i] * (g[i] - c[i]); G2 += c[i] * c[i]
+                else:
+                    G1 += g[i] * (g[i] - c[i]); G2 += t[i] * (g[i] - c[i])
+                c[i] = g[i]
+            if G1 > tol:
+                G3 = G1 / G2 if G2 > 0.0 else 1.0
+                gradproj = 0.0
+                for i in range(n):
+                    t[i] = t[i] * G3 - g[i]
+                    gradproj += t[i] * g[i]
+                steplength = oldstep
+                accpoint = False
+                while True:
+                    count = 0
+                    for i in range(n):
+                        B[i] = X[i] + steplength * t[i]
+                        if _RELTEST + X[i] == _RELTEST + B[i]:
+                            count += 1
+                    if count < n:
+                        f = f_(B)
+                        funcount += 1
+                        accpoint = math.isfinite(f) and f <= Fmin + gradproj * steplength * _ACCTOL
+                        if not accpoint:
+                            steplength *= _STEPREDN
+                        else:
+                            Fmin = f
+                    if count == n or accpoint:
+                        break
+                if count < n:
+                    newstep = 2 * (f - Fmin - gradproj * steplength)
+                    if newstep > 0:
+                        newstep = -(gradproj * steplength * steplength / newstep)
+                        for i in range(n):
+                            B[i] = X[i] + newstep * t[i]
+                        Fmin = f
+                        f = f_(B)
+                        funcount += 1
+                        if f < Fmin:
+                            Fmin = f
+                        else:
+                            for i in range(n):
+                                B[i] = X[i] + steplength * t[i]
+            oldstep = setstep * steplength
+            if oldstep > 1.0:
+                oldstep = 1.0
+            if not ((count != n) and (G1 > tol) and (cycle != cyclimit)):
+                break
+        if not ((cycle != 1) or ((count != n) and (G1 > tol) and Fmin > abstol)):
+            break
+    # like R's optim, the result is the last base point X (not the last trial point)
+    return {"par": np.array(X), "value": Fmin, "counts": (funcount, gradcount), "convergence": fail}