lessPython 0.1.0__py3-none-any.whl

lessPy/corCFA.py

@@ -0,0 +1,316 @@
+# corCFA.py — analog of corCFA.R + cor_mimm.R.
+#
+# corCFA(): a Multiple-Indicator Measurement Model (MIMM)
+# confirmatory factor analysis of a correlation matrix, given a
+# measurement model that assigns items to factors. Reports scale
+# composition, reliability (Cronbach's alpha, McDonald's omega),
+# the item-factor pattern loadings with an indicator diagnostic,
+# the item/factor correlations, the residual correlations, and
+# the lavaan specification, plus a heat map. The core is a direct
+# port of lessR's deterministic .mimm() (sum-of-correlations
+# composites, a communality iteration, then standardization) — no
+# optimization, so it reproduces R exactly.
+#
+# The model is given as a lavaan-style string ("F1 =~ X1 + X2")
+# or as F-keyword lists of item names (F1=["X1","X2"]).
+
+import re
+
+import numpy as np
+import pandas as pd
+
+from .utils import fmt, get_option
+
+
+def _mimm(R, cuts, NItems, NF, Iter):
+    """The MIMM computation. R is the (NItems+NF) square matrix
+    with the item correlations in the top-left block and zeros in
+    the factor rows/cols; cuts[j] = (start, end) item indices of
+    factor j. Returns (expanded correlation matrix, alpha,
+    omega). Direct port of cor_mimm.R .mimm()."""
+    R = R.copy().astype(float)
+    n = NItems + NF
+    # item-factor and factor-factor covariances (column sums)
+    for I in range(n):
+        for J in range(NF):
+            L = NItems + J
+            s = 0.0
+            for K in range(cuts[J][0], cuts[J][1] + 1):
+                s += R[I, K]
+            R[I, L] = s
+            R[L, I] = s
+    # Cronbach's alpha
+    Alpha = np.zeros(NF)
+    for J in range(NF):
+        L = NItems + J
+        N = cuts[J][1] - cuts[J][0] + 1
+        if N == 1:
+            Alpha[J] = 1.0
+        else:
+            DSum = sum(R[I, I]
+                       for I in range(cuts[J][0], cuts[J][1] + 1))
+            XN = float(N)
+            RMean = (R[L, L] - DSum) / (XN * (XN - 1.0))
+            Alpha[J] = (XN * RMean) / ((XN - 1) * RMean + 1.0)
+    # communality iteration
+    if Iter >= 0:
+        for J in range(NF):
+            if Alpha[J] > 0:
+                L = NItems + J
+                for _ in range(Iter):
+                    OldFF = R[L, L]
+                    R[L, L] = 0.0
+                    for I in range(cuts[J][0], cuts[J][1] + 1):
+                        OldII = R[I, I]
+                        R[I, I] = R[I, L] ** 2 / OldFF
+                        R[I, L] = R[I, L] + (R[I, I] - OldII)
+                        R[L, L] += R[I, L]
+    # standardize to correlations
+    for J in range(NF):
+        L = NItems + J
+        FacSD = np.sqrt(R[L, L])
+        for I in range(L + 1):
+            R[I, L] /= FacSD
+            R[L, I] = R[I, L]
+        for I in range(J, NF):
+            LI = NItems + I
+            R[L, LI] /= FacSD
+            R[LI, L] = R[L, LI]
+    # McDonald's omega
+    Omega = np.zeros(NF)
+    for IFac in range(NF):
+        FI = NItems + IFac
+        SumLam = SumUnq = 0.0
+        for J in range(cuts[IFac][0], cuts[IFac][1] + 1):
+            Lam = R[FI, J]
+            SumLam += Lam
+            SumUnq += 1 - Lam ** 2
+        Omega[IFac] = SumLam ** 2 / (SumLam ** 2 + SumUnq)
+        if Iter == 0:
+            Omega[IFac] = 1.0
+    return R, Alpha, Omega
+
+
+class corCFAResults:
+    """Results of corCFA(): the item-factor loadings (if_cor),
+    factor correlations (ff_cor), communalities, alpha, omega,
+    predicted and residual correlations, and the plotly heat map
+    in .plots."""
+
+    def __init__(self, **kw):
+        self.__dict__.update(kw)
+
+    def __repr__(self):
+        return (f"<lessPy corCFA: {len(self.alpha)} factors, "
+                f"{self.if_cor.shape[0]} items>")
+
+
+def _parse_model(model, factors, fkw, cols):
+    """Collect the factor -> item-name lists from a lavaan-style
+    string, a factors dict, or F1=/F2= keyword lists."""
+    fac = {}
+    if model is not None:
+        for line in model.splitlines():
+            line = line.strip()
+            if not line or "=~" not in line:
+                continue
+            name, rhs = line.split("=~")
+            fac[name.strip()] = [t.strip()
+                                 for t in rhs.split("+")]
+    if factors is not None:
+        fac.update({k: list(v) for k, v in factors.items()})
+    for k in sorted(fkw, key=lambda s: int(s[1:])):
+        fac[k] = list(fkw[k])
+    if not fac:
+        raise ValueError(
+            "specify the measurement model: a lavaan-style "
+            'string ("F1 =~ X1 + X2"), factors={...}, or '
+            "F1=[...], F2=[...]")
+    for name, items in fac.items():
+        bad = [it for it in items if it not in cols]
+        if bad:
+            raise ValueError(
+                f"factor {name}: items not in the correlation "
+                f"matrix: {', '.join(bad)}")
+    return fac
+
+
+def corCFA(R, model=None, factors=None, min_cor=0.10,
+           min_res=0.05, iter=50, sort=True, resid=True,
+           item_cor=True, heat_map=True, **fkw):
+    """Confirmatory factor analysis (MIMM) of a correlation
+    matrix R (a DataFrame or array; raw data is correlated
+    first). The measurement model assigns items to factors, given
+    as a lavaan-style string, factors={...}, or F1=[...] lists.
+    Prints reliability, the loadings and diagnostics, residuals,
+    and the lavaan code; returns a corCFAResults. R analog:
+    corCFA()"""
+    Rm = pd.DataFrame(R)
+    vals = Rm.to_numpy(dtype=float)
+    if (Rm.shape[0] != Rm.shape[1]
+            or not np.allclose(vals, vals.T, atol=1e-8)):
+        Rm = Rm.select_dtypes("number").corr()
+    Rm.index = Rm.columns = [str(c) for c in Rm.columns]
+    Cmat = Rm.to_numpy(dtype=float)
+    pos = {c: i for i, c in enumerate(Rm.columns)}
+
+    fac = _parse_model(model, factors, fkw, set(Rm.columns))
+    fac_names = list(fac)
+    NF = len(fac_names)
+    label, cuts = [], []
+    for name in fac_names:
+        start = len(label)
+        for it in fac[name]:
+            label.append(pos[it])
+        cuts.append((start, len(label) - 1))
+    NItems = len(label)
+
+    def run(lab):
+        sub = Cmat[np.ix_(lab, lab)]
+        E = np.zeros((NItems + NF, NItems + NF))
+        E[:NItems, :NItems] = sub
+        return _mimm(E, cuts, NItems, NF, iter)
+
+    Rout, alpha, omega = run(label)
+    if sort:
+        newlab = []
+        for f in range(NF):
+            n1, n2 = cuts[f]
+            order = sorted(range(n1, n2 + 1),
+                           key=lambda j: -Rout[NItems + f, j])
+            newlab += [label[j] for j in order]
+        label = newlab
+        Rout, alpha, omega = run(label)
+
+    items = [Rm.columns[i] for i in label]
+    fcols = fac_names
+    if_cor = pd.DataFrame(Rout[:NItems, NItems:], index=items,
+                          columns=fcols)
+    ff_cor = pd.DataFrame(Rout[NItems:, NItems:], index=fcols,
+                          columns=fcols)
+    commun = pd.Series(np.diag(Rout[:NItems, :NItems]),
+                       index=items)
+
+    lines = _cfa_text(items, fcols, cuts, alpha, omega, iter,
+                      if_cor, Rout, NItems, NF)
+    pred = res = None
+    if resid:
+        pred, res = _residuals(if_cor, ff_cor, Cmat, label,
+                               items, cuts, NItems, NF, lines)
+    lines += _lavaan(fcols, cuts, items)
+    print("\n".join(lines))
+
+    plots = {}
+    if heat_map:
+        plots["heatmap"] = _cfa_heatmap(Rout, items, fcols)
+    return corCFAResults(
+        if_cor=if_cor, ff_cor=ff_cor, communalities=commun,
+        alpha=alpha, omega=omega, pred=pred, resid=res,
+        plots=plots)
+
+
+def _cfa_text(items, fcols, cuts, alpha, omega, iter, if_cor,
+              Rout, NItems, NF):
+    L = ["", "  FACTOR / SCALE COMPOSITION", ""]
+    for f, name in enumerate(fcols):
+        members = items[cuts[f][0]:cuts[f][1] + 1]
+        L.append(f"{name}:  " + "  ".join(members))
+    L += ["", "", "  RELIABILITY ANALYSIS", ""]
+    w = max(6, max(len(s) for s in fcols))
+    hdr = f"{'Scale':<{w}}{'Alpha':>9}"
+    if iter > 0:
+        hdr += f"{'Omega':>9}"
+    L.append(hdr)
+    for f, name in enumerate(fcols):
+        row = f"{name:<{w}}{fmt(alpha[f], 3):>9}"
+        if iter > 0:
+            row += f"{fmt(omega[f], 3):>9}"
+        L.append(row)
+    if iter > 0:
+        iw = max(10, max(len(s) for s in items) + 1)
+        L += ["", "", "  SOLUTION", "", "Indicator Analysis", "",
+              f"{'Factor':<8}{'Indicator':<{iw}}"
+              f"{'Pattern':>9}{'Unique':>9}   Diagnostics"]
+        for f, name in enumerate(fcols):
+            for it_i in range(cuts[f][0], cuts[f][1] + 1):
+                item = items[it_i]
+                lam = Rout[NItems + f, it_i]
+                unique = 1 - lam ** 2
+                diag = ""
+                if lam <= 0:
+                    diag = "** Negative loading on own factor **"
+                    unq = "   xxxx"
+                elif unique <= 0:
+                    diag = ("** Improper loading **"
+                            if cuts[f][1] > cuts[f][0]
+                            else "** Factor defined by one item **")
+                    unq = fmt(unique, 3)
+                else:
+                    unq = fmt(unique, 3)
+                    bad = [g + 1 for g in range(NF)
+                           if abs(Rout[NItems + g, it_i]) > lam]
+                    if bad:
+                        diag = " ".join(f"F{b}" for b in bad)
+                L.append(f"F{f + 1:<7}{item:<{iw}}"
+                         f"{fmt(lam, 3):>9}{unq:>9}   {diag}")
+    return L
+
+
+def _residuals(if_cor, ff_cor, Cmat, label, items, cuts, NItems,
+               NF, lines):
+    lam = np.zeros((NItems, NF))
+    for f in range(NF):
+        for i in range(cuts[f][0], cuts[f][1] + 1):
+            lam[i, f] = if_cor.iloc[i, f]
+    phi = ff_cor.to_numpy()
+    estR = lam @ phi @ lam.T
+    np.fill_diagonal(estR, 1.0)
+    Ritems = Cmat[np.ix_(label, label)]
+    resR = np.round(Ritems - estR, 5)
+    np.fill_diagonal(resR, 0.0)
+    pred = pd.DataFrame(np.round(estR, 5), index=items,
+                        columns=items)
+    res = pd.DataFrame(resR, index=items, columns=items)
+
+    ssq_tot = float((resR ** 2).sum())
+    n = NItems
+    rmsr = np.sqrt(ssq_tot / (n * n - n))
+    avg_abs = float(np.abs(resR).sum()) / (n * n - n)
+    lines += ["", "", "  RESIDUALS", "",
+              f"Total sum of squares for all items: "
+              f"{fmt(ssq_tot, 3)}",
+              f"Root mean square residual (RMSR): {fmt(rmsr, 3)}",
+              f"Average absolute residual off-diagonal: "
+              f"{fmt(avg_abs, 3)}"]
+    return pred, res
+
+
+def _lavaan(fcols, cuts, items):
+    L = ["", "", "  LAVAAN / semopy SPECIFICATION", "",
+         "MeasModel = \"\"\""]
+    for f, name in enumerate(fcols):
+        members = items[cuts[f][0]:cuts[f][1] + 1]
+        L.append(f"  {name} =~ " + " + ".join(members))
+    L += ["\"\"\"",
+          "# lavaan (R):  cfa(MeasModel, data=d, std.lv=True)",
+          "# semopy (Python):  Model(MeasModel).fit(d)"]
+    return L
+
+
+def _cfa_heatmap(Rout, items, fcols):
+    import plotly.graph_objects as go
+    from .plotly_utils import plotly_style, to_hex
+    labels = items + fcols
+    style = plotly_style()
+    fig = go.Figure(go.Heatmap(
+        z=Rout, x=labels, y=labels, zmin=-1, zmax=1,
+        colorscale="RdBu", reversescale=True,
+        colorbar=dict(title="r")))
+    fig.update_yaxes(autorange="reversed")
+    fig.update_layout(
+        template=None, paper_bgcolor=to_hex(style["window_fill"]),
+        title=dict(text="Item / Factor Correlations", x=0.5,
+                   xanchor="center",
+                   font=dict(size=round(
+                       16 * get_option("main_size", 1)))))
+    return fig

