The connection to R

How a chart gets a statistic. bio.viz computes no statistical test: a chart hands its table to R through a connection and prints what comes back. This page is the interface, for anyone writing a chart, an R function a chart will call, or the stored results a report ships with.

Everything here is exported as BioViz.r from the script-tag bundle and as r from the ES module bundle. Nothing in it depends on the rest of bio.viz or on safety.viz, so a connection can be handed to any chart as a setting.

At a glance

const connection = BioViz.r.createConnection({
  results, // stored results, optional
  browser: { sourceUrl: 'statistics.R', packages: ['survival'] } // R in the browser, optional
});

const result = await connection.run('rank_sum', {
  data: rows, // an array of records, one object per row
  args: { value: 'AVAL', group: 'ARM' }, // named arguments
  dataId: 'opening view' // which data this is; only the stored results use it
});

if (result.status === 'ok') {
  footnote.textContent = BioViz.r.formatStatistic(result.value).text;
} else {
  footnote.textContent = result.message;
}

createConnection(options)

Returns a frozen object with one method, run. Creating a connection loads nothing and requests nothing.

A malformed option throws a TypeError when the connection is created. That is the only place this interface throws.

With both forms configured, stored results are tried first and R in the browser answers whatever they do not hold. With neither, every answer is unavailable.

connection.run(name, { data, args, dataId })

Asks R to call the function name with the table first and the arguments after it: in R, name(data, value = "AVAL", group = "ARM").

run returns a promise that always resolves, to one of three results. It never rejects.

Reasons a result is unavailable:

A call that cannot be made at all (no function name, data that is not an array, args that is not an object) also resolves to { status: 'error', message }, with a message that begins bio.viz:.

R warnings are not carried in the result. An R function that has something to say about its answer says it in the value it returns, as gsm.bio's functions do in warnings and notes.

What R receives and returns

Going in, data becomes a data frame built with base R: one column per key found in any record, in the order first seen. Text becomes character (never a factor), numbers numeric, booleans logical. A value that is absent, undefined, null or not-a-number becomes NA. Keep each column to one type.

Coming out, the value is converted with base R and nothing else; no package is needed in the R session:

A table has one shape whatever its size. A data frame of no rows is an empty array, one row is an array of one object, and every row carries every column, with NA as null. Row names are not carried; a table that needs them puts them in a column. A column may itself hold lists or data frames, converted by the same rules.

