The stratified survival chart

Do participants with high and low levels of this biomarker have different outcomes? The chart draws a Kaplan–Meier curve for each group, with a mark at each censored time and the number at risk beneath, above a small histogram of the biomarker that shows where the cut falls and how many participants land on each side. The groups are a column's, or a biomarker or a participant-level number cut by the core's shared cut rule. A cut's line on the histogram can be dragged: the curves follow it at once, and when it is let go the cut becomes a typed point and R is asked again. Under the curves, R's log-rank test of the groups is printed with each group's median survival and its interval and, for two groups, the hazard ratio with its interval. A click on a curve, or on a count of the at-risk strip, lists its participants, and a row of the listing opens safety.viz's participant profile.

BioViz.stratifiedSurvival('#chart', {
  endpoint: 'EFS',
  group_by: { measure: 'CRP', visit: 'Baseline', cut: 'median' },
  connection: BioViz.r.createConnection({
    browser: { sourceUrl: 'vendor/gsm.bio/statistics.R', packages: ['survival'] }
  })
}).init({ results, participants, outcomes });

Experimental: the curves are safety.viz's estimator, kmEstimate, which awaits its clinical review.

What the page loads

safety.viz's script-tag bundle first, then bio.viz's: the chart is built from safety.viz's kit, which it finds on the page as SafetyViz.kit when it is made. Its curves are the kit's kmEstimate, and they and the histogram are drawn with the kit's Chart.js. Without safety.viz on the page the chart is refused with a message saying what is missing. R in the browser needs the survival package, which gsm.bio's Analyze_Survival calls: give it in the connection's browser.packages.

stratifiedSurvival(element, settings)

Makes the chart in element, a DOM element or a CSS selector for one, with settings laid over the defaults below. The controls are drawn at once; the tables are given to init. A setting that is not known, or a value a setting cannot take, is refused: stratifiedSurvival throws a TypeError whose message begins bio.viz: and names the setting.

The tables

init and setData take { results, participants, outcomes }, each an array of records, one object per row. results and participants are the tables the core reads, and the column settings are the core's. The groups come from them: a column of the participant table, or of the results rows, or a biomarker cut at a visit.

outcomes is one row per participant and endpoint, with the time and a flag, as ADaM's time-to-event datasets hold them: by default PARAMCD names the endpoint, PARAM says it in words, AVAL is the time, and CNSR is ADaM's censor flag, 1 for censored and 0 for an event. The flag may be read the other way round, as an event flag, 1 for an event: name it with event_col, as gsm.bio's Analyze_Survival takes strCensorCol or strEventCol. Exactly one is named. An outcomes table without a column the settings name is refused, with a message that names the column. Without an outcomes table the chart draws nothing and says that it needs one, with its controls.

A participant with a group and no row for the endpoint is left out and counted (No outcome for the endpoint), and so is one with more than one row for it, one whose time or flag is missing or not a number, one whose flag is not 0 or 1, and one whose time is below 0. A flag may also be logical, true or false, or written TRUE or FALSE, as R's Analyze_Survival takes one. A row of the outcomes table for a participant neither the participant table nor the results have is not used, and counted (Outcome row for no such participant). A participant with no group is left out and counted as the core counts it. When the filters together let nobody through, the chart draws nothing, asks R for nothing and reads No participant passes the filters., the words every chart uses. If drawing fails for any other reason, the footnote says This chart could not be drawn: and why, nothing half drawn is left, and the controls stay.

The chart's methods

Settings

Titles and footnotes

The settings title, subtitle and footnotes are text with named placeholders, filled from the view drawn each time the chart draws. A placeholder is a name in braces, and it is replaced by text: nothing in a setting or a value is evaluated, and a name the chart does not have is left as written. The title and the subtitle are drawn above the chart, and the footnotes under it; the chart's own footnote, always last, says when and by what it was drawn and what stands behind each statistic printed. The rules are in Getting results out.

Downloads

Under the footnotes a bar offers three downloads, each saved as a file named for the chart and the view, such as bio.viz-stratified-survival-….png:

A CSV file is written by RFC 4180: a field, or a heading, that holds a comma, a double quote or a line break is quoted. chart.fileOf(kind) gives the same file without saving it: a promise of { name, blob }, for kind 'png', 'statistics' or 'table'. The format of each file is in Getting results out.

What is drawn