lessPy/corEFA.py

@@ -0,0 +1,220 @@
+# corEFA.py — analog of corEFA.R.
+#
+# corEFA(): exploratory factor analysis of a correlation matrix,
+# maximum-likelihood extraction (a direct port of R's factanal
+# ML algorithm) with promax, varimax, or no rotation (ports of
+# R's promax()/varimax()). Reports the sorted loadings (small
+# ones blanked), the sum-of-squares table, and a generated
+# measurement-model string assigning each item to the factor of
+# its largest loading, plus any items deleted for loading below
+# min_loading. Returns a corEFAResults object.
+#
+# The numerics reproduce R to ~4 decimals: same optimizer
+# objective/gradient, same Kaiser-normalized varimax, same
+# promax power=4 target. Input is a correlation matrix (a
+# DataFrame or array); raw data is correlated first.
+
+import numpy as np
+import pandas as pd
+
+from .utils import fmt
+
+
+def _factanal(S, q):
+    """Maximum-likelihood factor extraction: optimize the
+    uniquenesses, then form the loadings from the top-q
+    eigenvectors of the scaled correlation matrix. Direct port of
+    R's factanal.fit.mle (FAfn/FAgr/FAout)."""
+    from scipy.optimize import minimize
+    p = S.shape[0]
+
+    def eig(psi):
+        sc = 1 / np.sqrt(psi)
+        v, V = np.linalg.eigh(sc[:, None] * S * sc[None, :])
+        return v[::-1], V[:, ::-1]                # descending
+
+    def out(psi):
+        v, V = eig(psi)
+        load = V[:, :q] * np.sqrt(np.maximum(v[:q] - 1, 0))
+        return np.sqrt(psi)[:, None] * load
+
+    def fn(psi):
+        v, _ = eig(psi)
+        e = v[q:]
+        return -(np.sum(np.log(e) - e) - q + p)
+
+    def gr(psi):
+        load = out(psi)
+        g = load @ load.T + np.diag(psi) - S
+        return np.diag(g) / psi ** 2
+
+    start = (1 - 0.5 * q / p) / np.diag(np.linalg.inv(S))
+    res = minimize(fn, start, jac=gr, method="L-BFGS-B",
+                   bounds=[(0.005, 1)] * p)
+    return out(res.x), bool(res.success)
+
+
+def _sort_extract(L):
+    """factanal's sortLoadings: order factors by descending SS,
+    flip each column so its loadings sum to a positive value."""
+    L = L[:, np.argsort(-(L ** 2).sum(0))]
+    neg = L.sum(0) < 0
+    L[:, neg] *= -1
+    return L
+
+
+def _varimax(x, normalize=True, eps=1e-5):
+    """Kaiser-normalized varimax. Port of R's stats::varimax."""
+    nc = x.shape[1]
+    if nc < 2:
+        return x
+    x = x.copy()
+    if normalize:
+        sc = np.sqrt((x ** 2).sum(1))
+        x = x / sc[:, None]
+    p, TT, d = x.shape[0], np.eye(nc), 0.0
+    for _ in range(1000):
+        z = x @ TT
+        B = x.T @ (z ** 3 - z @ np.diag((z ** 2).sum(0)) / p)
+        U, s, Vt = np.linalg.svd(B)
+        TT = U @ Vt
+        d, dpast = s.sum(), d
+        if d < dpast * (1 + eps):
+            break
+    z = x @ TT
+    return z * sc[:, None] if normalize else z
+
+
+def _promax(x, m=4):
+    """Promax oblique rotation, power m=4. Port of R's
+    stats::promax (varimax, then oblique target)."""
+    if x.shape[1] < 2:
+        return x
+    xv = _varimax(x)
+    Q = xv * np.abs(xv) ** (m - 1)
+    U = np.linalg.lstsq(xv, Q, rcond=None)[0]
+    U = U @ np.diag(np.sqrt(np.diag(np.linalg.inv(U.T @ U))))
+    return xv @ U
+
+
+class corEFAResults:
+    """Results of corEFA(): the sorted loadings DataFrame, the
+    sum-of-squares table, the measurement model string, and the
+    convergence flag."""
+
+    def __init__(self, **kw):
+        self.__dict__.update(kw)
+
+    def __repr__(self):
+        return (f"<lessPy corEFA: {self.n_factors} factors, "
+                f"{self.loadings.shape[0]} items>")
+
+
+def corEFA(R, n_factors, rotate="promax", min_loading=0.2,
+           sort=True):
+    """Exploratory factor analysis of a correlation matrix R
+    (a DataFrame or array; raw data is correlated first).
+    Maximum-likelihood extraction with rotate= "promax" (default),
+    "varimax", or "none". Prints the loadings, the sum-of-squares
+    table, and the measurement-model code; returns a
+    corEFAResults. R analog: corEFA()"""
+    if rotate not in ("promax", "varimax", "none"):
+        raise ValueError('rotate: "promax", "varimax", "none"')
+    Rm = pd.DataFrame(R)
+    vals = Rm.to_numpy(dtype=float)
+    if (Rm.shape[0] != Rm.shape[1]
+            or not np.allclose(vals, vals.T, atol=1e-8)):
+        Rm = Rm.select_dtypes("number").corr()   # raw data
+    names = [str(c) for c in Rm.columns]
+    S = Rm.to_numpy(dtype=float)
+
+    Lam, converged = _factanal(S, n_factors)
+    Lam = _sort_extract(Lam)
+    if n_factors > 1 and rotate != "none":
+        Lam = _promax(Lam) if rotate == "promax" else _varimax(Lam)
+
+    fac = [f"Factor{i + 1}" for i in range(n_factors)]
+    ld = pd.DataFrame(Lam, index=names, columns=fac)
+
+    if sort and n_factors > 1:
+        top = np.argmax(np.abs(ld.to_numpy()), axis=1)
+        order = []
+        for f in range(n_factors):
+            items = [i for i in range(len(ld)) if top[i] == f]
+            items.sort(key=lambda i: -abs(ld.iloc[i, f]))
+            order += items
+        ld = ld.iloc[order]
+
+    print("\n".join(_efa_output(ld, n_factors, rotate,
+                                min_loading, converged)))
+    model, deleted = _cfa_model(ld, n_factors, min_loading)
+    ss = _ss_table(ld, n_factors)
+    return corEFAResults(
+        loadings=ld, ss=ss, model=model, deleted=deleted,
+        converged=converged, n_factors=n_factors)
+
+
+def _ss_table(ld, n_factors):
+    v = (ld ** 2).sum(axis=0)
+    n = ld.shape[0]
+    rows = {"SS loadings": v, "Proportion Var": v / n}
+    if n_factors > 1:
+        rows["Cumulative Var"] = np.cumsum(v / n)
+    return pd.DataFrame(rows).T
+
+
+def _efa_output(ld, n_factors, rotate, min_loading, converged):
+    L = ["", "  EXPLORATORY FACTOR ANALYSIS", "",
+         "Extraction: maximum likelihood"]
+    if n_factors > 1:
+        L.append(f"Rotation: {rotate}")
+    if not converged:
+        L.append(">>> Warning: extraction did not fully converge")
+    L += ["", f"Loadings (except -{min_loading} to "
+          f"{min_loading})", ""]
+    w = max(len(s) for s in ld.index)
+    L.append(" " * w + "".join(f"{c:>10}" for c in ld.columns))
+    for item, row in ld.iterrows():
+        cells = "".join(
+            (f"{fmt(v, 3):>10}" if abs(v) >= min_loading
+             else " " * 10) for v in row)
+        L.append(f"{item:<{w}}{cells}")
+    # sum of squares
+    ss = _ss_table(ld, n_factors)
+    L += ["", "Sum of Squares", ""]
+    w2 = max(len(s) for s in ss.index)
+    L.append(" " * w2 + "".join(f"{c:>10}" for c in ss.columns))
+    for lbl, row in ss.iterrows():
+        L.append(f"{lbl:<{w2}}"
+                 + "".join(f"{fmt(v, 3):>10}" for v in row))
+    return L
+
+
+def _cfa_model(ld, n_factors, min_loading):
+    """Assign each item to the factor of its largest loading (if
+    above min_loading), build the F# =~ items measurement model
+    string, and collect deleted items. ~ corEFA MIMM code."""
+    lv = ld.to_numpy()
+    items = list(ld.index)
+    assign = []
+    for i in range(len(items)):
+        j = int(np.argmax(np.abs(lv[i])))
+        assign.append(j if abs(lv[i, j]) > min_loading else -1)
+
+    lines = []
+    for f in range(n_factors):
+        members = [items[i] for i in range(len(items))
+                   if assign[i] == f]
+        if members:
+            lines.append(f"  F{f + 1} =~ " + " + ".join(members))
+    model = "\n".join(lines)
+
+    deleted = [items[i] for i in range(len(items))
+               if assign[i] == -1]
+    print("\n".join(
+        ["", "  MEASUREMENT MODEL (for confirmatory analysis)",
+         "", model]
+        + (["", f"Deletion threshold: min_loading = {min_loading}",
+            "Deleted items: " + " ".join(deleted)]
+           if deleted else [])))
+    return model, deleted

