Skip to content

Timeline: the portal's root labels, sub-track order, hovered row and same-day lab values (PAT-TL-TR-1, TR-2, TR-5, TT-4) - #495

Open
alisman wants to merge 5 commits into
masterfrom
patient-timeline
Open

alisman wants to merge 5 commits into
masterfrom
patient-timeline

Conversation

@alisman

@alisman alisman commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

What

Four commits bring the Patient timeline's rows in line with the portal (cbioportal-clinical-timeline, timeline_helpers.tsx):

  1. PAT-TL-TR-1, root track labels.
    • Legacy groups a patient's events by eventType.toUpperCase() and labels each root track with it ("SPECIMEN", "SAMPLE ACQUISITION", "LAB_TEST"), and its TrackHeader shows every label without underscores ("LABTEST").
    • Ours kept the study's spelling ("Specimen"). Root tracks now use rootLabel, and the figure shows trackLabel (no underscores) for every track; the data labels and uids are unchanged. Sub-tracks keep their attribute values ("Chemo", "CEA"), as legacy's do.
  2. PAT-TL-TR-5, hovered row.
    • Legacy bands the row under the pointer (#F2F2F2, label and row); ours only lit a collapsible track's label.
    • The card finds the row from the figure's own layout (rowAt) and draws the band across it, multiplied over the white figure, so marks keep their colours. It takes no pointer events.
    • Page chrome only: the SVG is unchanged.
  3. PAT-TL-TR-2, sub-track order.
    • Legacy sortNestedTracks sorts by items[0].start. A track whose events all sit in its own sub-tracks holds none and sorts as 0. Ties keep first-occurrence order (lodash's stable sortBy).
    • Ours took the earliest start below a track and broke ties by label, so lgg_ucsf_2014 P04 listed Medical Therapy above Radiation Therapy (both day 488). The portal, and its API's event order, has Radiation Therapy first.
    • Now trackSortKey and a stable sort.
  4. PAT-TL-TT-4, simultaneous line-chart values.
    • Legacy plots one point a day on a lab line chart, at the highest value (getLineChartYCoordinateForEvents). Its tooltip pages through the day's events with "Plotted y value is the max of simultaneous events."
    • Ours drew each value as its own point. Now linePoints gives one point a day, its mark carries the day's events (data-line), and the tooltip adds the portal's note.

Checked

  • lgg_ucsf_2014 P04, in a headless browser:

    • The root labels read SPECIMEN, SURGERY, STATUS, TREATMENT.
    • TREATMENT's rows read Radiation Therapy, XRT, Medical Therapy, Chemotherapy, TMZ.
    • Hovering SURGERY draws a 20 px band over that row alone, cleared on leaving.
  • msk_chord_2024 P-0022637: 68 same-day lab marks. Hovering one gives "‹ 1 of 2 events › Plotted y value is the max of simultaneous events." No console errors.

  • test/timeline.test.ts:

    • the labels, rowAt's edges;
    • trackSortKey (P04's tie; a track's first listed event, not its earliest; parents at 0);
    • linePoints (max per day, marks per day, censored bounds kept).
  • The timeline snapshot was re-rendered (labels and row order).

  • npm test (after the review fixes): 7173 pass, 0 fail (39 todo). eslint is clean on the touched files.

  • Planted bugs in scripts/mutants/patient/timeline-track-labels.ts, each applied by hand and caught by the importing suites, the file restored:

    • timeline-root-label-as-spelled
    • timeline-hot-row-edge
    • timeline-parent-tracks-last
    • timeline-line-first-of-day

    timeline-download-interactive-marks follows its renamed site and is still caught.

  • Sites checked by script: each find occurs exactly once (755 bugs, 0 bad).

  • Merges cleanly with Pathways: the "Sample(s) … not profiled for …" alert (PTB-PW-1) #487 and Genomic Evolution table: the Annotation (OncoKB) column (PTB-GE-TB-1) #488.

Tracker

docs/legacy-spec/parity/40-patient-summary.md

ID verdict how note
PAT-TL-TR-1 ✅ B Root order ✅ (TRACK_ORDER); labels are the event type upper-cased and every label shown without underscores, as legacy's getTrackLabel ("SPECIMEN", "SAMPLE ACQUISITION", "LABTEST"; rootLabel, trackLabel, lib/timeline-tracks.ts); sub-tracks keep their values
PAT-TL-TR-2 ✅ B Nesting and lone-Other collapse ✅ (TCGA: Treatment › Other › Conatumumab …); sub-tracks sorted by their first event's start, a track holding only sub-tracks at 0, ties in first-occurrence order, as legacy's sortNestedTracks (trackSortKey; P1: Radiation Therapy above Medical Therapy, both day 488, as legacy)
PAT-TL-TR-5 ✅ C The row under the pointer banded #F2F2F2 across label and plot (rowAt, app/lab/timeline-body.tsx); collapsible labels also lit
PAT-TL-TT-4 ✅ B One event at a time, "‹ i of n events ›", ←/↓ previous and →/↑/space next, wrapping ✅ (msk_chord P-0000012 Treatment: 1 of 2 → 2 of 2); a line chart plots each day's highest value and its tooltip adds "Plotted y value is the max of simultaneous events." ✅ (linePoints; msk_chord_2024 P-0022637 PSA)

docs/PORTAL-PARITY.md, under the sub-item Timeline: drag-zoom, PDF/PNG/SVG/ZIP download, month ticks, tooltips pinned and paged, the sample row's clinical data in its tooltip (PAT-TL-ZM-1, PAT-TL-ZM-3, PAT-TL-ZM-4, PAT-TL-TT-1…4), after its last line, Drag to zoom, reset zoom and the cursor line (PAT-TL-ZM-3) (#405), add:

- [x] A lab line chart plots each day's highest value, its tooltip saying "Plotted y value is the max of simultaneous events." (PAT-TL-TT-4) (#495)
- [x] Root tracks named by the event type upper-cased, sub-tracks in the portal's sortNestedTracks order, the hovered row banded #F2F2F2 (PAT-TL-TR-1, PAT-TL-TR-2, PAT-TL-TR-5) (#495)

🤖 Generated with Claude Code

https://claude.ai/code/session_01Q3ezTVY3MHJRLp4DsZ9c7C

alisman and others added 4 commits November 19, 2026 22:14
…R-1)

The portal groups a patient's events by eventType.toUpperCase() and names
each root track with it ("SPECIMEN", "SAMPLE ACQUISITION", "LAB_TEST";
timeline_helpers). Ours kept the study's commonest spelling ("Specimen",
"Sample acquisition"). Root tracks now take rootLabel, that spelling
upper-cased. Sub-tracks keep their attribute values ("Chemo", "CEA"), as the
portal's do.