• The curves: each group's Kaplan–Meier estimate, the kit's kmEstimate, drawn as steps from 1 at time 0 to the group's last time, with a short upright mark at each censored time. A cut's groups run low to high, labelled with their bounds; a column's are in order of name. The legend gives each group's number of participants, and hides nothing when clicked. No confidence band is drawn, and none is worked out here: the chart reads only the estimate's steps and censored times, never the bounds kmEstimate also returns. A click lists a group only when it is on that group's curve, within a few pixels.
• The at-risk strip: for each group, the number at risk at each time of the axis, the participants whose time is at or after it. A group's name lists its participants, and a count lists the participants it counts.
• The histogram, for a cut variable: the values the cut points were worked out on, in equal bars, with a dashed line at each cut point and how many values fall in each group. Each line can be dragged with a pointer, and each is a slider of its own for the keyboard (see moving a cut line).
• A cut's points are worked out on the participants the filters keep who have a value of the cut variable and an outcome for the endpoint: the ones the curves are drawn of, so the median cuts them in halves, as R's Analyze_Screen cuts a biomarker for its hazard ratio. The footnote says so.
• The footnote: how to list a group, and how the variable was cut.

Moving a cut line

A line is taken hold of within a few pixels of it, more with a finger, and moves by as much as the pointer moves from where it took hold: a click on or beside a line, with no drag, leaves it where it is and asks R nothing. From the keyboard, each line is a slider (role="slider", with its value and how far it can go): the left and right arrows move it by one bar of the histogram, Page Up and Page Down by five, Home and End as far as it can go; the curves follow each key, and R is asked once the keys have rested. While a line is held the curves, the at-risk strip and the histogram follow it at once, drawn for the cut where the line is, and the statistics line says that R is asked when the line is let go: no answer for another cut stays on screen. When it is let go the line lands on the point its label writes, four significant digits, so the point in the settings, in the key R's stored result is found by and on the label are one number. The cut becomes typed points (the median 2.783, moved to 4, is cut: [4]), the Groups control holds it, and R is asked for the new groups. A line cannot pass its neighbour, nor stop where two points would be written alike, nor leave the values it cuts: it stays between the least and the greatest. Reset returns to the cut the settings name.

The statistics line

R is asked once per view, with one row per participant drawn: the id, time, group, and the flag, censor or event, as the outcomes table gives it. The line says it is waiting until R answers, and a change to a control, a filter or the cut clears it and asks again; an answer to a question no longer on screen is never shown. R's log-rank result is printed with its method and counts, labelled exploratory and unadjusted. Under it, each group's median survival with its log-log interval, as R's survfit() gives it, a median or a bound the curve did not reach reading not reached; and, for two groups, the hazard ratio with its interval, Cox's: for a cut, the hazard in the higher group over the hazard in the lower. Where R does not estimate the hazard ratio, as when one group has no event, it is not printed, and R's note says why. What R said about its answer is printed as R worded it. The chart computes no test statistic, no p-value, no median and no hazard ratio. With no R attached the curves are still drawn, and the line says that statistics are unavailable.

What R is asked

connection.run('Analyze_Survival', {
  data, // one row per participant drawn: the id, time, group, censor (or event)
  args: {
    strTimeCol: 'time',
    strGroupCol: 'group',
    strCensorCol: 'censor', // or strEventCol: 'event'
    chrGroups: ['> 2.783', '≤ 2.783'] // a cut's high to low, a column's by code point
  },
  dataId // what the rows are: see below
});

The groups R is handed are in an order that depends on nothing but them: a cut's high to low, a column's sorted by code point, as R's sort(method = "radix") sorts them, the same in every browser and every language. The hazard ratio is the first group's hazard over the second's, so for a cut it is the higher group's over the lower's, as the biomarker screen's "High / Low" is; The line lists the medians in the legend's order, and names a cut's hazard ratio Hazard ratio, high over low.

dataId states what the rows are, so a stored result is found by the function's name, these arguments and this identity together:

A cut biomarker reads a baseline when its value is the baseline or a change from it (value other than raw). The R recipe that writes the same key is survival_key in tools/r-survival.R, which writes the expected results the tests hold this chart to: each group's curve as survfit() gives it, and what Analyze_Survival answers.

On a phone

At 390 pixels the controls start folded away, the at-risk strip scrolls inside its own box when it is wider than the screen, and the page does not scroll sideways.

What is not here

No test statistic, p-value, median, hazard ratio, confidence band or adjustment is computed here: the chart draws the kit's product-limit estimate and counts who is at risk, which describe the participants, and every test and estimate printed is R's.