lessPy/corPrint.py

@@ -0,0 +1,45 @@
+# corPrint.py — analog of corPrint.R.
+#
+# corPrint(): print a correlation matrix in lessR's compact
+# style — two decimals with the leading "0." stripped (0.85 ->
+# "85", -0.07 -> "-07"), the diagonal 1.00 shown as "100", and
+# any coefficient with |r| < min_value blanked. Prints the
+# formatted matrix and returns it as a text string.
+
+import numpy as np
+import pandas as pd
+
+
+def _compact(v):
+    s = f"{v:.2f}".replace("0.", "")        # 0.85 -> "85"
+    return s.replace("1.00", "100").replace("-1.00", "-100")
+
+
+def corPrint(R, min_value=0):
+    """Print a correlation matrix R (a DataFrame or array; raw
+    data is correlated first) in the compact lessR style, blanking
+    coefficients with |r| < min_value. Returns the formatted text.
+    R analog: corPrint()"""
+    Rm = pd.DataFrame(R)
+    vals = Rm.to_numpy(dtype=float)
+    if (Rm.shape[0] != Rm.shape[1]
+            or not np.allclose(vals, vals.T, atol=1e-8)):
+        Rm = Rm.select_dtypes("number").corr()
+        vals = Rm.to_numpy(dtype=float)
+    names = [str(c) for c in Rm.columns]
+    n = len(names)
+    lab_w = max(len(s) for s in names) + 2
+    col_w = [max(4, len(nm) + 1) for nm in names]
+
+    lines = [" " * lab_w + "".join(
+        nm.rjust(col_w[j]) for j, nm in enumerate(names))]
+    for i in range(n):
+        row = (" " + names[i]).rjust(lab_w)
+        for j in range(n):
+            v = vals[i, j]
+            cell = "" if abs(v) < min_value else _compact(v)
+            row += cell.rjust(col_w[j])
+        lines.append(row)
+    text = "\n".join(lines)
+    print(text)
+    return text

