Link neural activity to target playback

app.py

@@ -893,6 +893,7 @@ def dataset_cards(selected_dataset: str) -> list[html.Article]:
 def target_space_graph(figure: go.Figure, label: str) -> html.Div:
     return html.Div(
         dcc.Graph(
+            id="dataset-target-trajectory",
             figure=figure,
             config={"displaylogo": False, "responsive": True},
         ),
@@ -1002,10 +1003,85 @@ def separated_trajectory_values(
     return x_values, y_values
 
 
-def target_trajectory_space(dataset: str, frame: pd.DataFrame) -> html.Div:
+def add_linked_target_traces(
+    figure: go.Figure,
+    x_values: Sequence[float],
+    y_values: Sequence[float],
+    customdata: np.ndarray,
+    hovertemplate: str,
+    *,
+    base_width: float,
+    progress_width: float,
+    halo_width: float | None = None,
+) -> None:
+    x_values = list(x_values)
+    y_values = list(y_values)
+    if halo_width is not None:
+        figure.add_trace(
+            go.Scatter(
+                x=x_values,
+                y=y_values,
+                mode="lines",
+                line=dict(color="#FFFFFF", width=halo_width),
+                opacity=0.9,
+                hoverinfo="skip",
+                showlegend=False,
+            )
+        )
+    figure.add_trace(
+        go.Scatter(
+            x=x_values,
+            y=y_values,
+            mode="lines",
+            line=dict(color="#102A3A", width=base_width),
+            opacity=0.34,
+            customdata=customdata,
+            meta={"benchdash_role": "example_trajectory"},
+            hovertemplate=hovertemplate,
+            showlegend=False,
+        )
+    )
+    figure.add_trace(
+        go.Scatter(
+            x=[x_values[0]],
+            y=[y_values[0]],
+            mode="lines",
+            line=dict(color="#102A3A", width=progress_width),
+            hoverinfo="skip",
+            meta={"benchdash_role": "linked_target_progress"},
+            showlegend=False,
+        )
+    )
+    figure.add_trace(
+        go.Scatter(
+            x=[x_values[0]],
+            y=[y_values[0]],
+            mode="markers",
+            marker=dict(
+                size=14,
+                color="#D55E00",
+                line=dict(color="#FFFFFF", width=3),
+            ),
+            hoverinfo="skip",
+            meta={"benchdash_role": "linked_target_cursor"},
+            showlegend=False,
+        )
+    )
+
+
+def target_trajectory_space(
+    dataset: str,
+    frame: pd.DataFrame,
+    example: pd.DataFrame,
+) -> html.Div:
     for column in ["trial_index", "condition_id", "time_index", "time_ms", "target_0", "target_1"]:
         frame[column] = pd.to_numeric(frame[column], errors="coerce")
-    example = frame[frame["is_example"]].sort_values("time_index")
+    for column in ["time_index", "time_ms", "target_0", "target_1"]:
+        example[column] = pd.to_numeric(example[column], errors="coerce")
+    example = example.sort_values("time_index")
+    example_customdata = np.column_stack(
+        [example["time_ms"].to_numpy(), example["time_index"].to_numpy()]
+    )
     figure = go.Figure()
     legend_items: list[tuple[str, str]] = []
 
@@ -1026,16 +1102,18 @@ def target_trajectory_space(dataset: str, frame: pd.DataFrame) -> html.Div:
                 )
             )
             legend_items.append((condition_label(dataset, condition_id), color))
