No tooltips on the Visualize and Compare by Buoy charts

[abkfenris]

Ideally linked across the stacked subplots, so hovering one unit shows the corresponding values in the others at the same x.

[abkfenris]

Implementation plan — accepted

Issue #140 — Tooltips + linked crosshair on Visualize/Compare charts

Context

GitHub issue #140:
"No tooltips on the Visualize and Compare by Buoy charts... Ideally linked
across the stacked subplots, so hovering one unit shows the corresponding
values in the others at the same x."

Both the "By Buoy" page (by_platform.py) and the "By Data Type" page
(by_standard_name.py) build Altair mark_line() charts with no tooltip=
encoding at all today, so hovering shows nothing. On top of that, "By Buoy"
stacks one subplot per unit (alt.vconcat), and those subplots are currently
fully independent views with no shared interaction — the ask is for a
crosshair that links them, so hovering any one row highlights the same
timestamp in every row.

Two implementation approaches were prototyped and empirically verified
against this repo's actual pinned altair==6.2.2 (not just reasoned about
from docs): an incremental fix that keeps the current per-row vconcat loop
and threads a shared Vega-Lite selection through it, and a restructure onto
Altair's native .facet(row=...), where the cross-row linking falls out of
Vega-Lite's own facet compiler. The facet approach was chosen — it
replaces the current legend-leakage workaround
(transform_filter(alt.FieldOneOfPredicate(...))) with a real Vega-Lite
feature (resolve_scale(color="independent")), and the cross-row linking is
backed by Vega's own group-scoping mechanism rather than relying on Altair's
selection-deduplication behavior (which works, but isn't a hard-documented
API guarantee).

This comes with two disclosed trade-offs, accepted as part of choosing this
approach:

• The NERACOOS logo can no longer be layered directly inside row 0 (Altair
  requires every layer of a faceted chart to share identical top-level data,
  and the logo's tiny image dataframe can't be merged into the tidy long
  frame without real awkwardness). It moves to its own thin strip above the
  faceted stack instead.
• Each facet row's hover tooltip shows the single nearest series's value
  (standard Vega-Lite nearest-point behavior), not a merged one-box readout
  across every series sharing that row's unit (e.g. two depths of the same
  variable). Merging would require a wide, per-row hit-frame, which conflicts
  with facet's shared-data rule the same way the logo does. This matches
  ordinary multi-line-chart tooltip behavior elsewhere and is not treated as
  a regression.

Approach

1. common.py — new shared helper: hover_crosshair()

Add after neracoos_logo() (common.py:309-362), same neighborhood since
it's the same kind of small chart-composition helper:

def hover_crosshair(
    data: pd.DataFrame,
    *,
    y: str,
    color: str,
    tooltip: list[alt.Tooltip],
    x: str = "time (UTC)",
    name_prefix: str = "hover",
) -> tuple[alt.Chart, alt.Chart, alt.Chart]:
    """Invisible-selector, visible-point, and crosshair-rule layers for a nearest-x hover.

    Layer the three returned charts alongside a plain mark_line() chart built
    from the same `data`/field names. When the same `data` is reused across
    multiple cells of one `.facet()` call (rather than independently built
    chart specs), hovering any one row's line moves the crosshair in every
    row: Vega-Lite compiles one shared top-level signal for the selection
    param, and only the per-cell interaction plumbing is replicated per facet
    cell by Vega's own faceting engine.

    Every layer gets an explicit `name=` to work around an Altair 6.2.2 bug
    (`_combine_subchart_params` crashes with `AttributeError: 'UndefinedType'
    object has no attribute 'rsplit'` when an unnamed layer sits inside a
    FacetChart that's itself inside a vconcat alongside another chart) --
    don't remove these as "redundant" on a future cleanup pass.
    """
    hover = alt.selection_point(
        fields=[x],
        nearest=True,
        on="pointerover",
        clear="pointerout",
        empty=False,
    )

    selectors = (
        alt.Chart(data, name=f"{name_prefix}_selectors")
        .mark_point()
        .encode(x=f"{x}:T", opacity=alt.value(0))
        .add_params(hover)
    )
    points = (
        alt.Chart(data, name=f"{name_prefix}_points")
        .mark_point()
        .encode(
            x=f"{x}:T",
            y=f"{y}:Q",
            color=alt.Color(f"{color}:N", legend=None),
            opacity=alt.condition(hover, alt.value(1), alt.value(0)),
            tooltip=tooltip,
        )
    )
    rule = (
        alt.Chart(data, name=f"{name_prefix}_rule")
        .mark_rule(color="gray")
        .encode(x=f"{x}:T")
        .transform_filter(hover)
    )
    return selectors, points, rule

