render.py

"""The PRIMO pages, rendered as ``pm-*`` markup for ``gr.HTML`` blocks.

Gradio has no card or rich-table component, so every page here is a string of
HTML styled entirely by ``primo.css`` -- the rail, the board grid, the
leaderboard tables and the tasks table. The functions are pure: they take the
data the app already fetched (``Board`` objects, the results ``DataFrame``, the
registry) and return a string, so they unit-test without Gradio or a network.

Two rules hold everywhere:

* Every string that comes from the registry or from a submission goes through
  ``html.escape`` -- board names, blurbs, disease names and, above all, the
  user-chosen model names that become table cells and column headers.
* New submissions can carry a public institution, author-submission check and paper
  link. Private legacy ``hf_username`` values stay hidden. Public strings and
  links are validated and escaped before rendering.

Navigation is reload-based: the rail is a column of ``<a href="?board=slug">``
and ``<a href="?tab=name">`` links, which costs a page load per click but buys
shareable per-board URLs and needs no JavaScript, matching how the board cards
have always worked.
"""

import math
import numbers
from html import escape
from urllib.parse import urlparse

import pandas as pd
from boards import (
    AREA_GROUP,
    CATEGORY_GROUP,
    GROUP_NOTE,
    MODALITY_GROUP,
    Board,
    OpenBoard,
    in_group,
    modality_label,
    open_in_group,
)
from leaderboard import ModelCell, per_task_table, ranked_table, tasks_table, top_models

SECTIONS = (MODALITY_GROUP, AREA_GROUP, CATEGORY_GROUP)
N_TOP_MODELS = 3

BRAND = (
    '<a class="pm-brand" target="_self" href="?tab=boards">'
    '<img src="/gradio_api/file=assets/primo-mark.webp" alt="">'
    "<b>PRIMO</b><span>benchmark</span></a>"
)

FOOT_LINKS = (
    ("tasks", "Tasks"),
    ("submit", "Submit a model"),
    ("contribute", "Contribute"),
    ("method", "Method"),
)

NAME_COLUMNS = frozenset({"Model", "Best"})
STRONG_COLUMNS = frozenset({"Task"})
METRIC_COLUMNS = frozenset({"Metric"})
RIGHT_COLUMNS = frozenset({"Rank", "Patients"})

CHEVRON = (
    '<svg class="pm-chevron" viewBox="0 0 16 16" width="12" height="12" '
    'aria-hidden="true"><path d="M6 4l4 4-4 4" fill="none" stroke="currentColor" '
    'stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></svg>'
)


# --------------------------------------------------------------------- rail
def rail_html(
    boards: list[Board], active_slug: str | None, active_tab: str | None
) -> str:
    """The left navigation: brand, a collapsible "Boards" menu, then the foot links.

    The board groups live inside a ``<details>`` toggle so the four foot links
    (Tasks, Submit, Contribute, Method) stay visible without scrolling. The toggle
    is pure HTML/CSS, keeping navigation reload-based and JavaScript-free.

    ``active_slug`` highlights the board a visitor is on; ``active_tab`` highlights
    a foot link, and its absence means we are on a board or the overview, so the
    "Boards" menu is the active one. Open boards link to Contribute, mirroring the
    overview cards.
    """
    on_boards = active_tab is None
    summary_cls = "pm-rail-summary pm-active" if on_boards else "pm-rail-summary"
    parts = [
        '<div class="pm-rail-inner">',
        BRAND,
        '<details class="pm-rail-section" open>',
        f'<summary class="{summary_cls}"><span>Boards</span>{CHEVRON}</summary>',
        '<div class="pm-rail-sections">',
    ]
    for group in SECTIONS:
        cards, opens = in_group(boards, group), open_in_group(boards, group)
        if not cards and not opens:
            continue
        parts.append(
            f'<div class="pm-rail-group"><p class="pm-rail-label">{escape(group)}</p>'
        )
        for board in cards:
            cls = "pm-link pm-active" if board.slug == active_slug else "pm-link"
            parts.append(
                f'<a class="{cls}" target="_self" href="?board={escape(board.slug)}">'
                f'<span class="pm-label">{escape(board.name)}</span>'
                f'<span class="pm-count">{board.n_tasks}</span></a>'
            )
        for board in opens:
            parts.append(
                '<a class="pm-link pm-link--open" target="_self" href="?tab=contribute">'
                f'<span class="pm-label">{escape(board.name)}</span>'
                '<span class="pm-badge pm-badge--quiet">open</span></a>'
            )
        parts.append("</div>")
    parts.append("</div></details>")
    parts.append('<div class="pm-rail-foot">')
    for tab, label in FOOT_LINKS:
        cls = "pm-foot-link pm-active" if tab == active_tab else "pm-foot-link"
        parts.append(
            f'<a class="{cls}" target="_self" href="?tab={tab}">{escape(label)}</a>'
        )
    parts.append("</div></div>")
    return "".join(parts)