lessPy/corProp.py

@@ -0,0 +1,73 @@
+# corProp.py — analog of corProp.R.
+#
+# corProp(): the item proportionality matrix — for each pair of
+# items, how similarly they correlate with all the OTHER items
+# (the correlation of their two correlation profiles, excluding
+# the pair itself). A high value means two items are nearly
+# interchangeable indicators, useful in scale construction.
+# Returns the proportionality matrix (rounded to 2 as in R); the
+# heat map is on the returned frame's .attrs["plots"].
+
+import numpy as np
+import pandas as pd
+
+from .utils import get_option
+
+
+def corProp(R, main=None, heat_map=True):
+    """Item proportionality coefficients of a correlation matrix
+    R (a DataFrame or array; raw data is correlated first): the
+    profile similarity of each item pair across the other items.
+    Returns the proportionality matrix DataFrame (rounded to 2,
+    as R); its .attrs["plots"] holds the heat map. R analog:
+    corProp()"""
+    Rm = pd.DataFrame(R)
+    vals = Rm.to_numpy(dtype=float)
+    if (Rm.shape[0] != Rm.shape[1]
+            or not np.allclose(vals, vals.T, atol=1e-8)):
+        Rm = Rm.select_dtypes("number").corr()
+    Rm.index = Rm.columns = [str(c) for c in Rm.columns]
+    S = Rm.to_numpy(dtype=float)
+
+    # Diag[i] = sum_k R[k,i]^2 ; RR = R @ R (the cross products).
+    # For a pair (i,j) exclude i and j from both the cross product
+    # and the two sums of squares, then normalize. ~ corProp.R
+    diag = np.diag(S)
+    Diag = (S ** 2).sum(axis=0)
+    RR = S @ S
+    cross = RR - S * (diag[:, None] + diag[None, :])
+    D1 = Diag[:, None] - (diag[:, None] ** 2 + S ** 2)
+    D2 = Diag[None, :] - (diag[None, :] ** 2 + S ** 2)
+    with np.errstate(invalid="ignore", divide="ignore"):
+        P = cross / np.sqrt(D1 * D2)
+    np.fill_diagonal(P, 1.0)
+    P = np.round(P, 2)
+
+    out = pd.DataFrame(P, index=Rm.index, columns=Rm.columns)
+    plots = {}
+    if heat_map:
+        plots["heatmap"] = _heatmap(out, main)
+    out.attrs["plots"] = plots
+    return out
+
+
+def _heatmap(df, main):
+    import plotly.graph_objects as go
+
+    from .plotly_utils import plotly_style, to_hex
+    labels = list(df.columns)
+    Z = df.to_numpy(dtype=float).copy()
+    np.fill_diagonal(Z, np.nan)            # ignore the diagonal
+    style = plotly_style()
+    fig = go.Figure(go.Heatmap(
+        z=Z, x=labels, y=labels, zmin=-1, zmax=1,
+        colorscale="RdBu", reversescale=True,
+        colorbar=dict(title="prop")))
+    fig.update_yaxes(autorange="reversed")
+    fig.update_layout(
+        template=None, paper_bgcolor=to_hex(style["window_fill"]),
+        title=dict(text=main or "Item Proportionalities", x=0.5,
+                   xanchor="center",
+                   font=dict(size=round(
+                       16 * get_option("main_size", 1)))))
+    return fig