2. by_platform.py — replace the row-building cell (lines 181-214)

Reshape into one fully tidy long frame (generic "value" column + "unit"
column, replacing the current "long by series, wide by unit" hybrid), then
build one faceted spec instead of a manual vconcat loop:

@app.cell
def _(filtered_df, platform_selector, unit_ts):
    _row_dfs = []
    for _unit, _ts_keys in unit_ts.items():
        _row_df = pd.melt(
            filtered_df[_ts_keys].reset_index(),
            id_vars="time (UTC)",
            var_name="variable",
            value_name="value",
        )
        _row_df["unit"] = _unit
        _row_dfs.append(_row_df)

    melted_df = pd.concat(_row_dfs, ignore_index=True)

    _line = alt.Chart(melted_df, name="line").mark_line().encode(
        x=alt.X("time (UTC):T", title="Time (UTC)"),
        y=alt.Y("value:Q", title=None),
        color=alt.Color("variable:N", title=None),
    )

    _selectors, _points, _rule = common.hover_crosshair(
        melted_df,
        y="value",
        color="variable",
        tooltip=[
            alt.Tooltip("time (UTC):T", title="Time (UTC)"),
            alt.Tooltip("variable:N", title="Series"),
            alt.Tooltip("value:Q", title="Value", format=".2f"),
            alt.Tooltip("unit:N", title="Unit"),
        ],
    )

    _cell = alt.layer(_line, _selectors, _points, _rule).properties(
        width="container",
        height=300,
    )

    # facet() replaces the manual for-loop + vconcat + per-row
    # transform_filter(FieldOneOfPredicate(...)) that used to stop each row's
    # legend from listing every other unit's series too; resolve_scale gives
    # each row its own independent y-domain and color scale/legend instead.
    _faceted = _cell.facet(
        row=alt.Row(
            "unit:N",
            header=alt.Header(title=None, labelFontWeight="bold"),
        ),
    ).resolve_scale(y="independent", color="independent")

    # The logo can't be layered inside one facet cell (Altair requires every
    # layer of a faceted chart to share identical top-level data), so it sits
    # as its own strip above the facet grid instead of inside row 0.
    _logo = common.neracoos_logo(
        filtered_df.index.max(),
        platform_selector.value["id"],
    ).properties(width="container", height=20)

    stack = alt.vconcat(_logo, _faceted, spacing=0).resolve_scale(x="shared")

    mo.ui.altair_chart(
        stack,
        chart_selection=False,
        legend_selection=False,
    )

Notes:

• alt.Row("unit:N", header=alt.Header(title=None, ...)) labels each row with
  the raw unit string (e.g. "degree_C", "hPa") — the same value that's
  the y-axis title today, just relocated to the row header since the y-axis
  now uses one generic "value" field shared by every row.