-        figure.add_trace(
-            go.Scattergl(
-                x=example["target_0"],
-                y=example["target_1"],
-                mode="lines",
-                line=dict(color="#102A3A", width=4),
-                customdata=example["time_ms"],
-                hovertemplate="Horizontal position=%{x:.3f}<br>Vertical position=%{y:.3f}<br>Time=%{customdata:.0f} ms<extra>Example</extra>",
-                showlegend=False,
-            )
+        add_linked_target_traces(
+            figure,
+            example["target_0"],
+            example["target_1"],
+            example_customdata,
+            (
+                "Horizontal position=%{x:.3f}<br>Vertical position=%{y:.3f}<br>"
+                "Paired bin=%{customdata[1]:.0f}<extra>Example</extra>"
+            ),
+            base_width=3,
+            progress_width=4,
+            halo_width=7,
         )
         figure.update_xaxes(title="Horizontal hand position")
         figure.update_yaxes(title="Vertical hand position", scaleanchor="x", scaleratio=1)
@@ -1069,15 +1147,14 @@ def target_trajectory_space(dataset: str, frame: pd.DataFrame) -> html.Div:
                 )
             )
             legend_items.append((MC_PROFILE_LABELS[condition_id], color))
-        figure.add_trace(
-            go.Scatter(
-                x=example["time_ms"],
-                y=example["target_0"],
-                mode="lines",
-                line=dict(color="#102A3A", width=3.5),
-                hovertemplate="Time=%{x:.0f} ms<br>Force=%{y:.3f}<extra>Example</extra>",
-                showlegend=False,
-            )
+        add_linked_target_traces(
+            figure,
+            example["time_ms"],
+            example["target_0"],
+            example_customdata,
+            "Paired bin=%{customdata[1]:.0f}<br>Force=%{y:.3f}<extra>Example</extra>",
+            base_width=3,
+            progress_width=4,
         )
         figure.add_vline(x=0, line_color="#71808D", line_dash="dash")
         figure.update_xaxes(title="Time from scoring onset (ms)")
@@ -1096,26 +1173,18 @@ def target_trajectory_space(dataset: str, frame: pd.DataFrame) -> html.Div:
                 hovertemplate="x=%{x:.3f}<br>y=%{y:.3f}<br>Samples=%{z}<extra></extra>",
             )
         )