Tests updated for the new labels; the timeline snapshot re-rendered (labels
only).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q3ezTVY3MHJRLp4DsZ9c7C
…-TL-TR-5)

The portal highlights the timeline row the pointer is on (#F2F2F2, label and
row). Ours lit only a collapsible track's label. The card now finds the row
under the pointer from the figure's own layout (rowAt, lib/timeline-svg.ts)
and draws the band across the whole row, label and plot. The band is
multiplied over the white figure, so the marks keep their colours, and it
takes no pointer events. Page chrome only: the figure and its SVG are
unchanged.

Checked on lgg_ucsf_2014 P04: hovering the SURGERY row draws a 20-px band
over exactly that row. Leaving the figure clears it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q3ezTVY3MHJRLp4DsZ9c7C
The portal sorts a track's sub-tracks by their first event's start
(sortNestedTracks: items[0].start). A sub-track whose events all sit in its
own sub-tracks holds none and sorts as 0. A stable sort keeps ties in the
order the values first occur. Ours took the earliest start anywhere below a
track and broke ties by label. On lgg_ucsf_2014 P04 that put Medical Therapy
above Radiation Therapy, both day 488; the portal lists Radiation Therapy
first, as its API lists the events.

trackSortKey (lib/timeline-tracks.ts) is the portal's key, and sortChildren
sorts stably by it. Checked: P04's timeline now reads TREATMENT, Radiation
Therapy, XRT, Medical Therapy, Chemotherapy, TMZ. The timeline snapshot was
re-rendered (row order only).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q3ezTVY3MHJRLp4DsZ9c7C
…o (PAT-TL-TT-4)