# ------------------------------------------------------------------ boards
def _leading(top) -> str:
    """The card's mini-ranking, with the same empty/baseline states as before.

    An empty board says "be the first"; a board held only by our baselines says
    "beat the baseline" instead, because "be the first" misleads once a PCA
    already holds a score.
    """
    parts = ['<p class="pm-over" style="margin-top:14px">Leading (Elo)</p>']
    if not top:
        parts.append(
            '<p class="pm-leader pm-leader--2">No ranked model yet. Be the first.</p>'
        )
        return "".join(parts)
    for row in top:
        badge = (
            ' <span class="pm-badge pm-badge--marine">baseline</span>'
            if row.is_baseline
            else ""
        )
        score = "n/a" if row.elo is None else str(row.elo)
        parts.append(
            f'<p class="pm-leader">{escape(row.name)}{badge}'
            f' <span class="pm-num--dim">{score}</span></p>'
        )
    return "".join(parts)


def _live_card(board: Board, df: pd.DataFrame, by_id: dict[str, dict]) -> str:
    top = top_models(df, by_id, board, N_TOP_MODELS)
    return (
        f'<a class="pm-card pm-card--live" target="_self" href="?board={escape(board.slug)}">'
        f"<h3>{escape(board.name)}</h3>"
        f'<p class="pm-meta">{board.n_tasks} tasks · {board.n_cohorts} cohorts<br>'
        f"{board.n_patients:,} patients · {board.n_diseases} diseases</p>"
        f'<p class="pm-asks">{escape(board.blurb)}</p>'
        f"{_leading(top)}</a>"
    )


def _open_card(board: OpenBoard) -> str:
    return (
        '<a class="pm-card pm-card--open" target="_self" href="?tab=contribute">'
        f"<h3>{escape(board.name)}</h3>"
        '<p class="pm-meta"><span class="pm-badge pm-badge--quiet">OPEN · no cohort yet</span></p>'
        f'<p class="pm-asks">{escape(board.blurb)}</p>'
        '<p class="pm-cta">Propose a cohort →</p></a>'
    )


def render_boards(boards: list[Board], df: pd.DataFrame, by_id: dict[str, dict]) -> str:
    """The Boards overview: every board as a card, grouped by facet.

    Live cards link to their board and teaser their leaders; open cards state a
    gap and link to Contribute. A section counts its open slices so the page
    reads as showing its own gaps, not the registry as the whole territory.
    """
    if not boards:
        return (
            '<div class="pm-body"><p class="pm-caption">The task registry is '
            "unavailable right now. Please retry in a moment.</p></div>"
        )
    out = [
        '<div class="pm-head"><div><h1>Leaderboards</h1>',
        "<p>PRIMO evaluates representations of omics samples through "
        "drug-development-related tasks. Benchmarks are organized by data "
        "modality, therapeutic area, or task category.</p></div></div>",
        '<div class="pm-body">',
    ]
    for group in SECTIONS:
        cards, opens = in_group(boards, group), open_in_group(boards, group)
        if not cards and not opens:
            continue
        note = escape(GROUP_NOTE.get(group, ""))
        counter = f" · +{len(opens)} open" if opens else ""
        out.append(
            '<div class="pm-group"><div class="pm-group-head">'
            f'<p class="pm-over">{escape(group)}</p>'
            f'<p class="pm-note">{note}{counter}</p></div><div class="pm-grid">'
        )
        out += [_live_card(b, df, by_id) for b in cards]
        out += [_open_card(b) for b in opens]
        out.append("</div></div>")
    out.append("</div>")
    return "".join(out)


# ------------------------------------------------------------- html tables
def _fmt_value(value, is_score: bool) -> str | None:
    """Display text for one cell; ``None`` marks a blank (``n/a``) cell."""
    try:
        if pd.isna(value):
            return None
    except (TypeError, ValueError):
        pass
    if isinstance(value, str):
        return value
    if isinstance(value, numbers.Integral):
        return str(int(value))
    if isinstance(value, numbers.Real):
        if not math.isfinite(float(value)):
            return None
        return f"{float(value):.3f}" if is_score else str(value)
    return str(value)


def _model_cell_html(cell: ModelCell) -> str:
    """Render one model label, allowing only escaped HTTP(S) paper links."""
    label = escape(str(cell))
    parsed = urlparse(cell.paper_link)
    if parsed.scheme in {"http", "https"} and parsed.netloc:
        url = escape(cell.paper_link, quote=True)
        label = (
            f'<a class="pm-model-link" href="{url}" target="_blank" '
            f'rel="noopener noreferrer">{label}</a>'
        )
    chip = (
        ' <span class="pm-author-chip" title="Submitted by the model authors" '
        'aria-label="Submitted by the model authors">✓ Authors</span>'
        if cell.is_author_submission
        else ""
    )
    return label + chip


def _score_columns(df: pd.DataFrame) -> list[str]:
    """Numeric columns to format and bold -- ``Rank`` is an index, not a score."""
    return [c for c in df.select_dtypes("number").columns if c not in RIGHT_COLUMNS]