• Dropping .properties(width="container") on the outer stack isn't
  needed — the per-cell width="container" plus the logo's own
  width="container" already drive the responsive layout, and
  mo.ui.altair_chart serializes with validate=False either way (confirmed
  by reading marimo's _plugins/ui/_impl/altair_chart.py), so this is a
  no-op either way, not a required change.

3. by_standard_name.py — replace the chart cell (lines 238-252)

Single view, no facet — just add the tooltip/crosshair layers directly
(hover_crosshair()'s data param reused as-is, no reshape needed since this
page already has one shared unit column across all its series):

@app.cell
def _(filtered_df, standard_name_dropdown, standards, unit):
    _logo = common.neracoos_logo(
        filtered_df.index.max(),
        standards[standard_name_dropdown.value]["long_name"],
    )

    _reset = filtered_df.reset_index()

    _line = alt.Chart(_reset, name="line").mark_line().encode(
        x="time (UTC):T",
        y=f"{unit}:Q",
        color="Timeseries:N",
    )

    _selectors, _points, _rule = common.hover_crosshair(
        _reset,
        y=unit,
        color="Timeseries",
        tooltip=[
            alt.Tooltip("time (UTC):T", title="Time (UTC)"),
            alt.Tooltip("Timeseries:N", title="Buoy"),
            alt.Tooltip(f"{unit}:Q", title=unit, format=".2f"),
        ],
    )

    _chart = alt.layer(_line, _selectors, _points, _rule, _logo).properties(
        width="container",
    )

    mo.ui.altair_chart(_chart)

No cross-view linking applies here (one view), so this is purely the
tooltip + precision-hover fix, using the same helper for consistency with
by_platform.py.

Files touched

• common.py — add hover_crosshair().
• by_platform.py — replace the cell at lines 181-214.
• by_standard_name.py — replace the cell at lines 238-252.
• tests/e2e/test_by_platform.py / tests/e2e/test_by_standard_name.py —
  add a coarse "a tooltip appears on hover" smoke check (see Verification).

No changes to climatology.py, root.py, app.py, or calculate_datums.py.

Existing helpers reused unchanged: common.neracoos_logo(), and (upstream of
these cells, untouched) common.resample_to_budget() / common.MAX_ROWS for
the data volume these charts render.

Risks / things to watch during implementation

• The _combine_subchart_params workaround (explicit name= on every layer)
  is confirmed for altair==6.2.2 (pinned >=6,<7); leave the docstring
  note in hover_crosshair() explaining why, so it doesn't get "cleaned up"
  later.
• resolve_scale(color="independent") restarts the categorical color index
  per facet row — a pre-existing property of today's per-row independent
  charts too, not a new regression, but worth a glance during manual
  verification now that rows sit visually closer together in one spec.
• A timeseries with a falsy/None unit would produce a facet row with a
  blank header label — pre-existing behavior (today's loop already keys off
  the same unit_ts dict), not new, but worth a quick look.

Verification

Manual: run the actual multi-page app (not pixi run app, which only
runs climatology.py standalone) — use pixi run serve (granian, serves
app:app), then in a browser:

1. /by_platform/ — pick a platform with 2+ different-unit timeseries (e.g.
   the existing e2e test's "B01 - Western Maine Shelf" with "Air Temperature"
   • "Barometric Pressure"). Hover over either row's line and confirm a
     tooltip appears and a vertical gray rule appears at the same x in both
     rows simultaneously, tracking as the cursor moves.
2. Confirm each row's legend lists only that row's own series.
3. Confirm the logo renders once, above the stack.
4. /by_standard_name/ — pick a data type and 2+ platforms, hover, confirm a
   tooltip and rule appear (no cross-row linking expected here — single
   view).
5. Resize the browser window narrow and confirm the chart still fills its
   container (regression check for width="container" under faceting).

Automated: run pixi run -e test e2e (Playwright). Keep the existing
assert_chart_rendered(page) calls in both test files passing unmodified —
they already assert the chart settles at a real width and that no "Duplicate
signal name" text appears, which is the right regression guard for the
faceting/selection changes here. Add one small addition to
tests/e2e/helpers.py and call it from both test_by_platform.py and
test_by_standard_name.py right after assert_chart_rendered(page):

def assert_hover_tooltip_appears(page: Page) -> None:
    chart = wait_for_chart_settled(page)
    box = chart.bounding_box()
    page.mouse.move(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)
    expect(page.locator("#vg-tooltip-element")).to_be_visible()

Confirm #vg-tooltip-element is actually the id vega-embed's bundled
tooltip handler uses in this marimo version during the manual pass above
before relying on it in the test. This proves a tooltip renders at all (the
literal bug in #140); asserting that row 2's rule visibly moves when
hovering row 1 isn't practical for Playwright (would need canvas pixel
diffing or reaching into Vega's view API) — that stays a manual check per
step 1 above.

Also run the existing unit/lint suite (prek run --all-files, and whatever
the project's pytest command is for tests/unit/) to make sure nothing
else regresses.