-        figure.add_trace(
-            go.Scatter(
-                x=example["target_0"],
-                y=example["target_1"],
-                mode="lines",
-                line=dict(color="#FFFFFF", width=5),
-                hoverinfo="skip",
-                showlegend=False,
-            )
-        )
-        figure.add_trace(
-            go.Scatter(
-                x=example["target_0"],
-                y=example["target_1"],
-                mode="lines",
-                line=dict(color="#102A3A", width=2.5),
-                customdata=example["time_ms"],
-                hovertemplate="x=%{x:.3f}<br>y=%{y:.3f}<br>Time=%{customdata:.0f} ms<extra>Example</extra>",
-                showlegend=False,
-            )
+        add_linked_target_traces(
+            figure,
+            example["target_0"],
+            example["target_1"],
+            example_customdata,
+            (
+                "x=%{x:.3f}<br>y=%{y:.3f}<br>"
+                "Paired bin=%{customdata[1]:.0f}<extra>Example</extra>"
+            ),
+            base_width=2.5,
+            progress_width=3.5,
+            halo_width=5,
         )
         figure.update_xaxes(title="x position", range=[0, 1])
         figure.update_yaxes(title="y position", range=[0, 1], scaleanchor="x", scaleratio=1)
@@ -1123,7 +1192,12 @@ def target_trajectory_space(dataset: str, frame: pd.DataFrame) -> html.Div:
         aria_label = "All simulated position targets shown as spatial occupancy density."
 
     figure_layout(figure, height=410)
-    figure.update_layout(margin=dict(l=62, r=24, t=18, b=62), showlegend=False)
+    figure.update_layout(
+        margin=dict(l=62, r=24, t=18, b=62),
+        showlegend=False,
+        meta={"benchdash_dataset": dataset},
+        uirevision=f"target-space-{dataset}",
+    )
     return html.Div(
         [
             html.Div(
@@ -1137,13 +1211,43 @@ def target_trajectory_space(dataset: str, frame: pd.DataFrame) -> html.Div:
     )
 
 
-def dataset_example_figures(dataset: str) -> tuple[go.Figure, html.Div, str]:
+def dataset_link_payload(dataset: str, example: pd.DataFrame) -> dict:
+    if dataset in {"allen_neuropixels", "speech"}:
+        return {"dataset": dataset, "enabled": False}
+    for column in ["time_index", "time_ms", "target_0", "target_1"]:
+        example[column] = pd.to_numeric(example[column], errors="coerce")
+    example = example.sort_values("time_index")
+    if dataset == "mc_pacman":
+        plot_x = example["time_ms"].to_numpy(dtype=float)
+        plot_y = example["target_0"].to_numpy(dtype=float)
+        value_kind = "force"
+    else:
+        plot_x = example["target_0"].to_numpy(dtype=float)
+        plot_y = example["target_1"].to_numpy(dtype=float)
+        value_kind = "position"
+    times = example["time_ms"].to_numpy(dtype=float)
+    return {
+        "dataset": dataset,
+        "enabled": True,
+        "time_index": example["time_index"].astype(int).tolist(),
+        "time_ms": times.tolist(),
+        "plot_x": plot_x.tolist(),
+        "plot_y": plot_y.tolist(),
+        "value_kind": value_kind,
+        "initial_index": int(np.argmin(np.abs(times))),
+    }
+
+
+def dataset_example_figures(dataset: str) -> tuple[go.Figure, html.Div, str, dict]:
     metadata = dataset_overview[dataset_overview["dataset"].astype(str).eq(dataset)].iloc[0]
     neural = dataset_example_neural[
         dataset_example_neural["dataset"].astype(str).eq(dataset)
     ].copy()
     targets = dataset_targets[dataset_targets["dataset"].astype(str).eq(dataset)].copy()
     targets["is_example"] = targets["is_example"].astype(str).str.lower().eq("true")
+    example_target = dataset_example_targets[
+        dataset_example_targets["dataset"].astype(str).eq(dataset)
+    ].copy()
     for column in (
         "time_index",
         "time_ms",
@@ -1168,7 +1272,13 @@ def dataset_example_figures(dataset: str) -> tuple[go.Figure, html.Div, str]:
         .sort_values("feature_display_index")["feature_index"]
         .to_numpy(dtype=int)
     )
-    customdata = np.repeat(feature_ids[:, None], values.shape[1], axis=1)
+    feature_customdata = np.repeat(feature_ids[:, None], values.shape[1], axis=1)
+    time_customdata = np.repeat(
+        np.arange(values.shape[1], dtype=int)[None, :],
+        values.shape[0],
+        axis=0,
+    )
+    customdata = np.stack([feature_customdata, time_customdata], axis=-1)
     upper = max(int(np.ceil(np.nanmax(values.to_numpy(dtype=float)))), 1)
     if upper <= 4:
         count_ticks = list(range(upper + 1))
@@ -1193,21 +1303,25 @@ def dataset_example_figures(dataset: str) -> tuple[go.Figure, html.Div, str]:
                 ticktext=[str(value) for value in count_ticks],
             ),
             hovertemplate=(
-                "Feature=%{customdata}<br>Time=%{x:.0f} ms<br>"
+                "Feature=%{customdata[0]}<br>Time=%{x:.0f} ms<br>"
                 "Count=%{z:.0f}<extra></extra>"
             ),
         )
     )
-    neural_figure.add_vline(x=0, line_color="#D55E00", line_dash="dash")
+    neural_figure.add_vline(x=0, line_color="#71808D", line_dash="dash")
     neural_figure.update_xaxes(title="Time from scoring onset (ms)")
     neural_figure.update_yaxes(title="Neural features", showticklabels=False)
     figure_layout(neural_figure, height=470)
-    neural_figure.update_layout(margin=dict(l=58, r=62, t=18, b=62))
+    neural_figure.update_layout(
+        margin=dict(l=58, r=62, t=18, b=62),
+        meta={"benchdash_dataset": dataset},
+        uirevision=f"dataset-neural-{dataset}",
+    )
 
     if dataset in {"allen_neuropixels", "speech"}:
         target_component = target_class_space(dataset, targets)
     else:
-        target_component = target_trajectory_space(dataset, targets)
+        target_component = target_trajectory_space(dataset, targets, example_target.copy())
 
     shown = int(metadata.example_features_shown)
     total = int(metadata.array_shape.split("×")[-1].strip())