The rule for whoever writes the R function: return a collection as a data frame or an unnamed list, never as a bare vector whose length may be one. A bare vector of length one arrives as a single value, so a chart reading it could not tell one group from a number. Single facts (a p-value, a method's name) are bare vectors of length one; counts by group are a named vector, which is an object at any length.

A value with no plain form, such as a function, is an error result.

Stored results

The precomputed form answers from results worked out ahead of time, by gsm.bio in R, and shipped with the page. It starts nothing and makes no network request.

results is an array. Each entry:

{
  "name": "rank_sum",
  "args": { "value": "AVAL", "group": "ARM" },
  "dataId": "opening view",
  "rows": 170,
  "value": {
    "method": "Wilcoxon rank-sum test",
    "p_value": 0.0312,
    "counts": { "Placebo": 86, "Active": 84 }
  }
}

A call is answered by a stored result only when all of these hold:

• name is the same.
• args are the same after sorting keys at every depth. Nothing else is normalised: "ARM" and ["ARM"] differ, and so do 1 and "1". Written from R, a single value must be written as a single value (jsonlite::toJSON(auto_unbox = TRUE)).
• dataId is the same, compared the same way. The call must give one.
• rows, if recorded, equals the number of records in data.

Anything else is a miss, answered unavailable with reason not-precomputed, or passed to R in the browser when that form is configured. A stored result is never returned for a call it was not computed for.

Written from R, the value must be in the shape the browser form would give it. With jsonlite that means auto_unbox = TRUE and data frames written by row, and it means counts by group are written as a named list: jsonlite drops the names of a named vector. tools/r-fixtures.R writes the R check page's stored results with a few lines of base R that follow the table above exactly.

The data identity is stated, not derived. It is whatever the producer and the chart agree to call a selection of the study: a label such as "opening view", or an object describing the filters in force. A fingerprint of the rows was considered and rejected: it would have to be computed identically in R and in JavaScript, and the two do not always read the same decimal text to the same number, so it would miss when it should match. The price of a stated identity is that the chart must state it truthfully: it must change dataId whenever a filter changes the rows. rows is the cheap cross-check on that.

Two entries with the same name, arguments and data identity are refused when the connection is created, as is any entry missing a required member.

The browser form

On the first run that needs R, and not before, the connection:

1. imports webr.mjs from baseUrl with a run-time import(); webR is not in the bundle and is not an npm dependency;
2. starts webR 0.6.0 on its PostMessage channel, which works on any static host, GitHub Pages included, and is used everywhere so behaviour does not differ by host;
3. installs and attaches packages;
4. evaluates the R source once.

Calls made while this is in progress wait for the same start; there is one R session per connection, kept for its lifetime. If the start fails, every waiting call is answered unavailable with reason load-failed, and the next call starts again.

A copy of webR served from another location must be version 0.6.0. The version is pinned by the default location, not checked.

WEBR_VERSION and WEBR_BASE_URL

Two constants, for a page that needs to say which R it runs or to load the same copy itself.

formatStatistic(statistic)

The one place the rules for printing a p-value live. It formats what R returned and computes nothing.

It reads these members of a statistics result, the names gsm.bio's functions return:

It returns { status, text }:

The rules, from the design:

• Never a p-value alone: without the method's name or the counts, the number is not printed.
• Three decimals. Below 0.001 it prints p < 0.001; where it would round to 1.000 it prints p > 0.999.
• Labelled Exploratory, unadjusted. unless the result names an adjustment, and then Exploratory, adjusted (Holm). An adjustment R names by its p.adjust method is printed by its usual name: holm as Holm, hochberg as Hochberg, hommel as Hommel, bonferroni as Bonferroni, BH and fdr as Benjamini-Hochberg, BY as Benjamini-Yekutieli. Any other name is printed as given.
• No stars, and never the word significant.
• A reason in place of a number when R declined to compute one, said once. A reason that already begins "Not computed", as gsm.bio's do, is printed as it is, with the counts after it as a sentence of their own. Any other reason is led in by the method's name and the words not computed: Wilcoxon rank-sum test: not computed, fewer than 5 participants in Placebo (Placebo n = 3, Active n = 84).
• A result R marked as an error is printed as R's message, after R reported an error:, with the counts where R knew them and no number.

Stating the filter a result was computed under is the chart's footnote, not this function's.

formatEstimate(estimate)

Formats one estimate R returned: one row of a result's estimates. It reads name, group (what it is an estimate of), estimate, and the interval as lower, upper and level.

It returns { status, text }:

Each number is printed to four significant figures, without trailing zeros, and is otherwise R's: nothing is computed, and an interval is never completed or widened here. The level is printed as a percentage, 0.95 as 95%.

formatMedian(estimate)

Formats one median survival time R returned: a row of estimates from gsm.bio's Analyze_Survival, named Median. It reads name, group, estimate, and the interval as lower, upper and level. R gives no median, or no bound, where the curve or its band did not fall to one half, and says so in its note; that part reads not reached.

Each number is printed to four significant figures, as formatEstimate prints one, and is otherwise R's: nothing is computed, and a missing part is never filled in.

formatComparison(comparison)

Formats one comparison of two groups from a result's rows, such as one pairwise comparison, by the rules a whole result is held to: its p-value is given only with its method, the two groups' counts and its label. It reads group_1, group_2, n_1, n_2, method, p_value (the adjusted one, when R adjusted), adjustment, status and reason.

It returns the sentence, and its parts for a chart that prints the comparisons as a table:

A table built from the parts prints p only beside the pair's counts and under a caption that carries method and label.

formatGroup(row)

Formats one group's result from a result's rows: an estimate R computed within one group, such as a correlation coefficient in one arm, with its interval, the group's count and its p-value. The p-value is held to the rules a whole result is held to. It reads group, counts, estimate, lower, upper, level, method, p_value, adjustment, status and reason.

It returns the sentence, and its parts for a chart that prints the groups as a table:

No interval is made up: where R returned none, none is printed. A group R could not compute for, one with too few pairs, gives R's reason and its count and no number: Treatment: Not computed: 2 complete pairs. The minimum is 5. Counts: n = 2.

formatPair(row)

Formats one pair's result from a correlation matrix's rows: the coefficient R computed for two of a grid's variables, with its interval and the number of complete pairs it used. It prints no p-value, by design: a grid of coefficients is not a grid of tests, and gsm.bio's Analyze_CorrelationMatrix returns none. It reads x, y, counts, estimate, lower, upper, level, status and reason, and nothing else: a p-value on a row is neither read nor printed.

It returns the sentence, and its parts for a cell and for a table:

No interval is made up: where R returned none, none is printed. A pair R could not compute for, one with too few complete pairs, gives R's reason and its count and no number: Not computed: 178 complete pairs. The minimum is 183. Counts: n = 178.

formatScreenRow(row, groups)

Formats one row of a biomarker screen's rows: one biomarker's estimate, a standardised difference or a coefficient, with its interval, the counts it used, and its p-value twice, as R computed it, unadjusted, and as R adjusted it across the rows that have one. Both are held to the rules a whole result is held to: never without the method and the counts, labelled exploratory, the adjustment named, no star and no verdict. It reads biomarker, counts, n_1, n_2, estimate, lower, upper, level, method, p_unadjusted, p_value, adjustment, adjusted_over, status and reason. groups, for a difference, names the two groups so the counts say whose they are.

It returns the sentence, and its parts for a table:

A row R could not compute gives R's reason and its counts and no number: CRP: Not computed: Placebo has 2; Treatment has 2. The minimum group size is 5. Counts: Placebo n = 2, Treatment n = 2.

Checked against real R

The R check page runs this interface against real R: a rank-sum test and a log-rank test, through the precomputed form and through R in the browser, each beside the answer desktop R gives, with the megabytes and seconds that starting R in a browser costs. The browser tests named RCON-LIVE-* run that page on every pull request.

The group comparison chart is the first chart to use it: its demo starts R in the browser with gsm.bio's statistics file, and the browser tests named GC-STAT-034 to GC-STAT-042 hold what it prints to desktop R.