The portal's line-chart rows group a day's events into one point at the
highest of their values (getLineChartYCoordinateForEvents). That point's
tooltip pages through the day's events, noting "Plotted y value is the max of
simultaneous events." Ours drew each value as its own point, with the line
zigzagging through them.

linePoints (lib/timeline-svg.ts) gives one point a day, at its highest value;
its mark carries every event of the day (data-line marks a line chart's day).
The card's tooltip adds the portal's note when such a mark holds more than
one event. The planted bug timeline-download-interactive-marks follows the
renamed site.

Checked: msk_chord_2024 P-0022637 has 68 same-day lab marks; hovering one
gives "‹ 1 of 2 events ›  Plotted y value is the max of simultaneous events."

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q3ezTVY3MHJRLp4DsZ9c7C
@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
cbiolab-genie Ready Ready Preview Nov 19, 2026 10:42pm UTC
cbiolab-new Ready Ready Preview Nov 19, 2026 10:42pm UTC
cohort-lab Ready Ready Preview Nov 19, 2026 10:42pm UTC

Request Review

Comment thread lib/timeline-svg.ts
if (tr.draw === "line" && !r.collapsed) {
const pts = r.items.map((it) => ({ it, v: numericResult(ev[it.i])! })).sort((a, b) => a.it.start - b.it.start);
const pts = linePoints(r.items, ev);
const { lo, hi } = lineRange(r.items);

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Line-chart axis range still comes from every value, including the ones no longer plotted. linePoints now plots only each day's highest value, but lineRange(r.items) (here and at L147 for the tick column) still takes min/max over all items. Example: CEA 1.8 and 3.2 on day 10, 2.0 on day 20. The bottom tick reads "1.8" and the scale reserves room for it, yet no point is drawn at 1.8, so the plotted line is squeezed. Taking the range over linePoints(...).map(p => p.v.v) would make the ticks match what is drawn (unless the portal's axis deliberately spans all values; if so, cite that).

Comment thread lib/timeline-svg.ts
for (const p of pts) {
const c = colorOf(ev[p.it.i]);
const c = colorOf(ev[p.at]);
if (p.v.censored) censored++;

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The censored count now covers only the plotted point of each day, so the caption undercounts. timelineSummary says "N lab values are recorded as a bound (< or >) and drawn hollow", but a censored value that loses to a higher value on the same day (for example <5 and 7 on one day) is neither drawn nor counted. The caption also never mentions that some same-day values are hidden; only the tooltip does. Per CLAUDE.md, "nothing is dropped without saying so": either count censored values across all items, or have the caption say that same-day values are reduced to their maximum.

Comment thread app/lab/timeline-body.tsx
if (!ev) { if (tip) dropTip(); return; }
holdTip();
setTip((t) => ({ x: e.clientX, y: e.clientY, ev: ev.split(",").map(Number), pinned: false, page: t && t.ev.join(",") === ev ? t.page : 0 }));
setTip((t) => ({ x: e.clientX, y: e.clientY, ev: ev.split(",").map(Number), pinned: false, page: t && t.ev.join(",") === ev ? t.page : 0, line: onLine(e) }));

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The tooltip for a line-chart day opens on the first-listed event, not on the value that is plotted. page starts at 0 = ix[0] (event-index order), while the point is drawn at at (the day's max). If you hover the point drawn at 3.2 (CEA 1.8 then 3.2 on day 10), the first page shows RESULT 1.8, directly under the note "Plotted y value is the max". Consider ordering ix with at first in linePoints, or starting page at the plotted event's position.

Comment thread lib/timeline-svg.ts Outdated
for (const it of items) (byDay.get(it.start) || byDay.set(it.start, []).get(it.start)!).push(it);
return [...byDay.entries()].sort((a, b) => a[0] - b[0]).map(([start, g]) => {
const vs = g.map((it) => ({ it, v: numericResult(events[it.i])! }));
const top = vs.reduce((m, x) => x.v.v > m.v.v ? x : m);

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A tie between a censored and an exact value on the same day goes to whichever is listed first. The comparison is strict > on v alone, so <0.5 listed before 0.5 on the same day plots a hollow (censored) point at 0.5, and listing them the other way round plots a filled one. That difference also changes the caption's censored count. A deterministic tie-break (prefer the uncensored value, or follow the portal's rule) would make the result independent of row order.

Comment thread app/lab/timeline-body.tsx
const at = figX(e);
setCursor(at?.inPlot ? at.x : null);
const svg = box.current?.querySelector("svg");
setHotRow(svg && drawn ? rowAt(drawn.layout, e.clientY - svg.getBoundingClientRect().top) : null);

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hot-row tracking also runs while the pointer is over the tooltip and during a drag, and duplicates DOM work. EventTip is a child of .tl-fig in the React tree, so mouse moves over a hovered or pinned tooltip bubble into onMove. Those moves highlight whichever figure row sits under the tooltip. Separately, every mousemove now calls querySelector('svg') and getBoundingClientRect() twice (once in figX, once here), and .closest('.tl-m') twice (marked + onLine). Suggestion: have figX return both x and y from one rect read, have one helper return {ev, line} from a single closest, and skip the row update when e.target is inside the tooltip.

Comment thread lib/timeline-tracks.ts
* own first event, or 0 for a track whose events are all in its sub-tracks (the portal's parent
* tracks hold none). Ties keep the order the values first occur in the patient's events.
*/
export const trackSortKey = (t: Pick<TlTrack, "items">): number => t.items.length ? t.items[0].start : 0;

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sort key depends on the order the events arrive in, not on their dates. items[0].start is the first event as listed (the test asserts -40 over -90). That matches the portal only because patientEventsSql orders by start, id. Any event source not sorted that way (a federated/remote timeline, or a future caller) would order the sub-tracks arbitrarily. Either document or assert that precondition at buildTracks, or check that remote sources return events sorted by start as well.

@alisman

alisman commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

Review verdict: changes (head 5d8d135)

Blocking:

  1. CI lint fails because of this PR's code. lib/timeline-svg.ts:112:20 sonarjs/reduce-initial-value is the vs.reduce(...) in linePoints. Give it an initial value, for example vs.slice(1).reduce(..., vs[0]), and update the timeline-line-first-of-day planted bug's find string to match.
  2. PAT-TL-TR-1: the root labels don't yet match legacy. Legacy draws every track header through getTrackLabel (cbioportal-clinical-timeline/src/TrackHeader.tsx), which returns (track.label || track.type).replace(/_/g, ''). So the portal shows "LABTEST", not "LAB_TEST". Our snapshot (msk_chord P-0000012) still draws >LAB_TEST<. The test and the tracker row record "LAB_TEST" as the legacy label. Strip the underscores the way legacy does (it applies to sub-track labels too), then fix the test, the snapshot and the tracker note.

Checked against legacy and fine:

The other inline comments are not blocking: the censored/exact tie at the max, the band showing over the tooltip, the extra DOM reads on each mouse move, the sort's dependence on event order (it matches legacy's), and the caption's censored count.

- lib/timeline-svg.ts linePoints: reduce() has its initial value
  (sonarjs/reduce-initial-value), and the timeline-line-first-of-day planted
  bug's find string follows it.
- The portal's track header shows every track's label with underscores
  dropped (getTrackLabel, cbioportal-clinical-timeline TrackHeader.tsx), so
  "LAB_TEST" reads "LABTEST". The figure now shows trackLabel, the label
  without underscores, for root and sub-tracks. The tracks' labels and uids
  are unchanged, so a document's collapsed tracks still match. Tested, with a
  planted bug; the timeline snapshot re-rendered.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Q3ezTVY3MHJRLp4DsZ9c7C

This branch was successfully deployed

1 active deployment
Preview – cohort-lab — 7432c097 Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant