eemkit 0.1.0__py3-none-any.whl

eemkit/parafac/_cp.py

@@ -0,0 +1,125 @@
+"""Non-negative CP/PARAFAC of a 3-way array with missing values (numpy only).
+
+Algorithm: alternating updates of the three factor matrices with HALS
+(hierarchical alternating least squares; Cichocki & Phan 2009, IEICE Trans.
+Fundamentals E92-A:708-721), which solves each column's non-negative least
+squares problem exactly. Missing values are handled by expectation-
+maximisation: before each sweep they are replaced by the current model
+(Tomasi & Bro 2005, Chemometr. Intell. Lab. Syst. 75:163-180), the approach of
+the N-way toolbox used by drEEM.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+EPS = 1e-16  # floor for non-negative entries; keeps HALS columns from dying
+
+
+@dataclass
+class CPResult:
+    A: np.ndarray
+    B: np.ndarray
+    C: np.ndarray
+    sse: float
+    n_iter: int
+    converged: bool
+    sse_trace: list[float] = field(default_factory=list)
+
+
+def khatri_rao(P: np.ndarray, Q: np.ndarray) -> np.ndarray:
+    """Column-wise Kronecker product; row index p * len(Q) + q."""
+    return (P[:, None, :] * Q[None, :, :]).reshape(-1, P.shape[1])
+
+
+def unfold(X: np.ndarray, mode: int) -> np.ndarray:
+    return np.moveaxis(X, mode, 0).reshape(X.shape[mode], -1)
+
+
+def reconstruct(A: np.ndarray, B: np.ndarray, C: np.ndarray) -> np.ndarray:
+    return (khatri_rao(A, B) @ C.T).reshape(A.shape[0], B.shape[0], C.shape[0])
+
+
+def _hals_update(M: np.ndarray, R: np.ndarray, G: np.ndarray) -> None:
+    """In-place HALS sweep over the columns of M for min ||X_(n) - M P^T||, M >= 0."""
+    for f in range(M.shape[1]):
+        if G[f, f] <= 0:
+            continue
+        M[:, f] = np.maximum(EPS, M[:, f] + (R[:, f] - M @ G[:, f]) / G[f, f])
+
+
+def _balance(A: np.ndarray, B: np.ndarray, C: np.ndarray) -> None:
+    """Unit-norm columns for B and C; the scale goes into A."""
+    nb = np.linalg.norm(B, axis=0)
+    nc = np.linalg.norm(C, axis=0)
+    nb[nb == 0] = 1
+    nc[nc == 0] = 1
+    B /= nb
+    C /= nc
+    A *= nb * nc
+
+
+def nn_parafac(
+    X: np.ndarray,
+    rank: int,
+    *,
+    init: tuple[np.ndarray, np.ndarray, np.ndarray] | None = None,
+    random_state: int | np.random.Generator | None = None,
+    tol: float = 1e-8,
+    max_iter: int = 5000,
+) -> CPResult:
+    """Fit X (I x J x K, NaN = missing) ~ sum_f a_f o b_f o c_f with A, B, C >= 0.
+
+    Stops when the relative decrease of the residual sum of squares over the
+    observed entries falls below ``tol``, or after ``max_iter`` sweeps.
+    """
+    X = np.asarray(X, dtype=float)
+    if X.ndim != 3:
+        raise ValueError("X must be 3-way")
+    observed = np.isfinite(X)
+    if not observed.any():
+        raise ValueError("X has no observed values")
+    rng = np.random.default_rng(random_state)
+    n_i, n_j, n_k = X.shape
+    if init is None:
+        A = rng.random((n_i, rank))
+        B = rng.random((n_j, rank))
+        C = rng.random((n_k, rank))
+    else:
+        A, B, C = (np.array(m, dtype=float, copy=True) for m in init)
+    A, B, C = (np.maximum(m, EPS) for m in (A, B, C))
+    _balance(A, B, C)
+
+    has_missing = not observed.all()
+    # least-squares scale of the random start, so missing values start near the data
+    model = reconstruct(A, B, C)
+    s = np.sum(X[observed] * model[observed]) / max(np.sum(model[observed] ** 2), EPS)
+    A *= max(s, EPS)
+    model *= max(s, EPS)
+    Xf = X
+
+    trace: list[float] = []
+    prev = np.inf
+    converged = False
+    n_iter = 0
+    for n_iter in range(1, max_iter + 1):  # noqa: B007 (n_iter is reported after the loop)
+        if has_missing:
+            Xf = np.where(observed, X, model)
+        # MTTKRPs as BLAS products without unfolding copies: T = X x3 C (I x J x F)
+        T = Xf @ C
+        _hals_update(A, np.einsum("ijf,jf->if", T, B), (B.T @ B) * (C.T @ C))
+        _hals_update(B, np.einsum("ijf,if->jf", T, A), (A.T @ A) * (C.T @ C))
+        _hals_update(C, Xf.reshape(n_i * n_j, n_k).T @ khatri_rao(A, B),
+                     (A.T @ A) * (B.T @ B))
+        _balance(A, B, C)
+
+        model = reconstruct(A, B, C)
+        sse = float(np.sum((X - model)[observed] ** 2))
+        trace.append(sse)
+        if np.isfinite(prev) and abs(prev - sse) <= tol * max(prev, EPS):
+            converged = True
+            break
+        prev = sse
+    return CPResult(A, B, C, trace[-1], n_iter, converged, trace)

eemkit/parafac/diagnostics.py

@@ -0,0 +1,56 @@
+"""Model diagnostics: core consistency, leverage, congruence and component matching."""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+
+
+def core_consistency(X: np.ndarray, A: np.ndarray, B: np.ndarray, C: np.ndarray) -> float:
+    """CORCONDIA in percent (Bro & Kiers 2003, J. Chemometrics 17:274-286).
+
+    The least-squares Tucker3 core for the given loadings is
+    ``X x1 A+ x2 B+ x3 C+`` (``+`` = pseudo-inverse); with ``T`` the
+    superdiagonal identity core, ``CC = 100 (1 - ||G - T||^2 / F)``.
+    ``X`` must be complete: impute missing values (e.g. with the model) first.
+    """
+    if not np.isfinite(X).all():
+        raise ValueError("core_consistency needs a complete array; impute missing values")
+    F = A.shape[1]
+    G = np.tensordot(np.linalg.pinv(A), X, axes=(1, 0))  # F x J x K
+    G = np.tensordot(G, np.linalg.pinv(B), axes=(1, 1))  # F x K x F
+    G = np.tensordot(G, np.linalg.pinv(C), axes=(1, 1))  # F x F x F
+    T = np.zeros((F, F, F))
+    T[np.arange(F), np.arange(F), np.arange(F)] = 1.0
+    return float(100.0 * (1.0 - np.sum((G - T) ** 2) / F))
+
+
+def leverage(M: np.ndarray) -> np.ndarray:
+    """Leverage of each row of a loading matrix: diag(M (M^T M)^-1 M^T)."""
+    return np.einsum("if,fg,ig->i", M, np.linalg.pinv(M.T @ M), M)
+
+
+def tucker_congruence(P: np.ndarray, Q: np.ndarray) -> np.ndarray:
+    """Tucker's congruence coefficients between the columns of P and Q (F_P x F_Q)."""
+    P = np.asarray(P, dtype=float)
+    Q = np.asarray(Q, dtype=float)
+    num = P.T @ Q
+    den = np.outer(np.linalg.norm(P, axis=0), np.linalg.norm(Q, axis=0))
+    with np.errstate(invalid="ignore", divide="ignore"):
+        return num / den
+
+
+def match_components(
+    ex1: np.ndarray, em1: np.ndarray, ex2: np.ndarray, em2: np.ndarray
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Pair components of two models by maximising the product of ex and em congruence.
+
+    Returns ``(order2, tcc_ex, tcc_em)``: model 2's component ``order2[f]``
+    matches model 1's component ``f``, with the congruences of each pair.
+    """
+    tex = tucker_congruence(ex1, ex2)
+    tem = tucker_congruence(em1, em2)
+    rows, cols = linear_sum_assignment(-(tex * tem))
+    order = cols[np.argsort(rows)]
+    f = np.arange(len(order))
+    return order, tex[f, order], tem[f, order]

eemkit/parafac/export.py

@@ -0,0 +1,54 @@
+"""Export of PARAFAC loadings in the OpenFluor text format.
+
+OpenFluor (openfluor.org; Murphy et al. 2014, Anal. Methods 6:658-661)
+accepts a tab-separated file: '#' comment lines, a block of ``key<TAB>value``
+metadata, then one line per wavelength, ``Ex`` or ``Em`` followed by the
+wavelength and the loading of each component. This follows the layout written
+by drEEM's ``openfluor`` function; check the file against the current
+OpenFluor upload template before submitting.
+"""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+
+import xarray as xr
+
+METADATA_KEYS = ("name", "creator", "email", "doi", "reference", "unit", "toolbox", "date",
+                 "fluorometer", "nSample", "constraints", "validation", "methods",
+                 "preprocess", "sources", "ecozones", "description")
+
+
+def to_openfluor(model: xr.Dataset, path: str | Path, **metadata: str) -> Path:
+    """Write ``model``'s excitation and emission loadings for OpenFluor.
+
+    Loadings are scaled to a maximum of 1 per component (OpenFluor compares
+    shapes). Unknown metadata are written as '?'; pass e.g. ``name=``,
+    ``creator=``, ``doi=``, ``description=``. Fields derived from the model
+    (unit, toolbox, date, nSample, constraints) are filled in unless given.
+    """
+    from eemkit import __version__
+
+    unknown = set(metadata) - set(METADATA_KEYS)
+    if unknown:
+        raise ValueError(f"unknown OpenFluor metadata {sorted(unknown)}; use {METADATA_KEYS}")
+    meta = {k: "?" for k in METADATA_KEYS}
+    meta.update(unit=str(model["scores"].attrs.get("units", "?")) or "?",
+                toolbox=f"eemkit {__version__}", date=date.today().isoformat(),
+                nSample=str(model.sizes["sample"]), constraints="non-negativity")
+    meta.update({k: str(v) for k, v in metadata.items()})
+
+    ex = model["ex_loadings"] / model["ex_loadings"].max("ex")
+    em = model["em_loadings"] / model["em_loadings"].max("em")
+    lines = ["#", "# Fluorescence Model", "#"]
+    lines += [f"{k}\t{meta[k]}" for k in METADATA_KEYS]
+    lines += ["#", "# Excitation/Emission (Ex, Em), wavelength [nm], component[n] [intensity]",
+              "#"]
+    for label, da, dim in (("Ex", ex, "ex"), ("Em", em, "em")):
+        for w in da[dim].values:
+            vals = da.sel({dim: w}).values
+            lines.append("\t".join([label, f"{w:g}"] + [f"{v:.6g}" for v in vals]))
+    path = Path(path)
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return path

eemkit/parafac/model.py

@@ -0,0 +1,191 @@
+"""Fitting PARAFAC models to an EEM dataset and packaging the result."""
+
+from __future__ import annotations
+
+import json
+import warnings
+
+import numpy as np
+import xarray as xr
+
+from eemkit.core.dataset import SAMPLE_DIM
+from eemkit.core.history import HISTORY_ATTR, get_history, make_entry
+from eemkit.errors import EEMKitWarning
+from eemkit.parafac._cp import nn_parafac, reconstruct
+from eemkit.parafac.diagnostics import core_consistency, leverage
+
+NORMALIZATIONS = ("norm", None)
+
+#: two runs whose SSE differs by less than this fraction are considered the same minimum
+SAME_MINIMUM_RTOL = 1e-3
+
+
+def _sample_scale(X: np.ndarray, normalization: str | None) -> np.ndarray:
+    if normalization is None:
+        return np.ones(X.shape[0])
+    if normalization == "norm":
+        s = np.sqrt(np.nansum(X ** 2, axis=(1, 2)))
+        if np.any(s == 0):
+            raise ValueError("a sample is all zero/NaN and cannot be normalised")
+        return s
+    raise ValueError(f"normalization must be one of {NORMALIZATIONS}")
+
+
+def fit_parafac(
+    ds: xr.Dataset,
+    rank: int,
+    *,
+    n_init: int = 10,
+    normalization: str | None = "norm",
+    tol: float = 1e-8,
+    max_iter: int = 5000,
+    random_state: int = 0,
+    variable: str = "intensity",
+) -> xr.Dataset:
+    """Non-negative PARAFAC of ``ds[variable]`` (sample, ex, em), best of ``n_init`` starts.
+
+    Parameters
+    ----------
+    rank
+        Number of components.
+    n_init
+        Random starts (seeds ``random_state``, ``random_state + 1``, ...). The
+        lowest-SSE fit is kept; all SSEs are stored to judge whether the
+        solution is reproducible.
+    normalization
+        ``"norm"``: each sample is divided by its Frobenius norm before
+        fitting and the scores are scaled back afterwards (Murphy et al. 2013);
+        ``None``: no scaling.
+    tol, max_iter
+        Convergence: relative SSE change below ``tol``.
+
+    Returns
+    -------
+    xarray.Dataset
+        ``scores(sample, component)`` in the units of the data (after undoing
+        the normalisation), ``ex_loadings(ex, component)`` and
+        ``em_loadings(em, component)`` with unit Euclidean norm, ``fmax``
+        (sample, component) = maximum fluorescence of each component in each
+        sample, leverages for every mode, per-sample residual SSE, and in
+        ``attrs`` the fit statistics (SSE, explained variance, core
+        consistency, iterations, all starts). Components are sorted by
+        decreasing contribution to the modelled sum of squares.
+    """
+    da = ds[variable].transpose(SAMPLE_DIM, "ex", "em")
+    X = da.values.astype(float)
+    scale = _sample_scale(X, normalization)
+    Xn = X / scale[:, None, None]
+
+    fits = []
+    for k in range(n_init):
+        fits.append(nn_parafac(Xn, rank, random_state=random_state + k, tol=tol,
+                               max_iter=max_iter))
+    sses = np.array([f.sse for f in fits])
+    best = fits[int(np.argmin(sses))]
+    if not best.converged:
+        warnings.warn(f"rank {rank}: best start did not converge in {max_iter} iterations",
+                      EEMKitWarning, stacklevel=2)
+
+    A, B, C = best.A.copy(), best.B.copy(), best.C.copy()
+    contrib = np.array([np.sum(np.einsum("i,j,k->ijk", A[:, f], B[:, f], C[:, f]) ** 2)
+                        for f in range(rank)])
+    order = np.argsort(-contrib)
+    A, B, C = A[:, order], B[:, order], C[:, order]
+
+    observed = np.isfinite(Xn)
+    model_n = reconstruct(A, B, C)
+    filled = np.where(observed, Xn, model_n)
+    cc = core_consistency(filled, A, B, C) if rank > 1 else 100.0
+    resid_n = np.where(observed, Xn - model_n, np.nan)
+    sse_n = float(np.nansum(resid_n ** 2))
+    explained = 100.0 * (1.0 - sse_n / float(np.nansum(Xn ** 2)))
+
+    scores = A * scale[:, None]
+    resid = resid_n * scale[:, None, None]
+    comp = np.arange(1, rank + 1)
+    sample_coords = {c: ds[c] for c in ds.coords
+                     if c != SAMPLE_DIM and ds[c].dims == (SAMPLE_DIM,)}
+    out = xr.Dataset(
+        {
+            "scores": ((SAMPLE_DIM, "component"), scores,
+                       {"units": da.attrs.get("units", ""),
+                        "long_name": "component scores (normalisation undone)"}),
+            "ex_loadings": (("ex", "component"), B,
+                            {"long_name": "excitation loadings, unit norm"}),
+            "em_loadings": (("em", "component"), C,
+                            {"long_name": "emission loadings, unit norm"}),
+            "fmax": ((SAMPLE_DIM, "component"), scores * B.max(axis=0) * C.max(axis=0),
+                     {"units": da.attrs.get("units", ""),
+                      "long_name": "maximum fluorescence of each component"}),
+            "leverage_sample": ((SAMPLE_DIM,), leverage(A)),
+            "leverage_ex": (("ex",), leverage(B)),
+            "leverage_em": (("em",), leverage(C)),
+            "sse_sample": ((SAMPLE_DIM,), np.nansum(resid ** 2, axis=(1, 2))),
+            "sse_sample_normalized": ((SAMPLE_DIM,), np.nansum(resid_n ** 2, axis=(1, 2))),
+            "init_sse": (("init",), sses),
+            "init_n_iter": (("init",), [f.n_iter for f in fits]),
+            "init_converged": (("init",), [f.converged for f in fits]),
+        },
+        coords={SAMPLE_DIM: da[SAMPLE_DIM].values, "ex": da["ex"].values,
+                "em": da["em"].values, "component": comp, "init": np.arange(n_init),
+                **sample_coords},
+    )
+    n_same = int(np.sum(sses <= sses.min() * (1 + SAME_MINIMUM_RTOL)))
+    out.attrs = {
+        "rank": rank,
+        "sse_normalized": sse_n,
+        "explained_variance_pct": explained,
+        "core_consistency_pct": cc,
+        "n_iter": best.n_iter,
+        "converged": int(best.converged),
+        "n_init": n_init,
+        "n_init_at_best_minimum": n_same,
+        "normalization": str(normalization),
+        "tol": tol,
+        "max_iter": max_iter,
+        "random_state": random_state,
+        "algorithm": "non-negative ALS (HALS updates, EM imputation of missing values)",
+        "fraction_missing": float(1 - observed.mean()),
+        "spectral_correction": ds.attrs.get("spectral_correction", "none"),
+    }
+    history = get_history(ds) + [make_entry(
+        "fit_parafac", rank=rank, n_init=n_init, normalization=normalization, tol=tol,
+        max_iter=max_iter, random_state=random_state, variable=variable)]
+    out.attrs[HISTORY_ATTR] = json.dumps(history)
+    return out
+
+
+def model_eem(model: xr.Dataset) -> xr.DataArray:
+    """Modelled EEMs (sample, ex, em) in data units."""
+    vals = reconstruct(model["scores"].values, model["ex_loadings"].values,
+                       model["em_loadings"].values)
+    return xr.DataArray(vals, dims=(SAMPLE_DIM, "ex", "em"),
+                        coords={SAMPLE_DIM: model[SAMPLE_DIM].values, "ex": model["ex"].values,
+                                "em": model["em"].values})
+
+
+def residuals(model: xr.Dataset, ds: xr.Dataset, variable: str = "intensity") -> xr.DataArray:
+    """Data minus model (NaN where data are missing)."""
+    data = ds[variable].transpose(SAMPLE_DIM, "ex", "em").sel(
+        {SAMPLE_DIM: model[SAMPLE_DIM].values})
+    return (data - model_eem(model)).rename("residual")
+
+
+def fit_ranks(ds: xr.Dataset, ranks, **kwargs) -> dict[int, xr.Dataset]:
+    """:func:`fit_parafac` for each rank."""
+    return {r: fit_parafac(ds, r, **kwargs) for r in ranks}
+
+
+def summary_table(models: dict[int, xr.Dataset]):
+    """One row per rank with the fit statistics."""
+    import pandas as pd
+
+    rows = []
+    for r, m in sorted(models.items()):
+        a = m.attrs
+        rows.append({"rank": r, "explained_pct": a["explained_variance_pct"],
+                     "core_consistency_pct": a["core_consistency_pct"],
+                     "sse_normalized": a["sse_normalized"], "n_iter": a["n_iter"],
+                     "converged": bool(a["converged"]),
+                     "starts_at_best": f"{a['n_init_at_best_minimum']}/{a['n_init']}"})
+    return pd.DataFrame(rows).set_index("rank")

eemkit/parafac/validation.py

@@ -0,0 +1,111 @@
+"""Split-half validation (Murphy et al. 2013, Anal. Methods 5:6557-6566).
+
+The 'S4C6T3' design: samples are divided into four groups; pairs of groups
+form six half-datasets, which make three independent comparisons
+(AB vs CD, AC vs BD, AD vs BC). A model is validated when, in every
+comparison, each component of one half matches a component of the other half
+with Tucker congruence above a threshold in both excitation and emission;
+0.95 is commonly used (Lorenzo-Seva & ten Berge 2006, Methodology 2:57-64).
+"""
+
+from __future__ import annotations
+
+import json
+
+import numpy as np
+import pandas as pd
+import xarray as xr
+
+from eemkit.core.dataset import SAMPLE_DIM
+from eemkit.parafac.diagnostics import match_components
+from eemkit.parafac.model import fit_parafac
+
+PAIRS = (((0, 1), (2, 3)), ((0, 2), (1, 3)), ((0, 3), (1, 2)))
+LETTERS = "ABCD"
+
+
+def split_groups(ds: xr.Dataset, *, random_state: int = 0,
+                 stratify: str | None = None) -> np.ndarray:
+    """Assign each sample to one of 4 groups (0-3).
+
+    Samples are shuffled; with ``stratify`` (a sample coordinate such as
+    'campaign') they are dealt round-robin within each stratum, so every group
+    holds a similar mix.
+    """
+    rng = np.random.default_rng(random_state)
+    n = ds.sizes[SAMPLE_DIM]
+    groups = np.empty(n, dtype=int)
+    strata = ds[stratify].values if stratify else np.zeros(n)
+    offset = 0
+    for s in pd.unique(strata):
+        idx = np.flatnonzero(strata == s)
+        rng.shuffle(idx)
+        groups[idx] = (np.arange(idx.size) + offset) % 4
+        offset += idx.size
+    return groups
+
+
+def split_half(
+    ds: xr.Dataset,
+    rank: int,
+    *,
+    groups: np.ndarray | None = None,
+    stratify: str | None = None,
+    split_random_state: int = 0,
+    threshold: float = 0.95,
+    **fit_kwargs,
+) -> xr.Dataset:
+    """Run the S4C6T3 split-half validation for one rank.
+
+    ``split_random_state`` seeds the division into groups; ``fit_kwargs``
+    (including ``random_state``) go to :func:`fit_parafac` for every half.
+    Returns a dataset with ``tcc_ex`` and ``tcc_em`` (test, component), the
+    half-model loadings (half, ex|em, component, aligned to the first half of
+    each test), ``groups(sample)`` and attrs ``validated`` and ``min_tcc``.
+    """
+    if groups is None:
+        groups = split_groups(ds, random_state=split_random_state, stratify=stratify)
+    halves = {}
+    for g1, g2 in PAIRS:
+        for g in (g1, g2):
+            key = "".join(LETTERS[i] for i in g)
+            if key not in halves:
+                sel = np.isin(groups, g)
+                halves[key] = fit_parafac(ds.isel({SAMPLE_DIM: sel}), rank, **fit_kwargs)
+
+    tex, tem, names, ex_l, em_l, half_names = [], [], [], [], [], []
+    for g1, g2 in PAIRS:
+        k1 = "".join(LETTERS[i] for i in g1)
+        k2 = "".join(LETTERS[i] for i in g2)
+        m1, m2 = halves[k1], halves[k2]
+        order, te, tm = match_components(m1.ex_loadings.values, m1.em_loadings.values,
+                                         m2.ex_loadings.values, m2.em_loadings.values)
+        tex.append(te)
+        tem.append(tm)
+        names.append(f"{k1} vs {k2}")
+        for k, m, o in ((k1, m1, np.arange(rank)), (k2, m2, order)):
+            half_names.append(k)
+            ex_l.append(m.ex_loadings.values[:, o])
+            em_l.append(m.em_loadings.values[:, o])
+
+    tex, tem = np.array(tex), np.array(tem)
+    min_tcc = float(np.minimum(tex, tem).min())
+    out = xr.Dataset(
+        {
+            "tcc_ex": (("test", "component"), tex),
+            "tcc_em": (("test", "component"), tem),
+            "half_ex_loadings": (("half", "ex", "component"), np.array(ex_l)),
+            "half_em_loadings": (("half", "em", "component"), np.array(em_l)),
+            "groups": ((SAMPLE_DIM,), groups),
+        },
+        coords={"test": names, "component": np.arange(1, rank + 1),
+                "half": [f"test{i // 2 + 1}:{n}" for i, n in enumerate(half_names)],
+                "ex": ds["ex"].values, "em": ds["em"].values,
+                SAMPLE_DIM: ds[SAMPLE_DIM].values},
+    )
+    out.attrs = {"rank": rank, "threshold": threshold, "min_tcc": min_tcc,
+                 "validated": int(min_tcc >= threshold), "design": "S4C6T3",
+                 "stratify": str(stratify), "split_random_state": split_random_state,
+                 "half_explained_pct": json.dumps(
+                     {k: round(m.attrs["explained_variance_pct"], 3) for k, m in halves.items()})}
+    return out