def _bold_cells(df: pd.DataFrame, score_cols: list[str], axis: int) -> set:
    """Which ``(row, col)`` cells hold the best value.

    ``axis=0`` bolds the best model per column (the ranked table, read down);
    ``axis=1`` bolds the best model per row (the per-task table, read across).
    """
    bold = set()
    if not score_cols:
        return bold
    if axis == 0:
        for col in score_cols:
            best = df[col].max(skipna=True)
            if pd.notna(best):
                for idx, value in df[col].items():
                    if pd.notna(value) and value == best:
                        bold.add((idx, col))
    else:
        for idx, row in df.iterrows():
            present = {c: row[c] for c in score_cols if pd.notna(row[c])}
            if present:
                best = max(present.values())
                bold.update((idx, c) for c, v in present.items() if v == best)
    return bold


def _cell_class(col: str, is_score: bool, blank: bool) -> str:
    if col in NAME_COLUMNS:
        return "pm-name"
    if col in STRONG_COLUMNS:
        return "pm-strong"
    if col in METRIC_COLUMNS:
        return "pm-metric"
    if is_score or col in RIGHT_COLUMNS:
        return "pm-num pm-num--dim" if blank else "pm-num"
    return ""


def _df_to_table(df: pd.DataFrame, bold_axis: int | None, empty: str) -> str:
    """Render a DataFrame as a ``pm-table``, escaping every header and cell."""
    if df.empty:
        return f'<p class="pm-caption">{escape(empty)}</p>'
    score_cols = _score_columns(df)
    bold = _bold_cells(df, score_cols, bold_axis) if bold_axis is not None else set()

    head = []
    for index, col in enumerate(df.columns):
        align = (
            ' style="text-align:right"'
            if col in score_cols or col in RIGHT_COLUMNS
            else ""
        )
        head.append(
            f'<th class="pm-sort" data-sort-index="{index}" tabindex="0" '
            f'role="button" aria-sort="none" title="Sort by {escape(str(col))}"'
            f"{align}>{escape(str(col))}</th>"
        )
    body = []
    for idx, row in df.iterrows():
        cells = []
        for col in df.columns:
            is_score = col in score_cols
            text = _fmt_value(row[col], is_score)
            cls = _cell_class(col, is_score, text is None)
            weight = ' style="font-weight:700"' if (idx, col) in bold else ""
            shown = (
                _model_cell_html(row[col])
                if isinstance(row[col], ModelCell)
                else "n/a"
                if text is None
                else escape(text)
            )
            cells.append(f'<td class="{cls}"{weight}>{shown}</td>')
        body.append(f"<tr>{''.join(cells)}</tr>")
    return (
        '<div class="pm-table-wrap"><table class="pm-table" style="table-layout:auto">'
        f"<thead><tr>{''.join(head)}</tr></thead>"
        f"<tbody>{''.join(body)}</tbody></table></div>"
    )


# ------------------------------------------------------------------- board
def _board_meta(board: Board) -> str:
    return (
        f"{escape(board.blurb)} · {board.n_tasks} tasks · {board.n_cohorts} cohorts · "
        f"{board.n_patients:,} patients · {escape(modality_label(board.modality))}"
    )


def render_board(board: Board | None, df: pd.DataFrame, by_id: dict[str, dict]) -> str:
    """One board: title strip, the ranked leaderboard, then the per-task table."""
    if board is None:
        return (
            '<div class="pm-head"><div><h1>No board available</h1>'
            "<p>The task registry could not be loaded. Please retry shortly.</p>"
            "</div></div>"
        )
    ranked = _df_to_table(
        ranked_table(df, by_id, board),
        bold_axis=0,
        empty="No model has covered every task of this board yet. Be the first to submit.",
    )
    per_task = _df_to_table(
        per_task_table(df, by_id, board),
        bold_axis=1,
        empty="No submission has scored on this board yet.",
    )
    return (
        '<div class="pm-head"><div><p class="pm-over">Board</p>'
        f"<h1>{escape(board.name)}</h1><p>{_board_meta(board)}</p></div></div>"
        '<div class="pm-body">'
        '<div class="pm-group"><div class="pm-group-head">'
        '<p class="pm-over pm-over--marine">Ranked</p>'
        f'<p class="pm-note">Only models that covered all {board.n_tasks} tasks are '
        "ranked by Elo. Elo compares models pairwise within each task and never "
        "compares AUROC with Pearson directly.</p>"
        f"</div>{ranked}</div>"
        '<div class="pm-group"><div class="pm-group-head">'
        '<p class="pm-over pm-over--marine">Per task</p>'
        '<p class="pm-note">Every submission, partial ones included. Read across a row.</p>'
        f"</div>{per_task}</div>"
        "</div>"
    )


# ------------------------------------------------------------------- tasks
def render_tasks(by_id: dict[str, dict]) -> str:
    """The Tasks page: one scannable row per hidden target. Provenance is never shown."""
    df = tasks_table(list(by_id.values()))
    table = _df_to_table(
        df, bold_axis=None, empty="The task registry is unavailable right now."
    )
    return (
        '<div class="pm-head"><div><h1>Tasks</h1>'
        f"<p>{len(df)} hidden clinical targets. One fixed linear probe reads each "
        "one out of your embedding; the cohorts stay anonymous, the biology does "
        "not.</p></div></div>"
        f'<div class="pm-body">{table}</div>'
    )