alphaengine 0.9.3__tar.gz → 0.9.5__tar.gz

{alphaengine-0.9.3 → alphaengine-0.9.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: alphaengine
-Version: 0.9.3
+Version: 0.9.5
 Summary: Validated research tooling for investment strategies: deflation, overfitting detection, and honest trial counts.
 Project-URL: Homepage, https://github.com/quantOSC/alphaengine
 Project-URL: Documentation, https://github.com/quantOSC/alphaengine#readme
@@ -334,6 +334,9 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `book [<name> \| status]` | show or load sleeves on the multi-strategy book | session |
 | `load <file \| module \| universe>` | a CSV, a project module, or a portal universe | session |
 | `thesis [<name> \| clear]` | choose a portal thesis for the next run | session |
+| `correlation` | the correlation of every loaded name with every other name | session |
+| `covariance` | the sample covariance of every loaded name with every other name | session |
+| `cointegration` | which loaded names are cointegrated | session |
 | `universe <name>` | same as load: a universe registered in the portal | session |
 | `data <file>` | same as load: a local CSV or parquet | session |
 | `project <module>` | same as load: a module with data and backtest_fn | session |

{alphaengine-0.9.3 → alphaengine-0.9.5}/README.md

@@ -289,6 +289,9 @@ w = hrp_weights(cov, names=names)    # no matrix inverse; weights sum to one
 | `book [<name> \| status]` | show or load sleeves on the multi-strategy book | session |
 | `load <file \| module \| universe>` | a CSV, a project module, or a portal universe | session |
 | `thesis [<name> \| clear]` | choose a portal thesis for the next run | session |
+| `correlation` | the correlation of every loaded name with every other name | session |
+| `covariance` | the sample covariance of every loaded name with every other name | session |
+| `cointegration` | which loaded names are cointegrated | session |
 | `universe <name>` | same as load: a universe registered in the portal | session |
 | `data <file>` | same as load: a local CSV or parquet | session |
 | `project <module>` | same as load: a module with data and backtest_fn | session |

{alphaengine-0.9.3 → alphaengine-0.9.5}/src/alphaengine/_version.py

@@ -88,4 +88,14 @@ is what a changed figure costs. The API may still move underneath it.
 # 0.9.3 IS THE SESSION, NOT THE MATHS. No computed value moved. The math pane
 # is narrower. A sentence is shown the workflow it is choosing and what a step
 # already measured, and a finished step is not run again.
-__version__ = "0.9.3"
+#
+# 0.9.4 IS THE SESSION, NOT THE MATHS. No computed value moved. The session
+# opens on the desk: what is loaded, the thesis on its own lines, and the
+# next thing to type.
+#
+# 0.9.5 IS THE SESSION, NOT THE MATHS. No golden moved. Correlation, covariance,
+# and cointegration run on the universe already loaded, and the square matrix
+# is filed for the portal. check_overlap keeps that universe: one named symbol
+# against the equal-weight of the others. The correlation and beta are the
+# same numbers; the step now also names the candidate and the book.
+__version__ = "0.9.5"

{alphaengine-0.9.3 → alphaengine-0.9.5}/src/alphaengine/charts.py

@@ -12,7 +12,14 @@ KINDS
     hist      {edges, counts}     histogram
     cost      {bps, sharpe}       cost ladder
     scatter   {x, y}              overlap
-    triangle  {a, b, v}           covariance heatmap
+    triangle  {a, b, v}           covariance heatmap, only when the
+                                  upper triangle fits in 512 cells
+    matrix    names + matrix      full square heatmap. `names[i]` labels
+                                  `matrix[i][j]`. Each row is at most 512
+                                  long, so a book larger than that is truncated
+                                  and `truncated` is true. This is the shape a
+                                  100-name correlation uses; `triangle` cannot
+                                  carry it.
     rows      bounded dict rows   table
     quantiles [float]             bar
 
@@ -32,6 +39,7 @@ CHART_KINDS = frozenset(
         "cost",
         "scatter",
         "triangle",
+        "matrix",
         "rows",
         "quantiles",
     }

{alphaengine-0.9.3 → alphaengine-0.9.5}/src/alphaengine/cli.py

@@ -1131,6 +1131,22 @@ def preflight(catalogue: list[dict[str, Any]], name: str, *, data: Any, backtest
     if not missing:
         return None
 
+    # check_overlap wants one candidate and a separate book. A loaded universe
+    # already holds both: name one symbol and the other names are the book.
+    # Telling somebody to pass --symbol and then discarding the rest of the
+    # names was the loop. The session builds that book itself; this message is
+    # the shell form of the same move.
+    if name == "check_overlap" and _looks_like_universe(data) and isinstance(data, dict):
+        example = next(iter(sorted(str(k) for k in data)), "MU")
+        return (
+            f"check_overlap compares ONE name with the equal-weight of the others, "
+            f"and a universe of {len(data)} names is loaded.\n"
+            f"      run check_overlap --symbol {example}\n"
+            "  That name is the candidate. The other names are the book.\n"
+            "  For every name against every other name:\n"
+            "      run correlation"
+        )
+
     # THE ANSWER THE LOADED DATA MAKES POSSIBLE, before the generic doors. A
     # user with a universe loaded who is told "load a universe" is in a loop
     # with no exit — the real move is naming which of their names to measure.
@@ -1653,16 +1669,107 @@ def _drive(run: Any, *, quiet: bool = False) -> None:
                 return
 
 
+def _publish_panel(session: Any, result: dict[str, Any], *, thesis_id: str | None = None) -> None:
+    """Hand the matrix or the pair table to the portal. A missing route is not a failure."""
+    if session is None or not hasattr(session, "file_panel"):
+        return
+    from .client.executor import _guard
+    from .core.relations import portal_figures
+
+    figures = portal_figures(result)
+    try:
+        _guard(figures)
+    except ValueError as exc:
+        say(yellow(str(exc)))
+        return
+    filed = session.file_panel(figures, thesis_id=thesis_id)
+    if not isinstance(filed, dict):
+        return
+    if filed.get("filed"):
+        say(dim("  filed to the portal"))
+        return
+    if filed.get("reason") == "missing":
+        say(dim("  held on this machine; the portal has no panels route yet"))
+        return
+    if filed.get("reason") and filed.get("reason") != "offline":
+        say(dim(f"  held on this machine ({filed.get('reason')})"))
+
+
+def _print_cross(
+    data: Any,
+    kind: str,
+    *,
+    session: Any = None,
+    thesis_id: str | None = None,
+) -> int:
+    from .core.relations import cointegration, correlation, covariance, summary_lines
+
+    try:
+        if kind == "correlation":
+            result = correlation(data)
+        elif kind == "covariance":
+            result = covariance(data)
+        else:
+            result = cointegration(data)
+    except ValueError as exc:
+        say(red(str(exc)))
+        return 2
+    for line in summary_lines(result):
+        say(line)
+    _publish_panel(session, result, thesis_id=thesis_id)
+    return 0
+
+
+def _overlap_payload(data: Any, symbol: str) -> dict[str, Any] | None:
+    """Candidate plus the equal-weight of the other loaded names, or None."""
+    from .core.relations import overlap_against_the_rest
+
+    if not _looks_like_universe(data):
+        return None
+    try:
+        prepared = overlap_against_the_rest(data, symbol)
+    except ValueError as exc:
+        say(red(str(exc)))
+        return None
+    others = len(prepared["book_names"])
+    say(dim(f"  {prepared['symbol']} against the equal-weight of {others} other names."))
+    return {"returns": prepared["returns"], "book_returns": prepared["book_returns"]}
+
+
 def cmd_run(args: argparse.Namespace) -> int:
     from .client import Offline, ServerError
+    from .core.relations import KINDS
 
     session, url = _session(args.url, args.key)
+    kind = KINDS.get(str(args.workflow).lower().replace("-", "_"))
+    if kind:
+        try:
+            data, _fn = resolve_data(args, session)
+        except (ProjectError, ValueError) as exc:
+            say(red(str(exc)))
+            return 2
+        return _print_cross(data, kind, session=session)
+    symbol = getattr(args, "symbol", None)
+    resolve_args = args
+    if args.workflow == "check_overlap" and symbol:
+        resolve_args = argparse.Namespace(**vars(args))
+        resolve_args.symbol = None
     try:
-        data, backtest_fn = resolve_data(args, session)
+        data, backtest_fn = resolve_data(resolve_args, session)
         workspace_id = None
     except (ProjectError, ValueError) as exc:
         say(red(str(exc)))
         return 2
+    if args.workflow == "check_overlap" and _looks_like_universe(data):
+        if symbol:
+            payload = _overlap_payload(data, str(symbol))
+            if payload is None:
+                return 2
+            data = payload
+        else:
+            say("  check_overlap measures one name against the equal-weight of the others.")
+            say(dim("  No name was given, so this is every name against every other name."))
+            return _print_cross(data, "correlation", session=session)
 
     inputs: dict[str, Any] = {}
     for pair in args.input or []:
@@ -3391,6 +3498,22 @@ def _ask(
             except Exception as exc:  # noqa: BLE001 - reachable and unloadable: say so, refuse below
                 say(yellow(f"  {wanted} is on your account and could not be loaded: {exc}"))
 
+    # check_overlap on a universe is one name against the equal-weight of the
+    # rest. Collapsing --symbol here used to throw the book away, which is why
+    # the next line was "needs book_returns, and none was loaded."
+    if name == "check_overlap" and _looks_like_universe(data):
+        sym = _symbol_in(request, data)
+        if sym:
+            payload = _overlap_payload(data, sym)
+            if payload is None:
+                return None
+            data = payload
+        else:
+            say("  check_overlap measures one name against the equal-weight of the others.")
+            say(dim("  No name was given, so this is every name against every other name."))
+            _print_cross(data, "correlation", session=session, thesis_id=thesis_id)
+            return None
+
     # "size MU" against a loaded universe is a complete instruction: the name
     # the question mentions picks the series out of the caller's own data.
     # One match only — two is a real ambiguity and the refusal below names the

{alphaengine-0.9.3 → alphaengine-0.9.5}/src/alphaengine/client/executor.py

@@ -788,6 +788,22 @@ class StepExecutor:
                     out["rolling_window"] = window
                     out["max_rolling_correlation"] = round(max(clean), 6)
                     out["min_rolling_correlation"] = round(min(clean), 6)
+        if isinstance(self.data, dict):
+            symbol = self.data.get("symbol")
+            if symbol:
+                out["symbol"] = str(symbol)
+            book_names = self.data.get("book_names")
+            if isinstance(book_names, list):
+                out["n_book_names"] = len(book_names)
+                if len(book_names) <= MAX_FIGURE_LIST:
+                    out["book_names"] = [str(name) for name in book_names]
+        hints = []
+        if out.get("overlap_scatter"):
+            hints.append(chart("scatter", "overlap_scatter", "candidate vs the book"))
+        if out.get("rolling_correlation"):
+            hints.append(chart("curve", "rolling_correlation", "rolling correlation"))
+        if hints:
+            out["charts"] = hints
         return out
 
     # ── the rest of the modeling week, previously library-only ─────────────

{alphaengine-0.9.3 → alphaengine-0.9.5}/src/alphaengine/client/session.py

@@ -506,6 +506,44 @@ class Session:
     # to `/api/me/proposals/from-os` and `/api/me/sleeves`. Those left with the
     # agent desk in 0.5.0. Selecting a thesis is the read above, not that writer.
 
+    def file_panel(
+        self,
+        figures: Figures,
+        *,
+        thesis_id: str | None = None,
+        label: str | None = None,
+    ) -> Figures:
+        """File a client-computed panel so the portal can draw it.
+
+        Correlation, covariance, and cointegration are not catalogue workflows.
+        Their matrix does not fit a `triangle` figure, so it travels here as
+        `figures.matrix` plus `figures.names`. A 404 means this portal has no
+        panels route yet: the maths already happened on this machine, and the
+        missing route must not fail that.
+        """
+        from .._version import __version__
+
+        kind = str(figures.get("kind") or "panel")
+        n = figures.get("n_names")
+        body: Figures = {
+            "kind": kind,
+            "label": label or (f"{kind}  {n} names" if n else kind),
+            "engine": f"alphaengine@{__version__}",
+            "figures": figures,
+        }
+        if thesis_id:
+            body["thesis_id"] = thesis_id
+        try:
+            out = self._post("/api/me/panels", body)
+        except ServerError as exc:
+            if exc.status in (404, 405):
+                return {"filed": False, "reason": "missing"}
+            return {"filed": False, "reason": str(exc)}
+        except Offline:
+            return {"filed": False, "reason": "offline"}
+        panel_id = out.get("id") if isinstance(out, dict) else None
+        return {"filed": True, "id": panel_id}
+
     def post_event(self, run_id: str, event: dict[str, Any]) -> Figures:
         """Allowlisted model/run event. 404-tolerant at the sink, not here.
 

{alphaengine-0.9.3 → alphaengine-0.9.5}/src/alphaengine/commands.py

@@ -490,6 +490,48 @@ COMMANDS: tuple[Command, ...] = _question_commands() + (
             "alphaengine run screen_universe --thesis momentum",
         ),
     ),
+    Command(
+        verb="correlation",
+        group="data",
+        args="",
+        scope="repl",
+        purpose="the correlation of every loaded name with every other name",
+        body=(
+            "Runs on the universe already loaded. Closes become returns. The full "
+            "matrix stays on this machine and opens on the right of the session.\n\n"
+            "`covariance` is the same panel as a sample covariance. "
+            "`cointegration` screens the closes, pairwise, and needs the factors extra.\n\n"
+            "`check_overlap` is a different question: one name against the equal-weight "
+            "of the others. Name it with `run check_overlap --symbol MU`. With no name, "
+            "that command shows this matrix instead of refusing."
+        ),
+        examples=("correlation", "run check_overlap --symbol MU"),
+    ),
+    Command(
+        verb="covariance",
+        group="data",
+        args="",
+        scope="repl",
+        purpose="the sample covariance of every loaded name with every other name",
+        body=(
+            "Same panel as `correlation`: the universe already loaded, closes "
+            "turned into returns, full matrix on the right of the session."
+        ),
+        examples=("covariance",),
+    ),
+    Command(
+        verb="cointegration",
+        group="data",
+        args="",
+        scope="repl",
+        purpose="which loaded names are cointegrated",
+        body=(
+            "Engle-Granger across the loaded closes, every pair. Needs the factors "
+            "extra (`pip install 'alphaengine[factors]'`). A hundred names is a few "
+            "thousand tests and takes a while. The pairs open on the right."
+        ),
+        examples=("cointegration",),
+    ),
     Command(
         verb="universe",
         group="data",

alphaengine-0.9.5/src/alphaengine/core/relations.py

@@ -0,0 +1,309 @@
+"""Correlation, covariance, and cointegration across a loaded universe.
+
+A universe is already {name: closes}. These read that panel on this machine.
+Nothing here asks for a separate book series, and the matrix stays local: what
+is said out loud is the counts and the strongest pairs, not every cell.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from ..charts import chart
+from .panel import align_panel
+from .series_shapes import series_values
+
+_FIGURE_CAP = 512
+_STRONG = 32
+
+__all__ = [
+    "KINDS",
+    "as_closes",
+    "as_returns",
+    "correlation",
+    "covariance",
+    "cointegration",
+    "overlap_against_the_rest",
+    "portal_figures",
+    "summary_lines",
+]
+
+KINDS = {
+    "correlation": "correlation",
+    "corr": "correlation",
+    "covariance": "covariance",
+    "cov": "covariance",
+    "cointegration": "cointegration",
+    "cointegrate": "cointegration",
+    "coint": "cointegration",
+}
+
+_SKIP = frozenset({"returns", "pnl", "book_returns", "signal", "prices"})
+
+
+def _values(series: Any) -> list[float] | None:
+    arr, _dates = series_values(series)
+    if arr.ndim != 1 or arr.size < 2:
+        return None
+    out = [float(v) for v in arr.tolist() if np.isfinite(v)]
+    return out if len(out) >= 2 else None
+
+
+def _looks_like_prices(values: list[float]) -> bool:
+    """Closes sit well above 1. A return series does not."""
+    return any(abs(v) > 1.5 for v in values)
+
+
+def _to_returns(values: list[float]) -> list[float] | None:
+    if not _looks_like_prices(values):
+        return [round(v, 8) for v in values]
+    if any(v == 0 for v in values[:-1]):
+        return None
+    return [round(values[i] / values[i - 1] - 1.0, 8) for i in range(1, len(values))]
+
+
+def as_closes(data: Any) -> dict[str, list[float]]:
+    """{name: levels}. A return series is left as-is; cointegration wants levels."""
+    if not isinstance(data, dict):
+        return {}
+    out: dict[str, list[float]] = {}
+    for name, series in data.items():
+        if str(name) in _SKIP:
+            continue
+        values = _values(series)
+        if values:
+            out[str(name)] = values
+    return out
+
+
+def as_returns(data: Any) -> dict[str, list[float]]:
+    """{name: per-period returns}, derived from closes when that is what was loaded."""
+    out: dict[str, list[float]] = {}
+    for name, values in as_closes(data).items():
+        returns = _to_returns(values)
+        if returns and len(returns) >= 2:
+            out[name] = returns
+    return out
+
+
+def _matrix(panel: dict[str, list[float]], *, kind: str) -> dict[str, Any]:
+    aligned, names, skipped = align_panel(panel, need=2)
+    if len(names) < 2:
+        raise ValueError("need at least two names with a shared history.")
+    if kind == "correlation":
+        grid = np.corrcoef(aligned, rowvar=False)
+    else:
+        grid = np.cov(aligned, rowvar=False, ddof=1)
+    grid = np.atleast_2d(np.asarray(grid, dtype=float))
+    rows: list[list[float | None]] = []
+    for i in range(grid.shape[0]):
+        row: list[float | None] = []
+        for j in range(grid.shape[1]):
+            value = float(grid[i, j])
+            row.append(round(value, 4) if np.isfinite(value) else None)
+        rows.append(row)
+    pairs: list[dict[str, Any]] = []
+    for i, a in enumerate(names):
+        for j in range(i + 1, len(names)):
+            value = rows[i][j]
+            if value is None:
+                continue
+            pairs.append({"a": a, "b": names[j], "value": value})
+    pairs.sort(key=lambda item: abs(float(item["value"])), reverse=True)
+    return {
+        "kind": kind,
+        "names": names,
+        "values": rows,
+        "n_obs": int(aligned.shape[0]),
+        "skipped": skipped,
+        "pairs": pairs,
+    }
+
+
+def correlation(data: Any) -> dict[str, Any]:
+    """Pearson correlation of every name with every other name."""
+    return _matrix(as_returns(data), kind="correlation")
+
+
+def covariance(data: Any) -> dict[str, Any]:
+    """Sample covariance of every name with every other name."""
+    return _matrix(as_returns(data), kind="covariance")
+
+
+def cointegration(data: Any) -> dict[str, Any]:
+    """Engle-Granger screen across the loaded closes. Levels, not returns."""
+    try:
+        from .pairs import find_cointegrated_pairs
+    except ModuleNotFoundError as exc:
+        raise ValueError(str(exc)) from exc
+    closes = as_closes(data)
+    prices = {name: values for name, values in closes.items() if _looks_like_prices(values)}
+    if len(prices) < 2:
+        raise ValueError("cointegration needs at least two names of closes, not a return series.")
+    found = find_cointegrated_pairs(prices, cointegrated_only=False)
+    rows = []
+    for pair in found.get("pairs") or []:
+        if not isinstance(pair, dict):
+            continue
+        coint = pair.get("cointegration") or {}
+        rows.append(
+            {
+                "a": pair.get("ticker_a"),
+                "b": pair.get("ticker_b"),
+                "p": coint.get("p_value"),
+                "half_life": pair.get("half_life_days"),
+                "cointegrated": bool(pair.get("cointegrated")),
+            }
+        )
+    rows.sort(key=lambda row: (not row["cointegrated"], row["p"] if row["p"] is not None else 1.0))
+    return {
+        "kind": "cointegration",
+        "names": list(prices),
+        "rows": rows,
+        "n_pairs": int(found.get("n_evaluated") or len(rows)),
+        "n_cointegrated": int(found.get("n_cointegrated") or sum(1 for row in rows if row["cointegrated"])),
+        "expected_false_positives": found.get("expected_false_positives"),
+        "multiple_testing_note": found.get("multiple_testing_note"),
+        "skipped": [name for name in closes if name not in prices],
+    }
+
+
+def overlap_against_the_rest(data: Any, symbol: str) -> dict[str, Any]:
+    """One name's returns, and the equal-weight of every other loaded name.
+
+    That is the book `check_overlap` is asking for. It does not have to be
+    loaded as a second series when the universe already holds the names.
+    """
+    panel = as_returns(data)
+    key = next((name for name in panel if name.upper() == symbol.upper()), None)
+    if key is None:
+        known = ", ".join(list(panel)[:8]) or "none"
+        raise ValueError(f"{symbol} is not in the loaded names. Loaded: {known}")
+    candidate = panel.pop(key)
+    if len(panel) < 1:
+        raise ValueError(
+            f"{key} is the only loaded name, so there is no rest of the book to compare it with."
+        )
+    aligned, names, _skipped = align_panel(panel, need=2)
+    if len(names) < 1:
+        raise ValueError("the other names do not share enough history to form a book.")
+    depth = min(len(candidate), int(aligned.shape[0]))
+    book = aligned[-depth:].mean(axis=1)
+    series = np.asarray(candidate, dtype=float)[-depth:]
+    return {
+        "returns": [round(float(v), 8) for v in series.tolist()],
+        "book_returns": [round(float(v), 8) for v in book.tolist()],
+        "symbol": key,
+        "book_names": names,
+    }
+
+
+def summary_lines(result: dict[str, Any]) -> list[str]:
+    """What to say. The full matrix stays in the result, for the inspector."""
+    kind = str(result.get("kind") or "")
+    if kind == "cointegration":
+        lines = [
+            f"  cointegration   {result.get('n_cointegrated')} of {result.get('n_pairs')} pairs"
+            "   across the loaded closes",
+            "  check_overlap is a different question: one name against the rest of the book.",
+        ]
+        shown = 0
+        for row in (result.get("rows") or [])[:8]:
+            if row.get("p") is None and not row.get("cointegrated"):
+                continue
+            flag = "yes" if row.get("cointegrated") else "no"
+            p = row.get("p")
+            p_text = f"{float(p):.3f}" if isinstance(p, (int, float)) else "-"
+            lines.append(f"  {row.get('a')}  {row.get('b')}   p {p_text}   cointegrated {flag}")
+            shown += 1
+        if not result.get("n_cointegrated") and shown:
+            lines.append("  None cleared the cointegration bar. The pairs above are the closest.")
+        elif not shown:
+            lines.append("  The loaded closes are too short to test cointegration.")
+        return lines
+    names = result.get("names") or []
+    lines = [f"  {kind}   {len(names)} names   {result.get('n_obs')} observations   full matrix on the right"]
+    skipped = result.get("skipped") or []
+    if skipped:
+        lines.append(f"  {len(skipped)} names skipped (short history)")
+    lines.append("  strongest pairs")
+    for pair in (result.get("pairs") or [])[:8]:
+        lines.append(f"  {pair['a']}  {pair['b']}   {pair['value']}")
+    return lines
+
+
+def portal_figures(result: dict[str, Any]) -> dict[str, Any]:
+    """The payload the portal draws. Derived numbers only, each list at most 512 long.
+
+    A 100-name correlation is a square of rows, not a triangle of pairs: the
+    triangle does not fit the figure cap, and the rows do. Closes and returns
+    never appear here.
+    """
+    kind = str(result.get("kind") or "")
+    if kind == "cointegration":
+        rows = []
+        for row in result.get("rows") or []:
+            if row.get("p") is None and not row.get("cointegrated"):
+                continue
+            rows.append(
+                {
+                    "a": row.get("a"),
+                    "b": row.get("b"),
+                    "p": row.get("p"),
+                    "half_life": row.get("half_life"),
+                    "cointegrated": bool(row.get("cointegrated")),
+                }
+            )
+        truncated = len(rows) > _FIGURE_CAP
+        names = [str(name) for name in (result.get("names") or [])]
+        if len(names) > _FIGURE_CAP:
+            names = names[:_FIGURE_CAP]
+            truncated = True
+        figures: dict[str, Any] = {
+            "kind": "cointegration",
+            "n_names": len(result.get("names") or []),
+            "n_pairs": result.get("n_pairs"),
+            "n_cointegrated": result.get("n_cointegrated"),
+            "names": names,
+            "pairs": rows[:_FIGURE_CAP],
+            "truncated": truncated,
+            "charts": [chart("rows", "pairs", "cointegrated pairs")],
+        }
+        if result.get("expected_false_positives") is not None:
+            figures["expected_false_positives"] = result["expected_false_positives"]
+        note = result.get("multiple_testing_note")
+        if isinstance(note, str) and note:
+            figures["multiple_testing_note"] = note
+        return figures
+
+    names = [str(name) for name in (result.get("names") or [])]
+    values = [list(row) for row in (result.get("values") or [])]
+    truncated = len(names) > _FIGURE_CAP
+    if truncated:
+        names = names[:_FIGURE_CAP]
+        values = [list(row[:_FIGURE_CAP]) for row in values[:_FIGURE_CAP]]
+    strongest: list[dict[str, Any]] = []
+    kept = set(names)
+    for pair in result.get("pairs") or []:
+        if pair.get("a") not in kept or pair.get("b") not in kept:
+            continue
+        strongest.append({"a": pair["a"], "b": pair["b"], "v": pair["value"]})
+        if len(strongest) >= _STRONG:
+            break
+    title = "correlation" if kind == "correlation" else "covariance"
+    return {
+        "kind": kind,
+        "n_names": len(result.get("names") or []),
+        "n_obs": result.get("n_obs"),
+        "n_skipped": len(result.get("skipped") or []),
+        "names": names,
+        "matrix": values,
+        "strongest": strongest,
+        "truncated": truncated,
+        "charts": [
+            chart("matrix", "matrix", title),
+            chart("rows", "strongest", "strongest pairs"),
+        ],
+    }