@@ -1216,11 +1330,19 @@ def dataset_example_figures(dataset: str) -> tuple[go.Figure, html.Div, str]:
         if shown == total
         else f"{shown} of {total} neural features are shown for legibility"
     )
-    description = (
-        f"The highlighted target corresponds to the neural activity shown at left; "
-        f"{feature_text}."
+    if dataset in {"allen_neuropixels", "speech"}:
+        description = (
+            f"The highlighted target corresponds to the neural activity shown at left; "
+            f"{feature_text}."
+        )
+    else:
+        description = f"{feature_text.capitalize()}."
+    return (
+        neural_figure,
+        target_component,
+        description,
+        dataset_link_payload(dataset, example_target),
     )
-    return neural_figure, target_component, description
 
 
 def overview_cards(dataset: str, models: Sequence[str] | None) -> list[html.Div]:
@@ -2758,6 +2880,11 @@ app.layout = html.Div(
                         ),
                         panel(
                             "Neural activity and task targets",
+                            dcc.Store(id="dataset-link-data"),
+                            html.Span(
+                                id="dataset-link-render-token",
+                                className="feature-story-render-token",
+                            ),
                             html.Div(
                                 [
                                     html.Div(
@@ -2774,11 +2901,15 @@ app.layout = html.Div(
                                                 "Example trial neural activity for the selected dataset.",
                                             ),
                                         ],
-                                        className="dataset-example-card",
+                                        className="dataset-example-card dataset-neural-card",
+                                    ),
+                                    html.Div(
+                                        id="dataset-link-controls",
+                                        className="dataset-link-controls",
                                     ),
                                     html.Div(
                                         id="dataset-target-space",
-                                        className="dataset-example-card",
+                                        className="dataset-example-card dataset-target-card",
                                     ),
                                 ],
                                 className="dataset-example-grid",
@@ -3106,12 +3237,28 @@ app.clientside_callback(
     Output("dataset-neural-example", "figure"),
     Output("dataset-target-space", "children"),
     Output("dataset-example-description", "children"),
+    Output("dataset-link-data", "data"),
     Input("dataset-filter", "value"),
 )
 def update_dataset_examples(dataset: str):
     dataset = dataset or DATASETS[0]
-    neural, target, description = dataset_example_figures(dataset)
-    return dataset_cards(dataset), neural, target, description
+    neural, target, description, link_data = dataset_example_figures(dataset)
+    return dataset_cards(dataset), neural, target, description, link_data
+
+
+app.clientside_callback(
+    """
+    function(linkData, activeTab) {
+        if (!window.benchdashDatasetLink) {
+            return window.dash_clientside.no_update;
+        }
+        return window.benchdashDatasetLink.schedule(linkData, activeTab);
+    }
+    """,
+    Output("dataset-link-render-token", "children"),
+    Input("dataset-link-data", "data"),
+    Input("tabs", "value"),
+)
 
 
 @app.callback(

assets/dataset_link.js

@@ -0,0 +1,340 @@
+(function () {
+  "use strict";
+
+  const CURSOR_COLOR = "#D55E00";
+  const PLAYBACK_DURATION_MS = 4200;
+  const autoplaySeen = new Set();
+  let activeState = null;
+  let scheduleGeneration = 0;
+
+  function clamp(value, low, high) {
+    return Math.max(low, Math.min(high, value));
+  }
+
+  function traceRole(trace) {
+    return trace && trace.meta && trace.meta.benchdash_role;
+  }
+
+  function traceIndex(graph, role) {
+    return graph.data.findIndex((trace) => traceRole(trace) === role);
+  }
+
+  function graphDataset(graph) {
+    return graph && graph.layout && graph.layout.meta && graph.layout.meta.benchdash_dataset;
+  }
+
+  function formatNumber(value, digits) {
+    if (!Number.isFinite(Number(value))) return "—";
+    const number = Number(value);
+    const magnitude = Math.abs(number);
+    const precision = magnitude >= 10 ? 2 : digits;
+    return number.toFixed(precision).replace(/^-/, "−");
+  }
+
+  function formatTime(value) {
+    const rounded = Math.round(Number(value));
+    if (rounded === 0) return "Neural time 0 ms";
+    return `Neural time ${rounded < 0 ? "−" : "+"}${Math.abs(rounded)} ms`;
+  }
+
+  function makeElement(tag, className, text) {
+    const node = document.createElement(tag);
+    if (className) node.className = className;
+    if (text !== undefined) node.textContent = text;
+    return node;
+  }
+
+  function buildControls(state) {
+    const lead = makeElement("div", "dataset-link-lead");
+    lead.append(
+      makeElement("strong", "dataset-link-title", "Linked trial"),
+      makeElement(
+        "span",
+        "dataset-link-hint",
+        "Hover the raster, scrub the timeline or press play."
+      )
+    );
+
+    const button = makeElement("button", "dataset-link-button", "Play");
+    button.type = "button";
+    button.setAttribute("aria-label", "Play linked neural activity and target trajectory");
+
+    const slider = makeElement("input", "dataset-link-slider");
+    slider.type = "range";
+    slider.min = "0";
+    slider.max = String(state.payload.time_ms.length - 1);
+    slider.step = "1";
+    slider.value = String(state.payload.initial_index || 0);
+    slider.setAttribute("aria-label", "Linked trial time bin");
+
+    const readout = makeElement("div", "dataset-link-readout");
+    const time = makeElement("span", "dataset-link-time");
+    const value = makeElement("span", "dataset-link-value");
+    readout.append(time, value);
+
+    const transport = makeElement("div", "dataset-link-transport");
+    transport.append(button, slider, readout);
+    state.controls.replaceChildren(lead, transport);
+    state.button = button;
+    state.slider = slider;
+    state.timeReadout = time;
+    state.valueReadout = value;
+  }
+
+  function setButton(state) {
+    state.button.textContent = state.playing ? "Pause" : "Play";
+    state.button.setAttribute(
+      "aria-label",
+      state.playing
+        ? "Pause linked neural activity and target trajectory"
+        : "Play linked neural activity and target trajectory"
+    );
+  }
+
+  function positionPlayhead(state) {
+    if (!state.neural.isConnected || !state.neural._fullLayout) return;
+    const layout = state.neural._fullLayout;
+    const axis = layout.xaxis;
+    const size = layout._size;
+    if (!axis || !size) return;
+    const time = Number(state.payload.time_ms[state.index]);
+    const left = size.l + axis.l2p(time);
+    state.playhead.style.left = `${left}px`;
+    state.playhead.style.top = `${size.t}px`;
+    state.playhead.style.height = `${size.h}px`;
+  }
+
+  function updateReadout(state) {
+    const index = state.index;
+    const x = Number(state.payload.plot_x[index]);
+    const y = Number(state.payload.plot_y[index]);
+    state.timeReadout.textContent = formatTime(state.payload.time_ms[index]);
+    state.valueReadout.textContent = state.payload.value_kind === "force"
+      ? `Paired force ${formatNumber(y, 3)}`
+      : `Paired target x ${formatNumber(x, 3)} · y ${formatNumber(y, 3)}`;
+  }
+
+  function renderIndex(state, requestedIndex) {
+    const lastIndex = state.payload.time_ms.length - 1;
+    const index = clamp(Math.round(Number(requestedIndex)), 0, lastIndex);
+    if (!Number.isFinite(index)) return;
+    state.index = index;
+    state.slider.value = String(index);
+    positionPlayhead(state);
+    updateReadout(state);
+
+    if (state.renderFrame !== null) cancelAnimationFrame(state.renderFrame);
+    state.renderFrame = requestAnimationFrame(() => {
+      state.renderFrame = null;
+      if (!state.target.isConnected || !state.target._fullLayout || !window.Plotly) return;
+      const progressX = state.payload.plot_x.slice(0, index + 1);
+      const progressY = state.payload.plot_y.slice(0, index + 1);
+      window.Plotly.restyle(
+        state.target,
+        {
+          x: [progressX, [state.payload.plot_x[index]]],
+          y: [progressY, [state.payload.plot_y[index]]],
+        },
+        [state.progressTrace, state.cursorTrace]
+      );
+    });
+  }
+
+  function pause(state) {
+    state.playing = false;
+    if (state.animationFrame !== null) cancelAnimationFrame(state.animationFrame);
+    state.animationFrame = null;
+    setButton(state);
+  }
+
+  function play(state) {
+    pause(state);
+    const finalIndex = state.payload.time_ms.length - 1;
+    if (state.index >= finalIndex) renderIndex(state, 0);
+    const startIndex = state.index;
+    const stepDuration = PLAYBACK_DURATION_MS / Math.max(finalIndex, 1);
+    const start = performance.now();
+    state.playing = true;
+    setButton(state);
+
+    const advance = (now) => {
+      if (!state.playing || activeState !== state) return;
+      const elapsedSteps = Math.floor((now - start) / stepDuration);
+      const nextIndex = Math.min(finalIndex, startIndex + elapsedSteps);
+      if (nextIndex !== state.index) renderIndex(state, nextIndex);
+      if (nextIndex >= finalIndex) {
+        pause(state);
+        return;
+      }
+      state.animationFrame = requestAnimationFrame(advance);
+    };
+    state.animationFrame = requestAnimationFrame(advance);
+  }
+
+  function eventIndex(state, event) {
+    const point = event && event.points && event.points[0];
+    const custom = point && point.customdata;
+    if (Array.isArray(custom) && Number.isFinite(Number(custom[1]))) {
+      return Number(custom[1]);
+    }
+    const time = point && Number(point.x);
+    if (!Number.isFinite(time)) return null;
+    let bestIndex = 0;
+    let bestDistance = Infinity;
+    state.payload.time_ms.forEach((candidate, index) => {
+      const distance = Math.abs(Number(candidate) - time);
+      if (distance < bestDistance) {
+        bestDistance = distance;
+        bestIndex = index;
+      }
+    });
+    return bestIndex;
+  }
+
+  function bindInteractions(state) {
+    const abort = state.abortController;
+    const selectFromNeural = (event) => {
+      const index = eventIndex(state, event);
+      if (index === null) return;
+      pause(state);
+      renderIndex(state, index);
+    };
+    const selectFromTarget = (event) => {
+      const point = event && event.points && event.points[0];
+      if (!point || point.curveNumber !== state.exampleTrace) return;
+      const index = eventIndex(state, event);
+      if (index === null) return;
+      pause(state);
+      renderIndex(state, index);
+    };
+    state.neural.on("plotly_hover", selectFromNeural);
+    state.neural.on("plotly_click", selectFromNeural);
+    state.target.on("plotly_hover", selectFromTarget);
+    state.target.on("plotly_click", selectFromTarget);
+    state.plotlyListeners = [
+      [state.neural, "plotly_hover", selectFromNeural],
+      [state.neural, "plotly_click", selectFromNeural],
+      [state.target, "plotly_hover", selectFromTarget],
+      [state.target, "plotly_click", selectFromTarget],
+    ];
+
+    state.button.addEventListener("click", () => {
+      if (state.playing) pause(state);
+      else play(state);
+    }, { signal: abort.signal });
+    state.slider.addEventListener("input", () => {
+      pause(state);
+      renderIndex(state, Number(state.slider.value));
+    }, { signal: abort.signal });
+    state.resizeObserver = new ResizeObserver(() => {
+      requestAnimationFrame(() => positionPlayhead(state));
+    });
+    state.resizeObserver.observe(state.neural);
+  }
+
+  function maybeAutoplay(state) {
+    const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    const mobile = window.matchMedia("(max-width: 560px)").matches;
+    if (reducedMotion || mobile || autoplaySeen.has(state.payload.dataset)) return;
+    state.intersectionObserver = new IntersectionObserver((entries) => {
+      const visible = entries.some((entry) => entry.isIntersecting && entry.intersectionRatio >= 0.25);
+      if (!visible || activeState !== state) return;
+      autoplaySeen.add(state.payload.dataset);
+      state.intersectionObserver.disconnect();
+      state.intersectionObserver = null;
+      state.autoplayTimer = window.setTimeout(() => {
+        if (activeState === state) {
+          renderIndex(state, 0);
+          play(state);
+        }
+      }, 450);
+    }, { threshold: [0.25] });
+    state.intersectionObserver.observe(state.controls);
+  }
+
+  function destroy(state) {
+    if (!state) return;
+    pause(state);
+    if (state.renderFrame !== null) cancelAnimationFrame(state.renderFrame);
+    if (state.autoplayTimer !== null) window.clearTimeout(state.autoplayTimer);
+    if (state.resizeObserver) state.resizeObserver.disconnect();
+    if (state.intersectionObserver) state.intersectionObserver.disconnect();
+    if (state.abortController) state.abortController.abort();
+    (state.plotlyListeners || []).forEach(([graph, event, listener]) => {
+      if (graph && typeof graph.removeListener === "function") {
+        graph.removeListener(event, listener);
+      }
+    });
+    if (state.playhead) state.playhead.remove();
+  }
+
+  function mount(payload) {
+    const controls = document.getElementById("dataset-link-controls");
+    const neural = document.querySelector("#dataset-neural-example .js-plotly-plot");
+    const target = document.querySelector("#dataset-target-trajectory .js-plotly-plot");
+    if (!controls || !neural || !target || !neural._fullLayout || !target._fullLayout) {
+      return false;
+    }
+    if (graphDataset(neural) !== payload.dataset || graphDataset(target) !== payload.dataset) {
+      return false;
+    }
+    const exampleTrace = traceIndex(target, "example_trajectory");
+    const progressTrace = traceIndex(target, "linked_target_progress");
+    const cursorTrace = traceIndex(target, "linked_target_cursor");
+    if ([exampleTrace, progressTrace, cursorTrace].some((index) => index < 0)) return false;
+
+    const state = {
+      payload,
+      controls,
+      neural,
+      target,
+      exampleTrace,
+      progressTrace,
+      cursorTrace,
+      index: payload.initial_index || 0,
+      playing: false,
+      animationFrame: null,
+      renderFrame: null,
+      autoplayTimer: null,
+      resizeObserver: null,
+      intersectionObserver: null,
+      abortController: new AbortController(),
+      plotlyListeners: [],
+    };
+    const playhead = makeElement("div", "dataset-linked-playhead");
+    playhead.style.backgroundColor = CURSOR_COLOR;
+    playhead.setAttribute("aria-hidden", "true");
+    neural.style.position = "relative";
+    neural.appendChild(playhead);
+    state.playhead = playhead;
+    buildControls(state);
+    bindInteractions(state);
+    activeState = state;
+    renderIndex(state, state.index);
+    maybeAutoplay(state);
+    return true;
+  }
+
+  function schedule(payload, activeTab) {
+    scheduleGeneration += 1;
+    const generation = scheduleGeneration;
+    destroy(activeState);
+    activeState = null;
+    const controls = document.getElementById("dataset-link-controls");
+    if (!payload || !payload.enabled || activeTab !== "datasets") {
+      if (controls) controls.replaceChildren();
+      return `${payload && payload.dataset ? payload.dataset : "none"}:inactive`;
+    }
+    let attempts = 0;
+    const tryMount = () => {
+      if (generation !== scheduleGeneration) return;
+      if (mount(payload)) return;
+      attempts += 1;
+      if (attempts < 180) requestAnimationFrame(tryMount);
+    };
+    requestAnimationFrame(tryMount);
+    return `${payload.dataset}:scheduled`;
+  }
+
+  window.benchdashDatasetLink = { schedule };
+})();

assets/styles.css

@@ -480,6 +480,124 @@ h2 {
   background: #ffffff;
 }
 
+.dataset-neural-card {
+  grid-column: 1;
+  grid-row: 1;
+}
+
+.dataset-target-card {
+  grid-column: 2;
+  grid-row: 1;
+}
+
+.dataset-link-controls {
+  grid-column: 1 / -1;
+  grid-row: 2;
+}
+
+.dataset-link-controls:empty {
+  display: none;
+}
+
+.dataset-link-controls:not(:empty) {
+  display: grid;
+  grid-template-columns: minmax(210px, 0.38fr) minmax(420px, 1fr);
+  gap: 18px;
+  align-items: center;
+  padding: 11px 13px;
+  border: 1px solid #dbe4e9;
+  border-radius: 8px;
+  background: #f7f9fa;
+}
+
+.dataset-link-lead {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: 1px;
+}
+
+.dataset-link-title {
+  color: #253b49;
+  font-size: 11px;
+  font-weight: 800;
+  letter-spacing: 0.055em;
+  text-transform: uppercase;
+}
+
+.dataset-link-hint {
+  overflow: hidden;
+  color: #647681;
+  font-size: 10px;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.dataset-link-transport {
+  display: grid;
+  grid-template-columns: auto minmax(160px, 1fr) minmax(250px, auto);
+  gap: 12px;
+  align-items: center;
+  min-width: 0;
+}
+
+.dataset-link-button {
+  min-width: 62px;
+  min-height: 32px;
+  padding: 5px 11px;
+  border: 1px solid #b94805;
+  border-radius: 6px;
+  background: #ffffff;
+  color: #a73f04;
+  cursor: pointer;
+  font: inherit;
+  font-size: 11px;
+  font-weight: 780;
+}
+
+.dataset-link-button:hover {
+  background: #fff5ef;
+}
+
+.dataset-link-slider {
+  width: 100%;
+  min-width: 0;
+  accent-color: #d55e00;
+  cursor: ew-resize;
+}
+
+.dataset-link-readout {
+  display: flex;
+  min-width: 0;
+  justify-content: flex-end;
+  gap: 10px;
+  color: #536773;
+  font-size: 10px;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+.dataset-link-time {
+  min-width: 112px;
+  color: #2f4654;
+  font-weight: 760;
+}
+
+.dataset-link-value {
+  overflow: hidden;
+  max-width: 210px;
+  text-overflow: ellipsis;
+}
+
+.dataset-linked-playhead {
+  position: absolute;
+  z-index: 8;
+  width: 2px;
+  border-radius: 999px;
+  box-shadow: 0 0 0 1px rgba(255, 255, 255, 0.86);
+  pointer-events: none;
+}
+
 .dataset-viz-heading {
   display: flex;
   min-height: 58px;
@@ -1154,6 +1272,25 @@ h2 {
     grid-template-columns: 1fr;
   }
 
+  .dataset-neural-card {
+    grid-column: 1;
+    grid-row: 1;
+  }
+
+  .dataset-link-controls {
+    grid-column: 1;
+    grid-row: 2;
+  }
+
+  .dataset-target-card {
+    grid-column: 1;
+    grid-row: 3;
+  }
+
+  .dataset-example-grid:has(.dataset-link-controls:empty) .dataset-target-card {
+    grid-row: 2;
+  }
+
 }
 
 @media (max-width: 820px) {
@@ -1201,6 +1338,11 @@ h2 {
     grid-template-columns: 1fr;
   }
 
+  .dataset-link-controls:not(:empty) {
+    grid-template-columns: 1fr;
+    gap: 8px;
+  }
+
   .feature-method-control {
     max-width: none;
   }
@@ -1241,6 +1383,29 @@ h2 {
     text-align: left;
   }
 
+  .dataset-link-controls:not(:empty) {
+    grid-template-columns: 1fr;
+    gap: 8px;
+  }
+
+  .dataset-link-hint {
+    white-space: normal;
+  }
+
+  .dataset-link-transport {
+    grid-template-columns: auto minmax(120px, 1fr);
+    gap: 8px;
+  }
+
+  .dataset-link-readout {
+    grid-column: 1 / -1;
+    justify-content: space-between;
+  }
+
+  .dataset-link-value {
+    max-width: 170px;
+  }
+
   .target-class-grid,
   .target-space-legend {
     grid-template-columns: repeat(2, minmax(0, 1fr));